R&D Pre-Notifications API (BETA - SUBJECT TO CHANGE)

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.

Pre-Notification

Start a new Pre-Notification submission

Overview

The pre-notification API is a RESTful API that allows users to submit pre-notifications to HMRC. The API is designed to simplify the process of submitting pre-notifications by providing a single endpoint that accepts pre-notification data in JSON format. The API also provides a webhook notification system that allows users to receive real-time updates on the status of their pre-notification submissions.

Features

The pre-notification API provides the following features:

  • Pre-notification submission Endpoint: The API provides a single endpoint that accepts pre-notification data in JSON format. Users can submit pre-notifications by sending a POST request to this endpoint.
  • Pre-notification checker: The API accepts a JSON structure that details checks whether a client is required to submit a pre-notification to HMRC. The API will return a response indicating whether a pre-notification is required or not.
  • Webhook Notifications: The API provides a webhook notification system that allows users to receive real-time updates on the status of their pre-notification submissions. Users can configure a webhook URL during the onboarding process to receive notifications when their pre-notifications are processed.
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
externalId
required
string (ExternalId)
object (CompanyDetailsRaw)
utr
string
object (AccountingPeriod)

First accounting period within the financial year. Optional - will use first accounting period of associated claim if not specified.

startDate
required
string <date>
endDate
required
string <date>
object (AgentDetailsRaw)
leadConsultantName
string
consultantEmail
string (EmailAddress)
object (SeniorOfficerRaw)
name
string
role
string
email
string (EmailAddress)
telephone
string
hmrcConfirmationEmailAddress
string (EmailAddress)
plannedActivities
string

Responses

Request samples

Content type
application/json
{
  • "externalId": "string",
  • "companyDetails": {
    },
  • "accountingPeriod": {
    },
  • "agentDetails": {
    },
  • "seniorOfficerDetails": {
    },
  • "hmrcConfirmationEmailAddress": "string",
  • "plannedActivities": "string"
}

Endpoint for retrieving submission document

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.

preNotificationId
required
string

A valid Pre-Notification ID

Responses

Endpoint to determine whether or not a pre-notification submission is required

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
object (PreviousClaimInfo)
submission_date
required
string <date>

The date the previous claim was submitted, required if previous_claim_info is provided

financial_year_start_date
required
string <date>

The start date of the financial year the previous claim was submitted for, required if previous_claim_info is provided

amendment_date
string <date>

The date the previous claim was amended, if omitted, the previous claim is assumed to have been submitted as part of the original tax return

Responses

Request samples

Content type
application/json
{
  • "previous_claim_info": {
    }
}

Response samples

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

Webhook

Customer chosen webhook endpoint for Claimer to send Pre-Notification events to

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 basic auth is set in the url (recommended)

Request Body schema: application/json
required
message_id
string

unique event/message id

timestamp
string <date-time>
PreNotificationSubmissionStarted (object) or PreNotificationSubmitted (object) or PreNotificationSubmissionFailed (object) (PreNotificationEvent)
One of
started_at
string <date-time>
client_id
string
claim_id
string
external_claim_id
string

The external reference used for claim/opportunity correlation

pre_notification_id
string
event_id
string
event_type
string
Enum: "pre-notification-submission-started" "pre-notification-submitted" "pre-notification-submission-failed"
event_timestamp
string <date-time>

Responses

Request samples

Content type
application/json
{
  • "message_id": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "event": {
    }
}