Documentation

Identifiers and entities

Join records across APIs through the identifiers they share.

An entity is an organisation (a company, nonprofit, council, hospital or utility) or a place (a state, county, ZCTA, address or parcel). People are never entities. Each entity has a stable, opaque Olympus ID such as org_… or place_…; it encodes nothing, so do not parse it.

An identifier is a scheme and a value, for example US-EIN 942404110 or OLY-US-SEC-CIK 0000320193. Every identifier says how it was linked to the entity (method: published, exact or derived), with a confidence and its source. Only identifiers in an active publication are returned. Probabilistic matches are never returned, and nothing is linked on name or address similarity. GET /v1/identifier-schemes reports each scheme as active or planned.

These endpoints take any valid API key; no plan entitlement is needed. Requests are metered as product platform and share its per-minute rate limit. The full reference is in the Platform API reference.

The shared identifier registry. An entity is an organisation or a place with a stable, opaque Olympus ID (org_..., place_...). Identifiers are scheme/value pairs: organisation schemes use the org-id.guide prefix where one exists (US-EIN, XI-LEI, GB-COH, ...); others are Olympus schemes prefixed OLY- (OLY-US-SEC-CIK, OLY-US-CENSUS-COUNTY, ...).

method says how an identifier was linked to the entity: published (the source publishes it for the record, e.g. EDGAR's EIN for a CIK), exact (the same normalised value in another dataset) or derived (computed from published values). Probabilistic matches are never returned. related links point to the record a product serves for the same entity.

Examples

Resolve an EIN

curl -s "https://api.olympus.new-odyssey.com/v1/resolve?scheme=US-EIN&value=94-2404110" \
  -H "X-API-Key: $OLYMPUS_API_KEY"

Resolve a CIK

curl -s "https://api.olympus.new-odyssey.com/v1/resolve?scheme=OLY-US-SEC-CIK&value=320193" \
  -H "X-API-Key: $OLYMPUS_API_KEY"

Read an entity

curl -s "https://api.olympus.new-odyssey.com/v1/entities/{entity_id}" \
  -H "X-API-Key: $OLYMPUS_API_KEY"

List schemes and coverage

curl -s "https://api.olympus.new-odyssey.com/v1/identifier-schemes" \
  -H "X-API-Key: $OLYMPUS_API_KEY"

Endpoints

One entity with its identifiers and related records

GET/v1/entities/{entity_id}

Identifiers come only from active publications. An entity whose identifiers are all unpublished (or that does not exist) answers 404 ENTITY_NOT_FOUND.

Authentication: API key (X-API-Key or Bearer)

Name	In	Type	Description
entity_idrequired	path	string	Olympus entity ID. Example: `org_01jb7r9x3q8m2v6k4t5w0zyc1d`

Responses: 200 EntityResponse400 Error401 Error403 Error404 Error429 Error

Find the entities an identifier belongs to

GET/v1/resolve

Normalises value for scheme (e.g. 94-2404110 -> 942404110 for US-EIN, 320193 -> 0000320193 for OLY-US-SEC-CIK) and returns the entities it is published for, with their identifiers and related records. A value belongs to at most one entity at a time, so data has zero or one element today; it is a list so that a future reviewed split can be represented. No match answers 404 ENTITY_NOT_FOUND; an unknown scheme or a value that is not valid for the scheme answers 400 VALIDATION_ERROR.

Authentication: API key (X-API-Key or Bearer)

Name	In	Type	Description
schemerequired	query	string	Scheme code from `GET /v1/identifier-schemes`. Example: `US-EIN`
valuerequired	query	string	Identifier value, in any accepted form; it is normalised before lookup. Example: `94-2404110`

Responses: 200 ResolveResponse400 Error401 Error403 Error404 Error429 Error

Identifier schemes and their coverage

GET/v1/identifier-schemes

Every scheme the registry knows, with status active (identifiers of this scheme are in an active publication) or planned (none are yet), and how many identifiers and entities are published. Planned schemes carry no coverage claim.

Authentication: API key (X-API-Key or Bearer)

Responses: 200 IdentifierSchemesResponse401 Error403 Error429 Error

Schemas

Entity

Field	Type	Description
entity_id *	string	Stable, opaque Olympus ID. Encodes nothing; do not parse it.
kind *	enum: organisation \| place
entity_type *	string	e.g. company, fund, state, county, zcta.
display_name *	string \| null	Name as published by the dataset that registered the entity.
identifiers *	array of Identifier	Published identifiers. A value asserted by several datasets appears once per dataset.
related *	array of RelatedLink	Records the products serve for this entity.

Identifier

One identifier of an entity, with how and where it was linked.

Field	Type	Description
scheme *	string	Scheme code (org-id.guide prefix, or an Olympus OLY- scheme).
value *	string	Normalised value.
method *	enum: published \| exact \| derived	`published`: the source publishes this identifier for the record. `exact`: the same normalised value in another dataset. `derived`: computed from published values.
confidence *	number	1 for published and exact links.
source *	IdentifierSource

IdentifierSource

Provenance of the link.

Field	Type	Description
dataset_id *	string	Registry dataset that published the link.
source_id *	string
source_url *	string
source_version *	string
source_date *	string (date) \| null
published_at *	string (date-time)

RelatedLink

The record a product serves for the same entity.

Field	Type	Description
product *	string	Public product ID.
resource *	string
path *	string	Public path of the record.
via *	RelatedVia

* required field