Discover Source Locations

Discover the first mile of a company's supply โ€” potentially dozens of candidate supplier / operating locations โ€” without ingesting any assets. This is the multi-result counterpart to POST /discovery/validate: where validate resolves one supplier name to its single top facility, source traces supply-ward from a company to the production areas and intermediary nodes that supply into it. No supply shed is generated and no record is persisted.

Discovery combines grounded search, geocoding and satellite-imagery confirmation. That sweep is long-running, so this endpoint is asynchronous:

  1. POST /discovery/source โ†’ 202 Accepted with a source_discovery_task id.
  2. Poll GET /discovery/source/{taskId}/status until status is completed (or failed).
  3. Fetch GET /discovery/source/{taskId}/results for the discovered locations.

Request

Method & Path

POST /discovery/source

Headers

  • x-api-key โ€” required.
  • Accept: application/json
  • Content-Type: application/json

Body

  • company (string, required for a new search) โ€” the company whose first-mile supply to discover. Omit when using continue_from.

  • commodities (string[], optional) โ€” commodities to map (any raw material, e.g. timber, rubber). Free-text, as on /discovery/validate. Omit (along with products) to let discovery infer the company's main raw materials.

  • products (string[], optional) โ€” product names; each is resolved to its upstream raw commodities and mapped. Ignored when commodities is supplied.

  • countries (string[], optional) โ€” countries to scope the search (e.g. Indonesia). Supplied countries filter candidates; a candidate without a country is retained. Omit for a global sweep: inferred sourcing countries guide the search but do not filter the result.

  • relationship (string, optional, default all) โ€” supply-ward filter: one of all, operated-by, intermediary, first-mile.

  • limit (integer, optional, min 1) โ€” max candidate locations: default 50, max 200 normally; default and max 10 in direct-operated mode.

  • company_address (string, optional, max 500) โ€” address of the company itself, not of a supply location. Use it to say which real-world entity company names when the name could be shared.

  • company_identifier (string, optional, max 200) โ€” a registry identifier for the company: EUDR/TRACES operator id, VAT/EORI, LEI, registration number or web domain.

  • company_aliases (string[], optional, max 20 items of 200) โ€” other names the company trades under: abbreviations, former names, native-script spellings, or the descriptive name a supplier file uses. Discovery matches a source against these as well as company.

  • company_identifiers (string[], optional, max 20 items of 200) โ€” further identifiers: LEI, FSC/PEFC certificate codes, registry ids, web domains. A source that carries one of these is a strong match.

  • refresh (boolean, optional, default false) โ€” recompute instead of serving the cached sweep.

  • direct_operated (boolean, default false) โ€” one sweep for the company's own facilities with exact site pins. Requires EUDR commodities and at most five countries; cannot be combined with traversal.

Supply-graph traversal

By default one call returns one tier of the supply graph. Set traverse: true to walk it upstream in the same task. Each intermediary with a deterministic link gets its own child sweep, until every branch ends at the first mile, at an entity already visited, or at a sweep that finds nothing new.

  • traverse (boolean, optional, default false) โ€” walk the supply graph upstream.
  • max_sweeps (integer, optional, 1โ€“10, default 10) โ€” budget of paid sweeps, the root sweep included for a new search. For a continuation, budgets only new sweeps; defaults to one per expand id, capped at 10. fm-api always sends a budget.
  • max_children_per_sweep (integer, optional, 0โ€“25, default 3) โ€” children expanded per parent, ranked by match confidence. 0 = no cap.
  • child_limit (integer, optional, 1โ€“200, default 25) โ€” max candidate locations per child sweep.

The three knobs require traverse: true. Without it they return 400.

Continue a finished traversal

Use continue_from (UUID) with the task id of a finished traversal in your organization, and expand (1โ€“50 candidate ids) to select nodes to sweep upstream. This creates a new traversal that keeps the previous nodes and their ids, and sweeps only the selected candidates. Send only continue_from, traverse: true, expand and, optionally, max_sweeps; the original task supplies the company and search settings.

{
  "continue_from": "00000000-0000-4000-8000-000000000001",
  "traverse": true,
  "expand": ["candidate-id-from-results"],
  "max_sweeps": 5
}

Replace the example ids with the finished task and its candidate ids. A candidate absent from that result, without a supplier name, or whose entity was already swept is refused with 422, listing the ids and reasons. Continuations are charged like other traversals.

A traversal runs for hours, not minutes: about 15 minutes per round of sweeps, and up to about 2 hours at the default budget of 10. Poll โ€ฆ/status at a slow interval.

Access. Traversal is enabled per organization. An org with no enabled discovery_traversal grant gets 403 SERVICE_NOT_ENABLED, and its one-tier calls still work. Ask your Epoch contact to enable it.

Trace allowance. Each accepted call is one Trace: a one-tier or direct-operated search, a traversal, or a continuation. A Trace counts once, whatever its max_sweeps. An organization gets 10 Traces, and 30 once it has paid for a checkout. Epoch can grant more, and some organizations are unlimited. A parent organization and its child organizations share one allowance. Cached, failed and unspent runs do not count once settled. Read the Traces left on GET /rate-limits/allowances.

With no Traces left, the call returns 402 USAGE_LIMIT_REACHED. A repeat can still return an existing cached result without spending a Trace: omit continue_from and leave refresh false. A cache miss is refused without starting a new search.

Rate limits. These apply whatever the allowance, to the calling organization, so acting as a child organization does not multiply them. Per-organization settings can override the defaults. One-tier discovery allows 60 calls an hour, and direct-operated mode a separate 120 an hour. Both charge the call at dispatch, even when the result comes from cache. A traversal draws on the daily trace-sweep limit, 80 by default: its whole max_sweeps is charged at dispatch, and unused sweeps are refunded when it settles. A budget larger than the whole daily limit is refused. Use Retry-After on a 429. Read the limits left on GET /rate-limits.

Response

  • 202 โ€” a source_discovery_task resource carrying the task id and the poll / results links (see schema below). Computed, not persisted โ€” its id is the upstream discovery task id.
  • 400 โ€” invalid body: missing company for a new search, an out-of-range limit or max_sweeps, an unknown relationship, a context term containing a comma, or a traversal knob without traverse: true.
  • 401 / 403 โ€” missing or invalid key, or the key lacks discovery:write.
  • 402 USAGE_LIMIT_REACHED โ€” the organization has no Traces left, and no cached result answers the call. data.details carries limit: trace and the counts (see Limit refusals in the error codes). Retrying does not help; the message says how to get more.
  • 403 SERVICE_NOT_ENABLED โ€” traverse: true, and the organization is not enabled for traversal.
  • 404 / 409 / 422 โ€” a continuation's prior task is unavailable, cannot be continued, or contains invalid expand ids. Read the refusal details.
  • 429 RATE_LIMIT_EXCEEDED โ€” the org's hourly discovery limit or daily trace-sweep limit is spent. data.details.limit says which, with the counts and resets_at; Retry-After gives the wait. A traversal whose max_sweeps exceeds the whole daily limit is always refused, so lower max_sweeps.
  • 502 โ€” a transient upstream failure dispatching the discovery (a 5xx, request timeout, or network error). Retryable, but note that dispatch is at-least-once: there is no idempotency key, so retrying after the task was already created may start a second (independent) discovery. A traversal's max_sweeps stays charged after a 502, because the task may already be running upstream. A retry is charged again, so it can hit the daily traversal limit.

Response schema

Only the data payload is described; the meta / links envelope is documented centrally.

FieldTypeDescription
typestringAlways source_discovery_task.
idstringDiscovery task id โ€” poll status, then fetch results.
attributes.statusstringTask lifecycle status at dispatch (e.g. processing).
attributes.companystringEcho of the requested company.
links.statusstringPoll this URL for task status.
links.resultsstringFetch the discovered locations here once status is completed.

Required scope: discovery:write