> ## Documentation Index
> Fetch the complete documentation index at: https://docs.watchdog.no/llms.txt
> Use this file to discover all available pages before exploring further.

# List approval rules

> Approval rules in the organization's order, each with its conditions and approvers. Read callers see the rules, conditions and approvers; who was skipped names invoices, so `skipped_people` and `skipped_teams` are empty and `include=skips` is refused below Admin.



## OpenAPI

````yaml /openapi.json get /v1/approval-rules
openapi: 3.1.0
info:
  title: Watchdog API
  version: 1.0.0
  description: >-
    The Watchdog API is served from https://api.watchdog.no. Request bodies are
    limited to 2 MiB unless an endpoint says otherwise. Files are uploaded
    directly to storage, not through the API.
servers:
  - url: https://api.watchdog.no
    description: Watchdog API
security: []
paths:
  /v1/approval-rules:
    get:
      tags:
        - Approval rules
        - Invoices
        - Settings
      summary: List approval rules
      description: >-
        Approval rules in the organization's order, each with its conditions and
        approvers. Read callers see the rules, conditions and approvers; who was
        skipped names invoices, so `skipped_people` and `skipped_teams` are
        empty and `include=skips` is refused below Admin.
      operationId: listApprovalRules
      parameters:
        - name: X-Organization-Id
          in: header
          required: false
          schema:
            type: string
          description: >-
            The organization to act in. Required for personal API keys; list the
            organizations you can access with GET /v1/organizations.
        - name: fields
          in: query
          required: false
          schema:
            type: array
            items:
              type: string
          style: form
          explode: false
          description: >-
            Return only these fields of each row; use dots for nested fields,
            such as approvers.user_id. id is always returned. Fields: id, name,
            subject, conditions, fallback, position, approvers, approver_teams,
            references, skipped_people, skipped_teams, created_at, updated_at.
        - schema:
            type: integer
            minimum: 1
            maximum: 1000
            default: 50
          required: false
          name: limit
          in: query
        - schema:
            type: string
            maxLength: 4096
          required: false
          name: cursor
          in: query
        - schema:
            type: string
            enum:
              - invoice
              - purchase_order
            description: Only rules for this subject.
          required: false
          description: Only rules for this subject.
          name: subject
          in: query
      responses:
        '200':
          description: A page of approval rules.
          headers:
            X-Request-Id:
              schema:
                type: string
              required: true
              description: >-
                Request ID, also included in error bodies. Include it when
                contacting support.
            Cache-Control:
              schema:
                type: string
                enum:
                  - private, no-store
                  - private, no-store, no-transform
              required: false
              description: API responses are private and must not be cached.
            X-RateLimit-Limit:
              schema:
                type: string
                example: '500'
              required: false
              description: >-
                Requests allowed per minute for this credential, or failed API
                key attempts allowed per minute from this IP address.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ApprovalRule'
                    maxItems: 1000
                  next_cursor:
                    type:
                      - string
                      - 'null'
                required:
                  - data
                  - next_cursor
        '400':
          description: >-
            The request is invalid. details lists up to 20 field errors. Request
            bodies are limited to 2 MiB.
          headers:
            X-Request-Id:
              schema:
                type: string
              required: true
              description: >-
                Request ID, also included in error bodies. Include it when
                contacting support.
            Cache-Control:
              schema:
                type: string
                enum:
                  - private, no-store
                  - private, no-store, no-transform
              required: false
              description: API responses are private and must not be cached.
            X-RateLimit-Limit:
              schema:
                type: string
                example: '500'
              required: false
              description: >-
                Requests allowed per minute for this credential, or failed API
                key attempts allowed per minute from this IP address.
          content:
            application/json:
              example:
                error:
                  code: validation_error
                  message: >-
                    The request is invalid. details lists up to 20 field errors.
                    Request bodies are limited to 2 MiB.
                  request_id: req_example
              schema:
                $ref: '#/components/schemas/Error_validation_error'
        '401':
          description: The bearer token is missing or invalid.
          headers:
            X-Request-Id:
              schema:
                type: string
              required: true
              description: >-
                Request ID, also included in error bodies. Include it when
                contacting support.
            Cache-Control:
              schema:
                type: string
                enum:
                  - private, no-store
                  - private, no-store, no-transform
              required: false
              description: API responses are private and must not be cached.
            X-RateLimit-Limit:
              schema:
                type: string
                example: '500'
              required: false
              description: >-
                Requests allowed per minute for this credential, or failed API
                key attempts allowed per minute from this IP address.
            WWW-Authenticate:
              schema:
                type: string
              required: false
              description: Bearer authentication challenge, when supplied.
          content:
            application/json:
              example:
                error:
                  code: invalid_token
                  message: The bearer token is missing or invalid.
                  request_id: req_example
              schema:
                $ref: '#/components/schemas/Error_invalid_token'
        '403':
          description: >-
            Access denied. The error code says why: forbidden, token_disabled,
            organization_required, insufficient_role or mfa_required.
          headers:
            X-Request-Id:
              schema:
                type: string
              required: true
              description: >-
                Request ID, also included in error bodies. Include it when
                contacting support.
            Cache-Control:
              schema:
                type: string
                enum:
                  - private, no-store
                  - private, no-store, no-transform
              required: false
              description: API responses are private and must not be cached.
            X-RateLimit-Limit:
              schema:
                type: string
                example: '500'
              required: false
              description: >-
                Requests allowed per minute for this credential, or failed API
                key attempts allowed per minute from this IP address.
          content:
            application/json:
              example:
                error:
                  code: forbidden
                  message: >-
                    Access denied. The error code says why: forbidden,
                    token_disabled, organization_required, insufficient_role or
                    mfa_required.
                  request_id: req_example
              schema:
                $ref: >-
                  #/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required
        '429':
          description: Too many requests. Wait for the Retry-After delay before retrying.
          headers:
            X-Request-Id:
              schema:
                type: string
              required: true
              description: >-
                Request ID, also included in error bodies. Include it when
                contacting support.
            Cache-Control:
              schema:
                type: string
                enum:
                  - private, no-store
                  - private, no-store, no-transform
              required: false
              description: API responses are private and must not be cached.
            X-RateLimit-Limit:
              schema:
                type: string
                example: '500'
              required: false
              description: >-
                Requests allowed per minute for this credential, or failed API
                key attempts allowed per minute from this IP address.
            Retry-After:
              schema:
                type: string
                example: '60'
              required: true
              description: Seconds to wait before retrying the request.
          content:
            application/json:
              example:
                error:
                  code: rate_limit_exceeded
                  message: >-
                    Too many requests. Wait for the Retry-After delay before
                    retrying.
                  request_id: req_example
              schema:
                $ref: '#/components/schemas/Error_rate_limit_exceeded'
        '500':
          description: >-
            Unexpected server failure. Include the request ID when contacting
            support.
          headers:
            X-Request-Id:
              schema:
                type: string
              required: true
              description: >-
                Request ID, also included in error bodies. Include it when
                contacting support.
            Cache-Control:
              schema:
                type: string
                enum:
                  - private, no-store
                  - private, no-store, no-transform
              required: false
              description: API responses are private and must not be cached.
            X-RateLimit-Limit:
              schema:
                type: string
                example: '500'
              required: false
              description: >-
                Requests allowed per minute for this credential, or failed API
                key attempts allowed per minute from this IP address.
          content:
            application/json:
              example:
                error:
                  code: internal_error
                  message: >-
                    Unexpected server failure. Include the request ID when
                    contacting support.
                  request_id: req_example
              schema:
                $ref: '#/components/schemas/Error_internal_error'
        '503':
          description: >-
            Temporarily unavailable. Retry after the Retry-After delay, when
            provided.
          headers:
            X-Request-Id:
              schema:
                type: string
              required: true
              description: >-
                Request ID, also included in error bodies. Include it when
                contacting support.
            Cache-Control:
              schema:
                type: string
                enum:
                  - private, no-store
                  - private, no-store, no-transform
              required: false
              description: API responses are private and must not be cached.
            X-RateLimit-Limit:
              schema:
                type: string
                example: '500'
              required: false
              description: >-
                Requests allowed per minute for this credential, or failed API
                key attempts allowed per minute from this IP address.
            Retry-After:
              schema:
                type: string
                example: '60'
              required: true
              description: Seconds to wait before retrying the request.
          content:
            application/json:
              example:
                error:
                  code: service_unavailable
                  message: >-
                    Temporarily unavailable. Retry after the Retry-After delay,
                    when provided.
                  request_id: req_example
              schema:
                $ref: '#/components/schemas/Error_service_unavailable'
      security:
        - ApiKeyBearer: []
components:
  schemas:
    ApprovalRule:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        subject:
          type: string
          enum:
            - invoice
            - purchase_order
          description: >-
            What the rule approves: `invoice`, or `purchase_order` for orders
            made in Watchdog before they open, and amendments that raise their
            commitment or change their supplier, buyer, currency or commitment
            basis. Fixed once the rule is created.
        conditions:
          $ref: '#/components/schemas/StoredSubscriptionFilter'
        fallback:
          type: boolean
          description: >-
            The fallback rule: who approves what no other rule of its subject
            gives approvers, at intake after the other rules, and when a waiting
            record loses its last approver. It has no conditions and matches
            every record, so a fallback for purchase orders makes every order
            made in Watchdog wait for approval. At most one per subject
            (WD-2930). Rules made as fallbacks before then may still have
            conditions and keep them.
        position:
          type: integer
          minimum: 0
          description: >-
            Where the rule stands in the organization's order, lowest first.
            Under the approval policy's `single_rule`, an invoice takes its
            approvers from the first rule that matches it, in that rule's steps.
            Otherwise every matching rule adds its approvers by step number, and
            someone several rules name takes the step of the first.
        approvers:
          type: array
          items:
            $ref: '#/components/schemas/ApprovalRuleApprover'
        approver_teams:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                format: uuid
              name:
                type: string
              step:
                type: integer
                minimum: 1
                description: The step the rule puts the approver in, 1 first (WD-2904).
            required:
              - id
              - name
              - step
          description: Teams that approve what the rule matches, by name.
        references:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                format: uuid
              name:
                type:
                  - string
                  - 'null'
              missing:
                type: boolean
              supplier_names:
                type: array
                items:
                  type: string
                description: Supplier names for agreement references.
              type:
                type: string
                enum:
                  - supplier
                  - recipient
                  - agreement
                  - agreement_tag
                  - company
                description: >-
                  `company`: a workspace company, which only approval rules
                  name.
            required:
              - id
              - name
              - missing
              - type
          description: >-
            Names of the companies, suppliers and recipients the conditions
            name.
        skipped_people:
          type: array
          items:
            type: object
            properties:
              user_id:
                type: string
                minLength: 1
                maxLength: 255
              name:
                type:
                  - string
                  - 'null'
              reason:
                type: string
                enum:
                  - no_access
                  - no_write
                  - removed_by_hand
                description: >-
                  `no_access`: their access limits hide the invoice. `no_write`:
                  role without write access. `removed_by_hand`: a person removed
                  them from the invoice.
              count:
                type: integer
                exclusiveMinimum: 0
                description: How many invoices the rule skipped them on.
              invoices:
                $ref: '#/components/schemas/ApprovalRuleSkippedInvoices'
            required:
              - user_id
              - name
              - reason
              - count
              - invoices
          description: >-
            People the rule names but did not add, once per person and reason,
            on invoices in Inbox or Needs approval, as of when each invoice
            arrived. Blocking reasons come first, then hand removals.
        skipped_teams:
          type: array
          items:
            type: object
            properties:
              team_id:
                type: string
                format: uuid
              name:
                type:
                  - string
                  - 'null'
              reason:
                type: string
                enum:
                  - nobody_can_act
                description: >-
                  `nobody_can_act`: nobody in the team had write access and
                  could see the invoice.
              count:
                type: integer
                exclusiveMinimum: 0
                description: How many invoices the rule skipped the team on.
              invoices:
                $ref: '#/components/schemas/ApprovalRuleSkippedInvoices'
            required:
              - team_id
              - name
              - reason
              - count
              - invoices
          description: >-
            Teams the rule names but did not add, on invoices in Inbox or Needs
            approval, as of when each invoice arrived, by name. Such an invoice
            gets the fallback rules' approvers, or none.
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      required:
        - id
        - name
        - subject
        - fallback
        - position
        - approvers
        - approver_teams
        - references
        - skipped_people
        - skipped_teams
        - created_at
        - updated_at
    Error_validation_error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - validation_error
            message:
              type: string
            request_id:
              type: string
            description:
              type: string
            details:
              type: array
              items:
                type: object
                properties:
                  code:
                    type: string
                  field:
                    type: string
                  message:
                    type: string
                required:
                  - code
                  - field
                  - message
              maxItems: 20
            workflow_run_id:
              type: string
              format: uuid
            import_id:
              type: string
              format: uuid
            existing_party:
              type: object
              properties:
                type:
                  type: string
                  enum:
                    - supplier
                    - recipient
                id:
                  type: string
                  format: uuid
              required:
                - type
                - id
          required:
            - code
            - message
            - request_id
      required:
        - error
    Error_invalid_token:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - invalid_token
            message:
              type: string
            request_id:
              type: string
            description:
              type: string
            details:
              type: array
              items:
                type: object
                properties:
                  code:
                    type: string
                  field:
                    type: string
                  message:
                    type: string
                required:
                  - code
                  - field
                  - message
              maxItems: 20
            workflow_run_id:
              type: string
              format: uuid
            import_id:
              type: string
              format: uuid
            existing_party:
              type: object
              properties:
                type:
                  type: string
                  enum:
                    - supplier
                    - recipient
                id:
                  type: string
                  format: uuid
              required:
                - type
                - id
          required:
            - code
            - message
            - request_id
      required:
        - error
    Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - forbidden
                - token_disabled
                - organization_required
                - insufficient_role
                - mfa_required
            message:
              type: string
            request_id:
              type: string
            description:
              type: string
            details:
              type: array
              items:
                type: object
                properties:
                  code:
                    type: string
                  field:
                    type: string
                  message:
                    type: string
                required:
                  - code
                  - field
                  - message
              maxItems: 20
            workflow_run_id:
              type: string
              format: uuid
            import_id:
              type: string
              format: uuid
            existing_party:
              type: object
              properties:
                type:
                  type: string
                  enum:
                    - supplier
                    - recipient
                id:
                  type: string
                  format: uuid
              required:
                - type
                - id
          required:
            - code
            - message
            - request_id
      required:
        - error
    Error_rate_limit_exceeded:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - rate_limit_exceeded
            message:
              type: string
            request_id:
              type: string
            description:
              type: string
            details:
              type: array
              items:
                type: object
                properties:
                  code:
                    type: string
                  field:
                    type: string
                  message:
                    type: string
                required:
                  - code
                  - field
                  - message
              maxItems: 20
            workflow_run_id:
              type: string
              format: uuid
            import_id:
              type: string
              format: uuid
            existing_party:
              type: object
              properties:
                type:
                  type: string
                  enum:
                    - supplier
                    - recipient
                id:
                  type: string
                  format: uuid
              required:
                - type
                - id
          required:
            - code
            - message
            - request_id
      required:
        - error
    Error_internal_error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - internal_error
            message:
              type: string
            request_id:
              type: string
            description:
              type: string
            details:
              type: array
              items:
                type: object
                properties:
                  code:
                    type: string
                  field:
                    type: string
                  message:
                    type: string
                required:
                  - code
                  - field
                  - message
              maxItems: 20
            workflow_run_id:
              type: string
              format: uuid
            import_id:
              type: string
              format: uuid
            existing_party:
              type: object
              properties:
                type:
                  type: string
                  enum:
                    - supplier
                    - recipient
                id:
                  type: string
                  format: uuid
              required:
                - type
                - id
          required:
            - code
            - message
            - request_id
      required:
        - error
    Error_service_unavailable:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - service_unavailable
            message:
              type: string
            request_id:
              type: string
            description:
              type: string
            details:
              type: array
              items:
                type: object
                properties:
                  code:
                    type: string
                  field:
                    type: string
                  message:
                    type: string
                required:
                  - code
                  - field
                  - message
              maxItems: 20
            workflow_run_id:
              type: string
              format: uuid
            import_id:
              type: string
              format: uuid
            existing_party:
              type: object
              properties:
                type:
                  type: string
                  enum:
                    - supplier
                    - recipient
                id:
                  type: string
                  format: uuid
              required:
                - type
                - id
          required:
            - code
            - message
            - request_id
      required:
        - error
    StoredSubscriptionFilter:
      description: >-
        A saved View filter, returned as stored for unrestricted callers; it may
        be null or no longer valid. A restricted caller receives null with
        filter_restricted=true when the definition contains unavailable
        references or cannot be safely read. To replace it, send a filter in the
        shape the View create and update requests accept.
    ApprovalRuleApprover:
      allOf:
        - $ref: '#/components/schemas/ApproverPerson'
        - type: object
          properties:
            step:
              type: integer
              minimum: 1
              description: The step the rule puts the approver in, 1 first (WD-2904).
          required:
            - step
    ApprovalRuleSkippedInvoices:
      type: object
      properties:
        invoices:
          type: array
          items:
            type: object
            properties:
              invoice_id:
                type: string
                format: uuid
              invoice_number:
                type:
                  - string
                  - 'null'
              supplier_name:
                type:
                  - string
                  - 'null'
            required:
              - invoice_id
              - invoice_number
              - supplier_name
          maxItems: 10
          description: >-
            Up to 10 of the invoices, by supplier and number. The count gives
            the total.
        supplier_name:
          type:
            - string
            - 'null'
          description: >-
            The supplier every one of the invoices is from, or null when there
            are several.
      required:
        - invoices
        - supplier_name
    ApproverPerson:
      type: object
      properties:
        user_id:
          type: string
          minLength: 1
          maxLength: 255
        first_name:
          type:
            - string
            - 'null'
        last_name:
          type:
            - string
            - 'null'
        email:
          type:
            - string
            - 'null'
      required:
        - user_id
        - first_name
        - last_name
        - email
  securitySchemes:
    ApiKeyBearer:
      type: http
      scheme: bearer
      description: >-
        Personal API key sent as a bearer token, together with
        X-Organization-Id. The key must have at least the access level the
        endpoint requires (read, write or admin).

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.