Verified First provides an API that allows access to client data for full or partial integrations with various partner systems. We also provide standard request and response formats that can be used to:

Place orders and retrieve order information
Retrieve account information and product information
Create, modify, or delete packages and users

Verified First provides endpoints for both production and staging/test environments:

Production Environment:

Verified First Production Portal: https://portal.verifiedfirst.com/

Associated API: https://api1.verifiedfirst.com/external/verified-first/

Staging/Test Environment:

Verified First Staging/Test Portal: https://staging.verifiedfirst.com

Associated API: https://api2.verifiedfirst.com/external/verified-first/

All new integrations and API connections must first be implemented and reviewed in the Staging/Test Environment. In order to successfully implement and review in Staging/Test environment, you must meet the following requirements:

There must be a user account in both the Verified First Production and Staging Portals.
You must coordinate with the Verified First Integrations team to configure, setup, and activate the formats. You can contact our Integrations Team at integrations@verifiedfirst.com to request a partial or full API integration with the Verified First platform.
Verified First will need to whitelist external domains and/or IP addresses. Please contact our Integrations Team at integrations@verifiedfirst.com to request additions to our whitelist.

Here are some examples of common API operations and the standard formats utilized by our partners.

Create Order - Used to Place an Order

Method:	POST
Endpoints:	Production: https://api1.verifiedfirst.com/external/verified-first/order Test: https://api2.verifiedfirst.com/external/verified-first/order
HTTP Header:	Content Type: application/json Authorization: Basic *********** - Type: Basic Authorization
HTTP Status Codes:	Success 200 Error 400, 403, 500
Request Body:	{ "order": { "search_type": "instant/app_invitation", "partner_applicant_ids": ["external id"], "package_id": "vf id", "first_name": "Hank", "middle_name": "F", "last_name": "Mess", "email": "hankthemess@gmail.com", "phone": "2125551212", "dob": "07/07/1977", "street": "123 Main St", "ssn": "333-22-1111", "city": "Houston", "state": "Texas", "zip": "77077", "mvrlicensenumber": "xxxxxxxxx", "mvrstate": "FL/Florida", "mvrduration": "3", "job_state": "Texas", "sms_message": "Yes/No/true/false", "manual_review": "Yes/No/true/false", "reference_code": "Sales Position", "annual_salary": "14.000", "urine_test_purpose": "Retest", "attachments": [ { "file_name": "fileName.png", "file_url": "url", "content_type": "image/png" } ] } }
Field Definitions	search_type - The search type of the order. Required. Can be 2 values: instant - order will be placed instantly app_invitation - order will be placed via invitation app. partner_applicant_ids - array with unique identifier of applicant from external system. Optional. package_id - ID of package for ordering. Optional. sms_message - option to invite via text message. Optional. manual_review - option to review data entered by the individual and manually order the report. Optional. job_state - state of job. Optional. attachments - array of files. Optional. file_name - Name of attaching file file_url - URL of attaching file content_type - Content type of attaching file urine_test_purpose - purpose for drug tests. first_name - First name of applicant. Required. last_name - Last name of applicant. Required. email - email of applicant. Required. ssn - SSN of applicant. Required for instant order for most products. middle_name - Middle name of applicant. Optional. generation - Generation of applicant. Optional. phone - Phone # of applicant. Optional. dob - Date of birth of applicant. Optional. street - Street address of applicant. Optional. city - City address of applicant. Optional. state - State address of applicant. Optional. zip - Zip address of applicant. Optional. mvrlicensenumber - License number for MVR. Optional for app_invitation; required for instant order. mvrstate - State for MVR. Optional for app_invitation; required for instant order. mvrduration - Duration for MVR. Optional. Note: the field "mvrlicensenumber", "mvrduration", and "mvrstate" can only be added for an instant order and will be proceeded if the selected package contains an MVR product. In addition, the field "urine_test_purpose" can only be added for "app_invitation" orders and will be proceeded if the selected package contains a Drug Screening product. The following values are available for the field “urine_test_purpose”: "Pre-Employment", "Random", "Periodic", "Post Incident", "For Cause", "Reasonable Suspicion", "Return To Duty", "Follow Up", "Reconfirmation", "Retest", "Point Of Collection Sampling", "Student", and "Other".
Response Body:	`{ "type": "background order", "order": { "order_id": "ec2d5720-xxxx-11e9-b039-01afafdeefa5" } }`

Create Batch Order - Used to Place a Batch Order

Method:	POST
Endpoints:	Production: https://api1.verifiedfirst.com/external/verified-first/batch-order Test: https://api2.verifiedfirst.com/external/verified-first/batch-order
HTTP Header:	Content Type: application/json Authorization: Basic *********** -Type: Basic Authorization
HTTP Status Codes:	Success 200 Error 400, 403, 500
Request Body:	`{ "order":{ "package_id": "vf id", "applicants":[ { "first_name": "Hank", "middle_name": "F", "last_name": "Mess", "email": "hankthemess@gmail.com", "dob": "07/07/1977", "ssn": "333-22-1111", "partner_applicant_ids": ["external IDs"], "job_state": "Texas/TX", "phone": "2125551212", "street": "123 Main St", "city": "Houston", "state": "Texas", "zip": "77077" } ], "job_state": "Texas/TX", "manual_review": "Yes/No/true/false", "sms_message": "Yes/No/true/false" } }`
Field Definitions:	package_id - ID of package for ordering. Optional. sms_message - option to invite via text message. Optional. manual_review - option to review data entered by the individual and manually order the report. Optional. job_state - state of job. Optional. applicants - array of applicant Applicant: first_name - First name of applicant. Required. last_name - Last name of applicant. Required. email - email of applicant. Required. ssn - SSN of applicant. Required for instant order for most products. middle_name - Middle name of applicant. Optional. generation - Generation of applicant. Optional. phone - Phone # of applicant. Optional. dob - Date of birth of applicant. Optional. street - Street address of applicant. Optional. city - City address of applicant. Optional. state - State address of applicant. Optional. zip - Zip address of applicant. Optional. job_state - state of job for specific applicant. Optional. partner_applicant_ids - array with unique identifier of applicant from external system. Optional.

Get Package List - Retrieve list of defined packages in Verified First

Method:	GET
Endpoints:	Production: https://api1.verifiedfirst.com/external/verified-first/package/list Test: https://api2.verifiedfirst.com/external/verified-first/package/list
HTTP Header:	Content Type: application/json Authorization: Basic *********** - Type: Basic Authorization
HTTP Status Codes:	Success 200 Error 400, 403, 500
Request Body:	None
Response Body:	{ "type": "package list", "package_list": [ { "package_id": "5ff7f1d0-xxxx-11e8-9666-a189d7700ee6", "package_name": "Verified Basic _sub_1", "product_list": [ "Adjudication" ] }, { "package_id": "5ff83eef0-xxxx-11e8-9666-a189d7700ee6", "package_name": "Verified Preferred _ sub_1", "product_list": [ "Social Security Address Trace", "Nationwide Sex Offender Registry", "Adjudication", "Employment Verification", ] }, { "package_id": "5ff86700-xxx-11e8-9666-a189d7700ee6", "package_name": "Verified Plus _sub_1", "product_list": [ "Social Security Address Trace", ] } ] }

POST Back Request

The Verified First API provides a method to send order results to an external platform if the following items are provided from the external system:

API Endpoint
Authorization header or credentials to authenticate the message

The data sent from Verified First does not contain any Personally Identifiable Information (PII) and can be stored in external platforms without the worry of inadvertently releasing access to sensitive information.

Example of Standard Verified First Request

{
	"type": "background status",
	"status_update": {
		"partner_applicant_ids": ["xxx-a84d00af4eea"],
		"account_number": "111-2222-33333-444444",
		"order_id": "b06a10e0-xxx-11e8-8c06-017b64ae2d2844",
		"order_number": "V1xxxxx",
		"flagged": "No",
		"package_name": "Verified Basic",
		"products_ordered": [
			"Social Security Address Trace",
			"Nationwide Criminal Database",
			"Adjudication"
		],
		"reference_code": "Salaries",
		"status": "Complete",
		"state": "Active",
		"adjudication": "In Need of Review",
		"url": "https://portal.verifiedfirst.com/#/report-results/b06a10e0-ef0b-11e8-xxx-017b64ae2d2844",
		"order_completed_date": "2018-12-05T18:58:31Z",
		"last_status_date": "2018-12-05T18:58:31Z"
	}
}

Field Definitions:

partner_applicant_ids - Unique identifier of applicant from external system (received from value(s) defined in "Create Order" API call)
account_number - Account number assigned by Verified First
order_id - Internal Verified First order identifier
order_number - Order number created by Verified First
flagged - Indicates if the order is flagged (Yes/No)
package_name - Package name used for the order
products_ordered - The list of products contained in the selected package for the order
reference_code - Reference code associated with the order (optional)
status - The latest status of the order
- Applicant Declined - the applicant clicked on the "Refuse the Background Check" link in the applicant invite email
- Applicant Invitation Expired - the applicant failed to complete the applicant invite within the allotted time
- Applicant is Minor - the applicant is younger than 15 years old and the application has been canceled
- Canceled - the order has been canceled by the vendor
- Complete - the file has been completed and results returned
- Draft Orders - the Verified First portal user has begun the order processing, but did not complete and submit the order
- Error - an error was generated when an order for a report was placed
- File Ordered - the background check has been ordered
- Invitation Sent - an invitation has been sent to applicant to complete their portion of the background screen
- Partially Complete - at least one product in the order has been marked as completed for the file
- Ready to Order - the applicant has finished the invitation and the order is ready for review. Requires account settings (Gear > Admin > Account > Review Process) to be set to either "Allow Both" or "Manual Order Only"
- User Withdrew the Invite - the applicant invite has been withdrawn
- Waiting on Applicant - the order has been created and information is needed from the applicant in order to submit the order
state - The activation state of the order. Orders that are archived (either manually or by scheduled expiration) move from "Active" state to "Inactive" state. (Active/Inactive)
adjudication - Adjudication status of the order (this field will only have values populated if "status" is "Complete")
- Ready for Review
- Approved
- Pre-Adverse Action
- Adverse Action
url - Link to view order
order_completed_date - Date that the order was completed (will be filled when "status" is "Complete")
last_status_date - Date of the most recent status update

Generate Pre-Signed URL for Upload Attachments

Method:	GET
Endpoint:	Production: https://api1.verifiedfirst.com/external/verified-first/signed-url Test: https://api2.verifiedfirst.com/external/verified-first/signed-url
HTTP Header:	Content Type: application/json Authorization: Basic *********** -Type: Basic Authorization
HTTP Status Codes:	Success 200 Error 400, 403, 500
Request Body:	None
Request Parameters	file_name: file.png
Response Body:	`{ "upload_url": "https:/pre_signed_url", "file_url": "https://file_url/file.png" }`
Description	The link will expire after 15 minutes; The file_url field should be used for create order; The upload file should be used for upload file in temporary; Available next file types: pdf, txt, rtf, doc, docx, xls, xlsx, odt, ods, jpg, png, gif, tif, tiff

Upload Attachments

Method:	PUT
Endpoint:	The pre-signed URL should be from get presigned URL. Also the get presigned request return required parameters.
HTTP Header:	Content Type: [The content type of uploading file]
HTTP Status Codes:	Success 200 Error 400, 403, 500
Request Body:	[binary of files]
Response Body

If you have any further questions, or need a product enabled on your account, 
please contact Verified First Client Services for assistance.

Call 844-709-2708 or email ClientServices@VerifiedFirst.com

Articles in this section

Standard API Request and Response Formats

Create Order - Used to Place an Order

Get Package List - Retrieve list of defined packages in Verified First

POST Back Request

Comments

Articles in this section

Create Order - Used to Place an Order

Get Package List - Retrieve list of defined packages in Verified First

POST Back Request

Related articles