Create a transaction

The created transaction will be assigned to the user whose access_token was used to authorise the API call, and if a company_number is supplied, will be linked to that company, allowing the company's data to be modified. In this case the company_number must match the authorising access_token's company filing permission scope, otherwise the create will be denied.

If no company_number is provided in the create request, then the transaction will not be assigned to a company, and therefore will not be able to participate in the modification of company data. Such a transaction could be used to incorporate a new company or to handle other data interactions with Companies House that are not directly company related.

Request

POST https://api.company-information.service.gov.uk/transactions

Request body

The request body takes a complete transaction resource, containing the following writable properties:

{
    "company_number": "string",
    "description": "string",
    "reference": "string",
    "resume_journey_uri": "string"
}

Properties

Name Type Description Additional
company_number string

The company number of the company that the transaction will modify. The user must be authorised to create transactions for this company (the matching company-permission scope must be present on the supplied access_token). If no company number is supplied, the transaction will be created outside of any company and cannot be used to modify existing company data.

Optional
description string

The description of intent for this transaction.

reference string

The user reference assiged to this transaction.

Optional
resume_journey_uri string

The URL that can be used to resume a web journey associated with this transaction.

Optional

Authorisation

This request requires the use of one of following authorisation methods: OAuth2.

For OAuth 2 authorisation, the following scopes are required:

Scope Description
https://api.company-information.service.gov.uk/company/{company_number}/registered-office-address.update Company ROA filing permission
https://identity.company-information.service.gov.uk/user/profile.read User profile read permission

Response

The following HTTP status codes may be returned, optionally with a response resource.

Status code Description Resource
201 Created

transaction created

transaction
401 Unauthorized

Not authorised to create a transaction