Guidance

Important information for software developers - read first

Updated 6 June 2024

You must read this guidance before reading the technical interface specification (TIS).

We plan to replace our XML platform with our (REST JSON) API in the long-term future. We do not have a definite timetable for this yet, but you should consider this before developing an XML gateway-based service.

Applying for a test account

Before you start, you’ll need to read and understand the contents of our specification. If you decide to start development, you’ll need to set up your test account first.

To activate a test account, you’ll need to give us the presenter’s:

• name
• contact name
• address
• email address
• telephone number

To apply for your test account, send us these details by email: [email protected]

Apart from the address, these are usually the developer’s details. Our main contact during testing is usually the development team, and not the presenter or company.

We’ll use these details to activate a test account. We’ll then give you the test presenter credentials which you must use in all test submissions.

To make sure test cases are effective, your test data should closely resemble ‘real life’ data.

Testing guidance

Your test submissions will be examined or ‘parsed’ by the gateway. Submissions will be automatically rejected if it detects any errors.

Your test account will only store submissions which have successfully parsed the gateway. These submissions need to be manually reviewed by Companies House and will stay pending until we’ve reviewed them.

You’ll need to tell us when you’ve made test submissions, so we can review them. Contact us by email: [email protected]

The schemas and examples will need to be tested with the test flag set to 1. See ‘More info’ for available examples.

You’ll need to use a unique submission (envelope) number for each of your submissions, so we can check and respond to your test submissions.

Read the technical specifications for guidance on submissions and responses. The diagram explains what communications to expect between you and Companies House.

These documents cover technical guidance only, and not the legal requirements of running a business.

Visit GOV.UK for more information on:

• registering a company
• running a company
• filing information with Companies House

Submitting attachments within XML

All incorporation submissions must have at least one attachment within the XML <Document> element. This also applies to some other document types.

You should test all variations of the image attachments.

If a company is using modified or bespoke articles of association, you’ll need to test these attachments. You do not need an attachment if the company is using ‘model’ articles of association.

You should also test any attachment letters that give permission or justification to use a company name that:

• includes a ‘sensitive’ word or expression
• is considered the ‘same as’ another company name registered

Creating attachment images

1. Save the document in one of the specified and supported PCL or PDF formats.
2. Compress this into a base64 string.
3. Paste the created base64 string into the XML <Data> element.

This information applies to the ‘input’ (filing) version of the XML gateway only.

To develop a ‘name availability search’ for your incorporation software, you’ll need the ‘output’ (search) version of the XML gateway. Email [email protected] for more information.

Completion of testing

Testing is complete when Companies House is confident that the development, relevant to the form types being tested, meets our strict criteria.

You’ll then need to apply for an online filing presenter account, if you do not have one already, and we’ll send you a presenter ID.

Useful links

Test link.

XML document schemas - see ‘More info’ for available examples.

Troubleshooting: common testing issues

No response to test submission whatsoever

You’ll need to confirm the URL you’ve used, and email your XML test submission to [email protected]

No further response to test submission after initial acknowledgement

All status requests must be polled for. Visit Companies House XML schemas and examples for the relevant ‘Get submission status’, ‘Get status ack’ and ‘Get document’ schemas.

Pending response received

This applies to test submissions that include an attachment. Email [email protected] to let us know and we’ll review your test, and change the status accordingly.

Reject reason: 502 Error

Check that both your sender (test presenter ID) and authentication value is correct and properly MD5# coded.

Check that the test flag is set to 1.

Check that the value is shown as ‘clear’.

Check that the package reference is 0012.

Reject reason: Failure - multiple tests

You have submitted multiple tests with the same submission number.

So we can check and respond to your test submissions, you’ll need to use a unique submission (envelope) number for each of your submissions. For guidance on submissions and responses, the technical specification contains a diagram of the communications you can expect between you and Companies House.

Reject reason: Only non-electronic filing accounts can access this service

You’ve probably tried to submit a ‘search request’ for a company name, data or images.

These options are not available through our software filing gateway. For information on our searchable software options, visit:

• Companies House XML Gateway - if you need the testing criteria for this, email [email protected]
• Companies House API