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

# List Bordereau Rows

> Returns a paginated, flat list of transaction-level premium rows (a "bordereau").
Each row represents one policy transaction and includes fixed columns (policy number,
insured name, action, dates, premium, premium change) plus optional field columns
resolved from the policy's field data.

Use `periodStart` and `periodEnd` to scope the report to transactions whose
`transactionTimestamp` falls within the half-open interval `[periodStart, periodEnd)`.
Use `actions` to filter by transaction type (e.g. only NEW_BUSINESS and ENDORSE).

Use `columns` with `{"kind":"field"}` entries to transpose any policy fields
into the `fieldColumns` map on each row. Each entry maps a dot-path into the
policy's field data to a named column header. Each row resolves its paths
against the policy data **as of that transaction's effective date**, so
fields that vary over the policy term (e.g. a mid-term endorsement's
changes, or the post-cancellation status) report the value the transaction
put in force. A path that does not exist in the policy data yields an empty
value, not an error.

**Note:** this endpoint accepts `{"kind":"field"}` column specs ONLY — its
typed JSON rows always carry every fixed property, so fixed-column selection
and ordering have no meaning here, and a `{"kind":"fixed"}` entry is
rejected with HTTP 400. For full column selection and ordering use the
rendered surfaces — the [CSV download](/api-reference/field-model/bordereau/download)
and [Google Sheets export](/api-reference/field-model/bordereau/export).

**Required permission:** `company.policy:read`




## OpenAPI

````yaml /openapi/generated-external-api.yaml get /api/v1/companies/{companyId}/policies/bordereau
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}/policies/bordereau:
    get:
      tags:
        - Field Model Bordereau
      summary: List Bordereau Rows
      description: >
        Returns a paginated, flat list of transaction-level premium rows (a
        "bordereau").

        Each row represents one policy transaction and includes fixed columns
        (policy number,

        insured name, action, dates, premium, premium change) plus optional
        field columns

        resolved from the policy's field data.


        Use `periodStart` and `periodEnd` to scope the report to transactions
        whose

        `transactionTimestamp` falls within the half-open interval
        `[periodStart, periodEnd)`.

        Use `actions` to filter by transaction type (e.g. only NEW_BUSINESS and
        ENDORSE).


        Use `columns` with `{"kind":"field"}` entries to transpose any policy
        fields

        into the `fieldColumns` map on each row. Each entry maps a dot-path into
        the

        policy's field data to a named column header. Each row resolves its
        paths

        against the policy data **as of that transaction's effective date**, so

        fields that vary over the policy term (e.g. a mid-term endorsement's

        changes, or the post-cancellation status) report the value the
        transaction

        put in force. A path that does not exist in the policy data yields an
        empty

        value, not an error.


        **Note:** this endpoint accepts `{"kind":"field"}` column specs ONLY —
        its

        typed JSON rows always carry every fixed property, so fixed-column
        selection

        and ordering have no meaning here, and a `{"kind":"fixed"}` entry is

        rejected with HTTP 400. For full column selection and ordering use the

        rendered surfaces — the [CSV
        download](/api-reference/field-model/bordereau/download)

        and [Google Sheets export](/api-reference/field-model/bordereau/export).


        **Required permission:** `company.policy:read`
      operationId: listBordereauRows
      parameters:
        - $ref: '#/components/parameters/companyId'
        - name: periodStart
          in: query
          schema:
            type: string
            format: date-time
          description: >
            Inclusive lower bound on `transactionTimestamp`. Only transactions
            at or after

            this timestamp are included.
        - name: periodEnd
          in: query
          schema:
            type: string
            format: date-time
          description: >
            Exclusive upper bound on `transactionTimestamp`. Only transactions
            before

            this timestamp are included.
        - name: actions
          in: query
          schema:
            type: string
          description: >
            Comma-separated list of transaction actions to include.

            Valid values: `NEW_BUSINESS`, `ENDORSE`, `CANCEL`, `REINSTATE`,
            `RENEW`.

            Omit to include all actions.


            **Note:** Unrecognized action values are not rejected — they
            silently

            match zero rows. Double-check spelling if results are unexpectedly
            empty.
          examples:
            singleAction:
              summary: Only new business
              value: NEW_BUSINESS
            multipleActions:
              summary: New business and endorsements
              value: NEW_BUSINESS,ENDORSE
        - name: columns
          in: query
          schema:
            type: string
          description: >
            JSON-encoded array of `{"kind":"field"}` column specs (see

            `BordereauColumnSpec`). Each entry maps a `path` (dot-separated path
            into

            the policy's field data) to a `header` (the key it appears under in
            each

            row's `fieldColumns` map).


            Any field path is accepted, including bare top-level per-segment
            fields

            (e.g. `policyStatus`): each row resolves its paths against the
            policy

            data as of that transaction's effective date. A malformed dot-path

            (empty, or with leading/trailing/doubled dots) is rejected with HTTP
            400

            (`InvalidProperties`); a well-formed path that doesn't exist in the

            policy data yields an empty value.


            `{"kind":"fixed"}` entries are rejected with HTTP 400 on this
            endpoint —

            the typed JSON rows always include every fixed property.
          examples:
            taxes:
              summary: Add a policy-taxes field column
              value: >-
                [{"kind":"field","path":"fullTermPricingInfo.taxes","header":"Taxes"}]
            perSegmentStatus:
              summary: Add the per-transaction policy status
              value: '[{"kind":"field","path":"policyStatus","header":"Status"}]'
            multipleColumns:
              summary: Add taxes and carrier field columns
              value: >-
                [{"kind":"field","path":"fullTermPricingInfo.taxes","header":"Taxes"},{"kind":"field","path":"fullTermPolicyRatingResult.carrier","header":"Carrier"}]
        - name: sortBy
          in: query
          schema:
            type: string
            enum:
              - policyNumber
              - primaryInsuredName
              - effectiveDate
              - transactionTimestamp
              - createdAt
          description: Field to sort results by. Default `transactionTimestamp`.
        - name: sortDirection
          in: query
          schema:
            type: string
            enum:
              - asc
              - desc
            default: desc
          description: Sort direction (default `desc`).
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 1000
            default: 50
          description: >
            Maximum number of rows to return per request. Default 50, maximum
            1000.
        - name: offset
          in: query
          schema:
            type: integer
            minimum: 0
            default: 0
          description: Number of rows to skip before returning results. Default 0.
      responses:
        '200':
          description: Paginated list of bordereau rows
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BordereauListResponse'
              examples:
                bordereauRows:
                  summary: Bordereau with two transactions
                  value:
                    items:
                      - policyNumber: POL-2025-001
                        primaryInsuredName: Mercy General Hospital
                        transactionAction: NEW_BUSINESS
                        policyVersion: 1
                        effectiveDate: '2025-01-01'
                        transactionTimestamp: '2025-01-15T10:30:00.000Z'
                        policyStartDate: '2025-01-01'
                        policyEndDate: '2026-01-01'
                        createdAt: '2025-01-15T10:30:00.000Z'
                        createdBy: api-key|abc123
                        policyPremium: 85000
                        policyPremiumChange: 85000
                        fieldColumns: {}
                      - policyNumber: POL-2025-001
                        primaryInsuredName: Mercy General Hospital
                        transactionAction: ENDORSE
                        policyVersion: 2
                        effectiveDate: '2025-06-01'
                        transactionTimestamp: '2025-06-01T14:00:00.000Z'
                        policyStartDate: '2025-01-01'
                        policyEndDate: '2026-01-01'
                        createdAt: '2025-06-01T14:00:00.000Z'
                        createdBy: api-key|abc123
                        policyPremium: 102000
                        policyPremiumChange: 17000
                        fieldColumns: {}
                    totalCount: 2
                withFieldColumns:
                  summary: Bordereau with field columns
                  value:
                    items:
                      - policyNumber: POL-2025-002
                        primaryInsuredName: Sunrise Medical Center
                        transactionAction: NEW_BUSINESS
                        policyVersion: 1
                        effectiveDate: '2025-03-01'
                        transactionTimestamp: '2025-03-01T09:00:00.000Z'
                        policyStartDate: '2025-03-01'
                        policyEndDate: '2026-03-01'
                        createdAt: '2025-03-01T09:00:00.000Z'
                        createdBy: api-key|abc123
                        policyPremium: 62000
                        policyPremiumChange: 62000
                        fieldColumns:
                          Policy Taxes: '3100'
                          Carrier: National Indemnity
                    totalCount: 1
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                fixedColumnOnList:
                  summary: columns contains a fixed-kind entry
                  value:
                    error:
                      code: ValidationError
                      message: >-
                        the bordereau list endpoint accepts only { kind: "field"
                        } entries in columns — its typed JSON rows always carry
                        every fixed property, so fixed-column selection and
                        ordering have no meaning here; use the CSV download or
                        Google Sheets export for full column control
                      userMessages:
                        - >-
                          the bordereau list endpoint accepts only { kind:
                          "field" } entries in columns — its typed JSON rows
                          always carry every fixed property, so fixed-column
                          selection and ordering have no meaning here; use the
                          CSV download or Google Sheets export for full column
                          control
                invalidFieldColumnPath:
                  summary: columns field path is a malformed dot-path
                  value:
                    error:
                      code: ValidationError
                      message: >-
                        path must be a dot-separated field path (no empty,
                        leading, trailing, or doubled segments)
                      userMessages:
                        - >-
                          path must be a dot-separated field path (no empty,
                          leading, trailing, or doubled segments)
                limitExceeded:
                  summary: Limit exceeds maximum
                  value:
                    error:
                      code: INVALID_REQUEST
                      message: limit must not exceed 1000
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  parameters:
    companyId:
      name: companyId
      in: path
      required: true
      schema:
        type: string
        format: uuid
      description: Company identifier
  schemas:
    BordereauListResponse:
      type: object
      description: Paginated bordereau response containing transaction-level premium rows.
      required:
        - items
        - totalCount
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/BordereauRow'
          description: Bordereau rows for the current page.
        totalCount:
          type: integer
          description: Total number of matching rows across all pages.
    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
                  message:
                    type: string
                    description: Description of the field error
                    example: Required field is missing
    BordereauRow:
      type: object
      description: >
        A single bordereau row representing one policy transaction. Each row
        contains

        fixed columns (always present) and optional field columns resolved from

        the policy's field data as of the transaction's effective date.
      required:
        - transactionAction
        - policyVersion
        - effectiveDate
        - transactionTimestamp
        - policyStartDate
        - policyEndDate
        - createdAt
        - fieldColumns
      properties:
        policyNumber:
          type: string
          nullable: true
          description: The policy number (policyId field from policy data), if set.
        primaryInsuredName:
          type: string
          nullable: true
          description: >
            Resolved name of the primary insured exposure. Null if the primary
            insured

            could not be resolved.
        transactionAction:
          type: string
          enum:
            - NEW_BUSINESS
            - ENDORSE
            - CANCEL
            - REINSTATE
            - RENEW
          description: The type of policy transaction that produced this row.
        policyVersion:
          type: integer
          description: The policy version number created by this transaction.
        effectiveDate:
          type: string
          format: date
          description: The effective date of the transaction.
        transactionTimestamp:
          type: string
          format: date-time
          description: >
            When the business decision was made. For imported policies this
            reflects

            the original transaction time, not the import time.
        policyStartDate:
          type: string
          format: date
          description: Policy term start date.
        policyEndDate:
          type: string
          format: date
          description: Policy term end date.
        createdAt:
          type: string
          format: date-time
          description: >
            When the database row was created. Differs from
            `transactionTimestamp` for

            imported policies (where `transactionTimestamp` reflects the
            original

            transaction time and `createdAt` reflects the import time).
        createdBy:
          type: string
          nullable: true
          description: The user or API key that created the transaction.
        policyPremium:
          type: number
          nullable: true
          description: Full-term policy premium for this version.
        policyPremiumChange:
          type: number
          nullable: true
          description: >
            Premium change from the prior version. Computed as

            `policyPremium - priorVersionPolicyPremium`. For NEW_BUSINESS
            transactions

            the prior premium is 0, so this equals the full premium.
        fieldColumns:
          type: object
          additionalProperties:
            type: string
            nullable: true
          description: >
            Dynamic columns resolved from the policy's field data as of this

            transaction's effective date, so per-segment fields (e.g.
            `policyStatus`)

            report the value this transaction put in force. Keys are the
            `header`

            values from the request's `{"kind":"field"}` `columns` entries;
            values

            are the resolved field values (or null if the path did not resolve).

            Empty when no field columns were requested.
  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.

````