API reference · v1.0.0

US Employee Benefits & Form 5500 API

Download OpenAPI (form-5500.yaml) · Base URL https://api.olympus.new-odyssey.com

Employee benefit plans by sponsor EIN and plan number, with their Form 5500 or 5500-SF filings by plan year: participants, assets, contributions, benefits paid and expenses. From the DOL EBSA Form 5500 datasets, with the provenance of every record. Served by the Olympus Go gateway.

Sources. The DOL "Latest" files (the most recent filing per plan and plan year) of Form 5500, Form 5500-SF, Schedule H (large plans) and Schedule I (small plans). GET /v1/form-5500/coverage lists the plan years and every file loaded (plan_years_in_scope). Form 5500-EZ (one-participant plans) and the other schedules are not included. Recent plan years fill in for months after the year ends.

Figures as filed. Financial fields come from the filing's Schedule H, Schedule I or the 5500-SF itself (financials.source), as filed and not audited by Olympus (figures_as_filed).

Identifiers, not names. Look sponsors up by EIN and plans by EIN and plan number (exact). A name query returns sponsors whose name starts with it: candidates, never matches (candidates_not_matches).

People. No signer, preparer or contact names, phone numbers or street addresses are stored or served. Sponsor responses carry the shared entity_id, identifiers and related blocks; a sponsor is registered only when it is evidently an organisation, and an EIN an SEC company or an exempt organisation also carries resolves to the same entity (exact identifier match).

Endpoints answer 503 while nothing is published; coverage answers 200 either way. Authenticate with an API key in X-API-Key or Authorization: Bearer; the plan must include form-5500.

Sponsors

Search plan sponsors by name prefix (candidates)

GET/v1/form-5500/sponsors

Sponsors whose name on their latest filing starts with name (case-insensitive), optionally in one state, in name order. Candidates, not matches. Paginate with cursor.

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

Parameters

Name	In	Type	Description
namerequired	query	string	Name prefix, 3-100 characters, case-insensitive. Matches names that start with it.
state	query	string	2-letter state code.
limit	query	integer	Page size, 1-100 (default 25).
cursor	query	string	Opaque cursor from `meta.pagination.next_cursor`. Keep the other parameters unchanged while paginating. A cursor from before a new publication, or a tampered one, answers 400.

Responses

200	Candidates.	SearchResponse
400	Invalid parameter (`VALIDATION_ERROR`; `details.fields` maps each parameter to the reason).	Error
401	Missing or invalid API key (`UNAUTHORIZED`), or a disabled, expired or revoked one (`API_KEY_DISABLED`, `API_KEY_EXPIRED`, `API_KEY_REVOKED`).	Error
403	Organization suspended (`ORGANIZATION_SUSPENDED`), no live subscription (`NO_ACTIVE_SUBSCRIPTION`), `form-5500` not on the plan (`PRODUCT_NOT_ENABLED`) or a key scoped to another product (`API_KEY_PRODUCT_SCOPE`).	Error
429	Per-minute rate limit exceeded (`RATE_LIMIT_EXCEEDED`) or monthly quota exhausted (`QUOTA_EXCEEDED`).	Error
503	Nothing the endpoint reads is published yet (`SERVICE_UNAVAILABLE`, `details.datasets`).	Error

curl

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

A plan sponsor and its plans

GET/v1/form-5500/sponsors/{ein}

The sponsor as on its latest filing in scope (name, DBA, city, state, business code), counts of plans and filings, each plan with its latest filing, and the shared entity blocks.

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

Parameters

Name	In	Type	Description
einrequired	path	string	Employer Identification Number, `NNNNNNNNN` or `NN-NNNNNNN`. Example: `942404110`

Responses

200	The sponsor.	SponsorResponse
400	Invalid parameter (`VALIDATION_ERROR`; `details.fields` maps each parameter to the reason).	Error
401	Missing or invalid API key (`UNAUTHORIZED`), or a disabled, expired or revoked one (`API_KEY_DISABLED`, `API_KEY_EXPIRED`, `API_KEY_REVOKED`).	Error
403	Organization suspended (`ORGANIZATION_SUSPENDED`), no live subscription (`NO_ACTIVE_SUBSCRIPTION`), `form-5500` not on the plan (`PRODUCT_NOT_ENABLED`) or a key scoped to another product (`API_KEY_PRODUCT_SCOPE`).	Error
404	No record for the identifier in the published data (`NOT_FOUND`).	Error
429	Per-minute rate limit exceeded (`RATE_LIMIT_EXCEEDED`) or monthly quota exhausted (`QUOTA_EXCEEDED`).	Error
503	Nothing the endpoint reads is published yet (`SERVICE_UNAVAILABLE`, `details.datasets`).	Error

curl

curl -s "https://api.olympus.new-odyssey.com/v1/form-5500/sponsors/942404110" \
  -H "X-API-Key: $OLYMPUS_API_KEY"

Plans

A plan's filings by plan year

GET/v1/form-5500/sponsors/{ein}/plans/{plan_number}

Every filing of the plan in scope (sponsor EIN + 3-digit plan number), newest plan year first, optionally for one plan_year.

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

Parameters

Name	In	Type	Description
einrequired	path	string	Employer Identification Number, `NNNNNNNNN` or `NN-NNNNNNN`. Example: `942404110`
plan_numberrequired	path	string	3-digit plan number (001-999; leading zeros optional). Example: `001`
plan_year	query	integer

Responses

200	The plan's filings (possibly none for a plan_year).	PlanResponse
400	Invalid parameter (`VALIDATION_ERROR`; `details.fields` maps each parameter to the reason).	Error
401	Missing or invalid API key (`UNAUTHORIZED`), or a disabled, expired or revoked one (`API_KEY_DISABLED`, `API_KEY_EXPIRED`, `API_KEY_REVOKED`).	Error
403	Organization suspended (`ORGANIZATION_SUSPENDED`), no live subscription (`NO_ACTIVE_SUBSCRIPTION`), `form-5500` not on the plan (`PRODUCT_NOT_ENABLED`) or a key scoped to another product (`API_KEY_PRODUCT_SCOPE`).	Error
404	No record for the identifier in the published data (`NOT_FOUND`).	Error
429	Per-minute rate limit exceeded (`RATE_LIMIT_EXCEEDED`) or monthly quota exhausted (`QUOTA_EXCEEDED`).	Error
503	Nothing the endpoint reads is published yet (`SERVICE_UNAVAILABLE`, `details.datasets`).	Error

curl

curl -s "https://api.olympus.new-odyssey.com/v1/form-5500/sponsors/942404110/plans/001" \
  -H "X-API-Key: $OLYMPUS_API_KEY"

Coverage

Plan years and files published

GET/v1/form-5500/coverage

The dataset's publication, every file behind it, the plan years loaded and what is excluded. 200 even before anything is published.

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

Responses

200	Coverage.	CoverageResponse
401	Missing or invalid API key (`UNAUTHORIZED`), or a disabled, expired or revoked one (`API_KEY_DISABLED`, `API_KEY_EXPIRED`, `API_KEY_REVOKED`).	Error
403	Organization suspended (`ORGANIZATION_SUSPENDED`), no live subscription (`NO_ACTIVE_SUBSCRIPTION`), `form-5500` not on the plan (`PRODUCT_NOT_ENABLED`) or a key scoped to another product (`API_KEY_PRODUCT_SCOPE`).	Error
429	Per-minute rate limit exceeded (`RATE_LIMIT_EXCEEDED`) or monthly quota exhausted (`QUOTA_EXCEEDED`).	Error

curl

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

Schemas

Error object

The error body shared by every Olympus service.

Field	Type	Description
error *	string	Human-readable message.
code *	string	Stable machine-readable code.
product	string
details	object

Provenance object

Where this record came from and which publication introduced this version of it.

Field	Type	Description
dataset_id *	enum: form5500.filings
source_id *	enum: dol_ebsa.form5500_datasets
source_url *	string (uri)	The published file the record was read from.
source_version *	string	`<file>@<Last-Modified date>`.
source_date *	string (date) \| null	The file's Last-Modified date.
published_at *	string (date-time)	When this version of the record was first published. Unchanged records keep their original time.
schema_version *	string
validation_status *	enum: passed \| passed_with_warnings
record_id *	string	Stable record key.

DatasetPublication object

Field	Type	Description
dataset_id *	string
publication_id *	integer (int64)
published_at *	string (date-time)
freshness *	enum: fresh \| stale

Notice object

Field	Type	Description
code *	enum: candidates_not_matches \| figures_as_filed \| plan_years_in_scope \| not_published
message *	string

Field	Type	Description
limit *	integer
has_more *	boolean
next_cursor *	string \| null

Meta object

Field	Type	Description
request_id	string
datasets *	DatasetPublication []	Active publications of the datasets this response read.
notices *	Notice []
pagination	Pagination

CoverageSource object

Field	Type	Description
source_id *	string
source_version *	string
source_url *	string
source_date *	string (date) \| null

CoverageDataset object

Field	Type	Description
dataset_id *	string
status *	enum: published \| unpublished
publication_id *	integer (int64) \| null
published_at *	string (date-time) \| null
freshness *	enum: fresh \| stale \| unpublished
record_count *	integer (int64) \| null
sources *	CoverageSource []
coverage *	object	The publication's coverage record (files, counts, what is excluded).
excluded *	string

CoverageResponse object

Field	Type	Description
data *	object
meta *	Meta

Identifier object

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 object

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 object

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

RelatedVia object

The identifier the link goes through.

Field	Type	Description
scheme *	string
value *	string

Amount number

US dollars as filed.

Financials object

Field	Type	Description
source *	enum: schedule_h \| schedule_i \| form_5500_sf \| null
total_assets_boy *	Amount
total_assets_eoy *	Amount
total_liabilities_eoy *	Amount
net_assets_boy *	Amount
net_assets_eoy *	Amount
employer_contributions *	Amount
participant_contributions *	Amount
total_income *	Amount
benefits_paid *	Amount
admin_expenses *	Amount
total_expenses *	Amount
net_income *	Amount

Participants object

Field	Type	Description
total_boy *	integer \| null
active_boy *	integer \| null
active_eoy *	integer \| null
total_eoy *	integer \| null	Active
with_account_balances *	integer \| null

Filing object

Field	Type	Description
ack_id *	string	EFAST2 acknowledgement ID.
form_type *	enum: 5500 \| 5500-SF
plan_year *	integer
plan_year_begin *	string (date) \| null
plan_year_end *	string (date) \| null
sponsor_ein *	string
plan_number *	string
plan_name *	string \| null
sponsor_name *	string \| null
sponsor_city *	string \| null
sponsor_state *	string \| null
sponsor_zip *	string \| null
business_code *	string \| null
plan_entity_code *	string \| null
plan_effective_date *	string (date) \| null
initial_filing *	boolean
amended *	boolean
final_filing *	boolean
short_plan_year *	boolean
collectively_bargained *	boolean
pension_benefit_codes *	array of string	DOL characteristic codes, e.g. 2E (profit-sharing), 2J (401(k)).
welfare_benefit_codes *	array of string
participants *	Participants
financials *	Financials
date_received *	string (date) \| null
provenance *	Provenance

PlanSummary object

Field	Type	Description
plan_number *	string
path *	string
latest_filing *	Filing

Sponsor object

Field	Type	Description
ein *	string
entity_id *	string \| null
name *	string \| null
dba *	string \| null
city *	string \| null
state *	string \| null
business_code *	string \| null
plan_count *	integer
filing_count *	integer
first_plan_year *	integer
latest_plan_year *	integer
plans *	PlanSummary []
identifiers *	Identifier []
related *	RelatedLink []
provenance *	Provenance

Plan object

Field	Type	Description
sponsor_ein *	string
plan_number *	string
plan_name *	string \| null
plan_year *	integer \| null
filings *	Filing []

Candidate object

Field	Type	Description
ein *	string
name *	string
city *	string \| null
state *	string \| null
plan_count *	integer
latest_plan_year *	integer
match_basis *	enum: name_prefix
profile *	string

Search object

Field	Type	Description
query *	string
state *	string \| null
match_type *	enum: name_candidates
candidates *	Candidate []

SponsorResponse object

Field	Type	Description
data *	Sponsor
meta *	Meta

PlanResponse object

Field	Type	Description
data *	Plan
meta *	Meta

SearchResponse object

Field	Type	Description
data *	Search
meta *	Meta

* required field

US Employee Benefits & Form 5500 API

Sponsors

Search plan sponsors by name prefix (candidates)

Parameters

Responses

A plan sponsor and its plans

Parameters

Responses

Plans

A plan's filings by plan year

Parameters

Responses

Coverage

Plan years and files published

Responses

Schemas

Error object

Provenance object

DatasetPublication object

Notice object

Pagination object

Meta object

CoverageSource object

CoverageDataset object

CoverageResponse object

Identifier object

IdentifierSource object

RelatedLink object

RelatedVia object

Amount number

Financials object

Participants object

Filing object

PlanSummary object

Sponsor object

Plan object

Candidate object

Search object

SponsorResponse object

PlanResponse object

SearchResponse object