Standard API Request and Response Formats

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 successfuly 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

{
"type": "background order"
"order":{
   “search_type”: “instant/app_invitation”, Required
   "partner_applicant_ids": ["123", "4b5", "7c8"], Optional
   "package_id": “vf guid”, Optional
   "first_name": “Hank”, Required
   "middle_name": “F”, Optional
   "last_name": “Mess”, Required
   "generation": “Jr”, Optional
   "email": “hankthemess@gmail.com”, Required
   "phone": “212-555-1212” or (2125551212), Optional
   “sms_message”: “Yes/No”, Optional
   "dob": “07/07/1977”, Optional
   "street": “123 Main St”, Optional
   “ssn”: “111-22-3333” or (111223333), Required for most products
   "city": “Houston”, Optional
   "state": “Texas, Optional
   "zip": “77077”, Optional
   "job_state": “Texas” or (TX), Optional
   "reference_code": “Sales Position”, Optional
   “annual_salary”: “14.000” Optional
   "mvrlicensenumber": "xxxxxxx", Optional/Required
   "mvrduration": "3", Optional 
   "mvrstate": "FL/Florida" Optional/Required
   "urine_test_purpose:" "Retest" Option/Required
   “attachments”:[                                                   Optional 
                {
                       "file_name": "file_1.png",
                       "file_url": "https://***.com/***/file_1.png",
                       "content_type": "image/png"
                },
                {
                       "file_name": "file_2.png",
                       "file_url": "https://s3.amazonaws.com/…/file_2.png",
                       "content_type": "image/png"
                }
           ]
   }
}

{ 
"type": "background order",
   "order": {
       "order_id": "ec2d5720-0367-11e9-b039-01afafdeefa5"
   }
}

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.  

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

{
   "type": "package list",
   "package_list": [
       {
           "package_id": "5ff7f1d0-b4e7-11e8-9666-a189d7700ee6",
           "package_name": "Verified Basic _sub_1",
           "product_list": [
               "Adjudication"
           ]
       },
       {
           "package_id": "5ff83eef0-b4e7-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-b4e7-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.

{
 "type": "background status",
 "status_update": {
 "partner_applicant_ids": ["eb94d16f-12ce-406d-99ab-a84d00af4eea"],
 "account_number": "111-2222-33333-444444",
 "order_id": "b06a10e0-ef0b-11e8-8c06-017b64ae2d2844",
 "order_number": "2240992",
 "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://staging.verifiedfirst.com/#/report-results/b06a10e0-ef0b-11e8-8c06-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
  • Canceled - Order has been canceled by the vendor
  • Error - An error was generated when an order for a report was placed
  • Waiting on Applicant - Order has been created by the vendor
  • Invitation Sent - Invitation has been sent to applicant
  • Partially Ordered - Verified First Portal user has performed Pre-Pull tasks and has developed jurisdictions for the applicant, but has not completed the order
  • Ready to Order - 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"
  • File Ordered - Background check file has been ordered
  • Partially Complete - At least one selected product has been completed for the file
  • Complete - The file has been completed and returned
  • Applicant Refused the invitation - this means the applicant has refused to complete the applicant invite
  • User withdrew the invite - the applicant invite has been withdrawn
  • Applicant invitation expired - the applicant failed to complete the applicant invite within the allotted time
• 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")
  • In Need of 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 up-to-date status

Generate Pre-Signed URL for Upload Attachments

{
  "upload_url": "https:/pre_signed_url",
  "file_url": "https://file_url/file.png"
}

Upload Attachments

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