Get candidate history

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,
    "user_id": 145,
    "company_id": 458,
    "brand_id": 7,
    "team_id": 2,
    "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,
    "document_id": 5,
    "archived": false,
    "overdue": false,
    "canceled": false,
    "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,
    "user_id": 145,
    "company_id": 458,
    "brand_id": 7,
    "team_id": 2,
    "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,
    "document_id": 5,
    "archived": false,
    "overdue": false,
    "canceled": false,
    "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,
    "user_id": 145,
    "company_id": 458,
    "brand_id": 7,
    "team_id": 2,
    "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,
    "document_id": 5,
    "archived": false,
    "overdue": false,
    "canceled": false,
    "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": {}
}

Cancel candidate

Request

Cancels the candidate and all in-progress checks. No-op if already canceled.

Security

bearerAuth

Path

partner_application_idstringrequired

value of candidate.partner_application_id

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

Responses

Canceled candidate

Bodyapplication/json

resultobject(Candidate)

statusinteger

Example: 200

errorobject or null

Response

application/json

{
  "result": {
    "id": 1,
    "user_id": 145,
    "company_id": 458,
    "brand_id": 7,
    "team_id": 2,
    "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,
    "document_id": 5,
    "archived": false,
    "overdue": false,
    "canceled": false,
    "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": {}
}

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,
    "user_id": 145,
    "company_id": 458,
    "brand_id": 7,
    "team_id": 2,
    "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,
    "document_id": 5,
    "archived": false,
    "overdue": false,
    "canceled": false,
    "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

Users

Company users

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

Checkmate REST API (1.0.0)CopyCopy for LLMCopy page as Markdown for LLMsView as MarkdownOpen this page as MarkdownOpen in ChatGPTGet insights from ChatGPTOpen in ClaudeGet insights from Claude

OAuth

Brands

Check Types

Bundles

Candidates

Create candidate

RequestExpand all

Responses

Was this helpful?

Get candidates

Request

Responses

Was this helpful?

Get candidate

Request

Responses

Was this helpful?

Update candidate

RequestExpand all

Responses

Was this helpful?

Delete candidate

Request

Responses

Was this helpful?

Cancel candidate

Request

Responses

Was this helpful?

Add files to candidate

Request

Responses

Was this helpful?

Get candidate history

Request

Responses

Was this helpful?

Set as started

Request

Responses

Was this helpful?

Checks

Sub-checks

Referees

Companies

Users

Company Checks

Forms

Uploads

Webhooks

Checkmate REST API (1.0.0)
Copy for LLM
Copy page as Markdown for LLMs
View as Markdown
Open this page as Markdown
Open in ChatGPT
Get insights from ChatGPT
Open in Claude
Get insights from Claude

Request

Request