Articles in this section

Standard API Request and Response Formats

Avatar
Stacy
  • Updated
Follow

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



Was this article helpful?
7 out of 11 found this helpful
Return to top

Related articles

Comments

0 comments

Please sign in to leave a comment.