---
title: "Generate Reference Policy"
url: "https://apipartners.mosaicinsurance.com/apis/trident-sandbox-1/versions/063565b3-7d5d-4ebb-9e4e-ea5966a41579/operations/generatePolicyReference"
---

> Full API specification: https://apipartners.mosaicinsurance.com/apis/trident-sandbox-1/versions/063565b3-7d5d-4ebb-9e4e-ea5966a41579.md

# Generate Reference Policy

`POST` `/policy/generatereference`

Operation ID: `generatePolicyReference`

Generates a policy reference number by forwarding the request to the outbound-services-call API. Returns the generated policy reference along with policy keys and status. ## Required fields `insured`, `producer`, `product`, `underwriter`. ## Optional fields `mop`, `notes`, `policyyearnumber`, `policyyear`, `quote`. ## Lookup objects `insured`, `producer`, `product`, and `underwriter` accept `id` only. `mop` and `quote` accept `code` only.

## Header parameters

- `X-Origination-Source` (string, required) - Identifies the calling system or channel that originated this request. Used for traceability and auditing across the platform.
- `X-Audit-UserId` (string, required) - Identifier of the end user on whose behalf this request is made, recorded for audit trail purposes.

## Request body (required)

Content types: `application/json`

## Responses

- `200` - Policy reference generated successfully.
- `400` - Bad Request — request body is missing or invalid.
- `500` - Internal Server Error — unexpected system error.

## OpenAPI definition

```yaml
openapi: 3.0.1
info:
  title: Trident APIs
  version: dev
servers:
  - url: https://apinonprod.mosaicinsurance.com
    description: Generated server url
paths:
  /policy/generatereference:
    post:
      security:
        - api_key: []
      tags:
        - Policy
      summary: Generate Reference Policy
      description: >-
        Generates a policy reference number by forwarding the request to the
        outbound-services-call API. Returns the generated policy reference along
        with policy keys and status.


        ## Required fields


        `insured`, `producer`, `product`, `underwriter`.


        ## Optional fields


        `mop`, `notes`, `policyyearnumber`, `policyyear`, `quote`.


        ## Lookup objects


        `insured`, `producer`, `product`, and `underwriter` accept `id` only.
        `mop` and `quote` accept `code` only.
      operationId: generatePolicyReference
      parameters:
        - $ref: "#/components/parameters/XOriginationSource"
        - $ref: "#/components/parameters/XAuditUserId"
      requestBody:
        description: Policy reference generation payload.
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PolicyReferenceGenerationRequest"
            examples:
              Generate Policy Reference:
                summary: Generate a new policy reference
                value:
                  insured:
                    id: "4040940"
                  producer:
                    id: "4031515"
                  mop:
                    code: STD
                  notes: ""
                  policyyearnumber: "26"
                  policyyear: "26"
                  product:
                    id: "4"
                  underwriter:
                    id: "2001685"
        required: true
      responses:
        "200":
          description: Policy reference generated successfully.
          headers:
            Access-Control-Allow-Origin:
              schema:
                type: string
            Access-Control-Allow-Methods:
              schema:
                type: string
            Access-Control-Allow-Headers:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PolicyReferenceResponse"
              examples:
                Successful Response:
                  summary: Policy reference generated
                  value:
                    createdBy: 2000574
                    generatedReference: PCY2434926AA
                    insured: "3000211"
                    policyreferencekey: 646
                    policyYear: "26"
                    policyYearNumber: 26
                    producer: "2000987"
                    product: 4
                    underwriter: 2000310
        "400":
          description: Bad Request — request body is missing or invalid.
          headers:
            Access-Control-Allow-Origin:
              schema:
                type: string
            Access-Control-Allow-Methods:
              schema:
                type: string
            Access-Control-Allow-Headers:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                Missing Request Body:
                  summary: Request body is mandatory
                  value:
                    error:
                      code: XFI_VALIDATION_FAILED
                      message: Policy reference generation request is mandatory
        "500":
          description: Internal Server Error — unexpected system error.
          headers:
            Access-Control-Allow-Origin:
              schema:
                type: string
            Access-Control-Allow-Methods:
              schema:
                type: string
            Access-Control-Allow-Headers:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                Internal Server Error:
                  summary: Unexpected error
                  value:
                    error:
                      code: INTERNAL_ERROR
                      message: An unexpected error occurred while generating policy reference
security:
  - api_key: []
components:
  parameters:
    XOriginationSource:
      name: X-Origination-Source
      in: header
      required: true
      description: Identifies the calling system or channel that originated this
        request. Used for traceability and auditing across the platform.
      schema:
        type: string
      example: S01x
    XAuditUserId:
      name: X-Audit-UserId
      in: header
      required: true
      description: Identifier of the end user on whose behalf this request is made,
        recorded for audit trail purposes.
      schema:
        type: string
      example: jsmith
  schemas:
    PolicyReferenceGenerationRequest:
      type: object
      description: Request payload for generating a policy reference. Supply the
        insured, producer, product, and underwriter at minimum — all as `id`
        references.
      required:
        - insured
        - producer
        - mop
        - policyyearnumber
        - product
        - underwriter
      properties:
        insured:
          $ref: "#/components/schemas/IdReference"
          description: Insured contact — `id` only.
        producer:
          $ref: "#/components/schemas/IdReference"
          description: Producer (broker) — `id` only.
        mop:
          $ref: "#/components/schemas/CodeReference"
          description: MOP (Method of Placement) `code` only.
        notes:
          type: string
          description: Optional free-text notes for the policy reference.
          example: ""
        policyyearnumber:
          type: string
          description: Policy year number.
          example: "26"
        policyyear:
          type: string
          description: Policy year.
          example: "26"
        product:
          $ref: "#/components/schemas/IdReference"
          description: Product reference `id` only.
        quote:
          $ref: "#/components/schemas/CodeReference"
          description: Quote type `code` only (e.g. `Q`).
        underwriter:
          $ref: "#/components/schemas/IdReference"
          description: Underwriter reference `id` only.
    PolicyReferenceResponse:
      type: object
      description: Response returned after generating a policy reference. Contains the
        generated reference, associated keys, and input echo fields.
      properties:
        createdBy:
          type: integer
          format: int32
          description: Contact key of the user who created the reference.
          example: 2000574
        generatedReference:
          type: string
          description: The generated policy reference string.
          example: PCY2434926AA
        insured:
          type: string
          description: Insured contact id echoed from the request.
          example: "3000211"
        policyreferencekey:
          type: integer
          format: int32
          description: Internal policy reference key identifier.
          example: 646
        notes:
          type: string
          nullable: true
          description: Notes echoed from the request.
          example: ""
        policyYear:
          type: string
          description: Policy year echoed from the request.
          example: "26"
        policyYearNumber:
          type: integer
          format: int32
          description: Policy year number echoed from the request.
          example: 26
        producer:
          type: string
          description: Producer contact id echoed from the request.
          example: "2000987"
        product:
          type: integer
          format: int32
          description: Product identifier.
          example: 4
        underwriter:
          type: integer
          format: int32
          description: Underwriter contact key.
          example: 2000310
    ErrorResponse:
      type: object
      properties:
        error:
          $ref: "#/components/schemas/ErrorDetail"
    IdReference:
      type: object
      description: Reference to a lookup-backed entity identified by `id` (the XFI
        lookup id, environment-specific).
      required:
        - id
      additionalProperties: false
      properties:
        id:
          type: string
          description: XFI lookup id — the canonical identifier (environment-specific).
          example: "260"
    CodeReference:
      type: object
      description: Reference to a lookup-backed entity identified by `code` (the
        environment-stable business code).
      required:
        - code
      additionalProperties: false
      properties:
        code:
          type: string
    ErrorDetail:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
  securitySchemes:
    api_key:
      type: apiKey
      name: x-api-key
      in: header
```