API Documentation

AccountChek LOS Workflow

The AccountChek Loan Origination System (LOS) Workflow provides a basic workflow for creating and building an AccountChek Order which will send an email to the Borrower to link their assets, and then retrieving the generated report and refreshing the report.

This workflow uses our Verifier API (Specifications).

A LOS workflow visual following what can be considered the “happy path” can be found HERE.

  1. Create an AccountChek Order
  2. Attach Services to the Order
  3. Set the Order to Opened
  4. Borrower Enrollment
  5. Check the Status
  6. Pull Lite Data
  7. Obtain the reportId
  8. Pull the Report
  9. Refresh a Report

Create an AccountChek Order

The first step of any AccountChek Order Workflow begins with creating an AccountChekOrder with Borrower information. See below for more details on the request and response.

Note: if you are not familiar with the term IntegratorId yet, please see documentation regarding implementing the IntegratorID and reach out to the AccountChek team.

Request

POST to /v1/accountchekorders

Specification Details

{
    "email": "johndoe@domain.com",
    "last4SSN": "6789",
    "referenceNumber": "1122334455",
    "firstName": "John",
    "lastName": "Doe",
    "notificationUrl": "https://example.com/accountchek/webhooks",
    "returnUrl": null,
    "phoneNumber": "706-123-4567",
    "employerName": "Informative Research",
    "ssn": "123-45-6789",
    "dateOfBirth": "1983-05-24",
    "address": {
        "street": "1234 Hawthorne Avenue",
        "street2": null,
        "city": "Athens",
        "state": "GA",
        "zip": "31032"
    }
}

See the table below for a list of the fields, a description of each field, and whether they are required or not. Note: Some fields are optional based on the type of verification you are going to be requesting on an AccountChek Order. Make sure to read each description to determine if you need to provide the field for the order.

Field Description Required/Optional
email The email of the Borrower for which you are opening the order. Email communications from the system to the Borrower will be sent to this email address. Required
last4SSN The last four digits of the Borrower social security number. Required
referenceNumber A value you may use to link an order to your system. Typically this value is a loan number. Required
firstName The first name of the Borrower. This value is used by the system when sending communications to the Borrower. You may also search on this value to find orders. Required
lastName The last name of the Borrower. This value is used by the system when sending communications to the Borrower. You may also search on this value to find orders. Required
notificationUrl When set, this URL will be called for all webhooks callbacks. See the webhooks documentation for more information. Optional
returnUrl The location the Borrower is redirected to after they logout. This is useful if you want the Borrower to be redirected to a custom location for later processing or a more integrated experience within your own systems. Optional
employerName Name of the employer for the Borrower. This field is only required if the Employment Report endpoints in Verifier API will be used for the AccountChek Order. AccountChek Plus does not require this field. Optional
phoneNumber A phone number that will be used to send a text message to the Borrower. This is required if this AccountChekOrder is going to include IdChek. Optional
ssn The full SSN of the Borrower. This is optional and should be sent if you are going to add a verification that needs it, like IdChek. If you send this value, you can skip sending the last4SSN property, as this value will overwrite any value you set there. The full value is never echoed here, only a masked value with the last 4 digits visible. Optional
dateOfBirth The date of birth of the Borrower. This is optional and should only be sent if you are going to add a verification that needs it, like IdChek. Optional
address The address information of the Borrower. This is optional and should only be sent if you are going to add a verification that needs it, like IdChek. Optional

Response

If the above request is successful, you will receive a HTTP Status 201 - Created. Below is an example of the body of the response.

{
    "id": "b943cae2-a8f5-e911-b5e9-0003ff4f1b49",
    "created": "2019-10-23T15:22:12.967Z",
    "isArchived": false,
    "status": "building",
    "loginUrl": "https://s-borrower.accountchek.net/Account/Login?vodkey=b943cae2a8f5e911b5e90003ff4f1b49",
    "daysRemaining": 58.222795108188656,
    "employmentVerificationRequested": false,
    "email": "johndoe@gmail.com",
    "last4SSN": "6789",
    "referenceNumber": "1122334455",
    "firstName": "John",
    "lastName": "Doe",
    "notificationUrl": null,
    "returnUrl": null,
    "phoneNumber": "706-123-4567",
    "employerName": "Informative Research",
    "ssn": "***-**-6789",
    "dateOfBirth": "1983-05-24T00:00:00Z",
    "address": {
        "street": "1234 Hawthorne Avenue",
        "street2": null,
        "city": "Athens",
        "state": "GA",
        "zip": "31032"
    }
}

If the above request is unsuccessful, you will receive a HTTP Status 422 - Unprocessable Entity. The response body will contain the details of the cause of the error. Below is the structure of an error response.

{
    "general": [
        "string"
    ],
    "properties": [
        {
            "property": "string",
            "message": "string"
        }
    ]
}

Attach Services to the Order

Once the order is successfully created, you will receive a unique orderId in the output. Using this orderId, you will need to attach a verification service to the AccountChekOrder.

Verification Services Available

To find out what verification services are available for a given client, use the below API call:

Request

GET to /v1/company/verifications

Specification Details

Response

If the above request is successful, you will receive a HTTP Status 200 - OK. Below is an example of the body of the response.

{
  "voaEnabled": true,
  "voieEnabled": true,
  "dvoeEnabled": true
}

Attach a Service

At least one service must be attached to an AccountChek order as part of the order creation process. You may attach either the VOA service or the VOIE/VOE service, or both depending on platform/client needs.

If only one service was attached at time of opening the AccountChek order, the other service can be attached later on as long as the order is not canceled or closed.

Once you find out which service(s) is available using the verifications endpoint, you can make the call to attach the desired services.

For VOA: Attach VOA Service

For VOIE: Attach VOIE Service

Set the Order to Opened

Now that you have created the AccountChekOrder and attached a service(s) to it, you can set the AccountChekOrder status to opened. To do this, you will need to make the below request.

Request

PATCH to /v1/accountchekorders/{orderId}

Specification Details

{
    "status": "opened"
}

Response

If the above request is successful, you will receive a HTTP Status 200 - Ok. Below is an example of the body of the response.

{
    "id": "b943cae2-a8f5-e911-b5e9-0003ff4f1b49",
    "created": "2019-10-23T15:22:12.967Z",
    "isArchived": false,
    "status": "opened",
    "loginUrl": "https://s-borrower.accountchek.net/Account/Login?vodkey=b943cae2a8f5e911b5e90003ff4f1b49",
    "daysRemaining": 58.222795108188656,
    "employmentVerificationRequested": false,
    "email": "johndoe@gmail.com",
    "last4SSN": "6789",
    "referenceNumber": "1122334455",
    "firstName": "John",
    "lastName": "Doe",
    "notificationUrl": null,
    "returnUrl": null,
    "phoneNumber": "706-123-4567",
    "employerName": "Informative Research",
    "ssn": "***-**-6789",
    "dateOfBirth": "1983-05-24T00:00:00Z",
    "address": {
        "street": "1234 Hawthorne Avenue",
        "street2": null,
        "city": "Athens",
        "state": "GA",
        "zip": "31032"
    }
}

If the above request is unsuccessful, you will either receive a HTTP Status 404 - Not Found or 422 - Unprocessable Entity. If you receive a 404 - Not Found, then the orderId does not exist in the AccountChek system or you do not have visibility to the order. If you receive a 422 - Unprocessable Entity, then the response body will contain the details of the cause of the error. Below is the structure of an error response.

{
    "general": [
        "string"
    ],
    "properties": [
        {
            "property": "string",
            "message": "string"
        }
    ]
}

Borrower Enrollment

Once an AccountChekOrder is set to opened, an email will be sent to the email address provided with the initial AccountChekOrder creation request. The email will contain a link to the AccountChek Borrower UI to allow the Borrower to go through various steps depending on which services are attached to the order. Once the Borrower has finished their steps in the Borrower UI, the initial report generation will begin.

Check the Status

Note: Recommendations for this step vary depending on your platform. Please work with the AccountChek team to determine what will work best for your implementation.

Once you have set the AccountChekOrder status to opened, your platform’s users (e.g. Loan Officer) will want to know the status of the order. Our system by default sends an email to the Verifier on the order when a report gets generated but you may want additional solutions in your platform for status checking.

To provide the best experience for your platform users, we recommend checking the status of an AccountChekOrder every time its information is displayed, either as in a list of orders or as a detail page.

For VOA: Check VOA Status

For VOIE: Check VOIE Status

Additionally, we do provide functionality for webhook postbacks. If you provide a notificationUrl for the AccountChekOrder, we will send postbacks to the URL any time the VOA status changes. For more information on the Webhook Postbacks, please see our Verifier Webhook Documentation.

Note: the VOIE service does not support webhooks (i.e. no VOIE status updates).

Pull Lite Data

If you would like to make a request for summary-like data that has the added benefit of being available immediately after the Borrower has completed their steps, you can make a call to pull our lite data.

Note: This is currently only available for the VOA service.

For VOA: List VOA Reports

Obtain the reportId

Once the report statuses for the attached services show successful report generation, you will need to obtain the reportId in order to pull the full VOA and/or VOIE report(s). You can do that by pulling the list of reports for the given service.

For VOA: List VOA Reports

For VOIE: List VOIE Reports

Having pulled a list of reports for a given service, you are able to retrieve a specific service report by using the reportId and service endpoint to Pull the Report.

Pull the Report

Using the reportId and the correct service endpoint, you are able to pull a VOA or VOIE report in either JSON or PDF. See below for details for each service.

For VOA: Pull VOA Report

For VOIE: Pull VOIE Report

Refresh a Report

Once you have a report, you may want to generate a new one with updated data (i.e. “refresh”). This action can only be done on an order if it is still open and its AccountChek status is inprogress.

For VOA: Generate VOA Report

For VOIE: Generate VOIE Report

Once the report has been successfully created and is run, you will be able to pull it by obtaining the reportId and pulling the report as listed in prior sections.

Client Testing (CTE) Domains
  • https://verifierapi.accountchek.net
  • https://validatorapi.accountchek.net
Production Domains
  • https://verifierapi.accountchek.com
  • https://validatorapi.accountchek.com
AccountChek Statuses