HMRC EORI Check API: Request, Response and Errors

HMRC's Check an EORI number API takes a POST with up to ten GB numbers and needs no credentials. This guide gives the request that works, the response fields, the four error messages a caller meets, and where XI numbers go. Each was measured against the live API on 13 November 2026.

Short answer: an open POST endpoint for GB numbers

Unlike HMRC's VAT check API, this one has no OAuth step and no application to register for a production call. A request without an Authorization header returned HTTP 200 with a result. It checks numbers that start with GB and nothing else.

Send a request

curl --max-time 15 \
  "https://api.service.hmrc.gov.uk/customs/eori/lookup/check-multiple-eori" \
  --header "Content-Type: application/json" \
  --header "Accept: application/vnd.hmrc.1.0+json" \
  --data '{"eoris": ["GB123456789000", "GB999999999999"]}'

Each number must match ^(GB|XI)[0-9]{12,15}$: the prefix, then 12 to 15 digits, uppercase, no spaces. For a UK VAT-registered business the first 9 digits are its VAT number: HMRC's own example is GB123456789000. A business does not need a VAT registration to get an EORI number.

Read the response

The response below uses synthetic values in the shape the live API returns.

[
  {
    "eori": "GB999999999999",
    "valid": false,
    "processingDate": "2026-11-13T09:19:29+00:00"
  },
  {
    "eori": "GB123456789000",
    "valid": true,
    "companyDetails": {
      "traderName": "EXAMPLE TRADING LTD",
      "address": {
        "streetAndNumber": "1 HIGH STREET",
        "cityName": "LONDON",
        "postcode": "SW1A 1AA"
      }
    },
    "processingDate": "2026-11-13T09:19:29+00:00"
  }
]

Match entries on eori. A request for two numbers came back in reverse order. An unknown number is a normal entry with valid: false and HTTP 200, so there is no 404 to interpret.

Handle the four 400 messages

Every refusal is HTTP 400 with the code INVALID_REQUEST. Only the message tells them apart, and one bad number refuses the whole request.

Validate the format before sending so that one typo in a batch does not cost the other nine results. Treat a 400, a 5xx or a timeout as a check that did not complete, never as an answer that the number is not valid.

Send XI numbers to the EU service

The pattern in HMRC's own error message allows an XI prefix, and the API still refuses one:

{
  "code": "INVALID_REQUEST",
  "message": "Invalid payload - one or more EORI numbers begin with XI. To check an EORI number that starts with XI, use the EORI checker service on the European Commission website"
}

Northern Ireland numbers are checked with the European Commission's SOAP service, covered in the EU EORI validation guide. The reverse does not work either: the Commission's service answers Not valid for a GB number that HMRC lists as valid. A system that accepts both prefixes needs both integrations and a router in front of them.

Sandbox, rate limits and stability

• Sandbox. https://test-api.service.hmrc.gov.uk serves mock answers chosen by the last digit of the number. HMRC's API page lists which digit gives which answer.
• Rate limit. HMRC publishes no figure for this API. Its reference guide says requests are rate limited, so bound each request with a timeout and retry with a pause.
• Stability. The version is labelled beta. Pin the Accept header to version 1.0 and run a scheduled check against a known number, so a change shows up in your monitoring before it shows up in an order.
• No search by name. The API takes numbers only.

HMRC directly vs Avatcado

HMRC directly is the right choice when you only meet GB numbers. Avatcado is useful when the same form also takes EU and XI numbers, or when you already validate VAT numbers through it.

# Set AVATCADO_API_KEY in this server environment first.
curl --max-time 30 \
  "https://api.avatcado.com/v1/eori/validate?eori_number=GB123456789000" \
  --header "Authorization: Bearer $AVATCADO_API_KEY"

The response reports hmrc in meta.source for a GB number and ec_eos for EU and XI numbers, so your records show which register answered.