This guide walks you through creating your account to your first customs classification via the API. In 5 minutes, you'll be up and running.

Prerequisites

A modern web browser
A tool for making HTTP requests (curl, Postman, or your favorite programming language)

Create an account and organization

Go to The Trade Hub and create your account. You can sign up with your email address or via Google/Microsoft.

Once logged in, create an organization. The organization is the entity that groups your API keys, usage and members.

Click on "Create an organization" in the dashboard
Enter your company name
Choose a unique slug (e.g., my-company)

Generate an API key

From your organization, go to the Developer page:

Go to Organization > Developer
Click "Create an API key"
Give your key a descriptive name (e.g., dev-local, production)
Select the required scopes (classify for classification, export_control for export control)
Copy the displayed key - it won't be visible again

Key format:

th_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

First classification

Create a classification job with your API key:

Create a classification job

curl -X POST https://api.thetradehub.eu/v1/classify/jobs \
  -H "X-API-Key: th_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "USB-C to Lightning cable for iPhone, 1m length, white color"
  }'

The request is asynchronous. You immediately receive a job identifier:

Initial response (202 Accepted)

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "pending",
  "created_at": "2026-02-25T10:30:00Z",
  "updated_at": "2026-02-25T10:30:00Z"
}

Retrieve the results

Poll the job status until results are available:

Check status

curl https://api.thetradehub.eu/v1/classify/jobs/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "X-API-Key: th_live_your_api_key"

Once processing is complete (3 to 8 seconds), you get the full result:

Classification result

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "completed",
  "result": {
    "classification": {
      "rankings": [
        {
          "rank": 1,
          "hs_code": "8544.42.90",
          "description": "Electric cables for voltage <= 1000V, fitted with connectors",
          "confidence": 0.94,
          "gri_justification": "GIR 1 - Heading 8544 covers electric cables...",
          "validated": true
        }
      ]
    },
    "text": "Based on EU BTI decisions and TARIC nomenclature...",
    "session_id": "sess_abc123"
  },
  "created_at": "2026-02-25T10:30:00Z",
  "updated_at": "2026-02-25T10:30:05Z"
}

Key response fields:

Field	Description
`rankings[].hs_code`	Harmonised System code (6, 8 or 10 digits)
`rankings[].confidence`	Confidence score (0 to 1)
`rankings[].gri_justification`	Justification based on General Interpretive Rules
`rankings[].validated`	`true` if the code has been verified in the TARIC nomenclature

Next steps

See the Classification API reference for complete parameter and response details
Explore batch classification to process multiple products
Discover integration patterns for production best practices
Browse the references for customs reference data

This guide walks you through creating your account to your first customs classification via the API. In 5 minutes, you'll be up and running.

Prerequisites

A modern web browser
A tool for making HTTP requests (curl, Postman, or your favorite programming language)

Create an account and organization

Go to The Trade Hub and create your account. You can sign up with your email address or via Google/Microsoft.

Once logged in, create an organization. The organization is the entity that groups your API keys, usage and members.

Click on "Create an organization" in the dashboard
Enter your company name
Choose a unique slug (e.g., my-company)

Generate an API key

From your organization, go to the Developer page:

Go to Organization > Developer
Click "Create an API key"
Give your key a descriptive name (e.g., dev-local, production)
Select the required scopes (classify for classification, export_control for export control)
Copy the displayed key - it won't be visible again

Key format:

th_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

First classification

Create a classification job with your API key:

Create a classification job

curl -X POST https://api.thetradehub.eu/v1/classify/jobs \
  -H "X-API-Key: th_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "USB-C to Lightning cable for iPhone, 1m length, white color"
  }'

The request is asynchronous. You immediately receive a job identifier:

Initial response (202 Accepted)

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "pending",
  "created_at": "2026-02-25T10:30:00Z",
  "updated_at": "2026-02-25T10:30:00Z"
}

Retrieve the results

Poll the job status until results are available:

Check status

curl https://api.thetradehub.eu/v1/classify/jobs/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "X-API-Key: th_live_your_api_key"

Once processing is complete (3 to 8 seconds), you get the full result:

Classification result

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "completed",
  "result": {
    "classification": {
      "rankings": [
        {
          "rank": 1,
          "hs_code": "8544.42.90",
          "description": "Electric cables for voltage <= 1000V, fitted with connectors",
          "confidence": 0.94,
          "gri_justification": "GIR 1 - Heading 8544 covers electric cables...",
          "validated": true
        }
      ]
    },
    "text": "Based on EU BTI decisions and TARIC nomenclature...",
    "session_id": "sess_abc123"
  },
  "created_at": "2026-02-25T10:30:00Z",
  "updated_at": "2026-02-25T10:30:05Z"
}

Key response fields:

Field	Description
`rankings[].hs_code`	Harmonised System code (6, 8 or 10 digits)
`rankings[].confidence`	Confidence score (0 to 1)
`rankings[].gri_justification`	Justification based on General Interpretive Rules
`rankings[].validated`	`true` if the code has been verified in the TARIC nomenclature

Next steps

See the Classification API reference for complete parameter and response details
Explore batch classification to process multiple products
Discover integration patterns for production best practices
Browse the references for customs reference data

Quick start

Prerequisites

Create an account and organization

Generate an API key

First classification

Retrieve the results

Next steps

On this page

Quick start

Prerequisites

Create an account and organization

Generate an API key

First classification

Retrieve the results

Next steps

On this page