---
title: "Create a reference check"
method: POST
path: "/checks"
tags: ["Checks"]
---

# Create a reference check

`POST /checks`

## Request

- Base URL: `https://verifyref.com/api/v1`
- URL: `https://verifyref.com/api/v1/checks`
- Auth: HTTP bearer

## Headers

- `Idempotency-Key` string

## Request body

- CreateCheckRequest: Provide either questionnaireId OR questionnaireTitle + questions[]. Provide references[] unless candidateProvidedReferences is true. externalId and externalSource must be provided together.
  - `candidateName` string, required
  - `candidateEmail` string, email, required
  - `candidateId` string: Talent pool candidate ID
  - `addToTalentPool` boolean
  - `candidateProvidedReferences` boolean
  - `externalId` string
  - `externalSource` 'bullhorn' | 'zoho_recruit' | 'sap_successfactors' | 'workday' | 'greenhouse' | 'lever' | 'other'
  - `metadata` object
  - `jobId` string
  - `newJob` NewJob
    - `title` string
    - `description` string
    - `status` 'OPEN' | 'CLOSED'
    - `location` string
    - `department` string
  - `questionnaireId` string
  - `questionnaireTitle` string
  - `questionnaireDescription` string
  - `questions` Question[]
    - `text` string, required
    - `type` 'TEXT' | 'TEXTAREA' | 'RATING' | 'MULTIPLE_CHOICE' | 'YES_NO', required
    - `required` boolean
    - `order` number, required
    - `options` string: Required for MULTIPLE_CHOICE (serialized choices)
  - `references` ReferenceInput[]
    - `name` string, required
    - `email` string, email, required
    - `relationship` string, required

## Response `201`

Check created

- CreateCheckResponse
  - `success` boolean
  - `checkId` string
  - `status` string
  - `jobId` string, nullable
  - `externalId` string, nullable
  - `externalSource` string, nullable
  - `sandbox` boolean
  - `idempotentReplay` boolean

## Other responses

- `402`: Insufficient credits
- `409`: Duplicate externalId

---

[API](https://skmtc.dev/verifyref/apis/verifyref-api.md) · [All operations](https://skmtc.dev/verifyref/apis/verifyref-api/llms.txt) · [OpenAPI document](https://skmtc.dev/verifyref/apis/verifyref-api/revisions/28eea5e6525b?raw)