HMRC claim tracking API (2.0.0)

Download OpenAPI specification:Download

Claimer Claim Completion Suite

Preparing an R&D claim can be a very intensive process, involving a large number of stakeholders, and a lot of information (both financial and technical).

Once the process of preparing the financial and technical information is done, the final phase of an R&D claim is largely administrative, a job for the 'back office' of a consultancy. This final phase - the Claim Completion phase - is about bringing all the prepared information together, getting it submitted to HMRC, and tracking the claim through to a successful outcome.

Claimer's Claim Completion Suite's is a suite of products/modules that facilitate a high-level of process automation across the whole completion phase. The goal is to significantly reduce the administrative burden consultancies encounter in this phase by providing software solutions for every step of the completion workflow.

Introduction to API Terminology

To address the inconsistent terminology used within the industry, we have chosen to adopt the preferred naming conventions of HM Revenue & Customs (HMRC).

For comprehensive understanding, it's essential to grasp two key concepts as outlined by HMRC:

Financial Year

  • Definition: The period covered by a company's annual accounts filed with Companies House, lasting up to a maximum of 18 months.

Accounting Period for Corporation Tax

  • Definition: A period, limited to a maximum of 12 months, for which R&D tax relief can be claimed via a tax return submission.

Relationship Between Financial Year and Accounting Period for Corporation Tax:

  • For a financial year lasting 12 months or less there is typically a single aligned accounting period for corporation tax.
  • If the financial year exceeds 12 months, it necessitates filing multiple corporation tax returns
    • This often occurs following a company's first year of incorporation. In such cases:
      • The financial year begins on the day of incorporation and ends on the last day of the same month one year later.
      • Two accounting periods are typically formed: one covering the initial 12 months and the other encompassing the remaining days beyond the initial 12 months.

Crucial Points:

  • An accounting period for corporation tax cannot span multiple financial years.
  • Historical financial year dates from Companies House filings are set in stone, serving as a reliable reference point.

Claim:

  • A "Claim" in our system aligns with the financial year, supporting multiple accounting periods for corporation tax.
  • Our system automatically determines accounting periods based on HMRC defaults, with the option for manual adjustment if required.

Users

Fetches the consultant ID for a given email address.

The email is used to identify the consultant within the system and the consultant ID is returned in the response.

Authorizations:
bearerAuth
path Parameters
emailAddress
required
string

Email address of consultant to lookup

Responses

Response samples

Content type
application/json
{
  • "user_id": "string"
}

Fetches the client user ID for a given email address.

The email is used to identify the client user within the system and the client ID is returned in the response.

Authorizations:
bearerAuth
path Parameters
registeredCompanyNumber
required
string

A valid Companies House company number for an R&D eligible company.

emailAddress
required
string

Email address of client to lookup

Responses

Response samples

Content type
application/json
{
  • "user_id": "string"
}

Registers user to client

Registers a new client user as a client representative

The user is identified by a unique ID, which is returned in the response.

Authorizations:
bearerAuth
path Parameters
registeredCompanyNumber
required
string

A valid Companies House company number for an R&D eligible company.

Request Body schema: application/json
required
first_name
string
last_name
string
email_address
string
job_title
string

Responses

Request samples

Content type
application/json
{
  • "first_name": "string",
  • "last_name": "string",
  • "email_address": "string",
  • "job_title": "string"
}

Response samples

Content type
application/json
{
  • "user_id": "string"
}

Tax services & connections

Request a new connection for client

Authorizations:
bearerAuth
path Parameters
registeredCompanyNumber
required
string

A valid Companies House company number for an R&D eligible company.

Request Body schema: application/json
access_request_assignee_email
string

The email address of the client to assign an access request task to

requester_email
string

The user email of the consultant creating the connection. If not supplied, the default consultant user will be selected

Responses

Request samples

Content type
application/json
{
  • "access_request_assignee_email": "string",
  • "requester_email": "string"
}

Response samples

Content type
application/json
{
  • "connection_id": "string",
  • "task_url": "string"
}

Retrieve connection details for a client given a specific connection id

Authorizations:
bearerAuth
path Parameters
registeredCompanyNumber
required
string

A valid Companies House company number for an R&D eligible company.

connectionId
required
string

The connection ID associated with the client.

Responses

Response samples

Content type
application/json
{
  • "government_gateway_id": "string",
  • "access_level": "Standard",
  • "status": "Created",
  • "access_request": {
    },
  • "services": {
    }
}

Delete a connection for a client given specific connection id

Authorizations:
bearerAuth
path Parameters
registeredCompanyNumber
required
string

A valid Companies House company number for an R&D eligible company.

connectionId
required
string

The connection ID associated with the client.

Responses

Response samples

Content type
application/json
Example
{
  • "errorCode": "invalid_connection_id",
  • "errorMessage": "string"
}

View liabilities for a client

Authorizations:
bearerAuth
path Parameters
registeredCompanyNumber
required
string

A valid Companies House company number for an R&D eligible company.

query Parameters
include_history
boolean
Default: false

Used to determine if we return history along with snapshot

Responses

Response samples

Content type
application/json
{
  • "current": {
    },
  • "history": [
    ]
}

Fetch services for client

Authorizations:
bearerAuth
path Parameters
registeredCompanyNumber
required
string

A valid Companies House company number for an R&D eligible company.

Responses

Response samples

Content type
application/json
{
  • "corporation_tax": {
    },
  • "paye": {
    },
  • "vat": {
    }
}

Require/unrequire a tax service for a client

Service Requirements

Requiring a service does not guarantee its availability. Instead, it indicates the intention for the service to be available. The status of a required service will be marked as "Required", indicating that a capabilities check is pending or running to determine the actual availability of the service. You can’t require a service if there are no connections - when there are no connections, tax services are all required: false by default. Attempting to mark an "Available" service as "Not Required" will result in a 400 Bad Request response. This restriction ensures consistency and prevents unnecessary modifications to already available services. A not required service will not be tracked by any financial years that have tracking enabled.

Authorizations:
bearerAuth
path Parameters
registeredCompanyNumber
required
string

A valid Companies House company number for an R&D eligible company.

serviceType
required
string (TaxServiceEnum)
Enum: "corporation_tax" "vat" "paye"
Request Body schema: application/json
required
boolean

Responses

Request samples

Content type
application/json
{
  • "required": true
}

Response samples

Content type
application/json
{
  • "errorCode": "invalid_company_number",
  • "errorMessage": "string"
}

Financial Year tracking

Enable tracking for Financial Year

It is necessary to explicitly enable tracking on a FY basis, although the actual success of a tracking attempt depends on the availability of services through client-centric HMRC connections.

Authorizations:
bearerAuth
path Parameters
registeredCompanyNumber
required
string

A valid Companies House company number for an R&D eligible company.

financialYear
required
string(\d{4}-\d{2}-\d{2})\.\.(\d{4}-\d{2}-\d{2})

Date range of financial year {startDate}..{endDate} - e.g. 2021-01-02..2021-12-31. Please refer to this section for more info about the Financial Years.

Request Body schema: application/json
required
enabled
boolean

The decision to enable tracking for a financial year as true

Responses

Request samples

Content type
application/json
{
  • "enabled": true
}

Response samples

Content type
application/json
Example
{
  • "errorCode": "invalid_company_number",
  • "errorMessage": "string"
}

Financial year tracking overview

Authorizations:
bearerAuth
path Parameters
registeredCompanyNumber
required
string

A valid Companies House company number for an R&D eligible company.

financialYear
required
string(\d{4}-\d{2}-\d{2})\.\.(\d{4}-\d{2}-\d{2})

Date range of financial year {startDate}..{endDate} - e.g. 2021-01-02..2021-12-31. Please refer to this section for more info about the Financial Years.

Responses

Response samples

Content type
application/json
Example
{
  • "enabled": true,
  • "disabled_at": null,
  • "available_services": [
    ]
}

Financial year corporation tax return history

Authorizations:
bearerAuth
path Parameters
registeredCompanyNumber
required
string

A valid Companies House company number for an R&D eligible company.

financialYear
required
string(\d{4}-\d{2}-\d{2})\.\.(\d{4}-\d{2}-\d{2})

Date range of financial year {startDate}..{endDate} - e.g. 2021-01-02..2021-12-31. Please refer to this section for more info about the Financial Years.

Responses

Response samples

Content type
application/json
{
  • "tracking_enabled": true,
  • "events": [
    ]
}

Webhook

Webhook endpoint for tax account event retrieval notifications

Authorizations:
bearerAuth
header Parameters
X-Request-ID
required
string

Request ID used for tracking or logging purposes. Value is unique to the request.

Content-Type
required
string

The media type of this message, e.g application/json

Authorization
string

Will be set if bearer auth is set in the url (recommended)

Request Body schema: application/json
required
message_id
string
request_timestamp
string <date-time> (Instant)

An instant in time.

ConnectionChangedEvent (object) or ConnectionChangedEvent (object) or ConnectionChangedEvent (object) or ConnectionChangedEvent (object) or ConnectionChangedEvent (object) or ConnectionChangedEvent (object) or ConnectionChangedEvent (object) or (ConnectionChangedEvents (ConnectionChangedEvent (object) or ConnectionChangedEvent (object) or ConnectionChangedEvent (object) or ConnectionChangedEvent (object) or ConnectionChangedEvent (object) or ConnectionChangedEvent (object) or ConnectionChangedEvent (object))) or HmrcTaxReturnEvent (object) or HmrcTaxReturnEvent (object) or HmrcTaxReturnEvent (object) or HmrcTaxReturnEvent (object) or HmrcTaxReturnEvent (object) or HmrcTaxReturnEvent (object) or HmrcTaxReturnEvent (object) or LiabilityEvent (object) (TaxAccountEvents)
One of
enabled_by
string
changed_at
string <date-time> (Instant)

An instant in time.

client_id
string (ClientId)

The client ID associated with the event.

event_id
string
event_type
string
event_timestamp
string <date-time>
is_baseline
boolean
batch_id
string
financial_year_id
string

The financial year ID associated with the event, if applicable.

request_type
string
Value: "hmrc-tax-account-change-events"

Responses

Request samples

Content type
application/json
{
  • "message_id": "string",
  • "request_timestamp": "2019-08-24T14:15:22Z",
  • "tax_account_change_event": {
    },
  • "request_type": "hmrc-tax-account-change-events"
}