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

# Get Policies Configuration

> Returns JSON Schemas describing the custom fields available for
Field Model V1 policies. The response contains separate schemas for
policy-level fields and exposure-level fields.

Each schema is a standard JSON Schema (draft 2020-12) that can be
used directly with validation libraries like Ajv or Zod.

The `policy` schema covers policy-level custom fields (used in
policy `fieldModelV1Data.policy` or segment `policy` objects).
The `exposure` schema covers exposure-level custom fields.

The `policy` schema excludes fields that are system-managed and
not user-input: calculated (Jexl-derived) fields, server-populated
fields (rating responses, billing, Google Drive ids, target rater),
and policy lifecycle fields (`policyStatus`, `policyNumber`).

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




## OpenAPI

````yaml /openapi/generated-external-api.yaml get /api/v1/external/companies/{companyId}/policies/configuration
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/configuration:
    get:
      tags:
        - Field Model Policies
      summary: Get Policies Configuration
      description: |
        Returns JSON Schemas describing the custom fields available for
        Field Model V1 policies. The response contains separate schemas for
        policy-level fields and exposure-level fields.

        Each schema is a standard JSON Schema (draft 2020-12) that can be
        used directly with validation libraries like Ajv or Zod.

        The `policy` schema covers policy-level custom fields (used in
        policy `fieldModelV1Data.policy` or segment `policy` objects).
        The `exposure` schema covers exposure-level custom fields.

        The `policy` schema excludes fields that are system-managed and
        not user-input: calculated (Jexl-derived) fields, server-populated
        fields (rating responses, billing, Google Drive ids, target rater),
        and policy lifecycle fields (`policyStatus`, `policyNumber`).

        **Required permission:** `company.policy:read`
      operationId: getFieldModelV1PoliciesConfiguration
      parameters:
        - $ref: '#/components/parameters/companyId'
      responses:
        '200':
          description: Configuration for FMV1 policy custom fields
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FieldModelV1PolicyConfigurationResponse'
              examples:
                withCustomFields:
                  summary: Configuration with policy and exposure fields
                  value:
                    policy:
                      $schema: https://json-schema.org/draft/2020-12/schema
                      type: object
                      properties:
                        effectiveDate:
                          type: string
                          title: effectiveDate
                        premium:
                          type: number
                          title: premium
                        status:
                          type: string
                          title: status
                          oneOf:
                            - const: active
                              title: Active
                            - const: cancelled
                              title: Cancelled
                            - const: expired
                              title: Expired
                      required:
                        - effectiveDate
                    exposure:
                      $schema: https://json-schema.org/draft/2020-12/schema
                      type: object
                      properties:
                        employeeCount:
                          type: number
                          title: employeeCount
                        isActive:
                          type: boolean
                          title: isActive
                      required: []
                emptySchema:
                  summary: No custom fields configured
                  value:
                    policy:
                      $schema: https://json-schema.org/draft/2020-12/schema
                      type: object
                      properties: {}
                      required: []
                    exposure:
                      $schema: https://json-schema.org/draft/2020-12/schema
                      type: object
                      properties: {}
                      required: []
        '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:
    FieldModelV1PolicyConfigurationResponse:
      type: object
      description: |
        Configuration response for Field Model V1 policies. Returns separate
        JSON Schemas for policy-level and exposure-level custom fields.
      required:
        - policy
        - exposure
      properties:
        policy:
          $ref: '#/components/schemas/FieldModelV1DataSchema'
          description: |
            JSON Schema for policy-level custom fields. These fields apply to
            `segments[].policy` objects (including `policyCoverages`).
        exposure:
          $ref: '#/components/schemas/FieldModelV1DataSchema'
          description: |
            JSON Schema for exposure-level custom fields. These fields apply to
            `segments[].exposures[]` objects.
    FieldModelV1DataSchema:
      type: object
      description: |
        Standard JSON Schema (draft 2020-12) describing field definitions
        for Field Model V1 entities. Includes a `required` array listing
        fields that must be provided.
      required:
        - $schema
        - type
        - properties
        - required
      properties:
        $schema:
          type: string
          enum:
            - https://json-schema.org/draft/2020-12/schema
          description: JSON Schema version identifier
        type:
          type: string
          enum:
            - object
        properties:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/JsonSchemaProperty'
          description: Map of field keys to their JSON Schema definitions
        required:
          type: array
          items:
            type: string
          description: |
            Field keys that are unconditionally required. Only fields with
            `requiredCondition.expression === "true"` are listed here.
            Fields with conditional JEXL expressions are not included since
            they cannot be evaluated at configuration time.
    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
    JsonSchemaProperty:
      type: object
      description: |
        A JSON Schema property definition describing a single field.
        Uses standard JSON Schema (draft 2020-12) format for compatibility
        with validation libraries (Ajv, Zod) and OpenAPI tooling.
      required:
        - title
      properties:
        type:
          type: string
          enum:
            - string
            - number
            - integer
            - boolean
            - array
            - object
          description: JSON Schema data type
        title:
          type: string
          description: Human-readable field label
        description:
          type: string
          description: Additional context about the field
        format:
          type: string
          description: >
            Semantic format hint for the field value. Common formats:

            - `date` - ISO 8601 date (YYYY-MM-DD)

            - `email` - Email address

            - `phone` - Phone number

            - `currency` - Monetary value

            - `percent` - Percentage value

            - `address` - Physical address

            - `entity:{target}` - Reference to another entity type via a Join
            field
        const:
          type: string
          description: |
            Exact value match. Used inside `oneOf` entries for Option Set values
            to represent the machine-readable key.
        enum:
          type: array
          items:
            oneOf:
              - type: string
              - type: number
          description: >
            Allowed values for legacy SelectField / RadioSelect /
            MultiSelectField /

            AsyncMultiSelectField fields. Each entry is a machine-readable
            option

            `value`. For MultiSelect-style fields the `enum` appears inside
            `items`

            (since the field stores an array of selected values); for
            single-select

            fields it appears at the top level. Pair with `enumLabels` to render

            human-readable labels.
        enumLabels:
          type: object
          additionalProperties:
            type: string
          description: >
            Optional companion to `enum`: a map from each enum `value`
            (stringified)

            to its human-readable label, so consumers can render labels without

            a second round-trip. Keys are always strings even if the underlying

            `enum` values are numbers — look up labels with `String(value)`.
        oneOf:
          type: array
          description: |
            Allowed values for Option Set fields (FMV1). Each entry provides a
            machine-readable key (`const`) and a human-readable label (`title`).
            Legacy MultiSelect/Select fields use `enum` + `enumLabels` instead.
          items:
            type: object
            required:
              - const
              - title
            properties:
              const:
                type: string
                description: Machine-readable key stored as the field value
              title:
                type: string
                description: Human-readable display label
        properties:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/JsonSchemaProperty'
          description: >
            Nested property definitions for object-type fields (e.g. Date,
            Currency,

            Address, CoverageLimit, custom objects). Also used inside `items`
            for

            legacy GroupField outputs to describe each row's subfield shape.
        required:
          type: array
          items:
            type: string
          description: >
            Required sub-fields within an object-type field. Only sub-fields
            with

            unconditional required conditions are listed.
        items:
          $ref: '#/components/schemas/JsonSchemaProperty'
          description: >
            Schema for array element items. Present for:

            - FMV1 "Object List" fields, producing `{ type: 'array', items: {
            type: 'object', properties: ... } }`

            - Legacy MultiSelectField / AsyncMultiSelectField, producing `{
            type: 'array', items: { type: 'string', enum: [...], enumLabels:
            {...} } }`

            - Legacy GroupField, producing `{ type: 'array', items: { type:
            'object', properties: {...subfields} } }`
  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.

````