Incorporation - SOAP API
Table of Contents
-
4.1 HelloWorld
4.3 CreateUpdateUser
1.0 Introduction
This document will be focused on all methods required to register a company via the SOAP API
2.0 General Information / Considerations
Users
Like many websites, everything within eFiling is assigned to a user. Typically a user account will be created/registered and then a companies etc will be created under that account.
You can either create a one user account to associate all companies, officers, addresses and manage the user accounts on your system or create a user per customer of yours, it depends on your requirements.
Company Officers
eFiling doesn't store directors, secretaries , shareholder etc as separate entities. The system stores one officer record and assigns the roles to that officer when assigning to a company.
An officer can have different roles on different companies; for example ABC limited , Joe blogs can be a Director and for XYZ limited Joe blogs can be a Secretary.
Companies House
The average company is formed between 3 — 5 hours after the initial submission but on the rare occasion it can take up to 24 hours unless it's a 'Same Day' incorporation, this will be guaranteed to be formed within 3 hours as long as it is submitted before 3PM.
3.0 Process Overview
This is a simplistic list of the methods that are needed to register a company via eFiling's SOAP API.
Required Data
Although it is assumed that the consumers of this API will know the required data when registering a company, you can visit our UAT system as a good reference for required data.
http://sandbox.efiling.co.uk/buy/standard/
This is a sandbox environment for our hosted platform which we use internally for training and experimentation — there may be some visual anomalies
Process
GetNameAvailability
- Check if the company name is available
- Returns GetNameAvailabilityResult
CreateUpdateUser
- Everything must/will be assigned to a user account
- Returns CreateUpdateUserResult
CreateUpdateAddress
- An address must be created before being assigned
- Returns CreateUpdateAddressResult
CreateUpdateOfficer
- An Officer must be created before being assigned
- Return CreateUpdateOfficerResult
CreateUpdateIncorporation
- Creates the company record
- Return CreateUpdateIncorporationResult
AddOfficerToIncorporation
- Add Officer to company
- Return AddOfficerToIncorporationResult
UpdateIncorporationStatus
- sets the status to start incorporation process
- Returns UpdateIncorporationStatusResult
GetIncorporationDocument
- retrieve Incorporation Documents once Incorporated (status:200)
- Returns GetIncorporationDocumentResult
Note: The Incorporation 'Status' will allow you to tell eFiling to submit this company for Incorporation. Once the company has been submitted for incorporation the status will change; the same applies for when the company has been incorporated. A list of statuses are provided in the appendix.
Post Submission
Once you've marked the company ready for Incorporation (status 170), you will be able to poll eFiling for updates.
GetIncorporationStatus
- eFiling receives updates every 20 minutes; we recommend your system polls every 20-30 minutes.
- Returns GetIncorporationStatusResult
GetIncorporationDocument
- You can retrieve the Incorporation Certificate once your company has been formed; Incorporation.status 200)
- Return GetIncorporationDocumentResult (Contains Base64 of PDF blob)
Note - retrieving documents before Incorporation.Status = 200 will result in blank PDF's being returned.
4.0 Function Definitions
Many of our API functions return objects that contain identifiers, e.g. CreateUpdateUser returns a User object which contains a UserId while CreateUpdateIncorporation returns an Incorporation object which contains an IncorporationId. You may wish to store these identifiers in your system so that they can be used with other functions where appropriate and required.
Please note when a SimpleObject is defined as an output parameter, this just indicates a simple object that returns a Code and Text parameter as defined above in common parameters.
4.1 HelloWorld
This is a simple test function that takes a single optional String as output and returns a SimpleObject. If you supply an input String, then this string will be returned in the SimpleObject. If you do not supply an input String, then the SimpleObject returns "HelloWorld".
Use this function to ensure you are communicating successfully with our API.
Inputs
| Parameter | Type | Description |
|---|---|---|
| Key | string | API Key |
| String | string | A String you would like returned. |
Outputs
Returns: SimpleObject
4.2 GetNameAvailability
This function allows you to check the availability of a company name for registration at Companies House.
You will get either a GREEN, AMBER or RED response. GREEN indicates the name is available without supporting evidence. AMBER indicates that the name is available but you will need to provide one or two types of supporting evidence (depending on the other information in the response). RED indicates the name is not available. If the response is AMBER and there are one or more SensitiveWords, then you need to provide NameAuthorisation supporting evidence with the Incorporation. If the response is AMBER and there is a Match.Name returned, then you must provide SameAs supporting evidence from the Incorporation with the name mentioned in Match.Name.
Inputs
| Parameter | Type | Description |
|---|---|---|
| Key | string | API Key |
| CompanyName | string | The company name, with or without type ending, that you wish to check for availability. |
Outputs
| Parameter | Type | Description |
|---|---|---|
| NameStatus | string | Either "GREEN", "AMBER" or "RED" depending on the availability of the CompanyName requested. |
| Request | Incorporation | An Incorporation object derived from the data provided from CompanyName specified in the input. |
| Match | Incorporation | An Incorporation object with information about an existing Incorporation whose name matches, or is similar to, the CompanyName requested. |
| SensitiveWords | SensitiveWord[] | An array of SensitiveWord objects, if relevant, complete with details about the nature of the sensitivity. See the WSDL for SensitiveWord parameter list. |
4.3 CreateUpdateUser
This function allows you to create and update a User. If you provide a UserId with your User input object then this function will update the specified User account with the details provided in your input.
A full list of parameters can be found in the WSDL file or parameter list document.
Inputs
| Parameter | Type | Description |
|---|---|---|
| Key | string | API Key |
| User | User | A User object containing details of the User you wish to create / update. |
Outputs
| Parameter | Type | Description |
|---|---|---|
| User | User | A User object containing details of the User you just created / updated. You may wish to save the UserId parameter in the User in your system as a foreign key. |
4.4 CreateUpdateAddress
This function allows you to create or update an Address in eFiling. If you provide an AddressId in your Address input parameter the function will assume an update operation. Addresses are widely used in the system so you will need to use this function to manipulate them.
A full list of parameters can be found in the WSDL file or parameter list document.
Inputs
| Parameter | Type | Description |
|---|---|---|
| Key | string | API Key |
| Address | Address | An Address object which contains the data you wish to create or update. To update an existing Address, please specify the AddressId |
| User | User | A User object. The Address will be assigned to this User. You MUST specify the User.UserId. |
Outputs
| Parameter | Type | Description |
|---|---|---|
| Address | Address | An Address object containing details of the Address you just created / updated. You may wish to save the AddressId parameter in the Address in your system as a foreign key. |
4.5 CreateUpdateOfficer
This function allows you to create or update an Officer in eFiling. If you provide an OfficerId in your Officer input parameter the function will assume an update operation. Officers are the entities that have roles within an Incorporation object, such as a director or shareholder. Before assigning an Officer to an Incorporation, the Officer must first exist using this function.
A full list of parameters can be found in the WSDL file or parameter list document.
Inputs
| Parameter | Type | Description |
|---|---|---|
| Key | string | API Key |
| Officer | Officer | An Officer object which contains the data you wish to create or update. To update an existing Officer, please specify the OfficerId. See WSDL for Officer parameter list. |
| User | User | A User object. The Officer will be assigned to this User. You MUST specify the UserId within the User parameter. |
Outputs
| Parameter | Type | Description |
|---|---|---|
| Officer | Officer | An Officer object containing details of the Officer you just created / updated. You may wish to save the OfficerId parameter in the Officer in your system as a foreign key |
4.6 CreateUpdateIncorporation
This function allows you to create or update an Incorporation in eFiling. If you provide an IncorporationId in your Incorporation input parameter the function will assume an update operation. The Status of the Incorporation that you provide will dictate its position within the incorporation process, e.g. Status "170" will queue the Incorporation to go to Companies House for incorporation.
Inputs
| Parameter | Type | Description |
|---|---|---|
| Key | string | API Key |
| Incorporation | Incorporation | An Incorporation object which contains the data you wish to create or update. To update an existing Incorporation, please specify the IncorporationId |
| User | User | A User object. The Incorporation will be assigned to this User. You MUST specify the UserId within the User parameter. |
Outputs
| Parameter | Type | Description |
|---|---|---|
| Incorporation | Incorporation | An Incorporation object containing details of the Incorporation you just created / updated. You may wish to save the IncorporationId parameter in the Incorporation in your system as a foreign key. |
4.7 AddOfficerToIncorporation
This function allows you to add an existing Officer to an existing Incorporation along with their roles in that Incorporation. Executing this function first clears the specified Officer's roles within the company so you must send all their roles with each request. For example, you cannot send a request to add an Officer as a director and consequently send a request to add that same Officer as a shareholder. The second request will clear the initial request settings. You must specify an Officer's complete roles with in a single call. The data you send to this function will vary according to the Incorporation type so please consider this carefully when using this function. You can only add an Officer to an Incorporation with a Status of < 170. Incorporations with a Status of greater than this cannot be modified this way as they may be / or are in the process of being, incorporated.
Inputs
| Parameter | Type | Description |
|---|---|---|
| Key | string | API Key |
| Incorporation | Incorporation | An Incorporation object. You MUST specify the IncorporationId with the Incorporation parameter. This is the Incorporation in which you are adding an Officer. |
| Officer | Officer | An Officer object. You MUST specify the OfficerId with the Officer parameter. This is the Officer that you are adding to the Incorporation. |
| User | User | A User object to which the Incorporation and the Officer must belong. You MUST specify the UserId within the User parameter. This is required to validate ownership of the other parameters. |
| TopDog | string | Send a "1" if this Officer is to be a director (LBS/LBG/PLC Incorporation) or a member (LLP Incorporation). Send a "0" if not. |
| Secretary | string | Send a "1" if this Officer is to be a secretary in the Incorporation. Send a "0" if not. |
| Holder | string | Send a "1" if this Officer is to be a shareholder (LBS/PLC Incorporation) or a guarantor (LBG Incorporation) or a designated member (LLP Incorporation). Send a "0" if not. |
| Holdings | Holding[] | An optional array of Holdings. Only provide if Holder parameter is set to "1" and for LBS/LBG/PLC Incorporations only. Complete all appropriate fields depending on the Incorporation type. See WSDL for Holding parameter list. |
| Psc | string | Send a "1" if this Officer is a Person of Significant Control or a Relevant legal entity. Send a "0" if not. |
| NatureOfControl | PSCControlType[] | An optional array of PSCControlType . Only provide if PSC parameter is set to “1” . Required Fields per entry are: PSCControlType.Name and PSCControlType.Value. Refer to Appendix |
Outputs
Returns: Simple Object
4.8 RemoveOfficerFromIncorporation
This function allows you to remove an Officer from an Incorporation. This will remove the Officer completely along with all their roles. You can only remove an Officer from an Incorporation with a Status of < 170. Incorporations with a Status of greater than this cannot be modified this way as they may be / or are in the process of being, incorporated, by Companies House.
Inputs
| Parameter | Type | Description |
|---|---|---|
| Key | string | API Key |
| Incorporation | Incorporation | An Incorporation object. You MUST specify the IncorporationId with the Incorporation parameter. This is the Incorporation in which you are removing an Officer. |
| Officer | Officer | An Officer object. You MUST specify the Officer.OfficerId. This is the Officer that you are removing from the Incorporation. |
| User | User | A User object to which the Incorporation and the Officer must belong. You MUST specify the UserId within the User parameter. This is required to validate ownership of the other parameters. |
Outputs
Returns: Simple Object
4.9 GetIncorporationStatus
This function returns the Incorporation status number back as a SimpleObject. Use this when polling for updates on Incorporations you have sent through this API. This is less resource intensive than the complete GetIncorporation function call.
Inputs
| Parameter | Type | Description |
|---|---|---|
| Key | string | API Key |
| User | User | The User to whom the Incorporation belongs. You just need to supply the User's UserId parameter here. |
| IncorporationId | string | The Incorporation ID of the Incorporation you wish to check the status for. Note this is a string input and not a complete Incorporation object. |
Outputs:
Returns : Simple Object
The Incorporation status is returned in the SimpleObject.Code parameter
4.10 GetIncorporationDocument
A function that returns a base 64 encoded PDF document for a particular Incorporation.
Inputs
| Parameter | Type | Description |
|---|---|---|
| Key | string | API Key |
| User | User | The User to whom the Incorporation belongs. You just need to supply the User's UserId parameter here. |
| Incorporation | Incorporation | The Incorporation to which the document belongs. You just need to supply the Incorporation's IncorporationId parameter here. |
| DocumentReference | string | Specify which document you wish to be returned. Options include |
- IncorporationCertificate = the certificate of incorporation
- MemorandumAndArticles = the mem' and art's
- Register - the company register
- Summary - the company summary document
- HolderCertificates - For LBS and PLC, the share certificates.For LBG, the guarantor certificates and for LLP the member certificates
AsAt | string | Deprecated
Outputs
| Parameter | Type | Description |
|---|---|---|
| DocumentTemplate | DocumentTemplate | A container which contains the base 64 encoded PDF. The data is held within the Base64Content parameter |
5.0. Sample Code
To help get you started, this document should be accompanied by a Zip file containing example code. The example code uses PHP 5.3 and take advantage of the PHP SoapClient.