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

{
    "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

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

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

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:

The OpenCorporates source object

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

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.

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/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": "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.

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

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&current_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,previous_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

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/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/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 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:

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:

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

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

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:

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.

  "derived_from": {
    "before": {
      "current_status": "Exists"
    },
    "after": {
      "current_status": "In Liquidation"
    }
  }

  "derived_from": {
    "before": {
      "name": "Mazer Appliance, Inc."
    },
    "after": {
      "name": "MA Appliance, Inc."
    }
  }

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

  "derived_from": {
    "before": {"inactive": false},
    "after": {"inactive": true}
   }

  "derived_from": {
    "before": {"inactive": true},
    "after": {"inactive": false}
  }

  "payload": {
    "officer": { // officer object }
  }

  "payload": {
    "officer": { // officer object }
  }

  "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 BAR LIMITED
    (Company Number 00000000) Registered office: 1b The Street, Bigtown,
    ZZ11 1ZZ Principal trading address: 1b Road Avenue, Small Town, YY11
    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 Wales)
    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.

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:

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

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.

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.

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:

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:

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:

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 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:

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:

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

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

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

Error/HTTP response codes

• 200 OK: Success!
• 304 Not Modified: There was no new data to return.
• 400 Bad Request: The request was invalid. An accompanying error message will explain why.
• 401 Unauthorized: Authentication credentials were incorrect.
• 403 Forbidden: The request is understood, but it has been refused. This is the status code will be returned during rate limiting
• 404 Not Found: The URI requested is invalid or the resource requested, such as a company, does not exists.
• 500 Internal Server Error: Something is broken. Please contact us if the situation continues and your request is valid
• 502 Bad Gateway: OpenCorporates is down or being upgraded.
• 503 Service Unavailable: The OpenCorporates servers are up, but overloaded with requests. This is also the response code returned if a company's details have been temporarily redacted