API Reference: version 0.4.1

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 (or JSONP if a callback is requested) 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).

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_urlthis is url from which the data was obtained, or the OpenCorporates url for the user, if it was contributed by a user
confidencea 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_typethe 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_typethe 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_messagea note on the source, particularly if the data was added by a user (e.g. a corporate network relationship)
created_atthe 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_ata timestamp of when the information was retrieved from the source, or the data was created.
source_typethis is either 'user' if the information was contributed by a user, or 'external' if the information was obtained from an external source.
urlwhere 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.
publisherIf 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.
termsif 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.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.

namethe legal name of the company
company_numberthe identifier given to the company by the company register
jurisdiction_codethe code for the jurisdiction in which the company is incorporated
company_typethe type of company (e.g. LLC, Private Limited Company, GBMH)
current_statusthe given description of the filing
incorporation_datethe date the company was incorporated
dissolution_datethe date the company was dissolved
inactivea 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_urlthe url of the company on OpenCorporates
previous_nameschange in responsean array of previous name objects. Each previous name object has a company_name attribute and type attribute (e.g. 'trading', 'legal') and the following optional attributes: start_date, end_date, language as ISO-639 code (for example if it is an alternative legal name in another language)
alternative_namesnewan array of alternative name objects. Each alternative 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_fullthe registered address of the company, as a single string
registered_addressthe registered address of the company, as a structured object
industry_codeschange in responseReturns an array of industry_codes representing the industries the company operates in (see below for more on industry_codes). This is part of our new industry code and the code objects returned are different from the previous representation
registry_urlthe url of the companies page in the company register. Note, not all company registers provide persistent urls for the companies in the register
controlling_entityThis 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_statusa 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_companywhen 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.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": "WipoTrademark",
                            "description": null,
                            "id": 9790033,
                            "opencorporates_url": "https://opencorporates.com/data/9790033",
                            "title": "International Trademark Registration"
                        }
                    },
                   {
                        "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"
                }
            ],
            "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'). NEWYou can now 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' or 'Barclays Big 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, and by default 30 filings are returned, together with the current page number, and total number of pages. For users with an API key, this 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.

NEWNote that from v0.4, the company information now returns the registered address if known.

*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_codeThe companies searched for can be restricted to a given jurisdiction by passing a jurisdiction_code query parameter. NEW You can now search multiple specific jurisdictions simultaneously by passing through a pipe-separated list, e.g. jurisdiction_code=gb|ie
country_codeNEWThe companies searched for can be restricted to a given country by passing a country_code query parameter. Note 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. You can also pass a pipe-separated list for searching multiple countries, e.g. country_code=gb|us
company_typeThe type of the company, as defined by the company register.
current_statusThe current status of the company, as defined by the company register.
industry_codesNEWOne or more industry codes representing the industries the company operates in. This is part of our new industry code and 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). If you pass in multiple industry_codes separated by pipes you will get companies that match any of the given industry_codes; if you separate them by commas, you will get companies returned that match all of those industry_codes
registered_addressNEWThe companies searched for can be restricted by passing in an address or parts of an address. This performs a similar search to 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'
created_sincecompanies added to OpenCorporates after the given date.
incorporation_dateNEWAs with all date fields, incorporation_date can be supplied either as a specific date or as a span of dates. If a span of dates 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
dissolution_dateNEWas with all date fields, dissolution_date can be supplied either as a specific date or as a span of dates. See incorporation_date for details
incorporated_beforeDeprecatedRestrict to companies with an incorporation_date before the given date. Deprecated in favour of new incorporation_date functionality.
incorporated_sinceDeprecatedRestrict to companies with an incorporation_date after the given date. Deprecated in favour of new incorporation_date functionality.
dissolved_beforeDeprecatedRestrict to companies with a dissolution_date before the given date. Deprecated in favour of new dissolution_date functionality.
dissolved_sinceDeprecatedRestrict to companies with a dissolution_date after the given date. Deprecated in favour of new dissolution_date functionality.
exclude_inactiveDeprecatedRestrict to companies that are active/inactive. Deprecated in favour of new inactive functionality.
inactiveFilter by inactive status (boolean). This replaces the exclude_inactive filter from previous versions. If true is 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.
branchFilter by branch status (boolean). This replaces the exclude_branches filter from previous versions. If true is 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.
nonprofitNEWFilter by nonprofit company type (boolean). If true is supplied it will restrict to entities that we have identified as 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.
fieldsNEWBy default when searching with a term (e.g. 'Barclays Bank') it mirrors the search on the main OpenCorporates website, searching name, normalised name, company number, previous names etc. By using the fields parameter, you can limit to a given field or fields. Options are name, normalised_name, company_number, heavily_normalised_number (company number excluding leading zeroes, for example), previous_names, postal_code.

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

created_ata timestamp of when the company was added to OpenCorporates.
updated_atthe 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_datethe date of incorporation as given by the company register. Please note that not all company registries record and publish this date.
dissolution_datethe date of dissolution as given by the company register. Please note 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&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?industrycodes=eunace2-869,eunace_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_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_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

uidthe id given to the filing by the company registry
titlethis 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
descriptionthe given description of the filing
urlthe 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_namea human-readable name of the type of filing. This might have been computed from the filing_code
filing_codethe code given by the company registry to this type of filing

The response is paginated, and by default 30 filings are returned, together with the current page number, and total number of pages. For users with an API key, this 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.

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 the subject company to another company (a 'child' relationship), or from another company to the subject company (a 'parent' relationship). 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:

relationship_typethe type of relationship, e.g. subsidiary, shareholding. A subsdiary relationship typically comes from statutory filings (e.g. SEC 10-K reports); shareholding information typically coms from company registers, and is more granular
relationship_propertiesany additional properties of the relationship, e.g. ownership percentage
confidencea computed confidence in the relationship based on the underlying statements
parent_namethe name of the parent entity
parent_typethe type of entity the parent is
parent_opencorporates_urlthe OpenCorporates URL of the parent entity
child_namethe name of the child entity
child_typethe type of entity the child is
child_opencorporates_urlthe 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:

confidencea computed confidence in the relationship based on the underlying statements (between 0 and 100). Only relationships 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
datesBy 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, 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.
ownership_percentageBy 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 overriden by passing a numeric value here, 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

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

idthe id given to the filing by the company registry
titlethis is the title of the datum as displayed on OpenCorporates. It is computed internally depending on the data_type
descriptionthe 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_typethis is a string value denoting the type of data, e.g. 'CompanyAddress', 'OfficialRegisterEntry'

The response is paginated, and by default 30 companies are returned, together with the current page number, and total number of pages. For users with an API key, this 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.

Example:

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

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, and by default 30 officers are returned, together with the current page number, and total number of pages. For users with an API key, this 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.

*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_codeThe officers searched for can be restricted to a given jurisdiction by passing a jurisdiction_code query parameter. NEW You can now search multiple specific jurisdictions simultaneously by passing through a pipe-separated list, e.g. jurisdiction_code=gb|ie
date_of_birthNEWThe companies searched for can be restricted by passing in an exact date of birth or date span (note we currently only have date of birth for UK company directors). As with all date fields, incorporation_date can be supplied either as a specific date or as a span of dates. If a span of dates 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
positionNEWThe officers searched for can be restricted by passing a position (e.g. 'director', 'ceo', 'agent'). Dates should be given in ISO 8601
addressNEWThe officers searched for can be restricted by passing in an address or parts of an address. This performs a similar search to 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'
inactiveNEWFilter by inactive status (boolean). If true is supplied it will restrict to inactive officers (either where they are no longer directors of an 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:

positionthe position held (e.g. director, secretary, CEO)
uidthe id given to the officer by the company registry
start_datethis is date on which the officership started
end_datethis is date on which the officership ended
addressNEWthe given address of the officer, if known (only for users with API key)
date_of_birthNEWthe date of birth of the officer, if known (only for users with API key)

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, and by default 30 companies are returned, together with the current page number, and total number of pages. For users with an API key, this 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.

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

uidthe id given to the filing by the company registry
titlethis 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
descriptionthe given description of the filing
urlthe 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_namea human-readable name of the type of filing. This might have been computed from the filing_code
filing_codethe 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/: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:

datatypethe type of statement, e.g. subsidiary, shareholding, branchrelationship
propertiesthe 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
provenancesone 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.4/statements/11499887

GET placeholder/:id

Description: A placeholder is 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:

namethe name of the entity
jurisdiction_stringA 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_codethe code for the jurisdiction in which the placeholder is believed to be incorporated (see [GET company](#company)). 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_urlthe url of the placeholder.
companyif the placeholder has been matched to a company, the company will be included, together with basic information for the company.

GET placeholders/:id/network

Description: This returns the immediate 'computed corporate network' for the given placeholder 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 the subject entity to another entity (a 'child' relationship), or from another entity to the subject entity (a 'parent' relationship). These relationships are computed automatically from a number of relationship statements associated with each entity, 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:

relationship_typethe type of relationship, e.g. subsidiary, shareholding. A subsdiary relationship typically comes from statutory filings (e.g. SEC 10-K reports); shareholding information typically coms from company registers, and is more granular
relationship_propertiesany additional properties of the relationship, e.g. control percentage
confidencea computed confidence in the relationship based on the underlying statements
parent_namethe name of the parent entity
parent_typethe type of entity the parent is
parent_opencorporates_urlthe OpenCorporates URL of the parent entity
child_namethe name of the child entity
child_typethe type of entity the child is
child_opencorporates_urlthe 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:

confidencea computed confidence in the relationship based on the underlying statements (between 0 and 100). Only relationships 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
datesBy 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, 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.
ownership_percentageBy 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 overriden by passing a numeric value here, 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/companies/gb/00102498/statements
https://api.opencorporates.com/v0.4/companies/gb/00102498/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

NEW 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&relatedjurisdictioncode=us

NEW 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 are also beginning to 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 search by the derived 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 information on individual industry codes and their mapped equivalents at the industry_codes/:code_scheme_id/:code call. As most industry code schemes are hierarchical, there is also the potential in the future to search by parent codes, and we hope to implement this in the next API release.

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. (Note not all code_schemes have companies with those code schemes, as not all registers collect industry_code information. We will be adding further code schemes and increasing the number of companies with industry_codes in the future.)

Example:

https://api.opencorporates.com/v0.4/industry_codes

NEW 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

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

planthe type of plan that you are on.
expiry_datewhen 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.
statusstatus of the API account.
usagethis has two subvalues - today and this_month.
calls_remainingthis 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
            }
        }
    }
}