openapi: 3.0.3
info:
  title: Allianz Trade Claims Policy API
  description: Access and manage all insurance claims declared to Allianz Trade from within your ERP system. Retrieve claim status, submit new claims, and track claim progression for trade credit insurance policies.
  version: 1.0.0
  contact:
    name: Allianz Trade API Support
    email: api@allianz-trade.com
    url: https://developers.allianz-trade.com/
  x-generated-from: documentation
servers:
- url: https://api.allianz-trade.com/v1
  description: Allianz Trade API production server
security:
- OAuth2: []
tags:
- name: Policy
  description: Trade credit insurance policy management operations
paths:
  /policies:
    get:
      operationId: listPolicies
      summary: Allianz Trade List Policies
      description: Retrieve a paginated list of trade credit insurance policies in your portfolio.
      tags:
      - Policy
      parameters:
      - name: pageSize
        in: query
        required: false
        description: Number of items per page (Allianz Trade pagination standard)
        schema:
          type: integer
          default: 20
          minimum: 1
          maximum: 100
        example: 20
      - name: page
        in: query
        required: false
        description: Page number starting from 1
        schema:
          type: integer
          default: 1
          minimum: 1
        example: 1
      - name: totalRequired
        in: query
        required: false
        description: Whether to include total count in response headers
        schema:
          type: boolean
          default: false
        example: false
      - name: policyStatus
        in: query
        required: false
        description: Filter by policy status
        schema:
          type: string
          enum:
          - active
          - suspended
          - expired
          - cancelled
        example: active
      responses:
        '200':
          description: Policies retrieved successfully
          headers:
            Total-Items:
              description: Total number of policies (when totalRequired=true)
              schema:
                type: integer
            Total-Pages:
              description: Total number of pages (when totalRequired=true)
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PolicyList'
              examples:
                ListPolicies200Example:
                  summary: Default listPolicies 200 response
                  x-microcks-default: true
                  value:
                    data:
                    - policyId: POL-500123
                      policyNumber: TC-2026-001
                      policyHolderName: Your Company SAS
                      policyType: trade_credit
                      policyStatus: active
                      currency: EUR
                      maxCoverageAmount: 5000000.0
                      startDate: '2026-01-01'
                      endDate: '2026-12-31'
        '401':
          description: Unauthorized - invalid or missing OAuth2 token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden - insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /policies/{policyId}:
    get:
      operationId: getPolicy
      summary: Allianz Trade Get Policy
      description: Retrieve full details for a specific trade credit insurance policy by its identifier.
      tags:
      - Policy
      parameters:
      - name: policyId
        in: path
        required: true
        description: Unique identifier of the policy
        schema:
          type: string
        example: POL-500123
      responses:
        '200':
          description: Policy retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Policy'
              examples:
                GetPolicy200Example:
                  summary: Default getPolicy 200 response
                  x-microcks-default: true
                  value:
                    policyId: POL-500123
                    policyNumber: TC-2026-001
                    policyHolderName: Your Company SAS
                    policyType: trade_credit
                    policyStatus: active
                    currency: EUR
                    maxCoverageAmount: 5000000.0
                    coveragePercentage: 90
                    startDate: '2026-01-01'
                    endDate: '2026-12-31'
                    country: FR
                    createdAt: '2025-12-01T10:00:00Z'
        '404':
          description: Policy not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /policies/{policyId}/joint-insureds:
    get:
      operationId: listJointInsureds
      summary: Allianz Trade List Joint Insureds
      description: Retrieve joint insured entities registered under a policy.
      tags:
      - Policy
      parameters:
      - name: policyId
        in: path
        required: true
        description: Unique identifier of the policy
        schema:
          type: string
        example: POL-500123
      - name: pageSize
        in: query
        required: false
        schema:
          type: integer
          default: 20
          minimum: 1
          maximum: 100
        example: 20
      - name: page
        in: query
        required: false
        schema:
          type: integer
          default: 1
          minimum: 1
        example: 1
      - name: totalRequired
        in: query
        required: false
        schema:
          type: boolean
          default: false
        example: false
      responses:
        '200':
          description: Joint insureds retrieved successfully
          headers:
            Total-Items:
              description: Total number of joint insureds (when totalRequired=true)
              schema:
                type: integer
            Total-Pages:
              description: Total number of pages (when totalRequired=true)
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JointInsuredList'
              examples:
                ListJointInsureds200Example:
                  summary: Default listJointInsureds 200 response
                  x-microcks-default: true
                  value:
                    data:
                    - jointInsuredId: JI-500123
                      policyId: POL-500123
                      companyName: Subsidiary Corp SAS
                      registrationNumber: FR987654321
                      country: FR
                      status: active
        '404':
          description: Policy not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: addJointInsured
      summary: Allianz Trade Add Joint Insured
      description: Add a joint insured entity to a trade credit insurance policy.
      tags:
      - Policy
      parameters:
      - name: policyId
        in: path
        required: true
        description: Unique identifier of the policy
        schema:
          type: string
        example: POL-500123
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddJointInsuredRequest'
            examples:
              AddJointInsuredRequestExample:
                summary: Default addJointInsured request
                x-microcks-default: true
                value:
                  companyName: Subsidiary Corp SAS
                  registrationNumber: FR987654321
                  country: FR
      responses:
        '202':
          description: Joint insured addition accepted for processing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobResponse'
              examples:
                AddJointInsured202Example:
                  summary: Default addJointInsured 202 response
                  x-microcks-default: true
                  value:
                    jobId: JOB-500789
                    status: pending
                    createdAt: '2026-04-19T10:30:00Z'
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /jobs/{jobId}:
    get:
      operationId: getJobStatus
      summary: Allianz Trade Get Job Status
      description: Poll for the status of an asynchronous policy operation.
      tags:
      - Policy
      parameters:
      - name: jobId
        in: path
        required: true
        description: Unique identifier of the async job
        schema:
          type: string
        example: JOB-500789
      responses:
        '200':
          description: Job status retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobResponse'
              examples:
                GetJobStatus200Example:
                  summary: Default getJobStatus 200 response
                  x-microcks-default: true
                  value:
                    jobId: JOB-500789
                    status: processed
                    result:
                      jointInsuredId: JI-500123
                    createdAt: '2026-04-19T10:30:00Z'
                    completedAt: '2026-04-19T10:31:00Z'
        '404':
          description: Job not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    AddJointInsuredRequest:
      title: AddJointInsuredRequest
      type: object
      description: Request body for adding a joint insured to a policy
      required:
      - companyName
      - country
      properties:
        companyName:
          type: string
          description: Legal name of the company to add as joint insured
          example: Subsidiary Corp SAS
        registrationNumber:
          type: string
          description: Company registration number
          example: FR987654321
        country:
          type: string
          description: ISO 3166-1 alpha-2 country code
          example: FR
    JobResponse:
      title: JobResponse
      type: object
      description: Async job status response
      properties:
        jobId:
          type: string
          description: Unique identifier for the async job
          example: JOB-500789
        status:
          type: string
          description: Current status of the job
          enum:
          - pending
          - processed
          - failed
          example: processed
        result:
          type: object
          description: Result data after successful job completion
          example:
            jointInsuredId: JI-500123
        createdAt:
          type: string
          format: date-time
          description: When the job was created
          example: '2026-04-19T10:30:00Z'
        completedAt:
          type: string
          format: date-time
          description: When the job completed (null if still pending)
          example: '2026-04-19T10:31:00Z'
    Policy:
      title: Policy
      type: object
      description: A trade credit insurance policy from Allianz Trade
      properties:
        policyId:
          type: string
          description: Unique identifier for the policy
          example: POL-500123
        policyNumber:
          type: string
          description: Official Allianz Trade policy number
          example: TC-2026-001
        policyHolderName:
          type: string
          description: Legal name of the policy holder
          example: Your Company SAS
        policyType:
          type: string
          description: Type of trade credit insurance policy
          enum:
          - trade_credit
          - surety
          - ecommerce_b2b
          example: trade_credit
        policyStatus:
          type: string
          description: Current status of the policy
          enum:
          - active
          - suspended
          - expired
          - cancelled
          example: active
        currency:
          type: string
          description: ISO 4217 policy currency code
          example: EUR
        maxCoverageAmount:
          type: number
          format: double
          description: Maximum total coverage amount under the policy
          example: 5000000.0
        coveragePercentage:
          type: integer
          description: Percentage of loss covered by the policy
          minimum: 0
          maximum: 100
          example: 90
        startDate:
          type: string
          format: date
          description: Policy start date
          example: '2026-01-01'
        endDate:
          type: string
          format: date
          description: Policy end date
          example: '2026-12-31'
        country:
          type: string
          description: ISO 3166-1 alpha-2 country code for the policy
          example: FR
        createdAt:
          type: string
          format: date-time
          description: Timestamp when the policy was created
          example: '2025-12-01T10:00:00Z'
    PolicyList:
      title: PolicyList
      type: object
      description: Paginated list of trade credit insurance policies
      properties:
        data:
          type: array
          description: List of policy records
          items:
            $ref: '#/components/schemas/Policy'
    ErrorResponse:
      title: ErrorResponse
      type: object
      description: Standard error response
      properties:
        code:
          type: string
          description: Error code
          example: INVALID_REQUEST
        message:
          type: string
          description: Human-readable error description
          example: The policyId is required
        requestId:
          type: string
          description: Request identifier for support reference
          example: req-500999
    JointInsuredList:
      title: JointInsuredList
      type: object
      description: Paginated list of joint insured entities
      properties:
        data:
          type: array
          description: List of joint insured records
          items:
            $ref: '#/components/schemas/JointInsured'
    JointInsured:
      title: JointInsured
      type: object
      description: A joint insured entity registered under a policy
      properties:
        jointInsuredId:
          type: string
          description: Unique identifier for the joint insured
          example: JI-500123
        policyId:
          type: string
          description: Parent policy identifier
          example: POL-500123
        companyName:
          type: string
          description: Legal name of the joint insured company
          example: Subsidiary Corp SAS
        registrationNumber:
          type: string
          description: Company registration number
          example: FR987654321
        country:
          type: string
          description: ISO 3166-1 alpha-2 country code
          example: FR
        status:
          type: string
          description: Current status of the joint insured
          enum:
          - active
          - inactive
          example: active
  securitySchemes:
    OAuth2:
      type: oauth2
      description: OAuth2 client credentials for Allianz Trade API access
      flows:
        clientCredentials:
          tokenUrl: https://api.allianz-trade.com/oauth2/token
          scopes:
            claims:read: Read insurance claims
            claims:write: Submit and manage insurance claims