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:
POST /discovery/sourceโ202 Acceptedwith asource_discovery_taskid.- Poll
GET /discovery/source/{taskId}/statusuntilstatusiscompleted(orfailed). - Fetch
GET /discovery/source/{taskId}/resultsfor the discovered locations.
โถRequest
โถMethod & Path
POST /discovery/source
โถHeaders
x-api-keyโ required.Accept: application/jsonContent-Type: application/json
โถBody
-
company(string, required for a new search) โ the company whose first-mile supply to discover. Omit when usingcontinue_from. -
commodities(string[], optional) โ commodities to map (any raw material, e.g.timber,rubber). Free-text, as on/discovery/validate. Omit (along withproducts) 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 whencommoditiesis 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, defaultall) โ supply-ward filter: one ofall,operated-by,intermediary,first-mile. -
limit(integer, optional, min1) โ max candidate locations: default50, max200normally; default and max10in 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 entitycompanynames 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 ascompany. -
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, defaultfalse) โ recompute instead of serving the cached sweep. -
direct_operated(boolean, defaultfalse) โ 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, defaultfalse) โ walk the supply graph upstream.max_sweeps(integer, optional,1โ10, default10) โ budget of paid sweeps, the root sweep included for a new search. For a continuation, budgets only new sweeps; defaults to one perexpandid, capped at 10. fm-api always sends a budget.max_children_per_sweep(integer, optional,0โ25, default3) โ children expanded per parent, ranked by match confidence.0= no cap.child_limit(integer, optional,1โ200, default25) โ 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_taskresource carrying the task id and the poll / results links (see schema below). Computed, not persisted โ itsidis the upstream discovery task id. - 400 โ invalid body: missing
companyfor a new search, an out-of-rangelimitormax_sweeps, an unknownrelationship, a context term containing a comma, or a traversal knob withouttraverse: 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.detailscarrieslimit: traceand 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
expandids. Read the refusal details. - 429
RATE_LIMIT_EXCEEDEDโ the org's hourly discovery limit or daily trace-sweep limit is spent.data.details.limitsays which, with the counts andresets_at;Retry-Aftergives the wait. A traversal whosemax_sweepsexceeds the whole daily limit is always refused, so lowermax_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_sweepsstays 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.
| Field | Type | Description |
|---|---|---|
type | string | Always source_discovery_task. |
id | string | Discovery task id โ poll status, then fetch results. |
attributes.status | string | Task lifecycle status at dispatch (e.g. processing). |
attributes.company | string | Echo of the requested company. |
links.status | string | Poll this URL for task status. |
links.results | string | Fetch the discovered locations here once status is completed. |
Required scope:
discovery:write