# Checkmate REST API

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

**Contact**
- Questions or feedback: [development@checkmate.tech](mailto:development@checkmate.tech)
- Become a partner: [team@checkmate.tech](mailto:team@checkmate.tech)


Version: 1.0.0

## Servers

Staging
```
https://staging-api.checkmate.tech/partners/v1
```

Production
```
https://api.checkmate.tech/partners/v1
```

## Security

### bearerAuth

API token from Integrations or OAuth 2.0 access token. Use header Authorization: Bearer {token}

Type: http
Scheme: bearer
Bearer Format: JWT

## Download OpenAPI description

[Checkmate REST API](https://docs.checkmate.tech/_bundle/api.yaml)

## OAuth

OAuth token authorization 

{% admonition type="info" name="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](https://app.checkmate.tech/company/integrations) under "Account API"
  
  Remember to store it safely!
{% /admonition %}


{% admonition type="info" name="Basic Authorization" %}
  placeholder
{% /admonition %}


### Oauth token

 - [POST /oauth/token](https://docs.checkmate.tech/api/oauth/oauthtoken.md): - Authorization code: Exchange code for access_token and refresh_token.
- Refresh: Use refresh_token to get a new access_token (access tokens expire after 5 minutes).
Send body as application/x-www-form-urlencoded.

## Brands

Company branding

### Get brands

 - [GET /branding](https://docs.checkmate.tech/api/brands/getbranding.md): Retrieves all available brands for company.

## Check Types

Available check types

### Get check types

 - [GET /checks](https://docs.checkmate.tech/api/check-types/getchecktypes.md): Retrieves all available check types.

### Get check type details

 - [GET /checks/{type}](https://docs.checkmate.tech/api/check-types/getchecktypedetails.md): Retrieves the details for a specific check type.

## Bundles

Pre-configured check bundles

### Get bundles

 - [GET /bundles](https://docs.checkmate.tech/api/bundles/getbundles.md): Retrieves company bundles.

### Create bundle

 - [POST /bundles](https://docs.checkmate.tech/api/bundles/createbundle.md): Creates a Checks Bundle with checks data.

## Candidates

Candidate management

### Create candidate

 - [POST /candidates](https://docs.checkmate.tech/api/candidates/createcandidate.md): Creates a Candidate with associated checks.

### Get candidates

 - [GET /candidates](https://docs.checkmate.tech/api/candidates/getcandidates.md): Creates list of Candidate with associated checks.

### Get candidate

 - [GET /candidates/{partner_application_id}](https://docs.checkmate.tech/api/candidates/getcandidate.md): Retrieves a Candidate by partner_application_id.

### Update candidate

 - [PUT /candidates/{partner_application_id}](https://docs.checkmate.tech/api/candidates/updatecandidate.md): Updates a Candidate.

### Delete candidate

 - [DELETE /candidates/{partner_application_id}](https://docs.checkmate.tech/api/candidates/deletecandidate.md): Deletes a candidate.

### Add files to candidate

 - [POST /candidates/{partner_application_id}/files](https://docs.checkmate.tech/api/candidates/addcandidatefiles.md): Adds a file (e.g. ID, signature) to candidate. If is_signature is true, candidate is submitted (consent implied).

### Get candidate history

 - [GET /candidates/{partner_application_id}/history](https://docs.checkmate.tech/api/candidates/getcandidatehistory.md): Retrieves Candidate history events.

### Set as started

 - [POST /candidates/{partner_application_id}/start](https://docs.checkmate.tech/api/candidates/setcandidatestarted.md): Marks the candidate as started. Use only if you have a webhook configured for status updates.

## Checks

Candidate checks

### Add checks

 - [POST /candidates/{partner_application_id}/checks](https://docs.checkmate.tech/api/checks/addchecks.md): Adds checks to an existing candidate.

### Get check result file

 - [GET /candidates/{partner_application_id}/checks/{candidate_check_id}/result](https://docs.checkmate.tech/api/checks/getcheckresultfile.md): Retrieves result file or null if not present.

### Get check base64 result file

 - [GET /candidates/{partner_application_id}/checks/{candidate_check_id}/result/base_64](https://docs.checkmate.tech/api/checks/getcheckresultbase64.md): Retrieves result file data base64 encoded or null if not present.

## Sub-checks

Sub-check results

### Get sub-check result file

 - [GET /candidates/{partner_application_id}/sub_checks/{sub_check_id}/result](https://docs.checkmate.tech/api/sub-checks/getsubcheckresultfile.md): Retrieves result file or null if not present.

### Get sub-check base64 result file

 - [GET /candidates/{partner_application_id}/sub_checks/{sub_check_id}/result/base_64](https://docs.checkmate.tech/api/sub-checks/getsubcheckresultbase64.md): Retrieves result file data base64 encoded or null if not present.

## Referees

Reference check referees

### Get referees

 - [GET /candidates/{partner_application_id}/checks/{candidate_check_id}/referees](https://docs.checkmate.tech/api/referees/getreferees.md): Gets a list of referees for a Reference Check Plus / Custom Reference Check.

### Create referee

 - [POST /candidates/{partner_application_id}/checks/{candidate_check_id}/referees](https://docs.checkmate.tech/api/referees/createreferee.md): Creates a referee on a Reference Check Plus.

### Delete referee

 - [DELETE /candidates/{partner_application_id}/checks/{candidate_check_id}/referees/{referee_id}](https://docs.checkmate.tech/api/referees/deletereferee.md): Deletes a referee.

### Send request to referee

 - [POST /candidates/{partner_application_id}/checks/{candidate_check_id}/referees/{referee_id}/request](https://docs.checkmate.tech/api/referees/sendrefereerequest.md): Sends email/SMS to the referee requesting completion of the reference form.

## Companies

Company details

### Get company

 - [GET /company](https://docs.checkmate.tech/api/companies/getcompany.md): Retrieves company details.

## Company Checks

Company-enabled checks

### Get company checks

 - [GET /company/checks](https://docs.checkmate.tech/api/company-checks/getcompanychecks.md): Retrieves enabled check types for company.

## Forms

Forms (reference, questionnaire, etc.)

### Get forms

 - [GET /forms](https://docs.checkmate.tech/api/forms/getforms.md): Retrieves all available forms for company.

### Get forms by types

 - [GET /forms/types](https://docs.checkmate.tech/api/forms/getformsbytypes.md): Retrieves all available forms grouped by form type (library, customs, intelligent, questionnaires, candidates, referees).

## Uploads

File uploads

### Get upload

 - [GET /uploads/{upload_id}](https://docs.checkmate.tech/api/uploads/getupload.md): Retrieves upload object.

### Delete upload

 - [DELETE /uploads/{upload_id}](https://docs.checkmate.tech/api/uploads/deleteupload.md): Deletes an upload.

## Webhooks

{% admonition type="info" name="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.
{% /admonition %}

{% admonition type="info" name=":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.
{% /admonition %}


### Create or update webhook

 - [POST /webhooks](https://docs.checkmate.tech/api/webhooks/createorupdatewebhook.md): Creates or updates the Webhook for the company. Only one webhook per company and partner.
The Webhook will POST to the provided URL whenever a candidate check created using the same partner (unless global) changes status.