Reports

Reports contain the results of all background screens, searches, and verifications defined in the account package that was selected while creating the report.

See the Order Your First Report section.

List reports

Retrieve a paginated list of reports. 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 reports.

401

Unauthorized

404

Unauthorized

get/reports
Request samples 
Response samples 
application/json
{
  • "object": "list",
  • "meta": {
    },
  • "data": [
    ]
}
Create a report
Create a new report. The report will be generated based on the candidate ID provided.
 See Create Candidate for required attributes.
The account packages available will be configured during onboarding by Yardstik.
 Each account package will be configured with a set of screenings and configurations that determine the report flow and candidate experience.

 To see available packages use List Account Packages.


SecurityApiKey 
Request 
Request Body schema: application/json
account_candidate_consented
boolean
If false (or not sent), indicates that you're relying on Yardstik to capture candidate consent. Once the report is created, retrieve the apply url from the meta in the response and provide to your candidate so they can enter their information and consent.


If true, indicates that you've already obtained candidate consent. As long as you provide all necessary info, the report will process without candidate interaction. However, if you miss anything, we'll check your allow_invitation setting to determine whether to send an invite to the candidate to collect the missing info or return an error communicating what's missing. This feature must be enabled for your account.


 
account_package_id
required
string <UUID> 
The account package ID for the package you want use to create a report. Use id from List Account Packages.


 
allow_invitation
boolean
Only applies to reports ordered with account_candidate_consented: true. To order reports with this type of consent, the feature must be enabled for your account. If sent without enabling the feature, you'll receive an error.


If true, upon ordering the report, if required information is missing, Yardstik will automatically create an invitation and send to the candidate so they can provide the missing info.


If false, upon ordering the report, if required information is missing, Yardstik will return an error communicating what's missing. Yardstik will neither create the report nor create an invitation in this case.


If not sent, your account-level allow_invitation setting will be honored. By default this is true unless you've requested that Yardstik change it for you.


 
candidate_id
required
string <UUID> 
Unique identifier for the candidate.


 
group_id
string or null <UUID> 
The ID of a group to assign the report to. The group must belong to your account.


You can also assign or change the group after creation using the Assign a report to a group endpoint.


 
on_hold
boolean
 Default:  false
If true, the report will be created in on_hold status instead of processing immediately. This allows you to collect candidate information, then wait to process the report until certain conditions are met on your end.


To remove the hold and start processing, use the Remove hold from report endpoint.


 
reference_id
string
A reference ID that can be used for your application.


 
Responses 
201
Created


401
Unauthorized


422
Unprocessable Entity


post/reports
Request samples 
application/json
{
  • "candidate_id": "string",
  • "account_package_id": "string"
}
Response samples 
application/json
{
  • "id": "string",
  • "reference_id": "string",
  • "candidate_id": "string",
  • "status": "string",
  • "response_status": "string",
  • "adjudication": "string",
  • "submitted_at": "string",
  • "completed_at": "string",
  • "created_at": "string",
  • "updated_at": "string",
  • "decision": "string",
  • "usage_amount": 0,
  • "process_sequentially": true,
  • "permissible_purpose": "string",
  • "created_by": "string",
  • "candidate": {
    },
  • "account_id": "string",
  • "account_name": "string",
  • "report_url": "string",
  • "group": {
    },
  • "adverse_action_id": "string",
  • "report_screenings": [
    ],
  • "elapsed_timing": "string",
  • "package_name": "string",
  • "comments": [
    ],
  • "meta": {
    },
  • "adverse_action_settings": {
    }
}
Get a report
Get a report with the given ID.
 See the Report Lifecycle section for details on statuses, adverse actions, disputes, and downloading PDF results.


SecurityApiKey 
Request 
path Parameters
reportId
required
string
 
Responses 
200
OK


401
Unauthorized


404
Not Found


get/reports/{reportId}
Request samples 
Response samples 
application/json
{
  • "id": "string",
  • "reference_id": "string",
  • "candidate_id": "string",
  • "status": "string",
  • "response_status": "string",
  • "adjudication": "string",
  • "submitted_at": "string",
  • "completed_at": "string",
  • "created_at": "string",
  • "updated_at": "string",
  • "decision": "string",
  • "usage_amount": 0,
  • "process_sequentially": true,
  • "permissible_purpose": "string",
  • "created_by": "string",
  • "candidate": {
    },
  • "account_id": "string",
  • "account_name": "string",
  • "report_url": "string",
  • "group": {
    },
  • "adverse_action_id": "string",
  • "report_screenings": [
    ],
  • "elapsed_timing": "string",
  • "package_name": "string",
  • "comments": [
    ],
  • "meta": {
    },
  • "adverse_action_settings": {
    }
}
List report documents.
Retrieve a paginated list of documents for a report. See Pagination.


SecurityApiKey 
Request 
path Parameters
report_id
required
string <uuid>  (ResourceId)   <= 50 characters 
The report 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/reports/{report_id}/documents
Request samples 
Response samples 
application/json
{
  • "object": "list",
  • "meta": {
    },
  • "data": [
    ]
}
Create a new report 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
report_id
required
string <uuid>  (ResourceId)   <= 50 characters 
The report 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/reports/{report_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 report document
Retrieve a report document with the given ID.


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


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


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


401
Unauthorized


404
Not Found


get/reports/{report_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"
}
Assign a report to a group
Assign a report to a group with the given ID. The group must be enabled.

 To remove a group assignment, send group_id as null.


SecurityApiKey 
Request 
path Parameters
report_id
required
string <UUID> 
The report ID.


 
Request Body schema: application/json
required
group_id
required
string or null <UUID> 
The ID of the group to assign the report to. Send null to remove the group assignment.


 
Responses 
200
Group assignment was updated successfully.


401
Unauthorized


404
Not Found


422
Unprocessable Entity


patch/reports/{report_id}/assign-group
Request samples 
application/json
{
  • "group_id": "string"
}
Response samples 
application/json
{
  • "id": "string",
  • "reference_id": "string",
  • "candidate_id": "string",
  • "status": "string",
  • "response_status": "string",
  • "adjudication": "string",
  • "submitted_at": "string",
  • "completed_at": "string",
  • "created_at": "string",
  • "updated_at": "string",
  • "decision": "string",
  • "usage_amount": 0,
  • "process_sequentially": true,
  • "permissible_purpose": "string",
  • "created_by": "string",
  • "candidate": {
    },
  • "account_id": "string",
  • "account_name": "string",
  • "report_url": "string",
  • "group": {
    },
  • "adverse_action_id": "string",
  • "report_screenings": [
    ],
  • "elapsed_timing": "string",
  • "package_name": "string",
  • "comments": [
    ],
  • "meta": {
    },
  • "adverse_action_settings": {
    }
}
Remove hold from report
Remove a hold from a report with the given ID. Once the hold is removed, the report will process (it can't be placed on hold again).
 Report must be in on_hold status to be eligible for hold removal. See Report Statuses for more information about the on_hold status.


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


 
 Example:  4f6cf35x-2c4y-483z-a0a9-158621f77a21
Responses 
200
Report hold removed successfully


401
Unauthorized


404
Not Found


422
Unprocessable Entity


delete/reports/{report_id}/hold
Request samples 
Response samples 
application/json
{
  • "id": "string",
  • "reference_id": "string",
  • "candidate_id": "string",
  • "status": "string",
  • "response_status": "string",
  • "adjudication": "string",
  • "submitted_at": "string",
  • "completed_at": "string",
  • "created_at": "string",
  • "updated_at": "string",
  • "decision": "string",
  • "usage_amount": 0,
  • "process_sequentially": true,
  • "permissible_purpose": "string",
  • "created_by": "string",
  • "candidate": {
    },
  • "account_id": "string",
  • "account_name": "string",
  • "report_url": "string",
  • "group": {
    },
  • "adverse_action_id": "string",
  • "report_screenings": [
    ],
  • "elapsed_timing": "string",
  • "package_name": "string",
  • "comments": [
    ],
  • "meta": {
    },
  • "adverse_action_settings": {
    }
}
➔ Next to Groups