logo
API docs by Redocly

Report Generator API (1.0.0)

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.

Start Report Generation

Start report generation for a given company and financial year

Endpoint URL: /clients/123456/financial-years/2022-01-01..2022-12-31/reports

Overview

The Report Generation endpoint is a vital part of the Claim Completion Suite's Report Generation module. It facilitates the creation of PDF-based R&D claim reports, comprising essential financials and project narratives. This endpoint is specifically designed to generate reports for individual companies based on structured data inputs.

Process

  • Asynchronous Operation: Upon receiving a request, the system validates it against the provided ReportRequestConfiguration. If validation succeeds, a unique report_instance_id is generated.
  • Background Generation: The actual report generation process operates in the background, ensuring efficient resource utilization.
  • Webhook Notifications: Upon completion, a webhook event is dispatched to a preconfigured endpoint. Different events will be dispatched depending on whether report was generated successfully or not.

Webhook Integration

  • Configuration: Webhook endpoints are set up during the onboarding process.
  • Data Retrieval: Upon receiving a webhook event, clients can retrieve generated documents or extracted AIF data using other designated endpoints. Those endpoints are described in more details below.

The Report Generation endpoint simplifies the generation of crucial R&D claim reports, offering clients a streamlined and efficient workflow for accessing essential documentation and data.

Rich text content

For company background and project narratives we support rich text content. In order for it to work the strings must be provided in HTML format.

HTML Formatting Examples

For fields that require HTML formatting, the following examples can be used as a reference. HTML support is not limited to those examples, and any valid HTML can be used. If images are included they need to be in the format specified below.

Paragraphs

<p>This is a sample paragraph.</p>

Bold text

<p>This is <b>bold text</b> within a paragraph.</p>

Italic text

<p>This is <i>italic text</i> within a paragraph.</p>

Numbered List

<ol>
    <li>First item</li>
    <li>Second item</li>
    <li>Third item</li>
</ol>

Bulleted List

<ul>
    <li>First item</li>
    <li>Second item</li>
    <li>Third item</li>
</ul>

Image Format

Images can be included in the report content by providing the image in base64 format. The image can be included in the report content as shown below. The numbering of the figure will be automatically generated by the report template.

<figure id="_123">
    <img src="[BASE64 encoded image]"/>
    <figcaption>Some caption</figcaption>
</figure>
Cross-referencing Images

If a caption is used as a cross-reference in any of the HTML strings, it needs to be wrapped in an <a> tag like this:

<p>Some text here. <a href="#_123">Some caption</a> shows something </p>

The href attribute should be the same as the id attribute of the figure element. The numbering of the figure will be automatically generated by the report template. By default, the numbering of the figure will be in the format Figure 1: [CaptionText], Figure 2: [CaptionText], etc.

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
template_name
required
string

The name of the template to be used for generating the report. This will be provided by Claimer during the onboarding process.

required
object (ReportRequestConfiguration)
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_review
required
boolean

Indicates whether automatic review is allowed. If set to true, the report can be automatically reviewed; otherwise, a review task will be created.

review_assignee
required
string

Represents the assignee of the review 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 review is disabled.

required
object (ReportData)
required
object (AgentSummary)

Contact details of the lead consultant who is responsible for this claim.

required
object (CompanySummary)

The company details for which the report is being generated.

scheme
required
string
Enum: "rdec" "sme" "mixed"

The scheme under which the claim is being made.

required
Array of objects (CompetentProfessionalSummary)

A list of competent professionals who have worked on the project. This can be null, however HRMC recommends that at least one competent professional is listed.

required
object (ExpenditureSummary)
required
object (ProjectsSummary)
required
object (SeniorOfficerSummary)
Array of objects (EnhancedSupportSummary)
object (RandDManager)

Contact details of the R&D manager who is responsible for this claim.

external_id
string <= 72 characters

An optional external identifier that can be used to correlate the report with an external system.

Responses

Request samples

Content type
application/json
{
  • "template_name": "string",
  • "configuration": {
    },
  • "model": {
    },
  • "external_id": "string"
}

Response samples

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

Additional Information Form (AIF)

Start AIF generation for a given report instance

Endpoint URL: /clients/123456/financial-years/2022-01-01..2022-12-31/reports/87655/aif

Overview

The 1-Click AIF API represents the next evolutionary step of the Claim Completion Suite's Report Generation module. It seamlessly integrates with the report module to simplify the submission of AIF based on extracted report data.

Integration and Configuration

When integrated with the report module, the 1-Click AIF API streamlines the submission process, allowing users to configure various parameters. Configuration options include deciding whether the AIF requires approval before submission to HMRC. If auto-approval is enabled and the AIF validation fails, the API automatically generates an approval task for the designated approval_assignee.

Webhook Notifications

To keep users informed about the progress of AIF submissions, the API sends webhook events to preconfigured endpoints. Upon receiving of webhook event for successful submission, users can easily download a copy of the confirmation using one of the endpoints provided by the 1-Click AIF API.

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.

reportInstanceId
required
string

The unique identifier of the report. This would have been returned as part of the success response when the report was requested.

Request Body schema: application/json
required
object (AifRequestConfiguration)
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
boolean

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

approval_assignee
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

Once AIF submission for accounting period is done, HMRC sends a confirmation email to the email address provided in this field.

external_id
string <= 72 characters

An optional external identifier that can be used to correlate the report with an external system.

Responses

Request samples

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

Response samples

Content type
application/json
null

Get structured AIF data for generated report

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.

reportInstanceId
required
string

The unique identifier of the report. This would have been returned as part of the success response when the report was requested.

Responses

Response samples

Content type
application/json
{
  • "company": {
    },
  • "agents": [
    ],
  • "senior_officer": {
    },
  • "projects": {
    },
  • "expenditure": {
    },
  • "enhanced_support_by_accounting_period": {
    }
}

Report Documents

Get list of generated documents for a report instance 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.

reportInstanceId
required
string

The unique identifier of the report. This would have been returned as part of the success response when the report was requested.

Responses

Response samples

Content type
application/json
Example
{ }

Download report file

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.

reportInstanceId
required
string

The unique identifier of the report. This would have been returned as part of the success response when the report was requested.

filename
required
string

A BASE64 encoded filename for generated report file

Responses

Response samples

Content type
application/json
Example
{ }

Report Webhooks

Customer chosen webhook endpoint for Claimer to send Report Generation 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>
DocumentsGenerated (object) or DocumentsGenerationFailed (object) or ReportReviewed (object) or ReportCancelled (object) (ReportGenerationEvent)
One of
generated_at
string <date-time>
client_id
string
financial_year_id
string
report_instance_id
string
event_id
string
event_type
string
Enum: "documents-generated" "documents-generation-failed" "report-reviewed" "report-cancelled"
event_timestamp
string <date-time>
tenant_id
string

Unique identifier of the tenant on Claimer's system.

external_id
string <= 72 characters

If external id has been provided when requesting report, then it will be returned in the event. This can be used to correlate events with external systems.

Responses

Request samples

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

Response samples

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