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

# Set Policy Invoice Type Money-Out Approval

> Sets whether a policy invoice type's money-out invoices require approval before a payment can be recorded. Money-in invoices never require approval. Uses the same audited operation as Financials settings; the URL fixes policy scope.

Each invoice records its own requirement when it is created, so a change through the API reaches new invoices only: open invoices keep the requirement they recorded. To also change open invoices, change the setting in the app, which offers to apply it to them.

**Required permission:** `financials.configure`



## OpenAPI

````yaml /openapi/generated-external-api.yaml put /api/v1/companies/{companyId}/financials/config/policy-invoice-types/{categoryId}/money-out-approval
openapi: 3.0.3
info:
  title: AI Insurance External API
  description: External API for AI Insurance platform
  version: 1.0.0
  contact:
    email: support@aiinsurance.io
servers:
  - url: https://go.aiinsurance.io
    description: Production
security:
  - ApiKeyAuth: []
paths:
  /api/v1/companies/{companyId}/financials/config/policy-invoice-types/{categoryId}/money-out-approval:
    put:
      tags:
        - Financials
      summary: Set Policy Invoice Type Money-Out Approval
      description: >-
        Sets whether a policy invoice type's money-out invoices require approval
        before a payment can be recorded. Money-in invoices never require
        approval. Uses the same audited operation as Financials settings; the
        URL fixes policy scope.


        Each invoice records its own requirement when it is created, so a change
        through the API reaches new invoices only: open invoices keep the
        requirement they recorded. To also change open invoices, change the
        setting in the app, which offers to apply it to them.


        **Required permission:** `financials.configure`
      operationId: setFinancialsPolicyInvoiceTypeMoneyOutApproval
      parameters:
        - $ref: '#/components/parameters/companyId'
        - name: categoryId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Policy invoice type ID from List Policy Invoice Types.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
                - moneyOutRequiresApproval
              properties:
                moneyOutRequiresApproval:
                  type: boolean
                  description: Whether the type's money-out invoices require approval.
            examples:
              request:
                summary: Require approval on money-out invoices
                value:
                  moneyOutRequiresApproval: true
      responses:
        '200':
          description: >-
            The complete refreshed Financials settings, including deprecated
            rows.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FinancialsV2Settings'
              examples:
                success:
                  summary: Refreshed settings
                  value:
                    categories: []
                    policyFinancials:
                      invoiceTypes:
                        - id: 550e8400-e29b-41d4-a716-446655440100
                          name: Return Premium
                          expectedDirection: payable
                          moneyOutRequiresApproval: true
                          deprecatedAt: null
                          everUsed: true
                          liveInvoiceCount: 3
                          vocabularyLock: invoice
                          hasLegacyLineItems: false
                          policyPresets: null
                          payeeDefaults: null
                      lineItemTypes: []
                    classifications: []
        '400':
          description: Invalid input, such as a missing value or an unknown field.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalidRequest:
                  summary: The request was refused
                  value:
                    error:
                      code: VALIDATION_ERROR
                      message: The request is invalid.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: The ID is not a policy invoice type of this company.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  parameters:
    companyId:
      name: companyId
      in: path
      required: true
      schema:
        type: string
        format: uuid
      description: Company identifier
  schemas:
    FinancialsV2Settings:
      type: object
      properties:
        paymentDefaults:
          nullable: true
          type: object
          properties:
            paymentCount:
              type: integer
              minimum: 0
              exclusiveMinimum: true
              maximum: 120
            owedLeadTimeDays:
              type: integer
              minimum: 0
              maximum: 3650
            endorsementHandling:
              oneOf:
                - type: object
                  additionalProperties: false
                  required:
                    - mode
                    - status
                  properties:
                    mode:
                      type: string
                      enum:
                        - void
                    status:
                      type: string
                      enum:
                        - scheduled
                        - owed
                        - all
                - type: object
                  additionalProperties: false
                  required:
                    - mode
                    - status
                  properties:
                    mode:
                      type: string
                      enum:
                        - keep
                    status:
                      type: string
                      enum:
                        - paid
                        - owed
                        - all
                - type: object
                  additionalProperties: false
                  required:
                    - mode
                  properties:
                    mode:
                      type: string
                      enum:
                        - manual
            paymentPeriod:
              type: string
              enum:
                - upfront
                - quarterly
                - monthly
            firstDueDate:
              type: object
              properties:
                anchor:
                  type: string
                  enum:
                    - today
                    - effective-date
                daysAfter:
                  type: integer
                  minimum: 0
                  maximum: 3650
              required:
                - anchor
                - daysAfter
              additionalProperties: false
            avoidWeekendSends:
              type: boolean
          required:
            - paymentCount
            - owedLeadTimeDays
            - endorsementHandling
          additionalProperties: false
        categories:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                format: uuid
                pattern: >-
                  ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
              name:
                type: string
              kind:
                type: string
                enum:
                  - operating
                  - reserved
              expectedDirection:
                type: string
                enum:
                  - payable
                  - receivable
              moneyOutRequiresApproval:
                type: boolean
                description: >-
                  Whether this type's money-out invoices require approval before
                  a payment can be recorded. Money-in invoices never require
                  approval.
              deprecatedAt:
                nullable: true
                type: string
                pattern: >-
                  ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$
              everUsed:
                type: boolean
              liveInvoiceCount:
                type: integer
                minimum: -9007199254740991
                maximum: 9007199254740991
              lineItemTypes:
                type: array
                items:
                  type: object
                  properties:
                    displayLabel:
                      type: string
                      nullable: true
                    id:
                      type: string
                      format: uuid
                      pattern: >-
                        ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    name:
                      type: string
                    direction:
                      type: string
                      enum:
                        - payable
                        - receivable
                    deprecatedAt:
                      nullable: true
                      type: string
                      pattern: >-
                        ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$
                    everUsed:
                      type: boolean
                    liveInvoiceCount:
                      type: integer
                      minimum: -9007199254740991
                      maximum: 9007199254740991
                  required:
                    - id
                    - name
                    - direction
                    - deprecatedAt
                    - everUsed
                    - liveInvoiceCount
                  additionalProperties: false
            required:
              - id
              - name
              - kind
              - expectedDirection
              - moneyOutRequiresApproval
              - deprecatedAt
              - everUsed
              - liveInvoiceCount
              - lineItemTypes
            additionalProperties: false
        policyFinancials:
          type: object
          properties:
            invoiceTypes:
              type: array
              items:
                $ref: '#/components/schemas/FinancialsV2PolicyInvoiceType'
            lineItemTypes:
              type: array
              items:
                $ref: '#/components/schemas/FinancialsV2PolicyLineItemType'
          required:
            - invoiceTypes
            - lineItemTypes
          additionalProperties: false
        classifications:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                format: uuid
                pattern: >-
                  ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
              key:
                type: string
              label:
                type: string
              rollup:
                type: string
                enum:
                  - premium
                  - taxes
                  - fees
              deprecatedAt:
                nullable: true
                type: string
                pattern: >-
                  ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$
              referenced:
                type: boolean
            required:
              - id
              - key
              - label
              - rollup
              - deprecatedAt
              - referenced
            additionalProperties: false
      required:
        - categories
        - policyFinancials
        - classifications
      additionalProperties: false
    ErrorResponse:
      type: object
      description: Standard error response for all external API endpoints
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              description: Machine-readable error code
              example: VALIDATION_ERROR
            message:
              type: string
              description: Human-readable error message
              example: 'submissionId: Required field is missing'
            userMessages:
              type: array
              description: >-
                Clean, verbatim-displayable messages — one entry per failure,
                free of error-code tags, field paths, and internal noise.
                Suitable for showing to end users as-is.
              items:
                type: string
              example:
                - Exposures of type 'company' require an address
            details:
              type: array
              description: Additional details for validation errors (field-level errors)
              items:
                type: object
                properties:
                  field:
                    type: string
                    description: The field that caused the error
                    example: submissionId
                  code:
                    type: string
                    description: Stable problem code for this individual validation failure
                    example: BLANK_LIST_ELEMENT
                  reason:
                    type: string
                    description: Stable reason the value violates its canonical contract
                    example: blank-list-element
                  expected:
                    type: string
                    description: The expected canonical value contract
                    example: nonblank trimmed string
                  message:
                    type: string
                    description: Description of the field error
                    example: Required field is missing
    FinancialsV2PolicyInvoiceType:
      type: object
      properties:
        id:
          type: string
          format: uuid
          pattern: >-
            ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
        name:
          type: string
        expectedDirection:
          type: string
          enum:
            - payable
            - receivable
        moneyOutRequiresApproval:
          type: boolean
          description: >-
            Whether this type's money-out invoices require approval before a
            payment can be recorded. Money-in invoices never require approval.
            Each invoice records its own requirement when it is created, so a
            change to this setting reaches new invoices only.
        deprecatedAt:
          nullable: true
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$
        everUsed:
          type: boolean
        liveInvoiceCount:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        vocabularyLock:
          nullable: true
          type: string
          enum:
            - invoice
            - policy
            - null
          description: >-
            A non-deleted invoice citation locks rename/delete. Historical
            postings alone do not. Pricing labels are independent of billing
            vocabulary.
        hasLegacyLineItems:
          type: boolean
          description: >-
            Delete these original-parent line items explicitly before deleting
            the invoice type.
        policyPresets:
          type: object
          properties:
            paymentCount:
              type: integer
              minimum: 0
              exclusiveMinimum: true
              maximum: 9007199254740991
            owedLeadTimeDays:
              type: integer
              minimum: 0
              maximum: 9007199254740991
            payeeRule:
              type: string
              enum:
                - primary-insured
                - broker
          required:
            - paymentCount
            - owedLeadTimeDays
            - payeeRule
          additionalProperties: false
          nullable: true
        payeeDefaults:
          type: object
          properties:
            expression:
              nullable: true
              type: string
              minLength: 1
              maxLength: 10000
            allowedEntityTypes:
              minItems: 1
              maxItems: 3
              type: array
              items:
                type: string
                enum:
                  - Exposure
                  - Person
                  - Organization
          required:
            - expression
            - allowedEntityTypes
          additionalProperties: false
          nullable: true
      required:
        - id
        - name
        - expectedDirection
        - moneyOutRequiresApproval
        - deprecatedAt
        - everUsed
        - liveInvoiceCount
        - vocabularyLock
        - hasLegacyLineItems
        - policyPresets
      additionalProperties: false
    FinancialsV2PolicyLineItemType:
      type: object
      properties:
        displayLabel:
          type: string
          nullable: true
        id:
          type: string
          format: uuid
          pattern: >-
            ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
        name:
          type: string
        direction:
          type: string
          enum:
            - payable
            - receivable
        deprecatedAt:
          nullable: true
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$
        everUsed:
          type: boolean
        liveInvoiceCount:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        vocabularyLock:
          nullable: true
          type: string
          enum:
            - invoice
            - policy
            - null
          description: >-
            A non-deleted invoice citation locks rename/delete. Historical
            postings alone do not. Pricing labels are independent of billing
            vocabulary.
        allowedOn:
          type: array
          items:
            type: object
            properties:
              invoiceTypeId:
                type: string
                format: uuid
                pattern: >-
                  ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
              label:
                type: string
                nullable: true
              removable:
                type: boolean
            required:
              - invoiceTypeId
              - label
              - removable
            additionalProperties: false
          description: >-
            Allowed invoice-type identities and optional display labels.
            removable=false marks an implicit legacy parent association.
      required:
        - id
        - name
        - direction
        - deprecatedAt
        - everUsed
        - liveInvoiceCount
        - vocabularyLock
        - allowedOn
      additionalProperties: false
  responses:
    Unauthorized:
      description: Unauthorized - Invalid or missing API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            missingApiKey:
              summary: Missing API key
              value:
                error:
                  code: AuthenticationError
                  message: API key authentication required
                  userMessages:
                    - API key authentication required
            invalidApiKey:
              summary: >-
                Invalid API key (e.g. unknown key, or a Bearer token used
                instead of an API key)
              value:
                error:
                  code: AuthenticationError
                  message: Invalid API key
                  userMessages:
                    - Invalid API key
    Forbidden:
      description: Forbidden - Insufficient permissions
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            insufficientPermissions:
              summary: Insufficient permissions
              value:
                error:
                  code: AuthorizationError
                  message: User is not authorized to perform the requested action
                  userMessages:
                    - User is not authorized to perform the requested action
            companyMismatch:
              summary: A valid API key naming another company in the URL
              value:
                error:
                  code: AuthorizationError
                  message: API key is not scoped to the requested company
                  userMessages:
                    - API key is not scoped to the requested company
    InternalServerError:
      description: Internal Server Error - Unexpected error occurred
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            internalError:
              summary: Unexpected server error
              value:
                error:
                  code: UncaughtActionError
                  message: Uncaught error occurred in <actionName>
                  userMessages:
                    - An unexpected error occurred. Please try again later.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: >-
        API key authentication. Send your raw API key as the `Authorization`
        header value with NO scheme prefix — `Authorization: YOUR-API-KEY`. Do
        NOT prefix it with `Bearer ` or `ApiKey `, and do not use an `X-API-Key`
        header; those are not accepted.

````

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