1-click AIF API (1.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.

Additional Information Form (AIF)

Start an AIF submission with a structured payload.

Claimer's AIF API is an essential function of the Claim Completion Suite, providing a comprehensive interface for the submission of AIFs. If you have chosen to set up a webhook, you will receive events throughout the AIF submission process. Additionally, you can retrieve AIF statuses, for non cancelled AIFs.

The usage of this API is made simple by the Report Generation API, as the structured data for the AIF submission can be generated by the Report Generation API. Though you can submit using this API only. The specification and terminology used in the AIF API are consistent with the Report Generation API, and HMRC, making it easy to understand and use. To understand in greater detail the requirements for AIF submissions, the HMRC website provides additional descriptions to clarify what we are asking for in each section of the AIF. https://www.gov.uk/guidance/submit-detailed-information-before-you-claim-research-and-development-rd-tax-relief. However, where there are optional fields, in the AIF, we take care to explain what omitting these fields means for the AIF submission.

The endpoints allow you to submit AIFs, retrieve AIF statuses, retrieve the HMRC confirmation IDs associated with a submitted AIF, and retrieve the HMRC submission document using the HMRC confirmation 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
required
object (SubmissionConfiguration)
strict_aif_validation
required
boolean

Indicates whether strict validation should be applied to the Additional Information Form (AIF). If set to true, strict validation rules are applied, and the request will be rejected if AIF validation fails.

allow_auto_approval
required
boolean

Indicates whether automatic approval is allowed. If set to true, the AIF can be automatically approved; otherwise, a approval task will be created. If AIF validation fails, the approval task will be created even when auto approval is enabled.

approval_assignee
required
string

Represents the assignee of the AIF approval task, if one is created. This is an email address of an existing consultant user in the platform. The task will only be created if auto approval is disabled or AIF validation failed.

confirmation_email
required
string

Email address to send the HMRC submission confirmation email to

required
object (ApiMultiAccountingPeriodAifModel)
required
object (CompanyReferences)
required
Array of objects (AgentDetails)

Any agent involved in the R&D claim includes

  • All agents who have provided advice in relation to any part of the R&D claim
  • agents who have helped prepare all or parts of the claim, through technical assessment, or analysing costs
  • agents who are involved in the claim, for example by:
    • providing information for or completing the online forms
    • filing the Company Tax Return
required
object (SeniorOfficerDetails)
required
object (Projects)
required
object (Expenditure)
object (EnhancedSupportSummary)

For accounting periods ending on or after 1 April 2023, the company must provide evidence in order to claim enhanced support. This is a requirement from HMRC. This is only applicable to claims that include SME expenditure and want to claim the higher rate of credit available under enhanced R&D intensive support.

external_id
required
string

External ID for the submission

Responses

Request samples

Content type
application/json
{
  • "submission_configuration": {
    },
  • "aif_model": {
    },
  • "external_id": "string"
}

Response samples

Content type
application/json
"string"

Retrieve AIF submission statuses

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Retrieve HMRC confirmation IDs for an AIF submission

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
[
  • "string"
]

Retrieve PDF submission document for an AIF submission

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

Webhook

Customer chosen webhook endpoint for Claimer to send AIF 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 message ID coming from Claimer

timestamp
string <date-time>

Timestamp when we attempted to send the message across the webhook. Internally we also timestamp the event when it's created, which is inside the aif event payload

AifSubmissionStarted (object) or AifSubmitted (object) or AifAllSubmitted (object) or AifApproved (object) or AifCancelled (object) (AifEvent)
One of
accounting_period_start
string <date>
accounting_period_end
string <date>
started_at
string <date-time>
client_id
string
financial_year_id
string
submission_id
string
report_instance_id
string
event_id
string
event_type
string
Enum: "aif-submission-started" "aif-submitted" "aif-all-submitted" "aif-approved" "aif-cancelled"
event_timestamp
string <date-time>
tenant-id
string

Responses

Request samples

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