FPO Commodity Code Identification Tool APIs

The FPO (Fast Parcel Operator) Commodity Code Identification Tool is a tool specifically for use by FPOs moving goods under the UK Authorised Carrier (UKC) scheme to identify 6-digit HS (Harmonized System) codes or 8-digit CN (Combined Nomenclature) codes for English language goods item descriptions.

Warning Note that this API is currently in invite-only private beta

If you represent a UK FPO, are planning to move parcels under the new UK Authorised Carrier Scheme and would like to be included in the beta service, contact hmrc-trade-tariff-support-g@digital.hmrc.gov.uk

For more information see the guidance for moving parcels from Great Britain to Northern Ireland under the Windsor Framework from 30 September 2024

This API accepts HTTP requests and responds with JSON data.

Bulk processing

Due to the synchronous operation of the API, if you’re dealing with large volumes of data or are batch processing it’s recommended to use a multi-threaded or asynchronous client to process several connections simultaneously.

This will be subject to rate limiting (to be implemented before 30 September 2024) which will allow up to 100 requests per second for each FPO.

Support

If you experience any issues or have questions regarding this API please contact hmrc-trade-tariff-support-g@digital.hmrc.gov.uk

Base URL

All requests to this API should be prefixed with the following URL:

https://search.trade-tariff.service.gov.uk

Authentication

API Key: Parameter X-Api-Key, in header.

Access to these APIs is restricted to only those Fast Parcel Operators (FPOs) who have been invited to test the service.

Those eligible organisations will be supplied with a secret API key which should be included in the X-Api-Key header of every request, e.g.:

X-Api-Key: a1b2c3defg4567

FPO endpoints

POST /fpo-code-search

Identifies potential commodity codes for a goods item description

Carries out a search for potential commodity codes for a single line item within a parcel

To perform this operation, you must be authenticated by means of one of the following methods: apiKey

Request body

{
  "description": "plastic toothbrush",
  "digits": 6,
  "limit": 5
}

Parameters

Parameter	In	Type	Required	Description
body	body	ItemSearchRequest	true	No description

Example Request

curl -d '{"description": "plastic toothbrush", "digits": 8}' \
  -H "Content-Type: application/json" -H "X-Api-Key: <your-api-key-here>" \
  -X POST https://search.trade-tariff.service.gov.uk/fpo-code-search

Example Response

{
  "results": [
    {
      "code": "123456",
      "score": 123.45
    },
    {
      "code": "987654",
      "score": 98.76
    }
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	Successful response	ItemSearchResponse
400	Bad Request	There was an issue with the request (e.g. invalid JSON)	None
403	Forbidden	Missing API key, or the supplied key was invalid	None
429	Too Many Requests	You are being rate limited. The API will be rate limited to 100 requests per second for each FPO	None

Response Headers

Status	Header	Type	Format	Description
200	X-Request-Id	string		Unique ID for this request. Use this if you need to raise an issue or a query for this specific response

Objects

ItemSearchRequest

Sample JSON

    
{
  "description": "plastic toothbrush",
  "digits": 6,
  "limit": 5
}

Fields

Name	Type	Required	Description
description	string	true	A brief plain English description of the item in the parcel. For example, it may include the type of product such as ‘shampoo’, ‘plastic cups’ or ‘iPhone’. You should avoid generic terms that do not allow the good to be identified such as ‘goods’, ‘gifts’, ‘samples’ or ‘parts’
digits	integer	false	The number of commodity code digits the response should return. ‘6’ will return 6-digit HS codes, ‘8’ will return 8-digit CN codes
limit	integer	false	The maximum number of results to send back

ItemSearchResponse

Sample JSON

    
{
  "results": [
    {
      "code": "123456",
      "score": 123.45
    },
    {
      "code": "987654",
      "score": 98.76
    }
  ]
}

Fields

Name	Type	Required	Description
results	[ItemSearchResponseResult]	false	The array of results, up to the specified limit, in order - best match first

ItemSearchResponseResult

Sample JSON

    
{
  "code": "123456",
  "score": 123.45
}

Fields

Name	Type	Required	Description
code	string	true	The 6 digit HS code, or 8 digit CN code (depending on the ‘digits’ request parameter)
score	number	true	A rating for how well the code matches. A higher number signifies a better match

ErrorResponse

Sample JSON

    
{
  "message": "string",
  "detail": "string"
}

Fields

Name	Type	Required	Description
message	string	true	The error message summary
detail	string	false	Extra information about the error