API reference · v1.0.0

US Nonprofit Financial Data API

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

US tax-exempt organisations by EIN, with their Form 990 series figures, from IRS bulk files and with the provenance of every record. Served by the Olympus Go gateway.

Sources. The IRS Exempt Organizations Business Master File extract (EO BMF, the four region CSVs, monthly) for organisations; the IRS Statistics of Income annual extract of tax-exempt organization financial data (Form 990, 990-EZ and 990-PF CSVs) for figures; the IRS Form 990 series e-file XML index for the returns the IRS publishes as XML. GET /v1/nonprofit-financials/coverage lists every file behind every publication, the SOI processing years and the index years loaded.

What is not parsed. The e-file XML returns themselves (about 4.4 GB of ZIPs a year, one document per return in many schema versions) are listed with their object id and IRS ZIP, not parsed. Financial figures come from the SOI extracts: returns the IRS processed in the loaded processing years only (figures_as_filed).

Not a determination. The EO BMF is the IRS's most recent information, extracted monthly. It does not establish current exempt status or deductibility; confirm with the IRS Tax Exempt Organization Search (not_a_determination, links.irs_teos).

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

People. The EO BMF "in care of" name (a person) and street addresses are not stored; officer and compensation detail in the returns is not served. Organisation responses carry the shared entity_id, identifiers and related blocks: an EIN that an SEC company or a Form 5500 plan sponsor also carries resolves to the same entity (exact identifier match).

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

Organizations

Search organisations by name prefix (candidates)

GET/v1/nonprofit-financials/organizations

Organisations whose IRS name starts with name (case-insensitive), optionally in one state, in name order. Candidates, not matches: confirm with the EIN. 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`), `nonprofit-financials` 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/nonprofit-financials/organizations" \
  -H "X-API-Key: $OLYMPUS_API_KEY"

An exempt organisation by EIN

GET/v1/nonprofit-financials/organizations/{ein}

The organisation's EO BMF record: name, city / state / ZIP, NTEE code, subsection, foundation, deductibility and status codes, ruling month, latest tax period, IRS asset and income bands and amounts, plus its most recent SOI figures (latest_financials, null when none are loaded) 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: `530196605`

Responses

200	The organisation.	OrganizationResponse
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`), `nonprofit-financials` 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/nonprofit-financials/organizations/530196605" \
  -H "X-API-Key: $OLYMPUS_API_KEY"

Form 990 series figures and e-filed returns by tax year

GET/v1/nonprofit-financials/organizations/{ein}/financials

Every SOI extract line for the EIN (Form 990, 990-EZ or 990-PF; newest tax period first) and every e-filed return in the loaded TEOS index years, optionally for one tax_year (the year the tax period begins, as the IRS counts it). sections says whether each dataset is published and whether anything was found.

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

Parameters

Name	In	Type	Description
einrequired	path	string	Employer Identification Number, `NNNNNNNNN` or `NN-NNNNNNN`. Example: `530196605`
tax_year	query	integer	Example: `2023`

Responses

200	Figures and returns (possibly none).	FinancialsResponse
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`), `nonprofit-financials` 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/nonprofit-financials/organizations/530196605/financials" \
  -H "X-API-Key: $OLYMPUS_API_KEY"

Coverage

What is published, from which files

GET/v1/nonprofit-financials/coverage

Every dataset with its publication, the files behind it, the SOI processing years and TEOS index years, 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`), `nonprofit-financials` 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/nonprofit-financials/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: nonprofits.organizations \| nonprofits.financials \| nonprofits.efile_returns
source_id *	enum: irs.eo_bmf \| irs.soi_eo_extract \| irs.teos_xml_index
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 \| not_a_determination \| figures_as_filed \| 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

Band object

IRS asset or income code and its dollar range (EO BMF documentation). max null for code 9.

Field	Type	Description
code *	integer
min *	integer (int64)
max *	integer (int64) \| null

Financial object

One return in the SOI extract. Whole dollars as filed; fields not on the form are null.

Field	Type	Description
form *	enum: 990 \| 990EZ \| 990PF
tax_period *	string	YYYY-MM the tax year ends.
tax_year *	integer	The year the tax period begins (990-PF as the IRS publishes it).
processing_year *	integer	SOI processing year of the extract.
efiled *	boolean \| null
subsection *	string \| null
total_revenue *	integer (int64) \| null
total_expenses *	integer (int64) \| null	990: total functional expenses; 990-PF: total expenses (books).
contributions *	integer (int64) \| null
program_service_revenue *	integer (int64) \| null
investment_income *	integer (int64) \| null
total_assets_eoy *	integer (int64) \| null
total_liabilities_eoy *	integer (int64) \| null
net_assets_eoy *	integer (int64) \| null
fair_market_value_eoy *	integer (int64) \| null	990-PF only.
provenance *	Provenance

EfileReturn object

One e-filed return in the IRS TEOS XML index (the XML is not parsed).

Field	Type	Description
object_id *	string
return_type *	string
tax_period *	string \| null
submission_year *	integer \| null
taxpayer_name *	string \| null
dln *	string \| null
index_year *	integer
xml_batch_id *	string \| null
xml_batch_url *	string \| null	The IRS ZIP that holds the return.
provenance *	Provenance

Organization object

Field	Type	Description
ein *	string
entity_id *	string \| null	Olympus entity of the EIN (null when not registered).
name *	string
sort_name *	string \| null	Secondary name line.
city *	string \| null
state *	string \| null
zip *	string \| null
ntee_code *	string \| null
subsection *	string \| null
classification *	string \| null
affiliation *	string \| null
group_exemption *	string \| null
deductibility *	string \| null	1 deductible
foundation *	string \| null
organization *	string \| null
exempt_status *	string \| null
ruling_month *	string \| null
tax_period *	string \| null
accounting_period *	string \| null
filing_requirement *	string \| null
pf_filing_requirement *	string \| null
asset_band *	Band \| null
income_band *	Band \| null
asset_amount *	integer (int64) \| null
income_amount *	integer (int64) \| null
revenue_amount *	integer (int64) \| null
latest_financials *	Financial \| null
links *	object
identifiers *	Identifier []
related *	RelatedLink []
provenance *	Provenance

Financials object

Field	Type	Description
ein *	string
name *	string \| null
tax_year *	integer \| null
financials *	Financial []
efile_returns *	EfileReturn []
sections *	object

Candidate object

Field	Type	Description
ein *	string
name *	string
sort_name *	string \| null
city *	string \| null
state *	string \| null
ntee_code *	string \| null
subsection *	string \| null
match_basis *	enum: name_prefix
profile *	string

Search object

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

OrganizationResponse object

Field	Type	Description
data *	Organization
meta *	Meta

FinancialsResponse object

Field	Type	Description
data *	Financials
meta *	Meta

SearchResponse object

Field	Type	Description
data *	Search
meta *	Meta

* required field

US Nonprofit Financial Data API

Organizations

Search organisations by name prefix (candidates)

Parameters

Responses

An exempt organisation by EIN

Parameters

Responses

Form 990 series figures and e-filed returns by tax year

Parameters

Responses

Coverage

What is published, from which files

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

Band object

Financial object

EfileReturn object

Organization object

Financials object

Candidate object

Search object

OrganizationResponse object

FinancialsResponse object

SearchResponse object