openapi: 3.1.0
info:
  title: ACORD Next-Generation Digital Standards (NGDS) Claims Policy API
  description: The ACORD NGDS API provides granular, transaction-centric REST/JSON standards for insurance data exchange covering underwriting, policy management, and claims administration. Based on the ACORD Object Model with JSON and YAML formats for microservices, IoT, and modern API architectures.
  version: 1.0.0
  contact:
    name: ACORD Standards
    url: https://www.acord.org/standards-architecture/acord-data-standards
  license:
    name: ACORD License
    url: https://www.acord.org
servers:
- url: https://api.insurer-internal.example.com/ngds
  description: NGDS REST API endpoint
security:
- oauth2: []
- bearerAuth: []
tags:
- name: Policy
  description: Policy administration and management
paths:
  /policies:
    get:
      operationId: listPolicies
      summary: ACORD List Policies
      description: Retrieve a paginated list of insurance policies matching the given filters.
      tags:
      - Policy
      parameters:
      - name: policyNumber
        in: query
        description: Filter by policy number
        schema:
          type: string
      - name: insuredPartyId
        in: query
        description: Filter by insured party identifier
        schema:
          type: string
      - name: lineOfBusiness
        in: query
        description: Filter by line of business (e.g., PropertyCasualty, Life, Annuity)
        schema:
          type: string
          enum:
          - PropertyCasualty
          - Life
          - Annuity
          - Reinsurance
      - name: status
        in: query
        description: Filter by policy status
        schema:
          type: string
          enum:
          - Active
          - Lapsed
          - Cancelled
          - Pending
          - Expired
      - name: page
        in: query
        schema:
          type: integer
          default: 1
      - name: pageSize
        in: query
        schema:
          type: integer
          default: 25
          maximum: 100
      responses:
        '200':
          description: Paginated list of policies
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PolicyList'
              examples:
                ListPolicies200Example:
                  summary: Default listPolicies 200 response
                  x-microcks-default: true
                  value:
                    data:
                    - {}
                    pagination:
                      page: {}
                      pageSize: {}
                      totalPages: {}
                      totalItems: {}
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: createPolicy
      summary: ACORD Create a New Policy
      description: Submit a new insurance policy for underwriting and issuance using ACORD NGDS data model.
      tags:
      - Policy
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PolicyRequest'
            examples:
              CreatePolicyRequestExample:
                summary: Default createPolicy request
                x-microcks-default: true
                value:
                  lineOfBusiness: PropertyCasualty
                  effectiveDate: '2025-03-15'
                  expirationDate: '2025-03-15'
                  premiumAmount: 5000.0
                  currency: sample-value
                  insuredParty:
                    partyType: {}
                    firstName: {}
                    lastName: {}
                    organizationName: {}
                    taxId: {}
                    address: {}
                    contacts: {}
                  coverages:
                  - {}
      responses:
        '201':
          description: Policy created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Policy'
              examples:
                CreatePolicy201Example:
                  summary: Default createPolicy 201 response
                  x-microcks-default: true
                  value:
                    policyId: '500123'
                    policyNumber: POL-2025-001234
                    lineOfBusiness: PropertyCasualty
                    status: Active
                    effectiveDate: '2025-03-15'
                    expirationDate: '2025-03-15'
                    premiumAmount: 5000.0
                    currency: sample-value
                    insuredParty:
                      partyId: {}
                      partyType: {}
                      firstName: {}
                      lastName: {}
                      organizationName: {}
                      taxId: {}
                      address: {}
                      contacts: {}
                    coverages:
                    - {}
                    createdAt: '2025-03-15T14:30:00Z'
                    updatedAt: '2025-03-15T14:30:00Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /policies/{policyId}:
    get:
      operationId: getPolicy
      summary: ACORD Get Policy by ID
      description: Retrieve a single insurance policy and all associated coverage details by policy identifier.
      tags:
      - Policy
      parameters:
      - name: policyId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Policy details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Policy'
              examples:
                GetPolicy200Example:
                  summary: Default getPolicy 200 response
                  x-microcks-default: true
                  value:
                    policyId: '500123'
                    policyNumber: POL-2025-001234
                    lineOfBusiness: PropertyCasualty
                    status: Active
                    effectiveDate: '2025-03-15'
                    expirationDate: '2025-03-15'
                    premiumAmount: 5000.0
                    currency: sample-value
                    insuredParty:
                      partyId: {}
                      partyType: {}
                      firstName: {}
                      lastName: {}
                      organizationName: {}
                      taxId: {}
                      address: {}
                      contacts: {}
                    coverages:
                    - {}
                    createdAt: '2025-03-15T14:30:00Z'
                    updatedAt: '2025-03-15T14:30:00Z'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    patch:
      operationId: updatePolicy
      summary: ACORD Update Policy
      description: Apply endorsements or amendments to an existing policy using ACORD NGDS change transactions.
      tags:
      - Policy
      parameters:
      - name: policyId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PolicyUpdate'
            examples:
              UpdatePolicyRequestExample:
                summary: Default updatePolicy request
                x-microcks-default: true
                value:
                  status: Active
                  expirationDate: '2025-03-15'
                  premiumAmount: 5000.0
                  endorsements:
                  - endorsementNumber: {}
                    description: {}
                    effectiveDate: {}
      responses:
        '200':
          description: Policy updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Policy'
              examples:
                UpdatePolicy200Example:
                  summary: Default updatePolicy 200 response
                  x-microcks-default: true
                  value:
                    policyId: '500123'
                    policyNumber: POL-2025-001234
                    lineOfBusiness: PropertyCasualty
                    status: Active
                    effectiveDate: '2025-03-15'
                    expirationDate: '2025-03-15'
                    premiumAmount: 5000.0
                    currency: sample-value
                    insuredParty:
                      partyId: {}
                      partyType: {}
                      firstName: {}
                      lastName: {}
                      organizationName: {}
                      taxId: {}
                      address: {}
                      contacts: {}
                    coverages:
                    - {}
                    createdAt: '2025-03-15T14:30:00Z'
                    updatedAt: '2025-03-15T14:30:00Z'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    Coverage:
      type: object
      properties:
        coverageId:
          type: string
        coverageType:
          type: string
        limit:
          type: number
        deductible:
          type: number
        premium:
          type: number
        currency:
          type: string
    Policy:
      type: object
      description: ACORD NGDS Policy object representing an insurance contract
      properties:
        policyId:
          type: string
          description: Unique internal policy identifier
        policyNumber:
          type: string
          description: Carrier-assigned policy number
        lineOfBusiness:
          type: string
          enum:
          - PropertyCasualty
          - Life
          - Annuity
          - Reinsurance
        status:
          type: string
          enum:
          - Active
          - Lapsed
          - Cancelled
          - Pending
          - Expired
        effectiveDate:
          type: string
          format: date
        expirationDate:
          type: string
          format: date
        premiumAmount:
          type: number
          format: double
        currency:
          type: string
          default: USD
        insuredParty:
          $ref: '#/components/schemas/Party'
        coverages:
          type: array
          items:
            $ref: '#/components/schemas/Coverage'
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    Party:
      type: object
      properties:
        partyId:
          type: string
        partyType:
          type: string
          enum:
          - Insured
          - Claimant
          - Agent
          - Broker
          - Carrier
        firstName:
          type: string
        lastName:
          type: string
        organizationName:
          type: string
        taxId:
          type: string
        address:
          $ref: '#/components/schemas/Address'
        contacts:
          type: array
          items:
            $ref: '#/components/schemas/Contact'
    CoverageRequest:
      type: object
      required:
      - coverageType
      - limit
      properties:
        coverageType:
          type: string
        limit:
          type: number
        deductible:
          type: number
        premium:
          type: number
        currency:
          type: string
          default: USD
    PolicyList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Policy'
        pagination:
          $ref: '#/components/schemas/Pagination'
    PolicyUpdate:
      type: object
      properties:
        status:
          type: string
          enum:
          - Active
          - Lapsed
          - Cancelled
          - Pending
          - Expired
        expirationDate:
          type: string
          format: date
        premiumAmount:
          type: number
        endorsements:
          type: array
          items:
            type: object
            properties:
              endorsementNumber:
                type: string
              description:
                type: string
              effectiveDate:
                type: string
                format: date
    Pagination:
      type: object
      properties:
        page:
          type: integer
        pageSize:
          type: integer
        totalPages:
          type: integer
        totalItems:
          type: integer
    Address:
      type: object
      properties:
        street1:
          type: string
        street2:
          type: string
        city:
          type: string
        state:
          type: string
        postalCode:
          type: string
        country:
          type: string
          default: US
    Error:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
        details:
          type: array
          items:
            type: string
    Contact:
      type: object
      properties:
        contactType:
          type: string
          enum:
          - Phone
          - Email
          - Fax
        value:
          type: string
    PartyRequest:
      type: object
      required:
      - partyType
      properties:
        partyType:
          type: string
          enum:
          - Insured
          - Claimant
          - Agent
          - Broker
          - Carrier
        firstName:
          type: string
        lastName:
          type: string
        organizationName:
          type: string
        taxId:
          type: string
        address:
          $ref: '#/components/schemas/Address'
        contacts:
          type: array
          items:
            $ref: '#/components/schemas/Contact'
    PolicyRequest:
      type: object
      required:
      - lineOfBusiness
      - effectiveDate
      - expirationDate
      - insuredParty
      properties:
        lineOfBusiness:
          type: string
          enum:
          - PropertyCasualty
          - Life
          - Annuity
          - Reinsurance
        effectiveDate:
          type: string
          format: date
        expirationDate:
          type: string
          format: date
        premiumAmount:
          type: number
          format: double
        currency:
          type: string
          default: USD
        insuredParty:
          $ref: '#/components/schemas/PartyRequest'
        coverages:
          type: array
          items:
            $ref: '#/components/schemas/CoverageRequest'
  responses:
    Forbidden:
      description: Forbidden - insufficient permissions
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Unauthorized - missing or invalid authentication
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: Bad request - invalid input data
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://auth.insurer-internal.example.com/oauth/token
          scopes:
            read:policies: Read policy data
            write:policies: Create and modify policies
            read:claims: Read claim data
            write:claims: Submit and update claims
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT