> ## Documentation Index
> Fetch the complete documentation index at: https://developers.opereit.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a claim

> Submit a new claim and its associated shipment and incidence details. This kicks off Opereit's review process and prepares the necessary documentation.

If a shipment with the same `tracking_number` already exists in your organization (e.g. from a previous claim) and it doesn't have an open claim on it, the new claim is attached to that existing shipment record — the `origin`/`destination` you send in this request are only used the first time a shipment is created for that tracking number, and are ignored on later requests for the same tracking number.



## OpenAPI

````yaml POST /v1/claims
openapi: 3.1.0
info:
  title: Opereit API
  description: >-
    Public API for Opereit. Create and track carrier claims, upload carrier
    contracts, run audits against incoming carrier invoices, and retrieve line
    items and findings.
  version: 1.0.0
servers:
  - url: https://api.opereit.ai
    description: Production
security:
  - apiKey: []
paths:
  /v1/claims:
    post:
      summary: Create a claim
      description: >-
        Submit a new claim and its associated shipment and incidence details.
        This kicks off Opereit's review process and prepares the necessary
        documentation.


        If a shipment with the same `tracking_number` already exists in your
        organization (e.g. from a previous claim) and it doesn't have an open
        claim on it, the new claim is attached to that existing shipment record
        — the `origin`/`destination` you send in this request are only used the
        first time a shipment is created for that tracking number, and are
        ignored on later requests for the same tracking number.
      operationId: createClaim
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateClaimRequest'
      responses:
        '201':
          description: Claim created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClaimCreated'
        '400':
          $ref: '#/components/responses/ClaimInvalidBody'
        '401':
          $ref: '#/components/responses/ClaimUnauthorized'
        '409':
          $ref: '#/components/responses/ClaimConflict'
        '500':
          $ref: '#/components/responses/ClaimInternalError'
components:
  schemas:
    CreateClaimRequest:
      type: object
      required:
        - shipment
        - incidence
      properties:
        shipment:
          type: object
          required:
            - tracking_number
            - carrier
            - origin
            - destination
            - line_items
          properties:
            tracking_number:
              type: string
              minLength: 1
              description: >-
                The carrier's tracking number for this shipment. Used to detect
                duplicate claims — see the endpoint description above.
              example: 1Z999AA1234567890
            carrier:
              type: string
              enum:
                - BPOST
                - BRT
                - CHRONOPOST
                - CORREOS
                - CORREOS_EXPRESS
                - CTT
                - DPD
                - EVRI
                - FEDEX
                - GLS
                - INPOST
                - MAERSK
                - PAACK
                - PC_COMPONENTES
                - POSTAG
                - SEUR
                - UPS
              description: >-
                The carrier that shipped the parcel. Must be one of the listed
                values — an unrecognized carrier is rejected with `400
                INVALID_REQUEST_BODY`.
            provider:
              type: string
              description: >-
                Optional shipping platform/aggregator the shipment was booked
                through (e.g. a multi-carrier shipping tool), if different from
                the carrier. Known values: `BPOST`, `BRT`, `CHRONOPOST`,
                `CORREOS`, `CORREOS_EXPRESS`, `CTT`, `DPD`, `EVRI`, `FEDEX`,
                `GLS`, `INPOST`, `MAERSK`, `PAACK`, `PC_COMPONENTES`, `POSTAG`,
                `SENDCLOUD`, `SEUR`, `UPS`, `WING`.
            origin:
              type: object
              required:
                - postcode
                - country
              properties:
                postcode:
                  type: string
                  minLength: 1
                  description: Origin postcode.
                country:
                  type: string
                  minLength: 1
                  description: Origin country, ISO 3166-1 alpha-2.
            destination:
              type: object
              required:
                - postcode
                - country
                - city
                - address
                - customer_name
              properties:
                postcode:
                  type: string
                  minLength: 1
                  description: Destination postcode.
                country:
                  type: string
                  minLength: 1
                  description: Destination country, ISO 3166-1 alpha-2.
                city:
                  type: string
                  minLength: 1
                  description: Destination city.
                address:
                  type: string
                  minLength: 1
                  description: Destination street address.
                customer_name:
                  type: string
                  minLength: 1
                  description: Recipient's name.
                customer_phone:
                  type: string
                  minLength: 6
                  maxLength: 20
                  description: >-
                    Recipient's phone number. Optional; 6-20 characters when
                    provided.
            line_items:
              type: array
              minItems: 1
              description: >-
                Items in the shipment covered by this claim. At least one
                required.
              items:
                type: object
                required:
                  - description
                  - quantity
                  - unit_price
                  - currency
                properties:
                  description:
                    type: string
                    minLength: 1
                    description: Item description.
                  quantity:
                    type: integer
                    minimum: 1
                    description: Number of units.
                  unit_price:
                    type: integer
                    minimum: 1
                    description: >-
                      Price per unit, in the smallest currency unit (e.g.
                      cents).
                  currency:
                    type: string
                    minLength: 3
                    maxLength: 3
                    description: ISO 4217 currency code, e.g. `EUR`.
                    example: EUR
        incidence:
          type: object
          required:
            - type
            - claimed_amount
          properties:
            type:
              $ref: '#/components/schemas/IncidenceType'
            description:
              type: string
              description: Optional free-text narrative of what happened.
            claimed_amount:
              type: integer
              minimum: 1
              description: >-
                Total amount being claimed, in the smallest currency unit (e.g.
                cents).
            currency:
              type: string
              minLength: 3
              maxLength: 3
              default: EUR
              description: ISO 4217 currency code. Defaults to `EUR` if omitted.
    ClaimCreated:
      type: object
      description: The claim just created, as returned by the create-claim endpoint.
      required:
        - id
        - number
        - status
        - status_reason
        - date
        - carrier_id
        - created_at
        - updated_at
        - total_amount
        - shipment
        - incidence
      properties:
        id:
          type: string
          description: Unique claim ID.
        number:
          type:
            - string
            - 'null'
          description: >-
            Human-readable claim reference. `null` until assigned by the Opereit
            team.
        status:
          $ref: '#/components/schemas/ClaimStatus'
          description: Always `CREATED` on this response.
        status_reason:
          type: 'null'
          description: >-
            Always `null` on this response — a newly created claim starts at
            `CREATED`, which doesn't carry a status reason. See [Status
            reasons](/guides/claims#status-reasons).
        date:
          type: string
          format: date
          description: Date the claim was filed.
        carrier_id:
          type: string
        provider_id:
          type:
            - string
            - 'null'
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        total_amount:
          type: integer
          description: Equal to `incidence.claimed_amount`, in the smallest currency unit.
        shipment:
          type: object
          required:
            - id
            - tracking_number
            - carrier_id
            - created_at
            - origin
            - destination
            - line_items
          properties:
            id:
              type: string
            tracking_number:
              type: string
            carrier_id:
              type: string
            service_type:
              type:
                - string
                - 'null'
              description: >-
                Carrier service used. Currently always `STANDARD` for newly
                created shipments.
            shipped_at:
              type:
                - string
                - 'null'
              format: date-time
              description: >-
                For a shipment created by this request, equals the shipment's
                `created_at`. For a reused existing shipment (see the
                tracking-number note above), carries whatever was set when that
                shipment was first created.
            delivered_at:
              type:
                - string
                - 'null'
              format: date-time
              description: Same behavior as `shipped_at`.
            number_of_items:
              type:
                - integer
                - 'null'
              description: Total quantity across all submitted line items.
            created_at:
              type: string
              format: date-time
            origin:
              type: object
              properties:
                postcode:
                  type: string
                country:
                  type: string
              description: >-
                Reflects the shipment's stored origin. If the tracking number
                already had a shipment on file, this is the original origin, not
                necessarily what you sent in this request.
            destination:
              type: object
              properties:
                postcode:
                  type: string
                country:
                  type: string
                city:
                  type:
                    - string
                    - 'null'
                address:
                  type:
                    - string
                    - 'null'
                customer_name:
                  type:
                    - string
                    - 'null'
                  description: >-
                    Recipient's name, snake_case here (see
                    `Claim.shipment.destination.customerName` for the get-by-id
                    casing).
              description: >-
                Same caveat as `origin` above — reflects the stored shipment,
                which may predate this request.
            line_items:
              type: array
              items:
                type: object
                properties:
                  id:
                    type: string
                  description:
                    type: string
                  quantity:
                    type: integer
                  unit_price:
                    type: integer
                  total:
                    type: integer
        incidence:
          type: object
          required:
            - id
            - type
            - claimed_amount
            - currency
            - line_items
          properties:
            id:
              type: string
            type:
              $ref: '#/components/schemas/IncidenceType'
            description:
              type:
                - string
                - 'null'
            claimed_amount:
              type: integer
            recovered_amount:
              type:
                - integer
                - 'null'
            currency:
              type: string
            created_at:
              type: string
              format: date-time
            updated_at:
              type: string
              format: date-time
            line_items:
              type: array
              items:
                type: object
                properties:
                  id:
                    type: string
    IncidenceType:
      type: string
      enum:
        - DAMAGED
        - LOST
      description: What happened to the shipment.
    ClaimStatus:
      type: string
      enum:
        - CREATED
        - UNDER_REVIEW
        - PENDING_ACTION
        - PENDING_REFUND
        - PENDING_REFUND_AMOUNT_CONFIRMED
        - RESOLVED
        - CANCELED
        - REJECTED
        - CLOSED
      description: >-
        Current stage of the claim.


        - `CREATED`: claim created, not yet reviewed.

        - `UNDER_REVIEW`: being reviewed by the carrier.

        - `PENDING_ACTION`: action is required from Opereit's team before it can
        move forward.

        - `PENDING_REFUND`: a refund is being processed; amount not confirmed
        yet.

        - `PENDING_REFUND_AMOUNT_CONFIRMED`: refund amount confirmed, not paid
        yet.

        - `RESOLVED`: the claim has been resolved.

        - `CANCELED`: the claim was canceled.

        - `REJECTED`: the claim was rejected by the carrier.

        - `CLOSED`: the claim is closed.


        A claim is considered **closed** (no longer open) when it's `REJECTED`
        (for any reason), or `CANCELED` with a status reason of
        `CREATED_INCORRECTLY` or `SHIPMENT_NOT_CLAIMABLE_YET`. Any other status
        counts as open, and an open claim is what blocks a new claim on the same
        tracking number (see `POST /v1/claims`).
    ApiError:
      type: object
      description: Error envelope returned by every endpoint.
      required:
        - statusCode
        - statusReasonCode
        - error
      properties:
        statusCode:
          type: integer
          description: HTTP status code — same value as the response status.
        statusReasonCode:
          type: string
          enum:
            - INVALID_REQUEST_BODY
            - INVALID_QUERY_PARAMETERS
            - CLAIM_NOT_FOUND
            - CLAIM_ALREADY_EXISTS
            - CONTRACT_NOT_FOUND
            - INVOICE_AUDIT_NOT_FOUND
            - INTERNAL_ERROR
            - AUTHENTICATION_REQUIRED
            - INVALID_CREDENTIALS_FORMAT
            - INVALID_CREDENTIALS_ENCODING
            - INVALID_CREDENTIALS
          description: Machine-readable error code.
        error:
          type: string
          description: Human-readable error message.
        details:
          type: object
          description: >-
            Present on `400` responses. `formErrors` holds errors not tied to a
            specific field; `fieldErrors` maps a top-level request field to the
            list of validation messages raised under it.
          properties:
            formErrors:
              type: array
              items:
                type: string
            fieldErrors:
              type: object
              additionalProperties:
                type: array
                items:
                  type: string
  responses:
    ClaimInvalidBody:
      description: >-
        The request body failed validation. `details.fieldErrors` is keyed by
        the top-level field (`shipment` or `incidence`) — it does not drill into
        which nested property failed, so a single key can carry more than one
        message.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
          example:
            statusCode: 400
            statusReasonCode: INVALID_REQUEST_BODY
            error: Invalid request body
            details:
              formErrors: []
              fieldErrors:
                shipment:
                  - >-
                    Invalid option: expected one of
                    "BPOST"|"BRT"|"CHRONOPOST"|...|"UPS"
                incidence:
                  - >-
                    Claimed amount must be a positive integer (smallest currency
                    unit)
    ClaimUnauthorized:
      description: >-
        Authentication is missing or invalid. Also returned as
        `WWW-Authenticate: Basic realm="Opereit API"` on the response headers.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
          example:
            statusCode: 401
            statusReasonCode: AUTHENTICATION_REQUIRED
            error: Authentication required
    ClaimConflict:
      description: An open claim already exists for this shipment's tracking number.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
          example:
            statusCode: 409
            statusReasonCode: CLAIM_ALREADY_EXISTS
            error: >-
              An open claim already exists for shipment 1Z999AA1234567890.
              Please contact Opereit support if you want to fix the previous
              claim.
    ClaimInternalError:
      description: Unexpected server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
          example:
            statusCode: 500
            statusReasonCode: INTERNAL_ERROR
            error: Internal server error
  securitySchemes:
    apiKey:
      type: http
      scheme: basic
      description: >-
        HTTP Basic Auth using your API key. Send `Authorization: Basic
        base64(key_id:key_secret)`.

````