> ## 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. # List claims > Returns a cursor-paginated list of claims for your organization, ordered by internal ID ascending (oldest first). ## OpenAPI ````yaml GET /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: get: summary: List claims description: >- Returns a cursor-paginated list of claims for your organization, ordered by internal ID ascending (oldest first). operationId: listClaims parameters: - $ref: '#/components/parameters/Limit' - $ref: '#/components/parameters/Cursor' - name: status in: query description: Filter by claim status. schema: $ref: '#/components/schemas/ClaimStatus' - name: carrierId in: query description: Filter by carrier ID (e.g. `ups`, `fedex`). schema: type: string - name: trackingNumber in: query description: Filter by the shipment's carrier tracking number. schema: type: string - name: fromDate in: query description: >- Return claims with a claim date on or after this date. Format `YYYY-MM-DD`. schema: type: string format: date - name: toDate in: query description: >- Return claims with a claim date on or before this date. Format `YYYY-MM-DD`. schema: type: string format: date responses: '200': description: Cursor-paginated list of claims. content: application/json: schema: type: object required: - data - pagination properties: data: type: array items: $ref: '#/components/schemas/ClaimListItem' pagination: $ref: '#/components/schemas/ClaimsCursorPagination' '400': $ref: '#/components/responses/ClaimInvalidQuery' '401': $ref: '#/components/responses/ClaimUnauthorized' '500': $ref: '#/components/responses/ClaimInternalError' components: parameters: Limit: name: limit in: query description: Number of items to return per request. schema: type: integer minimum: 1 maximum: 100 default: 50 Cursor: name: cursor in: query description: Opaque cursor from a previous response. Omit on the first request. schema: type: string schemas: 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`). ClaimListItem: type: object description: >- A claim as returned by the list endpoint. Note this uses camelCase field names, unlike the create and get-by-id endpoints below which use snake_case. required: - id - claimNumber - claimDate - status - statusReason - openedWith - createdAt - updatedAt - carrierId - totalAmount - aging - carrier properties: id: type: string description: Unique claim ID. claimNumber: type: - string - 'null' description: Human-readable claim reference number, if assigned. claimDate: type: string format: date description: Date the claim was filed. status: $ref: '#/components/schemas/ClaimStatus' statusReason: oneOf: - $ref: '#/components/schemas/ClaimStatusReason' - type: 'null' description: >- Set when `status` is `PENDING_ACTION`, `CANCELED`, or `REJECTED`. `null` for every other status. openedWith: type: - string - 'null' description: Channel or system through which the claim was opened. createdAt: type: string format: date-time description: When the record was created. updatedAt: type: string format: date-time description: When the record was last updated. carrierId: type: string description: ID of the carrier associated with the claim. providerId: type: string description: ID of the provider associated with the claim, if any. totalAmount: type: number description: Total claimed amount, in the smallest currency unit. aging: type: integer description: Number of days since the claim date. currency: type: string description: >- ISO 4217 currency code. May be absent if not set on the underlying incidence. carrier: type: object required: - id - name properties: id: type: string name: type: string provider: type: object description: Present only when the shipment has a provider set. required: - id - name properties: id: type: string name: type: string shipment: oneOf: - type: object required: - id - trackingNumber properties: id: type: string trackingNumber: type: string destinationCustomerName: type: - string - 'null' destinationCountry: type: - string - 'null' description: ISO 3166-1 alpha-2 country code. - type: 'null' description: Associated shipment summary. `null` if no shipment is linked. ClaimsCursorPagination: type: object required: - cursor - hasMore properties: cursor: type: - string - 'null' description: >- Opaque cursor to pass as `cursor` in the next request. `null` when there are no more pages. hasMore: type: boolean description: Whether there are more results beyond this page. ClaimStatusReason: type: object description: Additional detail on why the claim is in its current status. required: - id - slug - label properties: id: type: string description: Unique ID of this status reason. slug: $ref: '#/components/schemas/ClaimStatusReasonSlug' label: type: string description: Human-readable label for the reason. example: Missing Product Information 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 ClaimStatusReasonSlug: type: string enum: - MISSING_PRODUCT_INFORMATION - CLAIM_ALREADY_EXISTS - TIME_EXCEEDED - CLAIM_VOIDED_BY_CARRIER - DELIVERED_BY_CARRIER - CUSTOMS_HOLD_UNKNOWN - CUSTOMS_HOLD_AWAITING_PAYMENT - SHIPMENT_NOT_SENT - SHIPMENT_NOT_CLAIMABLE_YET - NOT_ABLE_TO_CONTACT_DESTINATARY - PACKAGE_AT_ACCESSPOINT - PENDING_UPLOAD_DOCUMENTS - UPDATE_ITEMS_INFORMATION - RESTRICTED_ACCOUNT_VIEW - TRACKING_REVIEW_REQUIRED - CREATED_INCORRECTLY - AI_COULD_NOT_CLASSIFY_EMAIL_REPLY - CUSTOMER_ACTION_REQUIRED_DAMAGE_PROOF - CUSTOMER_ACTION_REQUIRED_AFFIDAVIT - CUSTOMER_ACTION_REQUIRED_REFUND_CONFIRMATION description: >- Machine-readable reason the claim is in its current status. See [Status reasons](/guides/claims#status-reasons) for what each one means and which claim status it can appear under. responses: ClaimInvalidQuery: description: >- A query parameter failed validation, such as an unrecognized `status` value or a `limit` outside the allowed range. content: application/json: schema: $ref: '#/components/schemas/ApiError' example: statusCode: 400 statusReasonCode: INVALID_QUERY_PARAMETERS error: Invalid query parameters details: formErrors: [] fieldErrors: status: - >- Invalid option: expected one of "CREATED"|"UNDER_REVIEW"|"PENDING_ACTION"|"PENDING_REFUND"|"PENDING_REFUND_AMOUNT_CONFIRMED"|"RESOLVED"|"CANCELED"|"REJECTED"|"CLOSED" 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 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)`. ````