logo
API docs by Redocly

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

Download OpenAPI specification:Download

Support: customer.support@claimer.com

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

The Pre-Notification API allows you to submit Company Notification Forms (CNFs / Pre-Notifications) to HMRC on behalf of your clients. You send the data needed for a CNF in JSON; Claimer populates and submits the form to HMRC asynchronously and notifies you of the outcome via webhook.

What this API provides

  • Create a Pre-Notification — POST /clients/{...}/financial-years/{...}/pre-notifications accepts the form data and starts the submission process.
  • Check whether a Pre-Notification is required — POST .../pre-notifications/should-submit returns whether HMRC requires a CNF for this client and financial year, given optional prior-claim information.
  • Retrieve Pre-Notifications for a company — GET /clients/{...}/pre-notifications lists every CNF on file for a Companies House number, with current status and HMRC confirmation reference where available.
  • Download the submission confirmation PDF — once a CNF reaches Submitted, the PDF returned by HMRC can be retrieved via the confirmation-document endpoint.
  • Receive webhook events — Claimer POSTs events to a URL you configure during onboarding, covering the start and the terminal outcome of each submission. See the Webhook section for the event lifecycle and payloads.

Start a new Pre-Notification submission

Creates a new Pre-Notification submission for the supplied client and financial year.

The endpoint validates the request body synchronously and, on success, returns 201 with the new Pre-Notification's identifier. Claimer then populates and submits the form to HMRC asynchronously. You will receive a pre-notification-submission-started webhook shortly after the 201, followed eventually by either pre-notification-submitted (success, with HMRC confirmation reference) or pre-notification-submission-failed (terminal failure). See the Webhook section for the full event lifecycle.

If a Pre-Notification is already in progress for the same client and financial year, the endpoint returns 409 with the existing Pre-Notification's id.

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
external_id
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.

start_date
required
string <date>
end_date
required
string <date>
object (AgentDetailsRaw)
lead_consultant_name
string
consultant_email
string (EmailAddress)
object (SeniorOfficerRaw)
name
string
role
string
email
string (EmailAddress)
telephone
string
hmrc_confirmation_email_address
required
string

Email address HMRC will send the submission confirmation to. Must be a valid email of 241 characters or fewer.

planned_activities
string
agent_consent_to_use_email
required
boolean

True to give permission for HMRC to use email communications, which may include attached files. False, use post to send communications.

senior_officer_consent_to_use_email
required
boolean

True to give permission for HMRC to use email communications, which may include attached files. False, use post to send communications.

Responses

Request samples

Content type
application/json
{
  • "external_id": "string",
  • "company_details": {
    },
  • "accounting_period": {
    },
  • "agent_details": {
    },
  • "senior_officer_details": {
    },
  • "hmrc_confirmation_email_address": "string",
  • "planned_activities": "string",
  • "agent_consent_to_use_email": true,
  • "senior_officer_consent_to_use_email": true
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "external_id": "string",
  • "client_id": "string",
  • "financial_year_id": "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
}

Retrieve all pre-notifications for a company

Retrieves all Company Notification Forms (CNFs/pre-notifications) associated with a specific company registered in your account.

Notes:

  • Pre-notifications are ordered by creation date (newest first)
  • Only active (non-deleted) pre-notifications are returned
  • The submission_reference field will only contain a value when the status is Submitted
  • All timestamps are in UTC and follow ISO-8601 format
  • Financial year dates may be null if not yet set (during initial draft stages)

Use Cases:

  • Displaying a list of all CNFs for a company
  • Checking submission status of pre-notifications
  • Retrieving HMRC confirmation references for submitted forms
  • Tracking the history of pre-notifications across multiple financial years
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
[
  • {
    },
  • {
    },
  • {
    }
]

Webhook

Claimer POSTs Pre-Notification events to a URL you configure during onboarding. Events cover the start of a submission and its terminal outcome (success or failure). See the endpoint below for the full lifecycle, event payloads, and delivery guarantees.

Your webhook endpoint — Claimer POSTs Pre-Notification events here

Webhook lifecycle

Claimer delivers events to a customer-chosen webhook endpoint as a Pre-Notification progresses through its lifecycle. The lifecycle is summarised below — the table lists every event Claimer can send and whether it is guaranteed.

Event ordering

For any Pre-Notification that Claimer attempts to submit to HMRC, exactly two webhook events are delivered, in order:

  1. pre-notification-submission-started — sent first, when Claimer begins populating the Pre-Notification on the caller's behalf (immediately after a successful POST /pre-notifications). Always sent.
  2. Then one of:
    • pre-notification-submitted — sent on successful HMRC submission, with the HMRC confirmation reference. Terminal success.
    • pre-notification-submission-failed — sent if Claimer exhausts retries and the submission reaches a terminal failure state. Terminal failure.

These two terminal events are mutually exclusive: a given Pre-Notification will receive either pre-notification-submitted or pre-notification-submission-failed, never both.

POST /pre-notifications
        │
        ▼
pre-notification-submission-started   ── always sent
        │
        ▼
   (population + submission to HMRC, with retries)
        │
        ├──► pre-notification-submitted            ── success (terminal)
        │
        └──► pre-notification-submission-failed    ── terminal failure

Events and guarantees

Event When Guaranteed?
pre-notification-submission-started Population begins after POST /pre-notifications. Yes — always the first event.
pre-notification-submitted HMRC accepts the submission and returns a confirmation reference. Sent if and only if the submission succeeds.
pre-notification-submission-failed Claimer reaches a terminal failure state after exhausting retries. Sent if and only if the submission ultimately fails.

Status transitions that do not emit webhooks

The status field returned by GET /pre-notifications reflects more granular internal state than the webhook stream. The following transitions are observable via the REST API but do not produce webhook events:

  • Populating — intermediate state while Claimer is preparing the form.
  • AwaitingDraftApproval — populated draft awaiting in-app approval before submission.
  • SubmittedExternally — Pre-Notification marked as submitted outside of Claimer.
  • NotRequired — Pre-Notification determined not to be required.
  • Transient PopulationFailed / SubmissionFailed states that are subsequently retried.

If you need to react to any of these states, poll GET /pre-notifications.

Delivery and retries

  • Each event is delivered as a POST to your configured webhook URL with a JSON body matching the schema described below.
  • An HTTP 200 response acknowledges receipt. Any other status code is treated as failure and Claimer retries with exponential back-off.
  • Each delivery includes a unique message_id (envelope) and event_id (event body) — both are stable across retries of the same event, so receivers can deduplicate.
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
required
string

Unique event/message id. Stable across retries of the same event — use for deduplication.

timestamp
required
string <date-time>

Time the webhook delivery was attempted.

required
PreNotificationSubmissionStarted (object) or PreNotificationSubmitted (object) or PreNotificationSubmissionFailed (object) (PreNotificationEvent)
One of
started_at
required
string <date-time>
client_id
required
string
financial_year_id
required
string
external_id
required
string

The external reference used for claim/opportunity correlation

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

Responses

Request samples

Content type
application/json
Example
{
  • "message_id": "msg_8a3f1c2e9b40",
  • "timestamp": "2026-05-21T09:00:01Z",
  • "event": {
    }
}