Developer Docs

API Documentation

Integrate TTClassify into your systems with our Upload APIs. Post purchase orders and products for automated tariff classification.

Overview

TTClassify has been built from the ground up to be RESTful and secure. Use your credentials to connect and obtain a token, then use that token to make calls to our system.

All endpoints are protected with OAuth 2.0 Client Credentials via Microsoft Entra ID. You must obtain an access token and send it as a Bearer token in the Authorization header on every request.

Base Endpoints

POST/api/v1/system/purchase-orders/upload

POST/api/v1/system/products/upload

Request Content-Type

application/json

Token Request

application/x-www-form-urlencoded

Token Retrieval

Authenticate using Microsoft Entra ID Client Credentials flow. Request an access token from the token endpoint below, then include it as a Bearer token in all subsequent API calls.

Token Endpoint

https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token

The tenant-id, client_id, client_secret, and scope values are provided during onboarding. to get your API credentials.

Form Fields

Field	Type	Required	Notes
grant_type	string	Yes	Must be client_credentials
client_id	string	Yes	Provided per tenant
client_secret	string	Yes	Provided per tenant
scope	string	Yes	Use api://<api-client-id>/.default (value provided by TariffTel)

Sample Request

cURL

curl -X POST 'https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode 'client_id=<your-client-id>' \
  --data-urlencode 'client_secret=<your-client-secret>' \
  --data-urlencode 'scope=api://<api-client-id>/.default'

Sample Response

JSON

{
  "token_type": "Bearer",
  "expires_in": 3599,
  "ext_expires_in": 3599,
  "access_token": "eyJ0eXAiOiJKV1QiL..."
}

Use the access_token value in the Authorization header of all API requests: Authorization: Bearer eyJ0eXAiOiJKV1QiL...

Common Request Requirements

Headers

Authorization: Bearer <token>
Content-Type: application/json
Accept: application/json

Batching

Both upload endpoints accept a JSON array of items in a single request.

Rate Limiting

Both endpoints are rate limited to 30 requests per minute per client.

Product List Upload

TTClassify takes a product list as CSV and classifies each item listed. The specification below allows this to happen automatically.

POST/api/v1/system/products/upload

Request Body Example

JSON

[
  {
    "code": "PRD3312",
    "description": "Grated Cheese",
    "primarySize": "N/A",
    "primaryTariffCodeUnitCost": 1.95,
    "unitCostCodeCurrencyDescription": "GBP",
    "genderDescription": "N/A",
    "itemTypeGroupNameHint": "Food & Drink - Cheese"
  }
]

Field Reference

Field	Type	Notes
code	string	Unique product/SKU code.
description	string	Human-readable product description.
primarySize	string	Optional (e.g., N/A).
primaryTariffCodeUnitCost	number	Unit cost used for duty estimation.
unitCostCodeCurrencyDescription	string	ISO currency (e.g., GBP).
genderDescription	string	Optional (e.g., N/A).
itemTypeGroupNameHint	string	Category hint to aid classification (e.g., Food & Drink - Cheese).

Sample Request

cURL

curl -X POST 'https://<your-api-host>/api/v1/system/products/upload' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Content-Type: application/json' \
  -d '[{
    "code": "PRD3312",
    "description": "Grated Cheese",
    "supplierIdentifier": "THOC",
    "primarySize": "N/A",
    "primaryTariffCodeUnitCost": 1.9500,
    "unitCostCodeCurrencyDescription": "GBP",
    "genderDescription": "N/A",
    "itemTypeGroupNameHint": "Food & Drink - Cheese"
  }]'

Responses

202Accepted - Batch accepted for processing (async classification/validation may continue).

200OK - Synchronous validation accepted (if enabled).

400Bad Request - Malformed JSON or invalid field types.

401Unauthorized - Invalid or missing token.

403Forbidden - Insufficient scope.

415Unsupported Media Type - Content-Type not application/json.

422Unprocessable Entity - Business validation errors (e.g., invalid country code).

500Internal Server Error - Unexpected error.

Purchase Orders Upload

TTClassify takes a purchase order and classifies each item listed. The specification below allows this to happen automatically.

POST/api/v1/system/purchase-orders/upload

Request Body Example

JSON

[
  {
    "orderNumber": "ORD-12122",
    "supplierIdentifier": "THOC",
    "incoTermCode": "",
    "incoTermDescription": "",
    "shipmentMethodDescription": "",
    "orderLineTypeCode": "string",
    "orderLineTypeDescription": "string",
    "orderQuantity": 2,
    "dueDateForClassification": "2025-11-05",
    "productCode": "PRD-ORD-12121",
    "productCodeDescription": "Grated Cheese",
    "primarySize": "NA",
    "primaryTariffCodeUnitCost": 1.95,
    "unitCostCodeCurrencyDescription": "GBP",
    "genderDescription": "NA",
    "itemTypeGroupName": "Food & Drink - Cheese",
    "importRegionCountryCode": "GB",
    "countryOfOriginCode": "CN"
  }
]

Field Reference

Field	Type	Notes
orderNumber	string	Client PO number or unique order ref.
supplierIdentifier	string	Supplier code known to TariffTel.
incoTermCode	string	Optional; e.g., FOB, DDP. Empty string allowed.
incoTermDescription	string	Optional free text.
shipmentMethodDescription	string	Optional; e.g., Sea, Air.
orderLineTypeCode	string	Optional code for line type.
orderLineTypeDescription	string	Optional description for line type.
orderQuantity	number	Ordered quantity for this line.
dueDateForClassification	string (yyyy-MM-dd)	Required for SLA routing; UTC recommended.
productCode	string	Your product/SKU identifier.
productCodeDescription	string	Human-readable description.
primarySize	string	Optional (e.g., NA).
primaryTariffCodeUnitCost	number	Unit cost used for duty estimation.
unitCostCodeCurrencyDescription	string	ISO currency (e.g., GBP).
genderDescription	string	Optional (e.g., NA).
itemTypeGroupName	string	E.g., Food & Drink - Cheese.
importRegionCountryCode	string	ISO 3166-1 alpha-2 (e.g., GB).
countryOfOriginCode	string	ISO 3166-1 alpha-2 (e.g., CN).

Sample Request

cURL

curl -X POST 'https://<your-api-host>/api/v1/system/purchase-orders/upload' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Content-Type: application/json' \
  -d '[{
    "orderNumber": "ORD-12122",
    "supplierIdentifier": "THOC",
    ...
  }]'

Responses

202Accepted - Batch accepted for processing (async classification/validation may continue).

200OK - Synchronous validation accepted (if enabled).

400Bad Request - Malformed JSON or invalid field types.

401Unauthorized - Invalid or missing token.

403Forbidden - Insufficient scope.

415Unsupported Media Type - Content-Type not application/json.

422Unprocessable Entity - Business validation errors (e.g., invalid country code).

500Internal Server Error - Unexpected error.

Contact

To speak to our development team about your project, .