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"
}

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"
}

Client tracking

View current tax liabilities

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": [
    ]
}

View accounting periods

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
{
  • "details": {
    },
  • "accounting_period_end": "2019-08-24"
}

View tracked HMRC events

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
Example
{
  • "event_type": "tax_return_repayment_cancelled_event",
  • "amount": 0,
  • "cancelled_date": "2019-08-24",
  • "financial_year_id": "string",
  • "year_end": "2019-08-24",
  • "client_id": "string",
  • "event_id": "string",
  • "event_timestamp": "2019-08-24T14:15:22Z",
  • "batch_id": "string",
  • "offset": 0
}

View change history

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
Example
{
  • "event_type": "tax_return_repayment_cancelled_event",
  • "amount": 0,
  • "cancelled_date": "2019-08-24",
  • "financial_year_id": "string",
  • "year_end": "2019-08-24",
  • "client_id": "string",
  • "event_id": "string",
  • "event_timestamp": "2019-08-24T14:15:22Z",
  • "batch_id": "string",
  • "offset": 0
}

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
One of
event_type
string
Value: "connection_enabled_event"
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_timestamp
string <date-time>
batch_id
string
offset
integer
message_id
string
request_timestamp
string <date-time> (Instant)

An instant in time.

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

Responses

Request samples

Content type
application/json
Example
{
  • "event_type": "connection_corp_tax_service_status_changed_event",
  • "old_value": "available",
  • "new_value": "available",
  • "changed_at": "2019-08-24T14:15:22Z",
  • "client_id": "string",
  • "event_id": "string",
  • "event_timestamp": "2019-08-24T14:15:22Z",
  • "batch_id": "string",
  • "offset": 0,
  • "message_id": "string",
  • "request_timestamp": "2019-08-24T14:15:22Z",
  • "request_type": "hmrc-tax-account-change-events"
}