Candidates

Candidates represent the individuals being screened. You must create a candidate before ordering a background check report.

POST/v1/candidates

Create a Candidate

Creates a new candidate profile. An invitation email can optionally be sent to collect consent and additional personal information.

Request Body

Field	Type	Required	Description
email	string	Yes	Candidate's email address
firstName	string	Yes	Legal first name
lastName	string	Yes	Legal last name
phone	string	No	E.164 formatted phone number
middleName	string	No	Legal middle name
sendInvitation	boolean	No	Send invitation email to candidate (default: true)
metadata	object	No	Arbitrary key-value pairs for your own use

Example Request

curl

curl -X POST https://api.coreverify.com/v1/candidates \
  -H "Authorization: Bearer sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "firstName": "Jane",
    "lastName": "Doe",
    "phone": "+15551234567",
    "sendInvitation": true
  }'

Response

201 Created

{
  "data": {
    "id": "cand_7xKm2pQrNvLw",
    "email": "[email protected]",
    "firstName": "Jane",
    "lastName": "Doe",
    "phone": "+15551234567",
    "status": "invitation_sent",
    "invitationSentAt": "2024-03-15T14:22:00Z",
    "createdAt": "2024-03-15T14:22:00Z",
    "updatedAt": "2024-03-15T14:22:00Z"
  }
}

GET/v1/candidates

List Candidates

Returns a paginated list of all candidates in your account, sorted by creation date descending.

Query Parameters

Parameter	Type	Description
page	integer	Page number (default: 1)
per_page	integer	Results per page, max 100 (default: 25)
email	string	Filter by email address (exact match)
status	string	Filter by status: `invitation_sent`, `completed`, `pending`
from	string	ISO 8601 date — filter candidates created on or after this date
to	string	ISO 8601 date — filter candidates created on or before this date

Example Response

200 OK

{
  "data": [
    {
      "id": "cand_7xKm2pQrNvLw",
      "email": "[email protected]",
      "firstName": "Jane",
      "lastName": "Doe",
      "status": "completed",
      "createdAt": "2024-03-15T14:22:00Z"
    },
    {
      "id": "cand_9mWn4bRsTeXz",
      "email": "[email protected]",
      "firstName": "John",
      "lastName": "Smith",
      "status": "invitation_sent",
      "createdAt": "2024-03-14T09:11:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 25,
    "total": 142,
    "total_pages": 6
  }
}

GET/v1/candidates/:id

Retrieve a Candidate

Returns the full details of a single candidate by their ID.

Example Response

200 OK

{
  "data": {
    "id": "cand_7xKm2pQrNvLw",
    "email": "[email protected]",
    "firstName": "Jane",
    "middleName": "Marie",
    "lastName": "Doe",
    "phone": "+15551234567",
    "status": "completed",
    "dateOfBirth": "1990-06-15",
    "ssn": "***-**-4321",
    "address": {
      "street": "123 Main St",
      "city": "San Francisco",
      "state": "CA",
      "zip": "94105",
      "country": "US"
    },
    "driverLicense": {
      "number": "D1234567",
      "state": "CA"
    },
    "invitationSentAt": "2024-03-15T14:22:00Z",
    "completedAt": "2024-03-15T15:45:00Z",
    "metadata": {
      "requisition_id": "REQ-2024-0301",
      "department": "engineering"
    },
    "createdAt": "2024-03-15T14:22:00Z",
    "updatedAt": "2024-03-15T15:45:00Z"
  }
}