> ## 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.

# Create Policy Line Item Type

> Uses the same audited operation and validation rules as Financials settings. The URL fixes policy scope; event vocabulary and other companies’ IDs cannot be changed here. Creates an independent company policy line item with name and direction. Associate it with one or more policy invoice types using Set Policy Line Item Associations.

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



## OpenAPI

````yaml /openapi/generated-external-api.yaml post /api/v1/companies/{companyId}/financials/config/policy-line-item-types
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-line-item-types:
    post:
      tags:
        - Financials
      summary: Create Policy Line Item Type
      description: >-
        Uses the same audited operation and validation rules as Financials
        settings. The URL fixes policy scope; event vocabulary and other
        companies’ IDs cannot be changed here. Creates an independent company
        policy line item with name and direction. Associate it with one or more
        policy invoice types using Set Policy Line Item Associations.


        **Required permission:** `financials.configure`
      operationId: createFinancialsPolicyLineItemType
      parameters:
        - $ref: '#/components/parameters/companyId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FinancialsV2CreatePolicyLineItemType'
            examples:
              request:
                summary: Create Policy Line Item Type
                value:
                  name: Broker Commission
                  direction: payable
      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: Agency Bill
                          expectedDirection: receivable
                          moneyOutRequiresApproval: false
                          deprecatedAt: null
                          everUsed: false
                          liveInvoiceCount: 0
                          vocabularyLock: null
                          hasLegacyLineItems: false
                          policyPresets: null
                          payeeDefaults: null
                      lineItemTypes:
                        - id: 550e8400-e29b-41d4-a716-446655440110
                          name: Broker Commission
                          direction: payable
                          deprecatedAt: null
                          everUsed: false
                          liveInvoiceCount: 0
                          vocabularyLock: null
                          allowedOn:
                            - invoiceTypeId: 550e8400-e29b-41d4-a716-446655440100
                              label: Broker Commission (Less)
                              removable: true
                    classifications: []
        '400':
          description: >-
            Invalid input, a duplicate live name, or a vocabulary rule refusing
            the change.
          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 vocabulary row 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:
    FinancialsV2CreatePolicyLineItemType:
      type: object
      properties:
        name:
          type: string
          minLength: 1
        direction:
          type: string
          enum:
            - payable
            - receivable
      required:
        - name
        - direction
      additionalProperties: false
    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.