EORI Bulk Validator & Monitor

An Apify Actor that checks only EORI identifiers supplied by the user against the official European Commission EORI validation service. It normalizes identifiers, performs privacy-conscious bulk checks, and compares current results with optional prior statuses.

This is an MVP for operational validation and monitoring workflows. It is not affiliated with or endorsed by the European Commission.

What it returns

One dataset row per unique normalized input:

Field	Meaning
eori	Trimmed, uppercased identifier with whitespace removed
country_prefix	First two letters, or null if unavailable
status	valid, invalid, or unknown
checked_at	ISO 8601 time when the result was produced
source	Official EC SOAP validation endpoint
previous_status	Optional normalized prior status
status_change	new, unchanged, changed, or not_comparable
input_occurrences	How often the normalized identifier appeared in this run
attempts	Number of official HTTP attempts; malformed local input has 0
error_code, error_message	Safe diagnostic fields for inconclusive results

changed is deliberately limited to a conclusive valid ↔ invalid transition. Any comparison involving unknown is not_comparable, which avoids false alerts during an EC outage.

Privacy by design

The EC response contract can include registrant name and address fields. This Actor intentionally discards those fields. They are not part of the TypeScript result type, dataset schema, summary, or logs—even when the upstream response contains them.

• Submit only EORI numbers you are authorized to process.
• Do not submit names, addresses, notes, or other personal data in the EORI input.
• Configure Apify retention and deletion to match your own legal obligations.
• Do not use a result as the sole basis for a legal, customs, credit, employment, or other consequential decision.

Input

{
  "eoriNumbers": ["IE6388047V", "DE000000000000000"],
  "priorStatuses": [
    { "eori": "IE6388047V", "status": "valid" }
  ],
  "maxConcurrency": 1,
  "minDelayMs": 1000,
  "maxRetries": 2,
  "requestTimeoutSecs": 20
}

Limits:

• 1–1,000 supplied values per run
• 1–4 concurrent tasks
• at least 500 ms between all official request starts
• up to 5 retries, only for timeout/network errors, HTTP 408/429, and 5xx responses

The conservative defaults are intentional. The official WSDL states that EORI count, message size, and request frequency are limited, but does not publish numeric limits. This Actor therefore sends one normalized identifier per SOAP request and globally spaces every attempt.

The EC's service announcement publishes a ceiling of 10 EORI numbers per request and 100 requests per second. This MVP intentionally stays far below it: one EORI per request and, by default, one request start per second.

Normalization and status rules

Inputs are Unicode NFKC-normalized, trimmed, stripped of whitespace, and uppercased. A value must then match two ASCII letters followed by 1–15 alphanumeric characters. A malformed value is returned as unknown with INVALID_FORMAT; it is never mislabeled invalid because no official lookup occurred.

For official responses:

• EC status 0 / description Valid → valid
• EC status 1 / description Not valid → invalid
• service failure, timeout, SOAP fault, malformed response, or unrecognized status → unknown

Duplicate normalized values are checked once within a run. One output row is returned with input_occurrences showing the duplicate count.

Monitoring pattern

Run the Actor on an Apify schedule and feed the previous run's eori + status pairs into priorStatuses. Alert only when status_change is changed; treat unknown as a service-health condition to retry later.

The MVP does not send email, webhook, or social messages by itself. That avoids hidden outbound side effects and lets the caller choose its own alert destination.

Pay-per-event monetization

The Actor includes native Apify PPE event definitions and hooks:

• apify-actor-start: $0.00005 once per run, charged automatically by Apify
• eori-validation: $0.002 for each conclusive valid or invalid dataset row

The code does not manually charge the automatic Actor-start event. Malformed identifiers and unknown results caused by upstream failures are returned to the dataset but do not trigger eori-validation. Consecutive rows with the same charging treatment are pushed in batches while preserving normalized input order. Apify's SDK treats the hooks as no-ops for billing when the Actor is run locally or under a non-PPE pricing model, while still storing all rows.

Local development

Requirements: Node.js 22+ and npm.

npm ci
npm run check

To run locally with Apify storage:

mkdir -p storage/key_value_stores/default
cp examples/INPUT.json storage/key_value_stores/default/INPUT.json
npm run start:dev

The default test suite is fully mocked and makes no network requests. A single opt-in live-safe check uses a syntactically valid dummy identifier that the EC service reports as invalid:

$npm run test:live

Do not run the live test repeatedly or in a tight CI loop.

Official sources

• European Commission EORI overview and format
• Official public EORI validator
• Official EORI SOAP WSDL
• EC validation-service limits announcement
• Apify Actor definition
• Apify input schema
• Apify dataset schema
• Apify output schema

Legal and reliability disclaimer

This software provides a point-in-time technical lookup of the official EC service. It does not certify an entity, guarantee customs clearance, establish identity, or provide legal, tax, sanctions, or customs advice. The EC service can be delayed, unavailable, rate-limited, or return incomplete information; such cases are reported as unknown. Verify consequential decisions with the appropriate national customs authority and qualified advisers.

Users are responsible for complying with applicable law, the European Commission's legal notice and privacy rules, Apify's terms, and any contractual or confidentiality duties governing submitted identifiers.