During the execution of a customs flow, documents are created. These documents are referred to as Declarations in CAS. They can be retrieved through the Get declaration endpoint. The most efficient way to retrieve a declaration is by the unique ID received through a webhook event as described in Notifications. However, it is also possible to search for a declaration based on a number of criteria (e.g. your own reference for the customs shipment externalReference) by using the Search declarations endpoint.

Scope: read:declarations for all retrieval and search endpoints, create:messages for the PATCH update endpoint.

Search parameters

The Search declarations endpoint accepts the following query parameters to filter results:

For array parameters (e.g. currentStatus, customsFlowStep), provide multiple values by repeating the parameter: ?currentStatus=Released&currentStatus=Accepted.

Pagination

Search results are paginated using limit and offset parameters:

• limit controls how many results to return per page (default and maximum: 100)
• offset controls how many results to skip (default: 0, must be divisible by limit)

Example: Iterating through all results

First page:  GET /v1/declarations/search?externalReference=MY-REF&limit=50&offset=0
Second page: GET /v1/declarations/search?externalReference=MY-REF&limit=50&offset=50
Third page:  GET /v1/declarations/search?externalReference=MY-REF&limit=50&offset=100

When the number of results returned is fewer than the limit, you have reached the last page.

Including additional data

When retrieving a single declaration via GET /v1/declarations/{declarationId}, you can request additional data using the include query parameter:

• ?include=errors -- Includes validation and customs errors in the response (the errors array)
• ?include=attachments -- Includes attachment metadata in the response (the attachments array)

Both can be combined: ?include=errors,attachments or ?include=errors&include=attachments.

Errors

When the declaration is in an Invalid or CustomsError status you can find the errors in the response data under the errors field (make sure to include ?include=errors).

For example, when you send in data like (JSON fragment)

{
  "singleAdministrativeDocument": {
    "declType": "IM",
    "addDeclType": "A",
    "additionalDocuments": [
      {
        "category": "N",
        "refNum": "SDoc1",
        "type": "380"
      }
   	],
    "agentStatus": "2",
    "declarationOfficeCode": "NL000567",
    "invoiceCurrency": "EUR",
    "agent": {
      "businessPartnerReference": [
        {
          "code": "NL100004337",
          "type": "Eori"
        }
      ]
    }
  }
}

you can get a validation error like (JSON fragment)

{
  "errors": [
    {
      "errorCode": "V0010",
      "message": "Invalid additional declaration type",
      "description": "SingleAdministrativeDocument.AddDeclType must be of type 'D'",
      "fieldReference": [
        {
          "fieldName": "AddDeclType1",
          "path": "SingleAdministrativeDocument"
        }
      ]
    }
  ]
}

Attachments

Declaration attachments (e.g. PDF documents like EAD, TSAD) can be downloaded using two sets of endpoints. Both return time-limited download URLs, but they differ in when you would use them.

Retrieving attachments by attachment ID

Use these endpoints when you already have an attachmentId, for example from the declaration detail response.

• GET /v1/declarations/{declarationId}/attachments/{attachmentId} -- Returns a 307 redirect to a time-limited download URL. Your HTTP client must follow redirects automatically.
• GET /v1/declarations/{declarationId}/attachments/{attachmentId}/url -- Returns a JSON response containing the temporary download URL without redirecting. Use this if your HTTP client does not support automatic redirects.

Retrieving attachments by document type

Use these endpoints when you are reacting to a notification. The DeclarationPdfCreated notification payload includes a ready-to-use URL containing both the documentType (e.g. EAD, TSAD) and attachmentId.

• GET /v1/declarations/{declarationId}/attachments/{documentType}/{attachmentId} -- Returns a 307 redirect to a time-limited download URL.
• GET /v1/declarations/{declarationId}/attachments/{documentType}/{attachmentId}/url -- Returns a JSON response containing the temporary download URL without redirecting.

You can also construct the /url variant by appending /url to the URL from the notification.

Download URL response

The /url endpoints return:

{
  "url": "https://temporary-download-url..."
}

Updating a declaration

You can modify a declaration directly using the PATCH /v1/declarations/{declarationId} endpoint. See Customs flows for details on when updates are allowed and how the selective update model works.

For managing individual goods items on a declaration, see Declaration items.

Error handling

For HTTP status codes and error response formats, see Error handling.