Skip to content

Checkmate REST API (1.0.0)

Checkmate API for launching background checks from your side using Checkmate.

Contact

Download OpenAPI description
api.json
api.yaml
Languages
Servers
Mock server
https://docs.checkmate.tech/_mock/api
Staging
https://staging-api.checkmate.tech/partners/v1
Production
https://api.checkmate.tech/partners/v1

OAuth

OAuth token authorization

Basic Authorization

If you are not planning to build a multi-tenant integration then, we encorauge you to skip OAuth authentication and use your Checkmate account token instead. You can grab it from your Partner's page under "Account API"

Remember to store it safely!

Basic Authorization

placeholder

Operations

Brands

Company branding

Operations

Check Types

Available check types

Operations

Bundles

Pre-configured check bundles

Operations

Candidates

Candidate management

Operations

Create candidate

Request

Creates a Candidate with associated checks.

Security
bearerAuth
Bodyapplication/jsonrequired
candidateobject(CandidateInput)required
candidate.​first_namestring
Example: "Luke"
candidate.​last_namestring
Example: "Skywalker"
candidate.​emailstring
Example: "luke.skywalker@email.com"
candidate.​contact_numberstring
Example: "+6493614595"
candidate.​job_rolestring
Example: "Padawan"
candidate.​departmentstring
Example: "Jedis"
candidate.​partner_application_idstring
Example: "your_unique_id"
candidate.​partner_application_startedboolean
Example: true
checksArray of objects(CheckData)
bundle_idinteger or null

If given, checks value will be ignored

Example: null
bypassboolean

If true, candidate won't be contacted

Default false
Example: false
user_emailstring

Match with existing company user as owner

Example: "user@company.com"
curl -i -X POST \
  https://docs.checkmate.tech/_mock/api/candidates \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "candidate": {
      "first_name": "Luke",
      "last_name": "Skywalker",
      "email": "luke.skywalker@email.com",
      "contact_number": "+6493614595",
      "job_role": "Padawan",
      "department": "Jedis",
      "partner_application_id": "your_unique_id",
      "partner_application_started": true
    },
    "checks": [
      {
        "type": "reference",
        "details": {},
        "renewal": true
      }
    ],
    "bundle_id": null,
    "bypass": false,
    "user_email": "user@company.com"
  }'

Responses

Created candidate

Bodyapplication/json
resultobject(Candidate)
statusinteger
Example: 200
errorobject or null
Response
application/json
{
  "result": {
    "id": 1,
    "reference_code": "whatever",
    "first_name": "Luke",
    "last_name": "Skywalker",
    "name": "Luke Skywalker",
    "email": "luke.skywalker@email.com",
    "contact_number": "+6493614595",
    "job_role": "Padawan",
    "department": "Jedis",
    "ip": null,
    "status": "submitted",
    "token": "https://app.checkmate.tech/assessments/details/12/eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1N...",
    "created_at": "2021-06-27T10:05:13+02:00",
    "submitted_at": null,
    "completed_at": null,
    "accepted_terms_and_conditions": false,
    "partner_application_id": "your_unique_id",
    "partner_application_started": true,
    "cc_notification_emails": "",
    "partner_link": "https://app.checkmate.tech/assessments/details/12/eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1N...",
    "candidate_checks": [ … ],
    "candidate_checks_values": { … }
  },
  "status": 200,
  "error": {}
}

Get candidates

Request

Creates list of Candidate with associated checks.

Security
bearerAuth
curl -i -X GET \
  https://docs.checkmate.tech/_mock/api/candidates \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Created candidate

Bodyapplication/json
resultobject
statusinteger
Example: 200
errorobject or null
Response
application/json
{
  "result": {
    "candidates": [ … ],
    "pagination": { … }
  },
  "status": 200,
  "error": {}
}

Get candidate

Request

Retrieves a Candidate by partner_application_id.

Security
bearerAuth
Path
partner_application_idstringrequired

value of candidate.partner_application_id

curl -i -X GET \
  'https://docs.checkmate.tech/_mock/api/candidates/{partner_application_id}' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Candidate

Bodyapplication/json
resultobject(Candidate)
statusinteger
Example: 200
errorobject or null
Response
application/json
{
  "result": {
    "id": 1,
    "reference_code": "whatever",
    "first_name": "Luke",
    "last_name": "Skywalker",
    "name": "Luke Skywalker",
    "email": "luke.skywalker@email.com",
    "contact_number": "+6493614595",
    "job_role": "Padawan",
    "department": "Jedis",
    "ip": null,
    "status": "submitted",
    "token": "https://app.checkmate.tech/assessments/details/12/eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1N...",
    "created_at": "2021-06-27T10:05:13+02:00",
    "submitted_at": null,
    "completed_at": null,
    "accepted_terms_and_conditions": false,
    "partner_application_id": "your_unique_id",
    "partner_application_started": true,
    "cc_notification_emails": "",
    "partner_link": "https://app.checkmate.tech/assessments/details/12/eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1N...",
    "candidate_checks": [ … ],
    "candidate_checks_values": { … }
  },
  "status": 200,
  "error": {}
}

Update candidate

Request

Updates a Candidate.

Security
bearerAuth
Path
partner_application_idstringrequired

value of candidate.partner_application_id

Bodyapplication/jsonrequired
candidateobject(CandidateInput)required
candidate.​first_namestring
Example: "Luke"
candidate.​last_namestring
Example: "Skywalker"
candidate.​emailstring
Example: "luke.skywalker@email.com"
candidate.​contact_numberstring
Example: "+6493614595"
candidate.​job_rolestring
Example: "Padawan"
candidate.​departmentstring
Example: "Jedis"
candidate.​partner_application_idstring
Example: "your_unique_id"
candidate.​partner_application_startedboolean
Example: true
curl -i -X PUT \
  'https://docs.checkmate.tech/_mock/api/candidates/{partner_application_id}' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "candidate": {
      "first_name": "Luke",
      "last_name": "Skywalker",
      "email": "luke.skywalker@email.com",
      "contact_number": "+6493614595",
      "job_role": "Padawan",
      "department": "Jedis",
      "partner_application_id": "your_unique_id",
      "partner_application_started": true
    }
  }'

Responses

Updated candidate

Bodyapplication/json
resultobject(Candidate)
statusinteger
Example: 200
errorobject or null
Response
application/json
{
  "result": {
    "id": 1,
    "reference_code": "whatever",
    "first_name": "Luke",
    "last_name": "Skywalker",
    "name": "Luke Skywalker",
    "email": "luke.skywalker@email.com",
    "contact_number": "+6493614595",
    "job_role": "Padawan",
    "department": "Jedis",
    "ip": null,
    "status": "submitted",
    "token": "https://app.checkmate.tech/assessments/details/12/eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1N...",
    "created_at": "2021-06-27T10:05:13+02:00",
    "submitted_at": null,
    "completed_at": null,
    "accepted_terms_and_conditions": false,
    "partner_application_id": "your_unique_id",
    "partner_application_started": true,
    "cc_notification_emails": "",
    "partner_link": "https://app.checkmate.tech/assessments/details/12/eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1N...",
    "candidate_checks": [ … ],
    "candidate_checks_values": { … }
  },
  "status": 200,
  "error": {}
}

Delete candidate

Request

Deletes a candidate.

Security
bearerAuth
Path
partner_application_idstringrequired

value of candidate.partner_application_id

curl -i -X DELETE \
  'https://docs.checkmate.tech/_mock/api/candidates/{partner_application_id}' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Success

Bodyapplication/json
resultobject or null
statusinteger
Example: 200
errorobject or null
Response
application/json
{
  "result": {},
  "status": 200,
  "error": {}
}

Add files to candidate

Request

Adds a file (e.g. ID, signature) to candidate. If is_signature is true, candidate is submitted (consent implied).

Security
bearerAuth
Path
partner_application_idstringrequired

value of candidate.partner_application_id

Bodyapplication/jsonrequired
datastringrequired

Base64 encoded file (e.g. data:image/jpeg;base64,...)

Example: "data:image/jpeg;base64,...."
id_typestring(FileTypeEnum)required
Enum"drivers_license""passport""nz_passport""firearm_license""card_18""birth_certificate""citizenship_certificate""centrelink_card""id"
Example: "passport"
is_signatureboolean

If true, file contains candidate signature and candidate is submitted.

Default false
Example: false
curl -i -X POST \
  'https://docs.checkmate.tech/_mock/api/candidates/{partner_application_id}/files' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "data": "data:image/jpeg;base64,....",
    "id_type": "passport",
    "is_signature": false
  }'

Responses

Upload details

Bodyapplication/json
resultobject(Upload)
statusinteger
Example: 200
errorobject or null
Response
application/json
{
  "result": {
    "id": 2589,
    "file_name": "dummy_result.pdf",
    "file_type": "application/pdf",
    "created_at": "2021-07-03T16:44:56+02:00",
    "url": "https://checkmate-staging.s3.ap-southeast-2.amazonaws.com/backg..."
  },
  "status": 200,
  "error": {}
}

Get candidate history

Request

Retrieves Candidate history events.

Security
bearerAuth
Path
partner_application_idstringrequired

value of candidate.partner_application_id

curl -i -X GET \
  'https://docs.checkmate.tech/_mock/api/candidates/{partner_application_id}/history' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

List of history events

Bodyapplication/json
resultArray of objects(HistoryEvent)
statusinteger
Example: 200
errorobject or null
Response
application/json
{
  "result": [
    { … }
  ],
  "status": 200,
  "error": {}
}

Set as started

Request

Marks the candidate as started. Use only if you have a webhook configured for status updates.

Security
bearerAuth
Path
partner_application_idstringrequired

value of candidate.partner_application_id

curl -i -X POST \
  'https://docs.checkmate.tech/_mock/api/candidates/{partner_application_id}/start' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Updated candidate

Bodyapplication/json
resultobject(Candidate)
statusinteger
Example: 200
errorobject or null
Response
application/json
{
  "result": {
    "id": 1,
    "reference_code": "whatever",
    "first_name": "Luke",
    "last_name": "Skywalker",
    "name": "Luke Skywalker",
    "email": "luke.skywalker@email.com",
    "contact_number": "+6493614595",
    "job_role": "Padawan",
    "department": "Jedis",
    "ip": null,
    "status": "submitted",
    "token": "https://app.checkmate.tech/assessments/details/12/eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1N...",
    "created_at": "2021-06-27T10:05:13+02:00",
    "submitted_at": null,
    "completed_at": null,
    "accepted_terms_and_conditions": false,
    "partner_application_id": "your_unique_id",
    "partner_application_started": true,
    "cc_notification_emails": "",
    "partner_link": "https://app.checkmate.tech/assessments/details/12/eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1N...",
    "candidate_checks": [ … ],
    "candidate_checks_values": { … }
  },
  "status": 200,
  "error": {}
}

Checks

Candidate checks

Operations

Sub-checks

Sub-check results

Operations

Referees

Reference check referees

Operations

Companies

Company details

Operations

Company Checks

Company-enabled checks

Operations

Forms

Forms (reference, questionnaire, etc.)

Operations

Uploads

File uploads

Operations

Webhooks

Webhooks are unique per partner and company!

Only one webhook can exists for a partner and company. You will only get updates notifications on candidates created under this context.

E.g. If you subscribe to a webhook using your Account API token you won't be get notified about updates on candidates created directly on the web application or other partners.

:global parameter

:global parameter is the only exception to the above. If global=true you will get notifications on all candidates created through the API. You still won't get notifications on candidates created from the web application as they don't belog to the API.

Operations