Quick start tutorial

This tutorial walks you through a complete integration with the CAS API, from authentication to retrieving a released declaration. By the end, you will have sent a customs shipment, subscribed to notifications, and downloaded a declaration document.

Before starting, make sure you have received your Client ID and Client Secret from Customs4trade Customer Success team. You also need the environment URLs for your CAS instance.

Step 1: Authenticate

Request a bearer token from the CAS identity provider using the Client Credentials Grant. See Authentication for full details on token management, scopes, and tenant identification.

Request:

POST https://login.customs4trade.com/oauth2/v2.0/token (production)
POST https://login-acc.customs4trade.com/oauth2/v2.0/token (acceptance)

Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id={client_id}&client_secret={client_secret}&scope=https%3A%2F%2Fc4t{env}b2c.onmicrosoft.com%2F{client_id}%2F.default

Replace {client_id}, {client_secret}, and {env} with the values provided by C4T. The {env} placeholder is part of the scope URI and depends on your environment (e.g., acc for acceptance, prd for production).

Response:

{
    "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6...",
    "token_type": "Bearer",
    "expires_in": 3600
}

Cache the access_token and reuse it until it expires. Do not request a new token for every API call. Use the token as a Bearer token in the Authorization header for all subsequent requests.

Step 2: Verify your token

Call the authorization status endpoint to confirm your token is valid and inspect your access rights.

Request:

GET /v1/authorizationStatus
Authorization: Bearer {access_token}

Response:

{
    "sourceSysRef": "your-source-system",
    "tenantIds": "your-tenant-id",
    "scopes": "create:messages read:declarations create:subscriptions read:subscriptions delete:subscriptions read:documents"
}

Verify that the scopes field includes the permissions you need. For this tutorial you need at minimum create:messages, read:declarations, and create:subscriptions.

Before sending any data, set up a webhook so CAS can notify you of status changes and processing results.

Request:

POST /v1/subscriptions
Authorization: Bearer {access_token}
Content-Type: application/json

{
    "eventType": "DeclarationStatusChanged",
    "subscriptionDestination": {
        "destinationType": "OAuthApiDestination",
        "destinationDescription": {
            "destinationUrl": "https://your-system.example.com/webhooks/cas"
        }
    }
}

This subscribes to all status changes. To subscribe to a specific status only (e.g. Released), add "eventSubType": "Released". A full list of event types and subtypes that a subscription can be defined for is available in Notification events.

You can protect your endpoint using OAuth or API key headers — see Notifications for details.

Response (201 Created):

{
    "id": "sub-uuid-1234",
    "eventType": "DeclarationStatusChanged",
    "subscriptionDestination": {
        "destinationType": "OAuthApiDestination"
    }
}

Step 4: Create a customs shipment

Send a customs shipment to CAS to start a customs flow. The example below shows a minimal import shipment.

Request:

POST /v1/customsshipments
Authorization: Bearer {access_token}
Content-Type: application/json

{
    "direction": "IN",
    "externalReference": "MY-SHIPMENT-001",
    "storageLocationReference": "WAREHOUSE-01",
    "messageType": "New",
    "singleAdministrativeDocument": {
        "declType": "IM",
        "addDeclType": "Z",
        "invoiceCurrency": "EUR",
        "declarationOfficeCode": "BE212000",
        "goodsShipment": {
            "consignor": {
                "businessPartnerReference": [
                    {
                        "code": "US12345678",
                        "type": "Eori"
                    }
                ]
            },
            "consignee": {
                "businessPartnerReference": [
                    {
                        "code": "BE0123456789",
                        "type": "Eori"
                    }
                ]
            },
            "governmentAgencyGoodsItems": [
                {
                    "commodity": {
                        "description": "Electronic components",
                        "classification": {
                            "id": "85423190"
                        }
                    },
                    "goodsMeasure": {
                        "gmass": 100.0,
                        "nmass": 95.0
                    },
                    "packaging": [
                        {
                            "type": "CT",
                            "quantity": 5,
                            "shippingMarks": "ELEC-001"
                        }
                    ],
                    "customsValue": {
                        "amount": 25000.00,
                        "currency": "EUR"
                    }
                }
            ]
        }
    }
}

This is a simplified example. The actual fields required depend on the customs flow and jurisdiction configured for your tenant. Refer to the API specification or the CustomsShipment XSD for the complete data model, or contact Customs4trade Customer Success team for a mapping guide tailored to your customs flow.

Response (202 Accepted):

{
    "referenceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

The referenceId uniquely identifies your ingested message. Store it — you will see it in creation and replace notification events (e.g. CreationUnsuccessful, ReplaceSuccessful) under ingestionReferences, allowing you to correlate the processing result back to this submission. Note that downstream events such as DeclarationStatusChanged do not include ingestionReferences; use the customsShipmentReference on those events to track declaration progress.

A 202 Accepted response means CAS has accepted the message for processing. It does not mean all business validations have passed. Your webhook (set up in the previous step) will receive the actual processing result.

Step 5: Receive a notification

When CAS processes your customs shipment and the declaration status changes, your webhook endpoint receives an HTTP POST:

{
    "id": "434513a3-0305-4639-baf6-c85235b965b3",
    "tenantId": "your-tenant-id",
    "eventTime": "2026-03-26T14:30:00.000Z",
    "eventType": "DeclarationStatusChanged",
    "eventSubType": "Released",
    "data": {
        "id": "987654321",
        "customsShipmentReference": "FQB1XH5TPU",
        "traderReference": "MY-SHIPMENT-001",
        "jurisdiction": "BE",
        "customsFlow": "INBE_H1",
        "customsFlowStep": "INBE_H1",
        "mrn": "26BEE0000001234567",
        "lrn": "LRN0001222",
        "declarationUrl": "https://api.customs4trade.com/v1/declarations/987654321",
        "currentStatus": "Released",
        "storageLocation": "WAREHOUSE-01"
    }
}

Key fields to extract:

data.id — The declaration ID, used to retrieve the full declaration
data.currentStatus — The new status (see Declaration statuses for all possible values)
data.traderReference — Your original externalReference, useful for correlating with your system
data.declarationUrl — Direct URL to retrieve the declaration

Your webhook must respond with a 2xx status code to acknowledge receipt. If it fails, CAS retries with exponential backoff for up to 24 hours.

Step 6: Retrieve the declaration

Use the declaration ID from the notification to retrieve the full declaration, including any errors and attachment metadata.

Request:

GET /v1/declarations/987654321?include=errors,attachments
Authorization: Bearer {access_token}

Response (200 OK): (abbreviated)

{
    "declarationId": "987654321",
    "currentStatus": "Released",
    "mrn": "26BEE0000001234567",
    "singleAdministrativeDocument": {
        "declType": "IM",
        "goodsShipment": {
            "governmentAgencyGoodsItems": [
                {
                    "commodity": {
                        "description": "Electronic components"
                    }
                }
            ]
        }
    },
    "errors": [],
    "attachments": [
        {
            "id": "att-uuid-5678",
            "documentType": "EAD",
            "fileName": "EAD_26BEE0000001234567.pdf"
        }
    ]
}

Step 7: Download an attachment

Download the EAD or any other attachment using the attachment ID from the previous response.

Option A: Direct download (follows redirect)

GET /v1/declarations/987654321/attachments/att-uuid-5678
Authorization: Bearer {access_token}

Returns 307 Temporary Redirect to the file location. Most HTTP clients follow this automatically.

Option B: Get a download URL

GET /v1/declarations/987654321/attachments/att-uuid-5678/url
Authorization: Bearer {access_token}

{
    "url": "https://storage.example.com/temp/EAD_26BEE0000001234567.pdf?token=..."
}

The download URL is temporary and expires after a short time. Do not store it — request a new URL each time you need to download.

Next steps

Now that you have completed the basic integration flow, explore these topics:

Customs flows — Understand how CAS processes your data, including correction mechanisms (Replace, Update, Upsert)
Sending data to CAS — All ingestion endpoints and their data models
Declarations — Searching and retrieving declarations, including pagination
Declaration actions — Post-creation actions like Submit, Invalidate, and Goods Arrived
Notifications — Advanced webhook configuration with OAuth and event filtering
Data types — Standard formats for dates, currencies, and country codes

← Previous Page Next Page →

Quick start tutorial

Step 1: Authenticate

Step 2: Verify your token

Step 3: Subscribe to notifications

Step 4: Create a customs shipment

Step 5: Receive a notification

Step 6: Retrieve the declaration

Step 7: Download an attachment

Next steps