EU EORI Validation API: SOAP Request and Response

curl --max-time 15 \
  "https://ec.europa.eu/taxation_customs/dds2/eos/validation/services/validation" \
  --header "Content-Type: text/xml; charset=utf-8" \
  --header 'SOAPAction: ""' \
  --data '<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ev="http://eori.ws.eos.dds.s/">
  <soapenv:Body>
    <ev:validateEORI>
      <ev:eori>IT01234567890</ev:eori>
      <ev:eori>NL123456789</ev:eori>
    </ev:validateEORI>
  </soapenv:Body>
</soapenv:Envelope>'

<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
  <S:Body>
    <ns0:validateEORIResponse xmlns:ns0="http://eori.ws.eos.dds.s/">
      <return>
        <requestDate>13/11/2026</requestDate>
        <result>
          <eori>IT01234567890</eori>
          <status>0</status>
          <statusDescr>Valid</statusDescr>
          <name>EXAMPLE S.P.A.</name>
          <street>VIA ROMA 1</street>
          <postalCode>41122</postalCode>
          <city>MODENA</city>
          <country>Italy</country>
        </result>
        <result>
          <eori>NL123456789</eori>
          <status>0</status>
          <statusDescr>Valid</statusDescr>
        </result>
        <result>
          <eori>DE000000000000000</eori>
          <status>1</status>
          <statusDescr>Not valid</statusDescr>
        </result>
      </return>
    </ns0:validateEORIResponse>
  </S:Body>
</S:Envelope>

<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
  <S:Body>
    <ns0:Fault xmlns:ns0="http://schemas.xmlsoap.org/soap/envelope/">
      <faultcode>ns0:Client</faultcode>
      <faultstring>cvc-pattern-valid: Value 'de123' is not facet-valid with respect to pattern '[A-Z]{2}\p{IsBasicLatin}+' for type 'EORINumber'.</faultstring>
    </ns0:Fault>
  </S:Body>
</S:Envelope>

type EoriResult =
  | { status: "Valid"; eori: string; register: "EU" | "HMRC"; name: string | null; address: string | null }
  | { status: "Invalid"; eori: string; register: "EU" | "HMRC" }
  | { status: "Malformed"; eori: string; reason: string }
  | { status: "Unavailable"; eori: string; register: "EU" | "HMRC"; reason: string };

const EU_URL = "https://ec.europa.eu/taxation_customs/dds2/eos/validation/services/validation";
const HMRC_URL = "https://api.service.hmrc.gov.uk/customs/eori/lookup/check-multiple-eori";
const TIMEOUT_MS = 15_000;

const XML_ENTITIES: Record<string, string> = { lt: "<", gt: ">", quot: '"', apos: "'", amp: "&" };

function element(xml: string, name: string): string | null {
  const match = xml.match(new RegExp("<(?:[\\w.-]+:)?" + name + ">([\\s\\S]*?)</(?:[\\w.-]+:)?" + name + ">"));
  if (!match) return null;
  const text = match[1].replace(/&(lt|gt|quot|apos|amp);/g, (_, entity: string) => XML_ENTITIES[entity]).trim();
  return text === "" ? null : text;
}

async function checkWithEu(eori: string): Promise<EoriResult> {
  const envelope =
    '<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ev="http://eori.ws.eos.dds.s/">' +
    "<soapenv:Body><ev:validateEORI><ev:eori>" + eori + "</ev:eori></ev:validateEORI></soapenv:Body>" +
    "</soapenv:Envelope>";
  const response = await fetch(EU_URL, {
    method: "POST",
    headers: { "Content-Type": "text/xml; charset=utf-8", SOAPAction: '""' },
    body: envelope,
    signal: AbortSignal.timeout(TIMEOUT_MS),
  });
  const xml = await response.text();

  // A fault is not an answer about the number. It arrives with HTTP 500.
  const fault = element(xml, "faultstring");
  if (fault) return { status: "Unavailable", eori, register: "EU", reason: fault };
  if (!response.ok) return { status: "Unavailable", eori, register: "EU", reason: "HTTP " + response.status };

  // Results come back in the service's own order, so match on the number.
  const results = xml.match(/<(?:[\w.-]+:)?result>[\s\S]*?<\/(?:[\w.-]+:)?result>/g) ?? [];
  const result = results.find((block) => element(block, "eori") === eori);
  if (!result) {
    const reason = element(xml, "errorDescription") ?? "no result for the number";
    return { status: "Unavailable", eori, register: "EU", reason };
  }

  const status = element(result, "status");
  if (status === "1") return { status: "Invalid", eori, register: "EU" };
  if (status !== "0") return { status: "Unavailable", eori, register: "EU", reason: "unexpected status " + status };

  // Build the address from the structured fields. The free-text address element can repeat the name.
  const locality = [element(result, "postalCode"), element(result, "city")].filter(Boolean).join(" ");
  const address = [element(result, "street"), locality, element(result, "country")].filter(Boolean).join(", ");
  return { status: "Valid", eori, register: "EU", name: element(result, "name"), address: address || null };
}

async function checkWithHmrc(eori: string): Promise<EoriResult> {
  const response = await fetch(HMRC_URL, {
    method: "POST",
    headers: { "Content-Type": "application/json", Accept: "application/vnd.hmrc.1.0+json" },
    body: JSON.stringify({ eoris: [eori] }),
    signal: AbortSignal.timeout(TIMEOUT_MS),
  });
  if (!response.ok) return { status: "Unavailable", eori, register: "HMRC", reason: "HTTP " + response.status };

  const entries: unknown = await response.json();
  const entry = Array.isArray(entries) ? entries.find((candidate) => candidate?.eori === eori) : undefined;
  if (typeof entry?.valid !== "boolean") {
    return { status: "Unavailable", eori, register: "HMRC", reason: "no result for the number" };
  }
  if (!entry.valid) return { status: "Invalid", eori, register: "HMRC" };

  const details = entry.companyDetails?.address;
  const address = [details?.streetAndNumber, details?.cityName, details?.postcode].filter(Boolean).join(", ");
  return {
    status: "Valid",
    eori,
    register: "HMRC",
    name: entry.companyDetails?.traderName ?? null,
    address: address || null,
  };
}

export async function checkEori(input: string): Promise<EoriResult> {
  // Greek EORI numbers use GR. The EU register answers "not valid" for the VAT prefix EL.
  const eori = input.toUpperCase().replace(/[\s.-]/g, "").replace(/^EL(?=\d)/, "GR");

  // Both registers answer a malformed number with an error for the whole request,
  // so reject it here instead of spending a call.
  if (!/^[A-Z]{2}[A-Z0-9]{1,15}$/.test(eori)) {
    return { status: "Malformed", eori, reason: "expected two letters followed by 1 to 15 letters or digits" };
  }
  const isGb = eori.startsWith("GB");
  if (isGb && !/^GB[0-9]{12,15}$/.test(eori)) {
    return { status: "Malformed", eori, reason: "GB numbers are GB followed by 12 to 15 digits" };
  }

  const register = isGb ? "HMRC" : "EU";
  try {
    return isGb ? await checkWithHmrc(eori) : await checkWithEu(eori);
  } catch (error) {
    // A timeout or network failure says nothing about the number. Never record it as invalid.
    const reason = error instanceof Error ? error.message : String(error);
    return { status: "Unavailable", eori, register, reason };
  }
}

// Run with Node.js 20 or later: npx tsx check-eori.ts GB123456789000
const input = process.argv[2];
if (input) {
  checkEori(input).then((result) => console.log(JSON.stringify(result, null, 2)));
}

# 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"

{
  "data": {
    "valid": true,
    "eori_number": "GB123456789000",
    "country_code": "GB",
    "company": {
      "name": "EXAMPLE TRADING LTD",
      "address": "1 HIGH STREET, LONDON, SW1A 1AA"
    },
    "requested_at": "2026-11-13T09:19:29.000Z"
  },
  "meta": {
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "request_duration_ms": 312,
    "source": "hmrc",
    "source_status": "live",
    "cached": false,
    "stale": false
  }
}