---
title: "List document checks across shipments"
method: GET
path: "/checks"
tags: ["Alerts and checks"]
---

# List document checks across shipments

`GET /checks`

## Request

- Base URL: `https://trackberry.com/api/v1`
- URL: `https://trackberry.com/api/v1/checks`
- Auth: HTTP bearer

Use this to find paperwork and data problems: missing documents, packing list totals that disagree with the declared ones, invalid container numbers, and similar. By default only checks that failed or warned are listed; pass `status` to see others. Across all shipments (archived ones included), newest first, keyset paged. Pass `shipment` to look at one shipment.

## Query parameters

- `status` string[]
- `shipment` string
- `limit` integer
- `starting_after` string

## Headers

- `Trackberry-Version` string

## Response `200`

A page of checks, newest first.

- object: The envelope every list endpoint returns.
  - `object` 'list', required: Always `list`.
  - `data` object[], required: The items of this page, in the order the endpoint documents. Each item is an object of the kind the endpoint returns.
    - `object` 'shipment_check', required: Always `shipment_check`.
    - `id` string, required: The check result id.
    - `shipment_id` string, required: The shipment the check ran against.
    - `shipment_reference` string, required: That shipment's Trackberry reference.
    - `key` string, required: The stable identifier of the check, for example `has_packing_list`, `packing_list_box_count` or `invoice_total`. New keys may be added.
    - `category` 'documents' | 'data_integrity' | 'data_completeness' | 'null', nullable, required: The kind of problem the check looks for. `documents` means a required document is missing; `data_integrity` means figures that should agree do not; `data_completeness` means a needed value is missing from a document. Null if the check no longer exists.
    - `status` 'pending' | 'passed' | 'failed' | 'skipped' | 'warning', required: The outcome. `pending` has not run yet; `passed` is fine; `failed` means something is wrong; `skipped` means its preconditions were not met; `warning` means it passed with a caveat.
    - `title` string, required: A short English name for this result.
    - `message` string, nullable, required: An English sentence explaining the outcome. Null when the check has not produced one.
    - `ran_at` string, date-time, nullable, required: When the check last ran. Null if it never ran.
  - `has_more` boolean, required: True when more items exist after this page. Pass the last item's `id` as `starting_after` to fetch them. Always false for unpaged lists.

## Other responses

- `400`: A parameter or header is invalid (`invalid_parameter`, with `param` naming it), a customer link cannot be made for this shipment (`not_shareable`), an uploaded file is empty, over 50 MB or of a type Trackberry does not read (`file_empty`, `file_too_large`, `unsupported_file_type`), an upload's container number is on more than one live shipment (`ambiguous_container`), an `Idempotency-Key` was already used for a different request (`idempotency_key_reused`) or `Trackberry-Version` names an unpublished version (`invalid_version`, with `param` set to `Trackberry-Version`). A parameter that must be a single value but was sent as an array or hash (`status[]=x`, `q[a]=1`) is also a 400.
- `401`: No token was sent (`missing_token`) or the token is wrong, expired, revoked, or its user left the organization (`invalid_token`). The response has a `WWW-Authenticate` header.
- `403`: The token may not do this. `insufficient_scope`: a write endpoint was called with a read-only token. `read_only_member`: a write endpoint was called by a token whose owner is now a read-only member of the organization. `revoke_not_allowed`: the link can only be revoked by an admin or by the member who made it. `billing_blocked`: an upload needed a new shipment and the organization's billing does not allow one.
- `429`: A rate limit was hit (`rate_limited`). Wait the number of seconds in `Retry-After`. A BI feed answers the same way (`feed_in_progress`) when another feed for the organization is still being produced.

---

[API](https://skmtc.dev/trackberry/apis/trackberry-api.md) · [All operations](https://skmtc.dev/trackberry/apis/trackberry-api/llms.txt) · [OpenAPI document](https://skmtc.dev/trackberry/apis/trackberry-api/revisions/be06ee7c17f3?raw)