Note this should be read in conjunction with the introduction to the OpenCorporates REST API, which covers optional authentication and versioning. The example urls given here will omit the versioning for simplicity (and will therefore always use the current API version).
Endpoint
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
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.
Response format
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.3/companies/gb/00102498?format=xmlhttps://api.opencorporates.com/v0.3/companies/search?q=barclays+bank&format=xmlOpenCorporates 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/00102498https://api.opencorporates.com/companies/gb/00102498Pagination
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:
| source_url | this is url from which the data was obtained, or the OpenCorporates url for the user, if it was contributed by a user |
| confidence | a confidence that the associated data object is correct (numeric value between 0 and 100). We will be publishing more about this value in the future |
| source_type | 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. data within the OpenCorporates system), or 'induction' (for example where data has been reconciled to a company by OpenCorporates) |
| actor_type | the type of the 'actor' that contributed the data. Possible values are 'bot' (an OpenCorporates Bot) or 'user' (in which cas the source_url will contain a link to the user page on OpenCorporates) |
| log_message | a note on the source, particularly if the data was added by a user |
| created_at | 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, and therefore a statement may have many provenances, which act as timestamps for the statement |
The OpenCorporates source 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).
So the detailed responses all include the provenance of the data as a source object, consisting of the following:
| retrieved_at | a timestamp of when the information was retrieved from the source, or the data was created. |
| source_type | this is either 'user' if the information was contributed by a user, or 'external' if the information was obtained from an external source. |
| url | 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 of the publisher. If the information was user-contributed it will be the OpenCorporates url of the user. |
| publisher | If the information came from an external source, this is the original publisher of the information; if the information was user-contributed, this will be the user's name. |
| terms | 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 the Open Government Licence). A Null value for this does *not* imply there is no underlying licence. |
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.3/versions
{
"results": {
"versions": {
"current_version": "0.3",
"requested_version": "0.2",
"supported_versions": [
"0.2",
"0.3"
]
}
}
}
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, along with parent company. 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 |
| company_number | the identifier given to the company by the company register |
| jurisdiction_code | the code for the jurisdiction in which the company is incorporated |
| company_type | the type of company (e.g. LLC, Private Limited 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 |
| inactive | a flag indicating if the company is 'inactive'. This is an OpenCorporates mapping from a number of different inactive company statuses, including dissolved, 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 |
| previous_names | an array of previous name objects. Each previous name object will has a company_name attribute and an 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) |
| registered_address_in_full | the registered address of the company, as a single string |
| registry_url | the url of the companies page in the company register. Note, not all company registers provide persistent urls for the companies in the register |
| controlling_entity | This is the controlling parent of the company in question, and is derived either from explicit subsidiary or parent data, or from a company having a majority equity stake in the company |
| branch_status | 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 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 |
| home_company | when a company is a branch of an out-of-jurisdiction company, this is the 'home' company (if we know it), 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.3/companies/gb/00102498
https://api.opencorporates.com/v0.3/companies/gb/00102498?sparse=true
{
"api_version": "0.3",
"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/KLcksqCVCdxlmAPA2MnLtb4lOTEEidxRguYMYklQFkOIwNDEwMjQ+MmNef83ILEvMzUYo/80uJUK6sIXx/3cCsrz9zE9FQo5Z1aSaQybgYGBkYgZgJiZiBmAWJWIGYDYnYg5gBiTiDmAmJuANC4NJA="
}
},
{
"filing": {
"date": "2014-02-13",
"id": 199825349,
"opencorporates_url": "https://opencorporates.com/filings/199825349",
"title": "Notice of cancellation of shares",
"uid": "771a5aeJxjZRd2YnXi4ohPyU9OSS1OBnHYQJzMFCdxfgMDA0djQy9/iwBXUxMzAycuzvi0/KLcksqCVCdxlmAPAzMnLtb4lOTEEidxRkuYMYklQFkOIwNDEwMjQ+MmNef83ILEvMzUYo/80uJUK6sIXx/3cCsrz9zE9FQo5Z1aSaQybgYGBkYgZgJiZiBmAWJWIGYDYnYg5gBiTiDmAmJuAOT2NK0="
}
}
],
"inactive": false,
"incorporation_date": "1909-04-14",
"industry_codes": [
{
"industry_code": {
"code_system": "UK SIC Codes 2007",
"title": "Activities of head offices",
"uid": "70.10"
}
}
],
"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"
}
],
"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 can be restricted to a given jurisdiction by passing the :jurisdiction_code query parameter, and other filters are also allowed (such as restricting to company type). The best way to understand these is to experiment with the main OpenCorporates web site and use the filters on the right-hand-side of the search results page.
The companies are returned in alphabetic order by default but you can return ordered by score (as ranked by our ElasticSearch search index search index](https://lucene.apache.org/ElasticSearch search index](https://www.elastic.co/)/)) by passing the order=score query parameter. The response is paginated (see pagination).
Additional sorting options (from v0.3): 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. |
| updated_at | the datetime the company was updated in any way. The company record will be considered to be updated in many circumstances, including when any associated data is changed. |
| incorporation_date | the date of incorporation as given by the company register. Please note that not all company registries record and publish this date. |
| dissolution_date | the date of dissolution as given by the company register. Please note that not all company registries record and publish this date. |
Additional filtering options (from v0.3): Users can also filter by dates: Note: All dates should be given in ISO 8601 format.
| created_since | companies added to OpenCorporates after the given date. |
| incorporated_before | companies with an incorporation_date before the given date. |
| incorporated_since | companies with an incorporation_date after the given date. |
| dissolved_before | companies with a dissolution_date before the given date |
| dissolved_since | companies with a dissolution_date after the given date. |
| exclude_inactive | exclude inactive companies (boolean). False by default |
| exclude_branches | exclude companies that are foreign 'branches' (boolean). False by default |
Example:
https://api.opencorporates.com/v0.3/companies/search?q=barclays+bank
https://api.opencorporates.com/v0.3/companies/search?q=barclays&per_page=50&page=2
https://api.opencorporates.com/v0.3/companies/search?q=barclays+bank&jurisdiction_code=gb
https://api.opencorporates.com/v0.3/companies/search?q=barclays+bank&jurisdiction_code=gb¤t_status=Active
https://api.opencorporates.com/v0.3/companies/search?q=bank+of+scotland
https://api.opencorporates.com/v0.3/companies/search?q=bank+of+scotland&order=score
https://api.opencorporates.com/v0.3/companies/search?q=bank+of+scotland&exclude_inactive=true
https://api.opencorporates.com/v0.3/companies/search?q=bank+of+scotland&order=incorporation_date
https://api.opencorporates.com/v0.3/companies/search?q=bank+of+scotland&order=incorporation_date&incorporated_before=2013-12-03>
{
"api_version": "0.3",
"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"
}
},
{
"company": {
"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"
}
},
{
"company": {
"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"
}
}
],
"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 |
| title | this is either the given title of the filing, or the filing_type, or a generic 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 |
| url | the url of the filing. This may be a url of an HTML page, or of the document itself, for those more enlightened jurisdictions which make this available without charge |
| filing_type_name | a human-readable name of the type of filing. This might have been 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.3/companies/gb/00102498/filings
https://api.opencorporates.com/v0.3/companies/gb/00102498/filings?page=2
{
"api_version": "0.3",
"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/KLcksqCVCdxlmAPA2MnLtb4lOTEEidxRguYMYklQFkOIwNDEwMjQ+MmNef83ILEvMzUYo/80uJUK6sIXx/3cCsrz9zE9FQo5Z1aSaQybgYGBkYgZgJiZiBmAWJWIGYDYnYg5gBiTiDmAmJuANC4NJA=",
"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/KLcksqCVCdxlmAPAzMnLtb4lOTEEidxRkuYMYklQFkOIwNDEwMjQ+MmNef83ILEvMzUYo/80uJUK6sIXx/3cCsrz9zE9FQo5Z1aSaQybgYGBkYgZgJiZiBmAWJWIGYDYnYg5gBiTiDmAmJuAOT2NK0=",
"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/KLcksqCVCdxlmAPAzMnLtb4lOTEEidxRkuYMYklQFkOIwNDEwMjQ+MmNef83ILEvMzUYo/80uJUK6sIXx/3cCsrz9zE9FQo5Z1aSaQybgYGBkYgZgJiZiBmAWJWIGYDYnYg5gBiTiDmAmJuAOqmNLU=",
"url": null
}
} ],
"page": 1,
"per_page": 30,
"total_count": 676,
"total_pages": 23
}
}
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
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.3/companies/gb/00102498/statements
https://api.opencorporates.com/v0.3/companies/gb/00102498/statements?page=2GET 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:
| title | this is the title of the datum as displayed on OpenCorporates. It is computed internally depending on the data_type |
| description | the given description of the datum as displayed on OpenCorporates. It is computed internally depending on the data_type. Together with the title this makes it easy to display a useful summary of the datum |
| data_type | this is a string value denoting the type of data, e.g. 'CompanyAddress', 'OfficialRegisterEntry' |
The response is paginated (see pagination).
Example:
https://api.opencorporates.com/v0.3/companies/gb/00102498/dataGET 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 can be restricted to a given jurisdiction by passing the :jurisdiction_code query parameter.
The officers are returned in alphabetic order by default but you can return ordered by score (as ranked by our ElasticSearch search index search index](https://lucene.apache.org/ElasticSearch search index](https://www.elastic.co/)/)) by passing the order=score query parameter. The response is paginated (see pagination).
Example:
https://api.opencorporates.com/v0.3/officers/search?q=john+smith
https://api.opencorporates.com/v0.3/officers/search?q=john+smiths&per_page=50&page=2
https://api.opencorporates.com/v0.3/officers/search?q=john+smith&jurisdiction_code=gb
https://api.opencorporates.com/v0.3/officers/search?q=john+smith&order=scoreGET 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 |
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 |
| title | this is either the given title of the filing, or the filing_type, or a generic 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 |
| url | the url of the filing. This may be a url of an HTML page, or of the document itself, for those more enlightened jurisdictions which make this available without charge |
| filing_type_name | a human-readable name of the type of filing. This might have been 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.3/data/2601371GET 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 |
| properties | the core of what is being said, for example for a licence, the regulator that has issued the licence, the type of licence (e.g. 'Bank') etc |
| provenances | one or more provenances for the statement. A provenance is made up of a datetime, a source_url, an actor which created the statement, and a confidence that the statement is true |
Example:
https://api.opencorporates.com/v0.3/statements/11499887GET 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 |
| jurisdiction_string | A plain text representation for the jurisdiction in which the placeholder is believed to be incorporated - this may be the name of a jurisdiction, of a country, or possibly an ISO 3166-2 code. |
| jurisdiction_code | the code for the jurisdiction in which the placeholder is believed to be incorporated (see [GET company](#get-companies/:id)). This is inferred by OpenCorporates from the jurisdiction_string. |
| identifier | an identifier that is associated with the placeholder, for example an SEC CIK code. |
| opencorporates_url | the url of the placeholder. |
| company | if the placeholder has been matched to a company, the company will be included, together with basic information for the company. |
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
The response is paginated (see pagination).
Example:
https://api.opencorporates.com/v0.3/placeholders/645258/statements
https://api.opencorporates.com/v0.3/placeholders/645258/statements?page=2GET 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:
an identifier that is associated with the placeholder, for example an SEC CIK code
| plan | the type of plan that you are on. |
| expiry_date | when the api_plan runs out. If you are on a regular payment plan, this 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.3/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
}
}
}
}