Pre-requisites

It is essential that anyone wishing to use the Companies House XML Gateway has sound experience in developing software that uses HTTP and XML.Companies House cannot provide any advice and support on developing your own software.

Transport

The Companies House XML Gateway exchanges XML over HTTP. Requests are submitted via the HTTP POST method, with a Content-Type of text/xml. Sessions are usually synchronous, with the requested XML document being returned in the response. There is one exception - see 'Document Ordering' for further details.

The example XML shown in the schemas section illustrate typical requests and responses to and from the XML Gateway.

Requests must be submitted with a Content-Type of text/xml. A typical transaction looks like this.

This envelope is subset of the UK GovTalk Message Envelope (http://www.govtalk.gov.uk) as the Companies House XML gateway is designed to allow data exchange between Government Departments that already use the GovTalk XML Messaging standard.

The envelope used by the Companies House XML Gateway may be found here with documentation here.

http://xmlgw.companieshouse.gov.uk/v1-0/xmlgw/Gateway

The content of the request document submitted to the Gateway describes the information being requested. The Gateway uses this information to route the request to the appropriate service once it has carried out some preliminary checks, such as authentication details.

Please email xml@companieshouse.gov.uk, for a specification of the authentication algorithm.

Details of the XML elements used to transport authentication details are described in the message envelope documentation.

All errors are returned in the <GovTalkErrors> envelope element. business and fatal errors are not recoverable and indicate that processing was unsuccessful. warning 'errors' return useful information which should be noted by the originator even though processing was successful.

A complete list of error codes and descriptions may be found here

Documents identified as being available as images by a Filing History may be ordered through the two-phase Document Ordering services.

In the first phase information about the required document is requested from the DocumentInfo service. This information will return the availablility of the document and a unique ordering key. If the document to be requested is likely to take some time to be satisfied, a warning is returned.

The document is requested in the second phase. This is done by passing the unique ordering key returned in the document information to the Document request service. The reply from this request will return an explicit URL to the requested document and a polling interval. The URL is returned in the GovTalk header <ResponseEndPoint> element. The PollInterval specifies the minimum period between accesses to the returned URL. It is up to the requestor to guarantee that requests are not made more frequently than the PollInterval dictates.

• Company Searching by Name
  This service provides a 'alphakey' search of the Companies House company name index, and returns the nearest or exact match. A window of results is returned giving a selection of company names that occur before and after the search match. The message envelope class to use when invoking this service is NameSearch.

  Company Names Search Schema
  Company Names Search Documentation
  Example Request
  Example Reply

• Company Searching by Number
  This service provides a search of the Companies House company name index by company number, returning company names and numbers of matches. Searches may be wildcarded. The message envelope class to use when invoking this service is NumberSearch.

  Company Number Search Schema
  Company Number Search Documentation
  Example Request
  Example Reply

• Company Details
  The message envelope class to use when invoking this service is CompanyDetails.

  Company Details Schema
  Company Details Documentation
  Example Request
  Example Reply

• Company Filing History
  The message envelope class to use when invoking this service is FilingHistory.

  Filing History Schema
  Filing History Documentation
  Example Request
  Example Reply

• Company Appointments
  The message envelope class to use when invoking this service is CompanyAppointments.

  Company Appointments Schema
  Company Appointments Documentation
  Example Request
  Example Reply

• Company Mortgages
  The message envelope class to use when invoking this service is CompanyMortgages.

  Company Mortgages Schema
  Company Mortgages Documentation
  Example Request
  Example Reply

• Document Information and Ordering
  These functions allow the ordering of document returned by a filing history if they are available on the image server.
  The message envelope class to use when invoking the document info service is DocumentInfo.
  The message envelope class to use when requesting a document is Document.

  Company Documents Schema
  Company Document Ordering Documentation
  Document Info Example Request
  Document Info Example Reply
  Document Request Example Request
  Document Request Example Reply

• Company Officer Search
  The message envelope class to use when invoking this service is OfficerSearch.

  Officer Search Schema
  Officer Search Documentation
  Example Request
  Example Reply

• Company Officer Details
  The message envelope class to use when invoking this service is OfficerDetails.

  Officer Details Schema
  Officer Details Documentation
  Example Request
  Example Reply