InclusivMetrics Applicant API

Overview

This service receives batches of applicant records for a specific client, validates them, and loads them for processing. Deduplication and resend-limit rules are applied downstream, so the number of records added may be fewer than the number submitted. It is a server-to-server, write-only API intended for automated integrations.

Service status: /health

Base URL

All paths below are relative to the service base URL for the environment you were onboarded to:

https://<your-host>

Endpoints are versioned under /api/v1.

Authentication

Every request must include the API key issued to your client:

X-API-Key: <your-api-key>

You may only submit for the client your key is issued to. An optional Idempotency-Key header lets you retry safely without duplicating an upload.

Endpoints

Method	Path	Description
POST	`/api/v1/clients/{clientId}/applicants`	Submit a batch of applicants for a client (max 1000 per request)
GET	`/health`	Service readiness (database connectivity)

Rate limiting

Requests are limited to 100 per minute per source IP. Exceeding the limit returns 429 Too Many Requests (empty body) — wait a moment and retry.

Request body

Send a JSON array of applicant objects. All fields are required.

Field	Type	Max length
`Job_Reference`	string	50
`Job_Title`	string	100
`Application_Received_Date`	date-time	–
`Applicant_Email_Address`	string (email)	100
`Applicant_First_Name`	string	50
`Applicant_Last_Name`	string	50

Example request:

[
  {
    "Job_Reference": "2524552",
    "Job_Title": "Project Manager",
    "Application_Received_Date": "2026-06-30T00:00:00",
    "Applicant_Email_Address": "richard.smith@inclusivmetrics.com",
    "Applicant_First_Name": "Richard William",
    "Applicant_Last_Name": "Smith"
  }
]

Example response (201 Created):

{
  "outcome": "Success",
  "statusCode": 201,
  "statusMessage": "3 records have been successfully imported....",
  "errorMessage": null
}

Example error response (400 Bad Request):

{
  "outcome": "Failure",
  "statusCode": 100,
  "statusMessage": null,
  "errorMessage": "Email address must be 100 characters or fewer. (records 0, 1, 2)"
}

On failure, outcome is "Failure", the body statusCode is 100, and errorMessage describes the problem. Authentication failures return 401/403 with an empty body.

Quick start

Submit one applicant with cURL (replace the API key and client id):

curl -X POST "{baseUrl}/api/v1/clients/<your-client-id>/applicants" \
  -H "X-API-Key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "Job_Reference": "2594455",
      "Job_Title": "Project Manager",
      "Application_Received_Date": "2026-06-30T00:00:00",
      "Applicant_Email_Address": "jane.doe@example.com",
      "Applicant_First_Name": "Jane",
      "Applicant_Last_Name": "Doe"
    }
  ]'

Response codes

Status	Type	When it is returned
`201`	Created	Applicants accepted (`outcome: "Success"`)
`400`	Bad request	The payload is invalid, incomplete, or does not match the API contract
`401`	Unauthorized	Authentication is missing or the provided API key is invalid
`403`	Forbidden	The `clientId` does not match your API key (empty body)
`429`	Too many requests	Rate limits were exceeded. Retry with exponential backoff
`500`	Server error	Includes a reference id in `errorMessage`

Versioning

The current version is v1, referenced in the URL path (/api/v1/…). Backwards-incompatible changes will ship under a new version path (e.g. /api/v2); the previous version remains available during a transition period.

FAQ

How do I get an API key and client id?

Both are issued to your organisation during onboarding. Treat the API key as a secret — send it in the X-API-Key header and never expose it in client-side code or public repositories. Contact InclusivMetrics if you need a key reissued.

Why am I getting a 401 or 403?

A 401 means the X-API-Key header is missing or the key is not valid. A 403 means the key is valid but the {clientId} in the URL does not match the client your key was issued to — you may only submit applicants for your own client.

How many applicants can I send in one request?

Up to 1000 per request. Larger batches are rejected with a 400 Bad Request, so split bigger uploads across multiple calls.

How do I retry safely without creating duplicates?

Include an Idempotency-Key header (up to 100 characters) with your request. If a call times out and you resend it with the same key, the upload is processed only once, so retries never duplicate applicants.

Why were fewer records imported than I submitted?

Deduplication and resend-limit rules are applied downstream after the batch is accepted, so the final count in statusMessage may be lower than the number of records you sent. This is expected behaviour, not an error.

What date format should Application_Received_Date use?

Use ISO 8601 date-time, for example 2026-06-30T00:00:00. All fields in each applicant object are required; a missing or unparseable value is rejected with a 400.

What does a 429 response mean?

You have exceeded the limit of 100 requests per minute for your source IP. Wait a moment and retry — the response body is empty.

How can I check whether the service is available?

Call the /health endpoint. It is unauthenticated and reports whether the API can reach its database.

How do I get help or report a problem?

Email our support team at support@inclusivmetrics.co.uk. Please include your client id and, where relevant, any reference id returned in an errorMessage so we can investigate quickly.

Resources

Health check