Right Person API Documentation

Authentication

All API requests require a bearer token in the Authorization header. Tokens are permanent and do not expire.

Authorization: Bearer <token>

If the token is missing or invalid, the API responds with 401 Unauthorized .

Rate limiting

API requests are limited to 60 requests per minute per API key. Exceeding this limit returns 429 Too Many Requests with the following headers:

Header	Description
X-RateLimit-Limit	Maximum requests per window (60).
X-RateLimit-Remaining	Requests remaining in the current window.
X-RateLimit-Reset	Unix timestamp when the window resets.
Retry-After	Seconds until the next request is allowed.

{ "error": { "type": "rate_limit_exceeded", "message": "Rate limit exceeded. Retry later." } }

Errors

All error responses use a consistent envelope with a machine-readable type and a human-readable message .

{ "error": { "type": "validation_error", "message": "Subjects can't be blank" } }

Status	Type	Description
400	validation_error	Missing required parameter.
401	authentication_error	Invalid or missing API token.
403	forbidden	API key lacks permission for this action.
404	not_found	Requested resource does not exist.
422	validation_error	Request body failed validation.
429	rate_limit_exceeded	Too many requests. See rate limiting section.

List checks

GET /api/v1/checks

Returns all submitted check requests for the authenticated account, ordered by most recent first.

Response

200 Success

[ { "id": "a1b2c3d4-...", "type": "basic", "status": "submitted", "submitted_at": "2026-02-27T12:00:00Z", "subjects": [ { "id": "e5f6a7b8-...", "slug": "A1B2C3", "email": "jane.doe@example.com", "first_name": "Jane", "last_name": "Doe", "phone": "+4712345678", "status": "pending_consent", "requested_at": "2026-02-27T12:00:00Z" } ] } ]

Get a check

GET /api/v1/checks/:id

Returns a single check request by ID, including all subjects.

Response

200 Success

{ "id": "a1b2c3d4-...", "type": "basic", "status": "submitted", "submitted_at": "2026-02-27T12:00:00Z", "subjects": [ { "id": "e5f6a7b8-...", "slug": "A1B2C3", "email": "jane.doe@example.com", "first_name": "Jane", "last_name": "Doe", "phone": "+4712345678", "status": "pending_consent", "requested_at": "2026-02-27T12:00:00Z" } ] }

404 Not found

{ "error": { "type": "not_found", "message": "Resource not found" } }

Create a check

POST /api/v1/checks

Creates and submits a background check with one or more subjects in a single request.

Request body

POST /api/v1/checks Content-Type: application/json Authorization: Bearer <token> { "type": "basic", "message": "Please complete your background check", "subjects": [ { "email": "jane.doe@example.com", "first_name": "Jane", "last_name": "Doe", "phone": "+4712345678" }, { "email": "john.smith@example.com", "first_name": "John", "last_name": "Smith" } ] }

Top-level attributes

Attribute	Type	Required	Description
type	String	Yes	Check package type. See Check types .
subjects	Array	Yes	One or more subjects to check. Min 1.
message	String	No	Custom message included in the candidate notification email.
contact_name	String	No	Contact person name. Defaults to the account's primary user.
contact_email	String	No	Contact person email. Defaults to the account email.
contact_phone_number	String	No	Contact person phone.
contact_role	String	No	Contact person role/title.
education_requirements	String	No	Education requirements description (shown to candidates).

Criminal record check attributes required when type is criminal_record

Attribute	Type	Required	Description
organization_name	String	Yes (CRC)	Name of the requesting organization.
organization_number	String	Yes (CRC)	Organization number.
crc_purpose_id	UUID	Yes (CRC)	Criminal record check purpose.
e_learning_course	String	No	`"none"` (default), `"generic"` , or `"sports"` .

Subject attributes

Attribute	Type	Required	Description
email	String	Yes	Candidate's email. Duplicates within the request are ignored.
first_name	String	Yes	Candidate's first name.
last_name	String	Yes	Candidate's last name.
phone	String	No	Candidate's phone number. Used for SMS notifications.

Criminal record check subject attributes required when type is criminal_record

Attribute	Type	Required	Description
job_role	String	Yes (CRC)	The role the candidate is being hired for.
job_description	String	Yes (CRC)	Description of the job.
already_employed	Boolean	Yes (CRC)	Whether the candidate is already employed.
temporary_job	Boolean	Yes (CRC)	Whether the position is temporary.
employed_on	String	Yes (CRC)	Employment date ( `"YYYY-MM-DD"` ).

Response

201 Success

{ "id": "a1b2c3d4-...", "type": "basic", "status": "submitted", "submitted_at": "2026-02-27T12:00:00Z", "subjects": [ { "id": "e5f6a7b8-...", "slug": "A1B2C3", "email": "jane.doe@example.com", "first_name": "Jane", "last_name": "Doe", "phone": "+4712345678", "status": "pending_consent", "requested_at": "2026-02-27T12:00:00Z" }, { "id": "c9d0e1f2-...", "slug": "X4Y5Z6", "email": "john.smith@example.com", "first_name": "John", "last_name": "Smith", "phone": null, "status": "pending_consent", "requested_at": "2026-02-27T12:00:00Z" } ] }

422 Validation error

{ "error": { "type": "validation_error", "message": "Subjects can't be blank" } }

401 Unauthorized

{ "error": { "type": "authentication_error", "message": "Invalid or missing API token" } }

404 Not found

{ "error": { "type": "not_found", "message": "Resource not found" } }

Webhooks

Webhook endpoints are configured by your account administrator. When events occur, payloads are delivered to your registered endpoints.

Webhook delivery

Webhook payloads are sent as POST requests with a JSON body. Each delivery includes:

Header	Description
Content-Type	application/json
X-Webhook-Id	Unique delivery ID (UUID).
X-Webhook-Timestamp	Unix timestamp (seconds) when the delivery was sent.
X-Webhook-Signature	HMAC-SHA256 hex digest of `{timestamp}.{body}` using the endpoint secret. Verify by computing the same HMAC and comparing. Reject deliveries older than 5 minutes to prevent replay attacks.

Failed deliveries are retried with exponential backoff up to 5 attempts. Although duplicate deliveries are rare, your endpoint should be idempotent — use the X-Webhook-Id header to detect and ignore duplicates.

Webhook event types

Event	Description
check.created	A new check request was submitted via the API.
check.completed	All subjects in a check request have reached a final status.
subject.consent_given	A candidate gave consent to the background check.
subject.in_progress	Checks have begun for a subject.
subject.completed	All checks for a subject are complete.
subject.expired	A subject invitation expired without consent.

Check payload

Used by check.created and check.completed events.

{ "id": "a1b2c3d4-...", "type": "basic", "status": "submitted", "submitted_at": "2026-02-27T12:00:00Z", "subjects": [ { "slug": "A1B2C3", "email": "jane.doe@example.com", "first_name": "Jane", "last_name": "Doe", "phone": "+4712345678", "status": "pending_consent", "requested_at": "2026-02-27T12:00:00Z" } ] }

Subject payload

Used by subject.consent_given , subject.in_progress , subject.completed , and subject.expired events.

{ "id": "e5f6a7b8-...", "check_id": "a1b2c3d4-...", "slug": "A1B2C3", "email": "jane.doe@example.com", "first_name": "Jane", "last_name": "Doe", "phone": "+4712345678", "status": "pending_candidate", "requested_at": "2026-02-27T12:00:00Z" }

Check types

Type	Checks included
identity	Global identity
criminal_record	BankID, information, criminal record, e-learning
information	Identity, information
basic	Global identity, work experience, education
enhanced	Global identity, work experience, education, business interests, open source search
comprehensive	Global identity, work experience, education, business interests, open source search, personal credit, specific source search, related countries