API Reference: version 0.4.

8
Introduction

This documentation covers the main API (the so-called REST API). The API provides all the
information available on the OpenCorporates website as data. By default it returns data as
JSON, but XML is also available.
Access to all the data is free for open data projects under the same open licence conditions
as the rest of OpenCorporates. An API key is required in order to use the OpenCorporates
API, and usage limits depend on your account type and plan.
If you are matching company names to legal entities from an existing dataset, you should
investigate using Open Refine, software which allows data to be filtered and cleansed more
easily and more quickly than any other tool we know of. OpenCorporates provides a highly
popular reconciliation API for Open Refine, which allows matching company names to legal
entities.

Getting started

The endpoint is api.opencorporates.com. We currently support both http and https, but are
likely to move to https only in the near future, so all users are suggested to use the secure
endpoint

The API by default returns JSON, a lightweight but powerful way of representing data that is
natively understood by Javascript (and therefore perfect for widgets, etc), with excellent
libraries for all programming languages. It's also fairly easy to understand for humans.

For example the response to

https://api.opencorporates.com/companies/nl/17087985

is

{
"api_version": "0.2",
"results": {
"company": {
"name": "Bover B.V.",
"company_number": "17087985",
"jurisdiction_code": "nl",
"incorporation_date": null,
 "dissolution_date": null,
"company_type": "Besloten Vennootschap",
"registry_url": "https://server.db.kvk.nl/TST-BIN/FU/TSWS001@?BUTT=17087985",
"branch": null,
"branch_status": null,
"inactive": false,
"current_status": "Active",
"created_at": "2011-01-12T21:50:57+00:00",
"updated_at": "2012-02-02T10:36:46+00:00",
"retrieved_at": "2011-08-25T14:37:37+01:00",
"opencorporates_url": "https://opencorporates.com/companies/nl/17087985",
"previous_names": null,
"source": {
"publisher": "OpenKVK.nl",
"url": "https://www.openkvk.nl/17087985",
"retrieved_at": "2011-08-25T14:37:37+01:00"
},
"corporate_groupings": [],
"data": {
"most_recent": [
{
"datum": {
"id": 2457732,
"title": "SEC Edgar entry",
"data_type": "OfficialRegisterEntry",
"description": "register id: 1434782",
"opencorporates_url": "https://opencorporates.com/data/2457732"
}
},
{
"datum": {
"id": 2457731,
"title": "Company Address",
"data_type": "CompanyAddress",
"description": "BOKSHEIDE 20, EERSEL P7 5521 PM",
"opencorporates_url": "https://opencorporates.com/data/2457731"
}
}
],
"total_count": 2,
"url": "https://opencorporates.com/companies/nl/17087985/data"
},
"filings": [],
"officers": []
}
}
}

Best practices:
Always use the most up-to-date version, and set the version in your requests (that way if
the default version changes your code will still work).

Use the https endpoint - this may become mandatory in the future, and ensures that your
API key won't be stolen.
Use the GET /account_status call to keep an eye on your daily/monthly usage to ensure you
don't run out of API calls. Daily usage refreshes at midnight UTC each day, and monthly
usage refreshes at midnight UTC on the last day of the month.

Statements vs Data

At OpenCorporates we're obsessive about provenance of data – it not only gives confidence
in the data by showing the source, and how fresh it is, it also allows errors to be tracked
down and fixed, and provides essential context for the data, allowing it to be incorporated
in all sorts of different models and uses. This is particularly critical when incorporating such
tricky things as corporate relationships, and we think that in the future, 'black box'
company data will become recognized as being highly problematic.

The underlying model for data items attached to companies in OpenCorporates (e.g. a
telephone number) was the 'datum', but we have since improved this adding even more
granularity and more detail to the provenance data. As part of this we have moved to a
'statement' data model rather than the 'datum' model. Over the next few months, we will be
migrating all 'datum' items to 'statement' ones. After these migrations, calls to existing
datum/[:id] endpoints will still continue to work for some time; however, the data will not
be further updated.

Universal attributes/objects

Response

There are two parts to the response: the data that comprises the results, and this is
wrapped inside a results object/tag; and meta data, including the api version that was used
(useful if none was explicitly requested). XML responses are wrapped in a 'Response' root
object.
All objects are returned as JSON by default. We also (as of version 0.2) can return XML if
preferred. Simply add format=xml as a query parameter, e.g.
https://api.opencorporates.com/v0.4/companies/gb/00102498?format=xml

or
https://api.opencorporates.com/v0.4/companies/search?q=barclays+bank&format=xml

OpenCorporates URL

All objects are returned with their OpenCorporates URL. This has two benefits: it makes it
easy to get the api URL for the given object, by just prefixing the url with 'api.' (e.g. from
https://opencorporates.com/companies/gb/00102498

to
https://api.opencorporates.com/companies/gb/00102498

and it allows the OpenCorporates URL for the object to be linked to, as attribution
(remember, OpenCorporates' rights to the data are under the share-alike attribution Open
Database Licence).

Pagination

Those calls returning a number of results (e.g. searches, or filings for a company) return a
paginated response. By default 30 objects are returned, together with the current page
number, and total number of pages. The number per page can be increased (to up to 100)
by supplying a :per_page query parameter, and the page number is specified with the :page
query parameter (the :page parameter is limited to 100 to ensure that the API is as fast as
possible for all users).

The OpenCorporates provenance object

At OpenCorporates we're obsessive about provenance of data, and so we always make it

clear when information came from (and when it was retrieved). The provenance object is
gradually replacing the source object, and provides a greater granularity of data, as well as
additional attributes such as confidence and, sometimes, log messages.
Provenances are attached to multiple objects in the OpenCorporates system,
including statements and placeholders, but also the links between, for example,
placeholders and companies, or between placeholders and statements. This blog post gives
more detailed about the provenance model in OpenCorporates and we will be blogging
about it further in the future.
The provenance object consists of the following:

this is url from which the data was obtained, or the OpenCorporates url for
source_url
the user, if it was contributed by a user

a confidence that the associated data object is correct (numeric value

confidence between 0 and 100). We will be publishing more about this value in the
future

the type of source. Possible values are 'external' (i.e. data from a public
source, such as a company register, or government website), 'internal' (i.e.
source_type
data within the OpenCorporates system), or 'induction' (for example where
data has been reconciled to a company by OpenCorporates)

the type of the 'actor' that contributed the data. Possible values are 'bot' (an
actor_type OpenCorporates Bot) or 'user' (in which case the source_url will contain a
link to the user page on OpenCorporates)

a note on the source, particularly if the data was added by a user (e.g. a
log_message
corporate network relationship)

the date the provenance was created (and thus the date we retrieved the
data or made the match). Note we often regularly check statements are true,
created_at
and therefore a statement may have many provenances, which act as
timestamps for the statement

The OpenCorporates source object

The detailed responses all include the provenance of the data as a source object, consisting
of the following:

a timestamp of when the information was retrieved from the source, or the
retrieved_at
data was created.

this is either 'user' if the information was contributed by a user, or 'external'

source_type
if the information was obtained from an external source.

where the information was retrieved from. This may be the URL of a specific
datum, or the download URL of a data_dump, or if this is not available the
url
URL of the publisher. If the information was user-contributed it will be the
OpenCorporates url of the user.
 If the information came from an external source, this is the original publisher
publisher of the information; if the information was user-contributed, this will be the
user's name.

if we are aware that the external publisher of the data has applied an explicit
licence to the data (e.g. in the UK it is often Crown Copyright, or sometimes
terms
the Open Government Licence). A Null value for this does *not* imply there
is no underlying licence.

Filter types

Date filter
Date filters can be supplied either as a specific date or as a date range. If a date range is
given it should be in the form 2009-08-22:2012-01-08. Either the start date or the end date
may be omitted to make the date range unbounded at the start or end, e.g. :2012-01-
08 would represent any date before 8 Jan 2012.

Term filter
Term filters can be supplied as a single term, a comma separated list (the record must
match all terms; e.g. foo,bar,baz), or a pipe separated list (the record need only match one
term; e.g. foo|bar|baz).

Method calls

GET versions
Description: This returns the current version of the API and supported versions. If a specific
version has been requested it also returns the requested version.
Example:
https://api.opencorporates.com/v0.4/versions

{
"results": {
"versions": {
"current_version": "0.4",
"requested_version": "0.3",
"supported_versions": [
"0.3",
"0.4"
]
}
 }
}

GET companies/:jurisdiction_code/:company_number
Description: This returns the core data for the given company. The jurisdiction code is the
code for the jurisdiction which registered the company. If this is a country it is simply the
two-letter ISO code for that country, e.g. Spain = es, United Kingdom = gb. If this is a state or
province it is an underscore version of the ISO 3166-2 code for the jurisdiction, eg. Michigan
in the US is us_mi.
Included in the response will be the core data on the company (incorporation date,
company type, registered address, etc), a summary of other data held on the company (e.g.
trademarks, payments from government, other addresses), including the most recently
added data, and the most recent statutory filings, and parent company, if we have this
information (see the company_network method call for more detailed hierarchy data). If
you don't need the filings and the other data, or believe there are not likely to be such
results, you can pass sparse=true as a query parameter, and this will be both quicker, and
potentially a considerably smaller response.

name the legal name of the company

the identifier given to the company by the company

company_number
register

the code for the jurisdiction in which the company is

jurisdiction_code
incorporated

the type of company (e.g. LLC, Private Limited

company_type
Company, GBMH)

current_status the given description of the filing

incorporation_date the date the company was incorporated

dissolution_date the date the company was dissolved

 a flag indicating if the company is 'inactive'. This is an
OpenCorporates mapping from a number of different
inactive company statuses, including dissolved,
inactive removed, liquidated, etc. Note that not all companies
make company statuses available, so that it cannot be
inferred that a company is active just because inactive
is not true

opencorporates_url the url of the company on OpenCorporates

an array of previous name objects. Each previous

name object has a company_name attribute and type
attribute (e.g. 'trading', 'legal') and the following
previous_names
optional attributes: start_date, end_date, language as
ISO-639 code (for example if it is an alternative legal
name in another language)

an array of alternative name objects. Each alternative

name object will has a company_name attribute and an
alternative_names optional con_date attribute, which is the date the
company's name changed from the previous name
(and thus can be considered to be an end_date)

NEWan array of alternate registration objects (the

same company represented in another official
registration e.g when more than one headquarters is
alternate_registration_entities
registered). Each alternate registration object will
have company_name, jurisdiction_code,
company_number and opencorporates_url attributes.

NEWan array of previous registration objects. Previous

or superseded registrations are registrations of the
same company, which came earlier and have been
previous_registration_entities superseded by the requested company. Each previous
registration object will have company_name,
jurisdiction_code, company_number and
opencorporates_url attributes.

NEWan array of subsequent registration objects (a

registration of the same company, which came later
and supersedes the requested company). Each
subsequent_registration_entities
subsequent registration object will have
company_name, jurisdiction_code, company_number
and opencorporates_url attributes.
 the registered address of the company, as a single
registered_address_in_full
string

the registered address of the company, as a structured

registered_address
object

an array of industry_codes representing the industries

industry_codes the company operates in (see below for more on
industry_codes).

an array of identifier objects, including the identifier

system name and code, and the identifier uid. For
example for Canadian business numbers the uid would
identifiers be the business number (e.g. "800322042RC0001")
and "ca_bn" for the identifier_system_code and
"Canadian Business Number" for the
identifier_system_name

the url of the companies page in the company register.

registry_url Note, not all company registers provide persistent urls
for the companies in the register

This is the controlling parent of the company in

question, and is derived either from explicit subsidiary
controlling_entity
or parent data, or from a company having a majority
equity stake in the company

These are the ultimate beneficial owners of the

ultimate_beneficial_owners
company in question, if we know them

This is the ultimate controlling parent of the company

ultimate_controlling_company in question, if we know them. It is equivalent to the
Controlling Company section on the Website.

a flag to indicate if a company is a 'branch'. If the flag is

'F' it indicates this the entry in the company register
relates to an an out-of-jurisdiction company
(sometimes called a 'foreign corporation' in the US). If
branch it is 'L' it is a local office of a company (few company
registers collect this information). If it is null value, it
means either the company is not a branch, or the
company register does not make the information
available
 branch_status a descriptive text version of the 'branch' flag

when a company is a branch of an out-of-jurisdiction

company, this is the 'home' company (if we know it),
home_company
including the name, jurisdiction_code,
company_number and opencorporates_url

Note: We very very occasionally temporarily redact information on a company to allow the
official record to be changed (see OpenCorporates Temporary Redaction for details). In this
case, an error message with a 503 HTTP response code will be returned.
Example:
https://api.opencorporates.com/v0.4/companies/gb/00102498
https://api.opencorporates.com/v0.4/companies/gb/00102498?sparse=true

{
"api_version": "0.4",
"results": {
"company": {
"branch_status": null,
"company_number": "00102498",
"company_type": "Public Limited Company",
"corporate_groupings": [
{
"corporate_grouping": {
"name": "bp",
"opencorporates_url": "https://opencorporates.com/corporate_groupings/bp",
"updated_at": "2014-02-16T11:22:24+00:00",
"wikipedia_id": "BP"
}
}
],
"created_at": "2010-10-21T18:20:50+01:00",
"current_status": "Active",
"data": {
"most_recent": [
{
"datum": {
"data_type": "CompanyAddress",
"description": "1 St James's Square, London SW1Y 4PD, GB",
"id": 9788778,
"opencorporates_url": "https://opencorporates.com/data/9788778",
"title": "Company Address"
}
},
{
 "datum": {
"data_type": "Website",
"description":
"http://www.bp.com/sectiongenericarticle.do?categoryId=9021231&contentId=7039279",
"id": 8474113,
"opencorporates_url": "https://opencorporates.com/data/8474113",
"title": "Website"
}
},
{
"datum": {
"data_type": "OfficialRegisterEntry",
"description": "register id: 313807",
"id": 2452824,
"opencorporates_url": "https://opencorporates.com/data/2452824",
"title": "SEC Edgar entry"
}
}
],
"total_count": 125,
"url": "https://opencorporates.com/companies/gb/00102498/data"
},
"dissolution_date": null,
"filings": [
{
"filing": {
"date": "2014-02-13",
"id": 199825350,
"opencorporates_url": "https://opencorporates.com/filings/199825350",
"title": "Return of purchase of own shares",
"uid":
"284acfeJxjZRd2YnXi4ohPyU9OSS1OBnHYQJzMFCdxfgMDA0djQy9/Cw8TUxMzAycuzvi0/KLcksqCVCdxlmAPA2MnLt
b4lOTEEidxRguYMYklQFkOIwNDEwMjQ+MmNef83ILEvMzUYo/80uJUK6sIXx/3cCsrz9zE9FQo5Z1aSaQybgYGBkYgZ
gJiZiBmAWJWIGYDYnYg5gBiTiDmAmJuANC4NJA="
}
},
{
"filing": {
"date": "2014-02-13",
"id": 199825349,
"opencorporates_url": "https://opencorporates.com/filings/199825349",
"title": "Notice of cancellation of shares",
"uid":
"771a5aeJxjZRd2YnXi4ohPyU9OSS1OBnHYQJzMFCdxfgMDA0djQy9/iwBXUxMzAycuzvi0/KLcksqCVCdxlmAPAzMnLt
b4lOTEEidxRkuYMYklQFkOIwNDEwMjQ+MmNef83ILEvMzUYo/80uJUK6sIXx/3cCsrz9zE9FQo5Z1aSaQybgYGBkYgZ
gJiZiBmAWJWIGYDYnYg5gBiTiDmAmJuAOT2NK0="
}
}
],
"inactive": false,
"incorporation_date": "1909-04-14",
"industry_codes": [
{
"industry_code": {
"code": "70100",
"description": "Activities of head offices",
"code_scheme_id": "uk_sic_2007",
"code_scheme_name": "UK SIC Classification 2007"
}
}
],
"jurisdiction_code": "gb",
"name": "BP P.L.C.",
"officers": [
{
"officer": {
"end_date": null,
"id": 32609673,
"name": "DAVID JOHN JACKSON",
"opencorporates_url": "https://opencorporates.com/officers/32609673",
"position": "secretary",
"start_date": "2003-07-24",
"uid": null
}
},
{
"officer": {
"end_date": "2012-03-30",
"id": 32609674,
"name": "DAVID JOHN PEARL",
"opencorporates_url": "https://opencorporates.com/officers/32609674",
"position": "secretary",
"start_date": "2001-11-01",
"uid": null
}
},
{
"officer": {
"end_date": null,
"id": 32609675,
"name": "PAUL MILTON ANDERSON",
"opencorporates_url": "https://opencorporates.com/officers/32609675",
"position": "director",
"start_date": "2010-02-01",
"uid": null
}
 },
{
"officer": {
"end_date": null,
"id": 32609676,
"name": "FRANK BOWMAN",
"opencorporates_url": "https://opencorporates.com/officers/32609676",
"position": "director",
"start_date": "2010-11-08",
"uid": null
}
}
],
"opencorporates_url": "https://opencorporates.com/companies/gb/00102498",
"previous_names": [
{
"company_name": "BP AMOCO P.L.C.",
"con_date": "2001-05-01"
},
{
"company_name": "THE BRITISH PETROLEUM COMPANY P.L.C.",
"con_date": "1998-12-31"
}
],
"alternate_registration_entities": [],
"previous_registration_entities": [],
"subsequent_registration_entities": [],
"registered_address_in_full": "1 ST JAMES'S SQUARE, LONDON, SW1Y 4PD",
"registry_url": "http://data.companieshouse.gov.uk/doc/company/00102498",
"retrieved_at": "2014-02-16T10:06:59+00:00",
"source": {
"publisher": "UK Companies House",
"retrieved_at": "2014-02-16T10:06:59+00:00",
"terms": "UK Crown Copyright",
"url": "http://xmlgw.companieshouse.gov.uk/"
},
"updated_at": "2014-02-16T10:07:06+00:00"
}
}
}

GET companies/search
Description: This returns a collection of companies whose name matches the given search
term (submitted as :q in the query parameters). It's important to note that the search is
deliberately quite loose, requiring the returned companies to have all the searched-for
words (in any order), but allowing other words to be present too (so 'Bank Barclays' is the
same as 'Barclays Bank').

The search is case-insensitive and returns companies with previous names matching the
term as well as current name, and some normalisation of the company names is done,
removing non-text characters (e.g. dashes, parentheses, commas), common 'stop words'
(e.g. 'the', 'of'), and normalising common company types (e.g. Corp, Inc, Ltd, PLC) so that
both the short and long versions can be used.
The companies are returned in alphabetic order by default but you can return ordered by
score (as ranked by our ElasticSearch search index by passing the order=score query
parameter. The response is paginated (see pagination).

From v0.4, the company information returns the registered address if known.
Use of the wildcard '*': You can also search for company names beginning with the given
search term by ending the term with a '*', so that 'Barclays Bank*' will match 'Barclays Bank
PLC' but not 'Barclays UK Bank', 'Barclays Big Bank' or 'Local Barclays Branch'.
Facet restrictions: You can restrict the results by a number of 'facets' to allow extremely
powerful searching and exploring of the data, combining with company names or part of
names.

The companies searched for can be restricted to a given

jurisdiction_codeTerm filter
jurisdiction by passing a jurisdiction_code query parameter.

The companies searched for can be restricted to a given

country by passing a country_code query parameter. Note
country_codeTerm filter that in most cases the country and jurisdiction are the same,
but for multi-jurisdiction country such as the US or Canada
this can be very useful.

company_typeTerm filter The type of the company, as defined by the company register.

The current status of the company, as defined by the

current_statusTerm filter
company register.

One or more industry codes representing the industries the

company operates in. The codes can be those in the
industry_codesTerm filter
company's jurisdiction's native code scheme, or any mapped
schemes, or any parent of those codes (when the schemes are
 hierarchical). The values submitted should be the
industry_code uid, consisting of the
industry_code :code_scheme_id and :code joined with a
hyphen (see below for more on industry_codes).

The companies searched for can be restricted by passing in

an address or parts of an address. This performs a similar
registered_addressTerm search to the basic companies search, so searching for '52
filter London' will search for address with 52 and London in them,
e.g. '52 Acacia Ave, London, NW1', or '52 London Road, St
Albans'

created_atDate filter Companies added to OpenCorporates on the given date.

incorporation_dateDate filter Companies incorporated on the given date

dissolution_dateDate filter Companies dissolved on the given date

DEPRECATEDRestrict to companies added to OpenCorporates

created_before before the given date (ISO 8601 format). Deprecated in
favour of new created_at functionality.

DEPRECATEDRestrict to companies added to OpenCorporates

created_since after the given date (ISO 8601 format). Deprecated in favour
of new created_at functionality.

DEPRECATEDRestrict to companies with an

incorporation_date before the given date (ISO 8601 format).
incorporated_before
Deprecated in favour of new incorporation_date
functionality.

DEPRECATEDRestrict to companies with an

incorporation_date after the given date (ISO 8601 format).
incorporated_since
Deprecated in favour of new incorporation_date
functionality.

DEPRECATEDRestrict to companies with a dissolution_date

dissolved_before before the given date (ISO 8601 format). Deprecated in
favour of new dissolution_date functionality.
 DEPRECATEDRestrict to companies with a dissolution_date
dissolved_since after the given date (ISO 8601 format). Deprecated in favour
of new dissolution_date functionality.

DEPRECATEDRestrict to companies that are active/inactive.

exclude_inactive
Deprecated in favour of new inactive functionality.

Filter by inactive status (boolean). This replaces the

exclude_inactive filter from previous versions. If true is
inactive supplied it will restrict to inactive companies. If false is
supplied it will exclude inactive companies. If no value is
supplied it will not filter by inactive status.

Filter by branch status (boolean). This replaces the

exclude_branches filter from previous versions. If true is
branch supplied it will restrict to branch companies. If false is
supplied it will exclude branch companies. If no value is
supplied it will not filter by branch status.

Filter by nonprofit company type (boolean). If true is

supplied it will restrict to entities that we have identified as
nonprofit being of nonprofit company type. If false is supplied it will
exclude such companies. If no value is supplied it will not
filter by nonprofit company type.

The companies searched for can be restricted to those with

identifier_uidsTerm filter the given third-party identifier, such as business or charity
numbers, tax identifiers, etc.

By default when searching with a term (e.g. 'Barclays Bank')

it looks for a match in name, normalised_name, and
previous_names fields. Using the fields parameter gives you
more control over which fields to search in. This allows
access to additional fields like company_number or
postal_code and also gives the ability to exclude some of the
fields
default fields (e.g. when searching in previous names is not
desired). Options are name, normalised_name,
company_number, heavily_normalised_number (company
number excluding leading zeroes, for example),
native_company_number, previous_names, postal_codes,
trademark_registration_mark_texts.

Normalise company name before searching for it (boolean).

normalise_company_name
Unlike the main OpenCorporates website, the API does not
 normalise the company name before searching for it (so that
restrictions work effectively). If true is supplied, this will
normalise the submitted company name before searching (so
that Ltd will be normalised to Limited, Corp to Corporation
etc).

Filter results by companies that have the supplied types of

types_of_data_heldTerm filter related data. For valid options see the list visible when using
the search feature on opencorporates.com.

Additional sorting options (from v0.4): Users can also sort by 4 date fields (all in reverse
order, i.e. newest first):

created_at a timestamp of when the company was added to OpenCorporates.

the datetime the company was updated in any way. The company
updated_at record will be considered to be updated in many circumstances,
including when any associated data is changed.

the date of incorporation as given by the company register. Please

incorporation_date
note that not all company registries record and publish this date.

the date of dissolution as given by the company register. Please note

dissolution_date
that not all company registries record and publish this date.

Example:
https://api.opencorporates.com/v0.4/companies/search?q=barclays+bank
https://api.opencorporates.com/v0.4/companies/search?q=barclays&per_page=50&page=2
https://api.opencorporates.com/v0.4/companies/search?q=barclays+bank&jurisdiction_code=gb
https://api.opencorporates.com/v0.4/companies/search?q=barclays+bank*&jurisdiction_code=gb
https://api.opencorporates.com/v0.4/companies/search?q=barclays+bank&jurisdiction_code=gb&c
urrent_status=Active
https://api.opencorporates.com/v0.4/companies/search?q=bank+of+scotland
https://api.opencorporates.com/v0.4/companies/search?q=bank+of+scotland&order=score
https://api.opencorporates.com/v0.4/companies/search?q=bank+of+scotland&inactive=false
https://api.opencorporates.com/v0.4/companies/search?q=bank+of+scotland&order=incorporation
_date
https://api.opencorporates.com/v0.4/companies/search?q=bank+of+scotland&order=incorporation
_date&incorporation\date=2013-12-03:2014-05-22
https://api.opencorporates.com/v0.4/companies/search?q=bank+of+scotland&fields=name,previou
s_names
https://api.opencorporates.com/v0.4.1/companies/search?industry_codes=eu_nace_2-
869,eu_nace_2-691
{
"api_version": "0.4",
"results": {
"companies": [
{
"company": {
"branch_status": null,
"company_number": "SC024750",
"company_type": null,
"created_at": "2011-04-24T11:14:25+01:00",
"current_status": "Dissolved",
"dissolution_date": null,
"inactive": true,
"incorporation_date": null,
"jurisdiction_code": "gb",
"name": "ABERDEEN BANK OF SCOTLAND NOMINEES LIMITED",
"opencorporates_url": "https://opencorporates.com/companies/gb/SC024750",
"previous_names": null,
"registry_url": "http://data.companieshouse.gov.uk/doc/company/SC024750",
"retrieved_at": null,
"source": {
"publisher": "UK Companies House",
"retrieved_at": null,
"terms": "UK Crown Copyright",
"url": "http://xmlgw.companieshouse.gov.uk/"
},
"updated_at": "2014-01-18T22:44:40+00:00",
"registered_address_in_full": null
}
},
{
"company": {
"branch": "F",
"branch_status": "branch of an out-of-jurisdiction company",
"company_number": "344214",
"company_type": "Alien Corporations (RICO) - Foreign",
"created_at": "2011-09-30T12:52:25+01:00",
"current_status": "Active/Compliance",
"dissolution_date": null,
"inactive": false,
"incorporation_date": "2005-03-28",
"jurisdiction_code": "us_ga",
"name": "BANK OF SCOTLAND",
"opencorporates_url": "https://opencorporates.com/companies/us_ga/344214",
"previous_names": [],
"registry_url": "http://corp.sos.state.ga.us/corp/soskb/Corp.asp?344214",
"retrieved_at": "2011-10-04T15:15:15+01:00",
"source": {
 "publisher": "Georgia Secretary of State",
"retrieved_at": "2011-10-04T15:15:15+01:00",
"url": "http://corp.sos.state.ga.us/corp/soskb/Corp.asp?344214"
},
"updated_at": "2014-02-16T16:18:16+00:00",
"registered_address_in_full": "THE MOUND,EDINBURGH,EHI 1YZ, SCOTLAND ZF"
}
},
{
"company": {
"branch": "F",
"branch_status": "branch of an out-of-jurisdiction company",
"company_number": "601846892",
"company_type": "BNK",
"created_at": "2011-09-15T07:34:40+01:00",
"current_status": "Active",
"dissolution_date": null,
"inactive": false,
"incorporation_date": "1998-01-21",
"jurisdiction_code": "us_wa",
"name": "BANK OF SCOTLAND",
"opencorporates_url": "https://opencorporates.com/companies/us_wa/601846892",
"previous_names": null,
"registry_url": "http://www.sos.wa.gov/corps/search_detail.aspx?ubi=601846892",
"retrieved_at": "2013-03-06T16:59:21+00:00",
"source": {
"publisher": "Washington Secretary of State - Corporations Division",
"retrieved_at": "2013-03-06T16:59:21+00:00",
"url": "http://www.sos.wa.gov/corps/search_detail.aspx?ubi=601846892"
},
"updated_at": "2014-02-06T17:44:27+00:00",
"registered_address_in_full": null
}
}
],
"page": 1,
"per_page": 30,
"total_count": 190,
"total_pages": 7
}
}

GET companies/:jurisdiction_code/:company_number/filings
Description: This returns the statutory filings for the given company. Each filing will be
returned with the date of filing, the OpenCorporates id and url for the filing, and one or
many of the following

uid the id given to the filing by the company registry

this is either the given title of the filing, or the filing_type, or a generic
title field containing a human-friendly version of the date. This means that
every filing can be relied upon to have a filing_title

description the given description of the filing

the url of the filing. This may be a url of an HTML page, or of the
url document itself, for those more enlightened jurisdictions which make
this available without charge

a human-readable name of the type of filing. This might have been

filing_type_name
computed from the filing_code

filing_code the code given by the company registry to this type of filing

The response is paginated (see pagination).

Example:
https://api.opencorporates.com/v0.4/companies/gb/00102498/filings
https://api.opencorporates.com/v0.4/companies/gb/00102498/filings?page=2

{
"api_version": "0.4",
"results": {
"filings": [
{
"filing": {
"date": "2014-02-13",
"description": "RETURN OF PURCHASE OF OWN SHARES",
"filing_code": "SH03",
"filing_type": "Return of purchase of own shares",
"id": 199825350,
"opencorporates_url": "https://opencorporates.com/filings/199825350",
"title": "Return of purchase of own shares",
"uid":
"284acfeJxjZRd2YnXi4ohPyU9OSS1OBnHYQJzMFCdxfgMDA0djQy9/Cw8TUxMzAycuzvi0/KLcksqCVCdxlmAPA2MnLt
b4lOTEEidxRguYMYklQFkOIwNDEwMjQ+MmNef83ILEvMzUYo/80uJUK6sIXx/3cCsrz9zE9FQo5Z1aSaQybgYGBkYgZ
gJiZiBmAWJWIGYDYnYg5gBiTiDmAmJuANC4NJA=",
 "url": null
}
},
{
"filing": {
"date": "2014-02-13",
"description": "13/02/14 STATEMENT OF CAPITAL GBP 12706252, 13/02/14
STATEMENT OF CAPITAL USD 5084797994.75",
"filing_code": "SH06",
"filing_type": "Notice of cancellation of shares",
"id": 199825349,
"opencorporates_url": "https://opencorporates.com/filings/199825349",
"title": "Notice of cancellation of shares",
"uid":
"771a5aeJxjZRd2YnXi4ohPyU9OSS1OBnHYQJzMFCdxfgMDA0djQy9/iwBXUxMzAycuzvi0/KLcksqCVCdxlmAPAzMnLt
b4lOTEEidxRkuYMYklQFkOIwNDEwMjQ+MmNef83ILEvMzUYo/80uJUK6sIXx/3cCsrz9zE9FQo5Z1aSaQybgYGBkYgZ
gJiZiBmAWJWIGYDYnYg5gBiTiDmAmJuAOT2NK0=",
"url": null
}
},
{
"filing": {
"date": "2014-02-13",
"description": "13/02/14 STATEMENT OF CAPITAL GBP 12706252, 13/02/14
STATEMENT OF CAPITAL USD 5086635494.75",
"filing_code": "SH06",
"filing_type": "Notice of cancellation of shares",
"id": 199825348,
"opencorporates_url": "https://opencorporates.com/filings/199825348",
"title": "Notice of cancellation of shares",
"uid":
"6122e4eJxjZRd2YnXi4ohPyU9OSS1OBnHYQJzMFCdxfgMDA0djQy9/iwBfUxMzAycuzvi0/KLcksqCVCdxlmAPAzMnLt
b4lOTEEidxRkuYMYklQFkOIwNDEwMjQ+MmNef83ILEvMzUYo/80uJUK6sIXx/3cCsrz9zE9FQo5Z1aSaQybgYGBkYgZ
gJiZiBmAWJWIGYDYnYg5gBiTiDmAmJuAOqmNLU=",
"url": null
}
} ],
"page": 1,
"per_page": 30,
"total_count": 676,
"total_pages": 23
}
}

GET companies/:jurisdiction_code/:company_number/network
Description: This returns the immediate 'computed corporate network' for the given
company as a set of control relationships (i.e. one company is thought to control or
influence another company). This is the same data you can see on a company's network
page on the main OpenCorporates site.
A control relationship is a relationship of control from one company to another. The
relationship type can be found in the api response. Relationships are directional and we use
the terms 'parent' and 'child' to indicate the direction of the relationships. For example, if
'Company A' is a subsidiary of 'Company B', then the api response would
read {parent_name: Company B, child_name: Company A, relationship_type:

has_subsidiary"}. Conversely, if 'Company B' is a subsidiary of 'Company A', then the api

response would be {parent_name: Company A, child_name: Company B,

relationship_type: has_subsidiary"}

These relationships are computed automatically from a number of relationship statements

associated with each company, and the network will change as more statements are added,
because for example new relationships are discovered, or statements are added which say
that a previous statement is no longer true (see statements for more details), or even that
our algorithms for calculating relationships are improved.

Each relationship is made of the following attributes:

the type of relationship, e.g. subsidiary, shareholding. A

subsidiary relationship typically comes from statutory
relationship_type
filings (e.g. SEC 10-K reports); shareholding information
typically coms from company registers, and is more granular

any additional properties of the relationship, e.g. ownership

relationship_properties
percentage

a computed confidence in the relationship based on the

confidence
underlying statements

parent_name the name of the parent entity

parent_type the type of entity the parent is

parent_opencorporates_url the OpenCorporates URL of the parent entity

 child_name the name of the child entity

child_type the type of entity the child is

child_opencorporates_url the OpenCorporates URL of the child entity

The response is not paginated and can return no results (if we have no known
relationships) or hundreds of relationships. It currently returns just a depth of 1 (i.e. just
immediate parents and children). We are looking at adding greater levels of depth. Note the
related entities may be companies, or placeholders. Placeholders are objects that we
haven't yet matched to a company, either because we don't have the companies in that
jurisdiction, or because we can't confidently match it to a company. To allow the network to
be 'walked', you can also make network requests for placeholders, e.g. A Company controls
B Placeholder controls C Company. Note that some networks are circular (A controls B,
which controls C, which controls A), and you should allow for this when making repeated
network calls so that you do not get stuck in an endless loop.
Filter options:

a computed confidence in the relationship based on the

underlying statements (between 0 and 100). Only relationships
confidence above this confidence will be returned (the default value here is
60). You can also pass in 'all' here to get all relationships,
irrespective of the confidence in the data

By default, the network data will be what we think to be true

today (usually because the information on which it is based is
recent enough to make that a reasonable assumption). However,
dates if a date is passed in (in ISO 8601 format), it will be the network
data we have that is believed to be current on that date. This is
useful for data such as the US banks, for which we hold good data
going back over 10 years.

By default the API will return every control relationship we know

about where the percentage control is greater or equal to 2%.
However, this can be overridden by passing a numeric value here,
ownership_percentage for example 50 or even 0 (for every relationship, regardless of
percentage). Note that this will not affect the results for control
relationships where we do not know the percentage (e.g. many
subsidiary relationships)

Example:
https://api.opencorporates.com/v0.4/companies/gb/00102498/network
https://api.opencorporates.com/v0.4/companies/gb/00102498/network?confidence=80

GET companies/:jurisdiction_code/:company_number/statements
Description: This returns the statements associated with each company. A statement is a
purported 'statement of fact' from a source (a public record or a user). For example,
subsidiary statement may have been parsed from a filing at the US Securities And Exchange
Commission, or a user may have made a statement that one company is a parent of another.
For more details, see the statements section below
The response is paginated (see pagination).
Example:
https://api.opencorporates.com/v0.4/companies/gb/00102498/statements
https://api.opencorporates.com/v0.4/companies/gb/00102498/statements?page=2

GET companies/:jurisdiction_code/:company_number/data
Description: [Note the 'data' type is being deprecated in favour of statements, which has a
number of benefits, including improved provenance, and, shortly, improved searchability]
This returns the data held for the given company. In OpenCorporates a datum is a piece of
information derived from a public record, or contributed by a user. Examples are a website,
sales tax number, address, or entry in an official register (e.g. the UK Charity Register or US
SEC register). Each datum will be returned with the OpenCorporates id, the OpenCorporates
URL for the datum, timestamps indicating when they were created/updated and the
following:

this is the title of the datum as displayed on OpenCorporates. It is computed

title
internally depending on the data_type

the given description of the datum as displayed on OpenCorporates. It is

description computed internally depending on the data_type. Together with the title this
makes it easy to display a useful summary of the datum

this is a string value denoting the type of data, e.g. 'CompanyAddress',

data_type
'OfficialRegisterEntry'

The response is paginated (see pagination).

Example:
https://api.opencorporates.com/v0.4/companies/gb/00102498/data

GET companies/events
Description: This endpoint allows all company events to be queried and filtered. Each
matched event will be returned with its OpenCorporates ID and a range of data attributes,
described in more detail below.
What is an Event?

An Event may be defined as a "change" in the lifecycle of a particular corporate entity based
on data retrieved from the jurisdiction's company register. Each "change" in the official
company register triggers a "snapshot" (a point-in-time view of a company) to be created in
the OpenCorporates database. A comparison of these snapshots over time allows us to infer
and create different types of event. Events then describe a series of changes, from
incorporation to dissolution, from the official register during a corporate entity’s lifecycle.
Events may also be generated from a single piece of information that reflects a real-world
event (such as a specific filing or gazette notice).
GET companies/:jurisdiction_code/events
Description: This endpoint allows all company events to be queried and filtered for a
specified jurisdiction. Each matched event will be returned with its OpenCorporates ID and
a range of data attributes, described below.
Filters, Sorting & Pagination
The above events endpoints can be filtered using the following querystring parameters

Filter
parameters

Filter by date range of when events could have occurred (see definition
time_rangeDate below). Given that these are whole dates, the event dates
filter cover 00:00:00 to 23:59:59 on the specified date.
GET /companies/events?time_range=2019-01-01:2019-01-05

created_atDate Filter by date range of when the event was created (single date).
filter E.g. GET /companies/events?created_at=2019-02-02

Filter by event type. Although this is a term filter, and therefore

supports AND/OR type queries for multiple types, only OR will return
typeTerm filter
results, as events can only be 1 type. See below for list of types.
E.g. GET /companies/events?type=Event::Company::Incorporation

Filter by a category.
categories
E.g. GET /companies/events?categories=kyc
 Filter by jurisdiction of company registration.
jurisdiction_code
E.g. GET /companies/events?jurisdiction_code=us_fl

Filter by country code of company registration.

country_code
E.g. GET /companies/events?country_code=us

The following parameters allow sorting of data returned by the above endpoints.

Sort
parameters

Sorting is possible by the following two

attributes: created_at or time_range_ends_at. Currently only descending
order order is supported, however we will support ascending sort order in a future
release. E.g. GET
/companies/events?type=Event::Company::Incorporation&order=created_at

The above endpoints return a number of results, which are paginated. By default 30 objects
are returned, together with the current page number, and the total number of pages.
Returning results for a specific page is possible using the following parameters:

Pagination
parameters

Integer. Number of results to be returned on each page. Default is 30,

per_page maximum is 100. E.g. GET
/companies/events/gb?type=Event::Company::Incorporation&time_range=2019-
01-01:2019-01-05&per_page=30

Integer. Number of the required page of results. Default is page 1. This

parameter is limited to 100 to ensure that the API is as fast as possible for all
page users. E.g. GET
/companies/events/gb?type=Event::Company::Incorporation&time_range=2019-
01-01:2019-01-05&per_page=30&page=4

Total number of pages and number of results are included as part of the API response:

{
"api_version": "0.4.7",
"results": {
"events": [ ... ], // array of results
"page": 4,
"per_page": 30,
 "total_pages": 5,
"total_count": 145
}
}

GET companies/:jurisdiction_code/:company_number/events
Description: This returns an array of events data for the given company. Each event will be
returned with its OpenCorporates ID and a range of data attributes, described below.
The default response will be the most recent 30 events for a company based
on time_range_ends_at in descending sort order.

Attribute Description

id The unique id of an event record.

When this event record was created by Opencorporate

created_at
the date of the event). Timestamp in ISO 8601 format.

opencorporates_url The url of the company event on OpenCorporates

The ISO-3166 alpha-2 code for the jurisdiction in whic

jurisdiction_code For the US, Canada & UAE, the country code is followed
code Lower case, with country & region codes separate

company_number The identifier given to the company by the company re

Enumerable representing the event type code:

• Event::Company::ChangeOfName
• Event::Company::ChangeOfStatus
• Event::Company::BecameInactive
type • Event::Company::NoLongerInactive
• Event::Company::Incorporation
• Event::Company::AdditionOfOfficer
• Event::Company::RemovalOfOfficer
• Event::Company::GazetteNoticePublication

A list of categories which apply to the event type:

• corporate
• credit
• existence
categories
• kyc
• other

The following categories are mapped to the event type

 • Change of Name: corporate, kyc
• Change of Status: corporate, credit, kyc
• Became Inactive, No Longer Inactive: existence
• Incorporation: existence, corporate
• Officers: credit, kyc
• Gazette Notice Publication: other

The earliest date (if known) and the latest date on whi
time_range
occurred

time_range.starts_at Earliest date. Timestamp in ISO 8601 format

time_range.ends_at Latest date. Timestamp in ISO 8601 format

A text description of what happened.

Pattern: ^(BecameInactive|No Longer Inactive|Incor

'.+' to '.+'|Change of name from '.+' to '.+')$
description
Officer pattern: ^(New officer: '.+'|Removed officer

Gazette Notice pattern: ^(Gazette Notice|Gazette Not

An event is either calculated based on the difference be

company observed on different dates, or by a single pie
real-world event (such as a specific filing or gazette no
as a "statement"
provenance
The provenance provides the date(s) on which the sna
applicable event types), as well as more detailed prove
the sources where information for the event was taken
gazette notice).

Provenance information for the earlier snapshot objec

provenance.earlier_snapshot
one or more snapshots.

Date on which the earlier snapshot of company data w

provenance.earlier_snapshot.sample_date
8601 format

Provenance information for the subsequent snapshot o

provenance.later_snapshot from one or more snapshots. Some events are calculate
only (for example, Incorporation), in which case this ob
 Date on which the later snapshot of company data was
provenance.later_snapshot.sample_date
8601 format

provenance.id The statement ID. Applicable only to events derived fro

provenance.type Will be set to "statement". Applicable only to events de

The URL to the statement on OpenCorporates. Applicab

provenance.opencorporates_url
statements

Date on which the statement was observed. Date in ISO

provenance.sample_date
to events derived from statements

Object containing structured source data from which t

Information from this used to calculate the event descr
only have data in one of before or after

Change of status:

"derived_from": {
"before": {
"current_status": "Exists"
},
"after": {
"current_status": "In Liquidation"
}
}
Change of name:
derived_from
"derived_from": {
"before": {
"name": "Mazer Appliance, Inc."
},
"after": {
"name": "MA Appliance, Inc."
}
}
Company incorporation:

"derived_from": {
"before": null,
"after": {
"incorporation_date": "2019-03-19"
}
 }
Company Became Inactive:

"derived_from": {
"before": {"inactive": false},
"after": {"inactive": true}
}
Company Is No Longer Inactive:

"derived_from": {
"before": {"inactive": true},
"after": {"inactive": false}
}
Addition/Removal of officer. The before section contai
new/removed officer (if present) from the snapshot of
The after section will reflect the officer data from the l

Gazette Notice Publication. The before and after objec

a single observation. The datum relating to the event w

derived_from.before See above

derived_from.after See above

Contains structured source data that relates to the real

new or changed officer, given that the `derived_from` o
after picture of the officer, the payload object will cont
removed officer that triggered the event. For Gazette N
information about the gazette notice publication.
This object is populated only for the following event ty

Addition of officer (see above for fields returned for of

"payload": {
"officer": { // officer object }
payload }
Removal of officer (see above for fields returned for of

"payload": {
"officer": { // officer object }
}
Gazette Notice Publication (note that different sources
completion of the attributes described below):

"payload": {
"date_published": "2019-02-19",
 "identifier": 123456,
"uid": 123456,
"url": "https://www.thegazette.co.uk/notice/123456",
"issue": {
"publication": {
"publisher": {
"name": "The Stationery Office Limited",
"url": "http://www.tso.co.uk/",
"media_type": "text/html"
},
"jurisdiction_code": "gb",
"title": "The Gazette",
"url": "https://www.thegazette.co.uk/",
"media_type": "text/html"
},
"edition_id": "The London Gazette"
},
"classification": [
{
"name": "Corporate Insolvency > Meetings of Creditors",
"code": "2442"
}
],
"preview_text": "Meetings of Creditors TEST COMPANY FOO B
(Company Number 00000000) Registered office: 1b The Street, Bigt
ZZ11 1ZZ Principal trading address: 1b Road Avenue, Small Town, Y
1YY Notice is hereby given under Section 100 of the Insolvency Act
1986, and Rules 6.14 and 15.13 of the Insolvency (England and Wal
Rules 2016 that the Director(s) of the Company"
}

Example:
https://api.opencorporates.com/companies/us_nj/0400549703/events

Example response

{
"api_version": "0.4.7",
"results": {
"events": [
{
"id": 986979731,
"created_at": "2019-05-28T20:43:44Z",
"opencorporates_url": "https://opencorporates.com/events/986979731",
"jurisdiction_code": "us_nj",
"company_number": "0400549703",
"type": "Event::Company::Incorporation",
 "event_class": "company",
"categories": [
"existence",
"corporate"
],
"time_range": {
"starts_at": "2013-02-12T00:00:00Z",
"ends_at": "2013-02-13T00:00:00Z"
},
"description": "Incorporated",
"derived_from": {
"before": null,
"after": {
"incorporation_date": "2013-02-12"
}
},
"provenance": {
"type": "company",
"earlier_snapshot": null,
"later_snapshot": {
"sampled_at": "2019-01-23T07:58:05Z"
}
}
}
],
"page": 1,
"per_page": 30,
"total_pages": 0,
"total_count": 1
}
}

GET officers/search

This returns a collection of officers whose name matches the given search term (submitted
as :q in the query parameters). It's important to note that the search is deliberately quite
loose, requiring the returned officers to have all the searched-for words (in any order), but
allowing other words to be present too (so 'John Smith' is the same as 'Smith John').

The search is case-insensitive.

The officers are returned in alphabetic order by default but you can return ordered by score
(as ranked by our ElasticSearch search index by passing the order=score query parameter.
The response is paginated (see pagination).
Facet restrictions: You can restrict the results by a number of 'facets' to allow extremely
powerful searching and exploring of the data, combining with company names or part of
names. Note: All dates should be given in ISO 8601 format.

jurisdiction_codeTerm The officers searched for can be restricted to a given jurisdiction

filter by passing a jurisdiction_code query parameter.

The companies searched for can be restricted by passing in an

date_of_birthDate filter exact date of birth or date span (note we currently only have date
of birth for UK company directors).

The officers searched for can be restricted by passing a position

positionTerm filter
(e.g. 'director', 'ceo', 'agent').

The officers searched for can be restricted by passing in an

address or parts of an address. This performs a similar search to
addressTerm filter the basic companies search, so searching for '52 London' will
search for address with 52 and London in them, e.g. '52 Acacia
Ave, London, NW1', or '52 London Road, St Albans'

Filter by inactive status (boolean). If true is supplied it will restrict

to inactive officers (either where they are no longer directors of an
inactive active company, or where the company is inactive). If false is
supplied it will exclude inactive officers. If no value is supplied it
will not filter by inactive status.

Example:
https://api.opencorporates.com/v0.4/officers/search?q=john+smith
https://api.opencorporates.com/v0.4/officers/search?q=john+smiths&per_page=50&page=2
https://api.opencorporates.com/v0.4/officers/search?q=john+smith&jurisdiction_code=gb
https://api.opencorporates.com/v0.4/officers/search?q=john+smith&order=score

GET officers/:id
Description: This returns information on a particular officer (a director or an agent for a
company). Each officer will be returned with the name of the officer, the OpenCorporates id
and url for the officer, the company it relates to, and one or more of the following:

position the position held (e.g. director, secretary, CEO)

uid the id given to the officer by the company registry

 start_date this is date on which the officership started

end_date this is date on which the officership ended

address the given address of the officer, if known

date_of_birth the date of birth of the officer, if known

GET corporate_groupings/:name
Description: This returns information on a given CorporateGrouping. A CorporateGrouping
is a user-curated collection of companies that belong to some human-understand concept of
a corporation (which maps to the Wikipedia article about that corporation). See
(https://blog.opencorporates.com/2011/06/01/introducing-corporategroupings-where-
fuzzy-concepts-meet-legal-entities/). The name of the CorporateGrouping is case-
insensitive Included in the response will be core information for the CorporateGrouping
(:name, :wikipedia_url, :companies_count), together an array of membership of the
CorporateGrouping (each membership will contain a company and an OpenCorporates
Source Object), and an array of the users that are curating this CorporateGrouping
Example:
https://api.opencorporates.com/v0.4/corporate_groupings/capita

GET corporate_groupings/search
Description: This returns a collection of corporate_groupings whose name matches the
given search term (submitted as :q in the query parameters). The search is case-insensitive,
and is a stem-search, that is it searches for corporate_groupings whose name begins with
the given characters.
The response is paginated (see pagination).
Example:
https://api.opencorporates.com/v0.4/corporate_groupings/search?q=bar
https://api.opencorporates.com/v0.4/corporate_groupings/search?q=ba&per_page=50&page=2

GET filings/:id
Description: This returns information on a statutory filing for the a company. Each filing will
be returned with the date of filing, the OpenCorporates id and url for the filing, the company
it relates to, and one or many of the following
 uid the id given to the filing by the company registry

this is either the given title of the filing, or the filing_type, or a generic
title field containing a human-friendly version of the date. This means that
every filing can be relied upon to have a filing_title

description the given description of the filing

the url of the filing. This may be a url of an HTML page, or of the
url document itself, for those more enlightened jurisdictions which make
this available without charge

a human-readable name of the type of filing. This might have been

filing_type_name
computed from the filing_code

filing_code the code given by the company registry to this type of filing

GET data/:id
Description: [Note the 'data' type is being deprecated in favour of statements, which has a
number of benefits, including improved provenance, and, shortly, improved searchability] This
returns information on a given datum. In OpenCorporates a datum is a piece of information
derived from a public record, or contributed by a user. Examples are a website, sales tax
number, address, or entry in an official register (e.g. the UK Charity Register or US SEC
register). Note that a datum can relate to more than one company (e.g. an official notice of a
merger between two companies), and so an array of companies is returned, each including
the company name, jurisdiction_code, company_number and OpenCorporates url.
The datum will also return the datatype, title, and description, as described in GET
companies/:jurisdictioncode/:companynumber/data above. In addition the detailed attributes
of the datum are returned as 'attributes' – these vary depending on the datatype.
Finally the source of the data will be returned as an OpenCorporates source object
Example:
https://api.opencorporates.com/v0.4/data/2601371

GET statements/subsequent_registrations/search
Returns all subsequent registrations matching the given search term.
Results are ordered by created_at, the date the subsequent registration was created in
OpenCorporates
The response is paginated (see pagination)
Example:
https://api.opencorporates.com/v0.4/statements/subsequent_registrations/search

GET statements/alternate_registrations/search
Returns all alternate registrations matching the given search term.

Results are ordered by created_at, the date the alternate registration was created in
OpenCorporates
The response is paginated (see pagination)
Example:
https://api.opencorporates.com/v0.4/statements/alternate_registrations/search

GET statements/gazette_notices/search

This returns a collection of gazette notices that match the given search term (submitted
as :q in the query parameters). It's important to note that the search is deliberately quite
loose, but requires the returned gazette notices to have all the searched-for words (in any
order).

The search is case-insensitive.

The gazette notices are by default ordered by date published in reverse order (newest first),
but you can return ordered by score (as ranked by our ElasticSearch search index) by
passing the order=score query parameter.
The response is paginated (see pagination)
Facet restrictions: You can restrict the results by a number of 'facets' to allow extremely
powerful searching and exploring of the data. Note: All dates should be given in ISO
8601 format.

The gazette notices searched for can be

jurisdiction_codeTerm filter restricted to a given jurisdiction by passing a
jurisdiction_code query parameter.

The publication the gazette notice is published

publication_titleTerm filter
in
 normalised_classification_level_1Term The type of gazette notice
filter

Example:
https://api.opencorporates.com/v0.4/statements/gazette_notices/search?q=bar

GET statements/control_statements/search
This returns a collection of control statements that match the given search terms.
The control statements are by default ordered by date created in reverse order (newest
first), but you can return ordered by score (as ranked by our ElasticSearch search index) by
passing the order=score query parameter.
The response is paginated (see pagination).
Facet restrictions: You can restrict the results by a number of 'facets' to allow extremely
powerful searching and exploring of the data. Note: All dates should be given in ISO
8601 format.

whether the controlling entities are the

is_ultimate_beneficial_owner "ultimate beneficial owners" of the
controlled entity

whether any controlling entities are

has_controlling_entities
present in the statement

the types of control (e.g. share ownership,

control_mechanisms_mechanism_typeTerm voting rights). See the schema for the range
filter
of values

the types of controlling entities (e.g.

controlling_entities_entity_typeTerm filter company, person). See the schema for the
range of values

when the control statement was created in

created_atDate filter
the OpenCorporates system

controlled_entity_nameTerm filter the name of the controlled entity

controlling_entities_nameTerm filter the name of the controlling entities

Example:
https://api.opencorporates.com/v0.4/statements/control_statements/search
GET statements/trademark_registrations/search

Returns all trademark registrations matching the given search term.

Parameters:

q The search term, matching the trademark mark text.

created_at (default)
The date the trademark registration was created in OpenCorporates
mark_text
The trademark mark text
registration_date
order
The date the trademark was registered
expiry_date
The date the trademark expired, or is due to expire
score
The relevance as calculated by ElasticSearch

Example:
https://api.opencorporates.com/v0.4/statements/trademark_registrations/search?q=bar&
order=expiry_date

GET statements/:id
Description: This returns a 'statement' in the OpenCorporates system. A statement is a
purported 'statement of fact' from a source (a public record or a user). For example,
subsidiary statement may have been parsed from a filing at the US Securities And Exchange
Commission, or a user may have made a statement that one company is a parent of another.

All statements have the following attributes:

data_type the type of statement, e.g. subsidiary, shareholding, branch_relationship

the core of what is being said, for example for a licence, the regulator that
properties
has issued the licence, the type of licence (e.g. 'Bank') etc

one or more provenances for the statement. A provenance is made up of a

provenances datetime, a source_url, an actor which created the statement, and a
confidence that the statement is true

Example:
https://api.opencorporates.com/v0.4/statements/11499887

GET events/:id
Description: This returns the details for a given event id. The attributes returned are the
same as for GET companies/:jurisdictioncode/:companynumber/events described above.

Example:
https://api.opencorporates.com/events/986979731

Example response:

{
"api_version": "0.4.7",
"results": {
"event": {
"id": 986979731,
"created_at": "2019-05-28T20:43:44Z",
"opencorporates_url": "https://opencorporates.com/events/986979731",
"jurisdiction_code": "us_nj",
"company_number": "0400549703",
"type": "Event::Company::Incorporation",
"event_class": "company",
"categories": [
"existence",
"corporate"
],
"time_range": {
"starts_at": "2013-02-12T00:00:00Z",
"ends_at": "2013-02-13T00:00:00Z"
},
"description": "Incorporated",
"derived_from": {
"before": null,
"after": {
"incorporation_date": "2013-02-12"
}
},
"provenance": {
"type": "company",
"earlier_snapshot": null,
"later_snapshot": {
"sampled_at": "2019-01-23T07:58:05Z"
}
}
}
}
}

GET placeholders/:id
Description: A placeholder is what we call something we believe is probably a company. We
use placeholders as the intermediate link between statements and companies, or, if we can't
match the statement to a company (for example because for example we don't have
companies in the given jurisdiction) as, well, placeholders for when we can match to a
company For more information see our the 4th part in our series of blog posts on corporate
networks

Each placeholder will be returned with the source and one or many of the following:

name the name of the entity

A plain text representation for the jurisdiction in which the

jurisdiction_string placeholder is believed to be incorporated - this may be the name of
a jurisdiction, of a country, or possibly an ISO 3166-2 code.

the code for the jurisdiction in which the placeholder is believed to

jurisdiction_code be incorporated (see [GET company](#get-companies/:id)). This is
inferred by OpenCorporates from the jurisdiction_string.

an identifier that is associated with the placeholder, for example an

identifier
SEC CIK code.

opencorporates_url the url of the placeholder.

if the placeholder has been matched to a company, the company will

company
be included, together with basic information for the company.

GET placeholders/:id/network
Description: This returns the immediate 'computed corporate network' for the given
company as a set of control relationships (i.e. one company is thought to control or
influence another company). This is the same data you can see on a company's network
page on the main OpenCorporates site.
A control relationship is a relationship of control from one company to another. The
relationship type can be found in the api response. Relationships are directional and we use
the terms 'parent' and 'child' to indicate the direction of the relationships. For example, if
'Company A' is a subsidiary of 'Company B', then the api response would
read {parent_name: Company B, child_name: Company A, relationship_type:
has_subsidiary"}. Conversely, if 'Company B' is a subsidiary of 'Company A', then the api

response would be {parent_name: Company A, child_name: Company B,

relationship_type: has_subsidiary"}

These relationships are computed automatically from a number of relationship statements

associated with each company, and the network will change as more statements are added,
because for example new relationships are discovered, or statements are added which say
that a previous statement is no longer true (see statements for more details), or even that
our algorithms for calculating relationships are improved.

Each relationship is made of the following attributes:

the type of relationship, e.g. subsidiary, shareholding. A

subsidiary relationship typically comes from statutory
relationship_type
filings (e.g. SEC 10-K reports); shareholding information
typically coms from company registers, and is more granular

any additional properties of the relationship, e.g. control

relationship_properties
percentage

a computed confidence in the relationship based on the

confidence
underlying statements

parent_name the name of the parent entity

parent_type the type of entity the parent is

parent_opencorporates_url the OpenCorporates URL of the parent entity

child_name the name of the child entity

child_type the type of entity the child is

child_opencorporates_url the OpenCorporates URL of the child entity

The response is not paginated and can return no results (if we have no known
relationships) or hundreds of relationships. It currently returns just a depth of 1 (i.e. just
immediate parents and children). We are looking at adding greater levels of depth. Note the
related entities may be companies, or placeholders. Placeholders are objects that we
haven't yet matched to a company, either because we don't have the companies in that
jurisdiction, or because we can't confidently match it to a company. Note that some
networks are circular (A controls B, which controls C, which controls A), and you should
allow for this when making repeated network calls so that you do not get stuck in an
endless loop.
Filter options:

a computed confidence in the relationship based on the

underlying statements (between 0 and 100). Only relationships
confidence above this confidence will be returned (the default value here is
60). You can also pass in 'all' here to get all relationships,
irrespective of the confidence in the data

By default, the network data will be what we think to be true

today (usually because the information on which it is based is
recent enough to make that a reasonable assumption). However,
dates if a date is passed in (in ISO 8601 format), it will be the network
data we have that is believed to be current on that date. This is
useful for data such as the US banks, for which we hold good data
going back over 10 years.

By default the API will return every control relationship we know

about where the percentage control is greater or equal to 2%.
However, this can be overridden by passing a numeric value here,
ownership_percentage for example 50 or even 0 (for every relationship, regardless of
percentage). Note that this will not affect the results for control
relationships where we do not know the percentage (e.g. many
subsidiary relationships)

Example:
https://api.opencorporates.com/v0.4/placeholders/645258/network
https://api.opencorporates.com/v0.4/placeholders/645258/network?confidence=80

GET placeholders/:id/statements
Description: This returns the statements associated with a given placeholder. A statement is
a purported 'statement of fact' from a source (a public record or a user). For example,
subsidiary statement may have been parsed from a filing at the US Securities And Exchange
Commission, or a user may have made a statement that one company is a parent of another.
For more details, see the statements section below

A maximum of 30 statements are returned per request, and response is paginated, enabling
you to get further results
Example:
https://api.opencorporates.com/v0.4/placeholders/645258/statements
https://api.opencorporates.com/v0.4/placeholders/645258/statements?page=2

GET jurisdictions
Description: This returns the list of all the jurisdictions we know about (not all of which we
have companies for), as well as the jurisdiction_code for the jurisdiction
Example:
https://api.opencorporates.com/v0.4/jurisdictions

GET jurisdictions/match
Description: This matches the name of a jurisdiction to the jurisdiction. It tries to be highly
accurate but accepts a wide variety of formats. For example, "GB", "G.B.", "United Kingdom",
"Great Britain" all return the jurisdiction for the UK. "Delaware, USA", "Delaware (USA)",
"DELAWARE", "DE (US)" all return the jurisdiction of the US state of Delaware.

You can also supply an optional :related_jurisdiction_code to help the matcher disambiguate
between say "Georgia" the US State and Georgia, the Eastern European country, or between
"PA" (the US state of Pennsylvania) and PA (for Panama).
Example:
https://api.opencorporates.com/v0.4/jurisdictions/match?q=The+Netherlands
https://api.opencorporates.com/v0.4/jurisdictions/match?q=PA&related_jurisdiction_code=us

GET industry_codes
Description: From v0.4 OpenCorporates has moved to a new way of representing industry
codes (previously we only catered for UK SIC codes), and we can now handle a wide variety
of different industry codes, including US NAICS codes and EU NACE codes (and their
derivatives). Where a company register makes available the industry codes, we now store
that code, together with the code scheme which it belongs to, e.g. For this Belgian company,
the industry code consists of the code scheme (in this case be_nace_2008, which represents
the NACE-BEL 2008 code scheme) and the code 66191 (which in NACE-BEL 2008 is the
code for 'Agenten en makelaars in bankdiensten'). This can be represented as a uid (in this
case 'be_nace_2008-66191') to make searching by industry codes consistent and
straightforward.
We also map different code schemes to each other, and for those code schemes that can be
mapped (such as ones derived from the EU NACE 2 scheme) you can also use the mapped
schemes. So, in the above example you can search companies by the industry_code uid of
'eu_nace_2-66191' as well as 'be_nace_2008-66191'. You can get information on individual
industry codes and their mapped equivalents at
the industry_codes/:code_scheme_id/:code call.
This call returns all the code schemes we know about, including links to the official pages
for the code scheme. See industry_codes/:code_scheme_id to get a list of the codes
associated with each code scheme.
Example:
https://api.opencorporates.com/v0.4/industry_codes

GET industry_codes/:code_scheme_id
Description: This call returns further details about the code_scheme, together with the list
of industry codes associated with it
Example:
https://api.opencorporates.com/v0.4/industry_codes/be_nace_2008

GET industry_codes/:code_scheme_id/:code
Description: This call returns the details of a specific code.
Example:
https://api.opencorporates.com/v0.4/industry_codes/be_nace_2008/66191

GET account_status
Description: This returns the status of your API Account (this information may also be
retrieved at https://OpenCorporates.com/users/account)
Note this only works for valid API Accounts. To get an API Account go
to https://OpenCorporates.com/api_accounts/new

The following values will be returned:

plan the type of plan that you are on.

when the api_plan runs out. If you are on a regular payment plan, this
expiry_date
will be the date of the expiry of the current payment period.

status status of the API account.

usage this has two subvalues - today and this_month.

 calls_remaining this has two subvalues - today and this_month.

Example:
https://api.opencorporates.com/v0.4/account_status?api_token=yourapitokengoeshere

{
"results": {
"account_status": {
"calls_remaining": {
"this_month": 49997,
"today": 9998
},
"expiry_date": "2015-01-27",
"plan": "open_data",
"status": "approved",
"usage": {
"this_month": 3,
"today": 2
}
}
}
}

Usage limits

By default you're allowed up to 200 requests per month, and 50 requests per day, but usage
limits depend on your account type and plan.

API accounts

An API key is required in order to use the OpenCorporates API.

API accounts are free if you are going to be using the data in an open data project or
product, i.e. the product or database in which the data is incorporated is also be released
under an open licence (specifically share-alike attribution, with attribution to
OpenCorporates as detailed at the OpenCorporates licence page).

We also have paid-for API Accounts, which remove the OpenCorporates share-alike
restrictions (on the rights acquired by OpenCorporates in assembling and cleaning up the
data, particularly database rights).
To get an API key (or token) simply follow the instructions at our new API Account page.

Authentication
Authentication is through a simple API token at present (see API accounts, below), and this
should be submitted with each request in the query parameters. This token is available
from your account page on OpenCorporates. Please keep your API key safe.
Please note that example requests provided elsewhere in this document do not include an
API key and will return a 503 error unless an API key is appended as a query paramter. For
example, the authenticated version of the GET request to get information on BP PLC, for
example is:
https://api.opencorporates.com/companies/gb/00102498?api_token=ab123cd45

where ab123cd45 is the value of your token.

Stability/Versioning

The OpenCorporates API uses a versioning system. This means that when we introduce
changes to the API we can change the version number, so that queries to the previous
version will still behave in the same way. If you supply a version number to the API that
version will be used, provided it is still supported. If no version number is supplied, the
current version will be used. See Versions for details of changes and current version. The
v0.1 form of the GET request to get information on BP PLC, for example, is:
https://api.opencorporates.com/v0.1/companies/gb/00102498

The unversioned form is:

https://api.opencorporates.com/companies/gb/00102498