> ## Documentation Index > Fetch the complete documentation index at: https://docs.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 dynamic columns resolved from FullTerm custom object fields. 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 `additionalColumns` to transpose FullTerm custom object fields into extra columns. Each entry maps a dot-path into the segment's policy data to a named column header. **Required permission:** `company.policy:read` ## OpenAPI ````yaml /openapi/generated-external-api.yaml get /api/v1/external/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://app.aiinsurance.io description: Production security: - ApiKeyAuth: [] paths: /api/v1/external/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 dynamic columns resolved from FullTerm custom object fields. 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 `additionalColumns` to transpose FullTerm custom object fields into extra columns. Each entry maps a dot-path into the segment's policy data to a named column header. **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: additionalColumns in: query schema: type: string description: > JSON-encoded array of additional column definitions. Each element is an object with `path` (dot-separated path into the segment's policy data) and `columnHeader` (display name for the column). examples: taxes: summary: Add policy taxes column value: >- [{"path":"fullTermPolicyBilling.policyTaxes","columnHeader":"Policy Taxes"}] multipleColumns: summary: Add taxes and carrier columns value: >- [{"path":"fullTermPolicyBilling.policyTaxes","columnHeader":"Policy Taxes"},{"path":"carrier","columnHeader":"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 additionalColumns: {} - 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 additionalColumns: {} totalCount: 2 withAdditionalColumns: summary: Bordereau with additional 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 additionalColumns: Policy Taxes: '3100' Carrier: National Indemnity totalCount: 1 '400': description: Invalid request parameters content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalidAdditionalColumns: summary: Invalid JSON in additionalColumns value: error: code: INVALID_REQUEST message: additionalColumns must be valid JSON 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' 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 additional columns resolved from FullTerm custom object fields. required: - transactionAction - policyVersion - effectiveDate - transactionTimestamp - policyStartDate - policyEndDate - createdAt - additionalColumns 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. additionalColumns: type: object additionalProperties: type: string nullable: true description: > Dynamic columns resolved from FullTerm custom object fields. Keys are the `columnHeader` values from the `additionalColumns` query parameter; values are the resolved field values (or null if the path did not resolve). 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: UNAUTHORIZED message: Authorization header is required bearerTokenNotAllowed: summary: Bearer token used instead of API key value: error: code: UNAUTHORIZED message: External API endpoints require API key authentication Forbidden: description: Forbidden - Insufficient permissions content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: insufficientPermissions: summary: Insufficient permissions value: error: code: FORBIDDEN message: Insufficient permissions to perform this action 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: INTERNAL_ERROR message: An unexpected error occurred. Please try again later. securitySchemes: ApiKeyAuth: type: apiKey in: header name: Authorization description: >- API key authentication. Include your API key in the Authorization header. ````