Candidates

Candidates represent the people you'll be running reports on.
All candidates must consent to the required legal documents before the report can begin processing.
Use this resource to collect all Personally Identifiable Information (PII) required to order a report or invite the candidate.

List candidates

Retrieve a paginated list of candidates. See Pagination.

SecurityApiKey
Request
query Parameters
order
string

Order listing results in ascending or descending order, when using order_by.
Accepted values are asc or desc. If not passed, defaults to ascending asc.

Examples:
order=desc
order_by
string

Order listing results by a specific property.

Examples:
order_by=created_at
page
integer

The page number to retrieve.

per_page
integer

The maximum number of results per page.

query
string

Filter listing results by a specific property.

Examples:
query[created_at_gteq]=2022-01-01T00:00:00.000Z
Responses
200

List of candidates

401

Unauthorized

404

Not Found

get/candidates
Request samples 
Response samples 
application/json
{
  • "object": "list",
  • "meta": {
    },
  • "data": [
    ]
}
Create a candidate
A candidate is the person whose information we'll use when you order a report. As far as providing their information to Yardstik, you have a couple of options.


Ask the candidate to enter their own info


If you plan to create an invitation or have the candidate enter their information in an embedded Yardstik view, you only need to provide the strictly required attributes when you create the candidate


    

  • first_name
    • 

  • last_name
    • 

  • email
    • 



Based on the package, the candidate will be presented with a form to enter the rest of the information needed to run their report. If you have additional candidate information, feel free to provide it. We’ll autofill it into the candidate’s form, saving them time.


Provide all candidate info yourself


If you have all of the candidate's information on-hand, you can provide it to Yardstik directly. The information required for each package will differ somewhat, so we recommend that you reference the intake_fields array on the list all packages response for the package you plan to use. Provide the required intake fields when you create the candidate. Some of the most commonly required candidate-level intake fields are


    

  • first_name
    • 

  • last_name
    • 

  • email
    • 

  • phone
    • 

  • ssn
    • 

  • date_of_birth
    • 

  • zip_code
    • 

  • driver_license_number
    • 

  • driver_license_state
    • 



Some packages additionally require screening-level fields (a separate intake_fields array within the screenings object on the same response), which you can send when you create the report. If any of the required intake fields are missing when you create a report with account_candidate_consented: true, we’ll invite the candidate to enter the missing information themselves.


SecurityApiKey 
Request 
Request Body schema: application/json
required
Array of objects
The addresses of the candidate.


 
object (CustomFieldsCreateOrUpdate) 
Custom fields must be passed in an object in key-value format 
 
Example:


{
  age: 31,
  hire_date: "2024-03-15",
  former_employee: true
}



 
date_of_birth
string or null <date-time> 
The date of birth of the candidate.


 
driver_license_number
string or null
The drivers license number of the candidate.


 
driver_license_state
string or null
The state the candidate's drivers license is issued by as ISO 3166-2 two letter code.


 
email
required
string
The email address of the candidate.


 
external_id
string or null
This field you can use to store any identifier that you could track back on your application.


 
first_name
required
string
The first name of the candidate.


 
gender
string or null
The gender of the candidate.


 
last_name
required
string
The last name of the candidate.


 
object
Relevant links for a candidate


 
middle_name
string or null
The middle name of the candidate.


 
no_middle_name
boolean or null
True if candidate has no middle name, otherwise False or null..


 
phone
string or null
The primary SMS capable phone number of the candidate. 
 Must be E.164 format, e.g. +14155552671.


 
previous_driver_license_number
string or null
The previous drivers license number of the candidate.


 
previous_driver_license_state
string or null
The state the candidate's previous drivers license is issued by as ISO 3166-2 two letter code.


 
ssn
string
The social security number of the candidate. 
 Must be formatted as ###-##-#### or #########, e.g. 111-11-1111 or 111111111. 

 The following SSNs are considered invalid per SSA guidelines: 
 - Area number (first 3 digits) cannot be 000, 666, or 900–999 
 - Group number (middle 2 digits) cannot be 00 
 - Serial number (last 4 digits) cannot be 0000 

 This field is write-only by default. It is included in responses only when the account has full SSN access enabled.


 
Responses 
200
Candidate already exists.


201
Candidate was created successfully.


401
Unauthorized


404
Not Found


422
Unprocessable Entity


post/candidates
Request samples 
application/json
{ }
Response samples 
application/json
{
  • "id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "object": "candidate",
  • "full_name": "string",
  • "first_name": "string",
  • "middle_name": "string",
  • "no_middle_name": true,
  • "last_name": "string",
  • "email": "joe.clean@example.com",
  • "phone": "+14155552671",
  • "ssn": "111-22-3333",
  • "ssn_masked": "string",
  • "additional_data": { },
  • "guardian": {
    },
  • "active": true,
  • "copy_requested": true,
  • "date_of_birth": "2019-08-24T14:15:22Z",
  • "date_of_birth_masked": "string",
  • "gender": "string",
  • "driver_license_number": "string",
  • "driver_license_number_masked": "string",
  • "driver_license_state": "string",
  • "previous_driver_license_number": "string",
  • "previous_driver_license_state": "string",
  • "evergreen": true,
  • "external_id": "string",
  • "account": {
    },
  • "reports": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "meta": {
    },
  • "addresses": [
    ],
  • "custom_fields": [
    ]
}
Get a candidate
Retrieve a candidate with the given ID.


SecurityApiKey 
Request 
path Parameters
candidate_id
required
string <uuid>  (ResourceId)   <= 50 characters 
The candidate unique identifier.


 
 Example:  4f6cf35x-2c4y-483z-a0a9-158621f77a21
Responses 
200
Candidate details.


401
Unauthorized


404
Not Found


get/candidates/{candidate_id}
Request samples 
Response samples 
application/json
{
  • "id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "object": "candidate",
  • "full_name": "string",
  • "first_name": "string",
  • "middle_name": "string",
  • "no_middle_name": true,
  • "last_name": "string",
  • "email": "joe.clean@example.com",
  • "phone": "+14155552671",
  • "ssn": "111-22-3333",
  • "ssn_masked": "string",
  • "additional_data": { },
  • "guardian": {
    },
  • "active": true,
  • "copy_requested": true,
  • "date_of_birth": "2019-08-24T14:15:22Z",
  • "date_of_birth_masked": "string",
  • "gender": "string",
  • "driver_license_number": "string",
  • "driver_license_number_masked": "string",
  • "driver_license_state": "string",
  • "previous_driver_license_number": "string",
  • "previous_driver_license_state": "string",
  • "evergreen": true,
  • "external_id": "string",
  • "account": {
    },
  • "reports": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "meta": {
    },
  • "addresses": [
    ],
  • "custom_fields": [
    ]
}
Update a candidate
Update a candidate with the given ID.


SecurityApiKey 
Request 
path Parameters
candidate_id
required
string <uuid>  (ResourceId)   <= 50 characters 
The candidate unique identifier.


 
 Example:  4f6cf35x-2c4y-483z-a0a9-158621f77a21
Request Body schema: application/json
required
Array of objects
The addresses of the candidate.


 
object (CustomFieldsCreateOrUpdate) 
Custom fields must be passed in an object in key-value format 
 
Example:


{
  age: 31,
  hire_date: "2024-03-15",
  former_employee: true
}



 
date_of_birth
string or null <date-time> 
The date of birth of the candidate.


 
driver_license_number
string or null
The drivers license number of the candidate.


 
driver_license_state
string or null
The state the candidate's drivers license is issued by as ISO 3166-2 two letter code.


 
email
required
string
The email address of the candidate.


 
external_id
string or null
This field you can use to store any identifier that you could track back on your application.


 
first_name
required
string
The first name of the candidate.


 
gender
string or null
The gender of the candidate.


 
last_name
required
string
The last name of the candidate.


 
object
Relevant links for a candidate


 
middle_name
string or null
The middle name of the candidate.


 
no_middle_name
boolean or null
True if candidate has no middle name, otherwise False or null..


 
phone
string or null
The primary SMS capable phone number of the candidate. 
 Must be E.164 format, e.g. +14155552671.


 
previous_driver_license_number
string or null
The previous drivers license number of the candidate.


 
previous_driver_license_state
string or null
The state the candidate's previous drivers license is issued by as ISO 3166-2 two letter code.


 
ssn
string
The social security number of the candidate. 
 Must be formatted as ###-##-#### or #########, e.g. 111-11-1111 or 111111111. 

 The following SSNs are considered invalid per SSA guidelines: 
 - Area number (first 3 digits) cannot be 000, 666, or 900–999 
 - Group number (middle 2 digits) cannot be 00 
 - Serial number (last 4 digits) cannot be 0000 

 This field is write-only by default. It is included in responses only when the account has full SSN access enabled.


 
Responses 
200
Candidate details.


401
Unauthorized


404
Not Found


422
Unprocessable Entity


patch/candidates/{candidate_id}
Request samples 
application/json
{ }
Response samples 
application/json
{
  • "id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "object": "candidate",
  • "full_name": "string",
  • "first_name": "string",
  • "middle_name": "string",
  • "no_middle_name": true,
  • "last_name": "string",
  • "email": "joe.clean@example.com",
  • "phone": "+14155552671",
  • "ssn": "111-22-3333",
  • "ssn_masked": "string",
  • "additional_data": { },
  • "guardian": {
    },
  • "active": true,
  • "copy_requested": true,
  • "date_of_birth": "2019-08-24T14:15:22Z",
  • "date_of_birth_masked": "string",
  • "gender": "string",
  • "driver_license_number": "string",
  • "driver_license_number_masked": "string",
  • "driver_license_state": "string",
  • "previous_driver_license_number": "string",
  • "previous_driver_license_state": "string",
  • "evergreen": true,
  • "external_id": "string",
  • "account": {
    },
  • "reports": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "meta": {
    },
  • "addresses": [
    ],
  • "custom_fields": [
    ]
}
Delete candidate address.
Permanently delete a candidate's address by the given address id.


SecurityApiKey 
Request 
path Parameters
address_id
required
string <uuid>  (ResourceId)   <= 50 characters 
The address ID.


 
 Example:  4f6cf35x-2c4y-483z-a0a9-158621f77a21
candidate_id
required
string <uuid>  (ResourceId)   <= 50 characters 
The candidate ID.


 
 Example:  4f6cf35x-2c4y-483z-a0a9-158621f77a21
Responses 
200
Deleted address details.


401
Unauthorized


404
Not Found


422
Unprocessable Entity


delete/candidates/{candidate_id}/addresses/{address_id}
Request samples 
Response samples 
application/json
{
  • "id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "object": "address",
  • "line1": "string",
  • "line2": "string",
  • "city": "string",
  • "state": "string",
  • "zip_code": "string",
  • "country": "string",
  • "current": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}
List candidate documents.
Retrieve a paginated list of documents for a candidate. See Pagination.


SecurityApiKey 
Request 
path Parameters
candidate_id
required
string <uuid>  (ResourceId)   <= 50 characters 
The candidate ID.


 
 Example:  4f6cf35x-2c4y-483z-a0a9-158621f77a21
query Parameters
page
integer
The page number to retrieve.


 
per_page
integer
The maximum number of results per page.


 
Responses 
200
List of documents


401
Unauthorized


404
Not Found


get/candidates/{candidate_id}/documents
Request samples 
Response samples 
application/json
{
  • "object": "list",
  • "meta": {
    },
  • "data": [
    ]
}
Create a new candidate document.
When sending a request to create a document, you can send the file in two different ways. 

 1. You can send the file as a binary file using the multipart/form-data content type. 

 2. You can send the parameter file_base64 as a base64 encoded string using the application/json content type. 

 The file size limit is 10MB.


SecurityApiKey 
Request 
path Parameters
candidate_id
required
string <uuid>  (ResourceId)   <= 50 characters 
The candidate ID.


 
 Example:  4f6cf35x-2c4y-483z-a0a9-158621f77a21
Request Body schema: application/json
document_type
required
string
The type of the document. Supported document types:
 
     
  • drivers_license_back
    •  
  • drivers_license_front
    •  
  • ga_statewide
    •  
  • pa_mvr
    •  
  • professional_license
    •  
  • proof_of_driving_experience
    •  
  • proof_of_employment
    •  
  • proof_of_insurance
    •  
  • ssn_card_front
    •  
  • va_statewide
    •  
  • medical_examiners_certificate
    •  


 
file
required
string
When using the multipart/form-data content type, the file must be sent as a binary file. 

 The file to upload. The file size limit is 10MB. 

 This is not a required field, if you send the file_base64 field, this field will be ignored.


 
file_base64
required
string
When using the application/json content type, the file must be sent as a base64 encoded string. 

 The file to upload encoded in base64. The file size limit is 10MB. 

 This is not a required field, if you send the file field, this field will be ignored.


 
filename
string
The filename of the document, this is the original filename that is being uploaded. You can override this filename by sending the filename in the request body.


 
id
string <uuid>   <= 50 characters 
The document identifier.


 
Responses 
200
Create document details.


401
Unauthorized


404
Not Found


422
Unprocessable Entity


post/candidates/{candidate_id}/documents
Request samples 
application/json
{
  • "document_type": "string",
  • "file": "string",
  • "file_base64": "string"
}
Response samples 
application/json
{
  • "id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "filename": "string",
  • "content_type": "string",
  • "document_type": {
    },
  • "url": "string",
  • "file_size": 0,
  • "created_at": "string",
  • "updated_at": "string"
}
Get a candidate document
Retrieve a candidate document with the given ID.


SecurityApiKey 
Request 
path Parameters
candidate_id
required
string <uuid>  (ResourceId)   <= 50 characters 
The candidate ID.


 
 Example:  4f6cf35x-2c4y-483z-a0a9-158621f77a21
document_id
required
string <uuid>  (ResourceId)   <= 50 characters 
The document ID.


 
 Example:  4f6cf35x-2c4y-483z-a0a9-158621f77a21
Responses 
200
Document details.


401
Unauthorized


404
Not Found


get/candidates/{candidate_id}/documents/{document_id}
Request samples 
Response samples 
application/json
{
  • "id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "filename": "string",
  • "content_type": "string",
  • "document_type": {
    },
  • "url": "string",
  • "file_size": 0,
  • "created_at": "string",
  • "updated_at": "string"
}
Proceed a report
Proceed a candidate's report that is in a status of consider. If successful, the report will update to a proceed status. This is a positive result, indicating that the results found on the report do not disqualify the candidate.


SecurityApiKey 
Request 
path Parameters
candidateId
required
string
 
Request Body schema: application/json
report_id
required
string <UUID> 
Unique identifier for the report.


 
Responses 
200
OK


401
Unauthorized


404
Not Found


422
Unprocessable Entity


patch/candidates/{candidateId}/approve_by_report
Request samples 
application/json
{
  • "report_id": "string"
}
Response samples 
application/json
{
  • "id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "object": "candidate",
  • "full_name": "string",
  • "first_name": "string",
  • "middle_name": "string",
  • "no_middle_name": true,
  • "last_name": "string",
  • "email": "joe.clean@example.com",
  • "phone": "+14155552671",
  • "ssn": "111-22-3333",
  • "ssn_masked": "string",
  • "additional_data": { },
  • "guardian": {
    },
  • "active": true,
  • "copy_requested": true,
  • "date_of_birth": "2019-08-24T14:15:22Z",
  • "date_of_birth_masked": "string",
  • "gender": "string",
  • "driver_license_number": "string",
  • "driver_license_number_masked": "string",
  • "driver_license_state": "string",
  • "previous_driver_license_number": "string",
  • "previous_driver_license_state": "string",
  • "evergreen": true,
  • "external_id": "string",
  • "account": {
    },
  • "reports": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "meta": {
    },
  • "addresses": [
    ],
  • "custom_fields": [
    ]
}
➔ Next to Consents