API Documentation

AccountChek POS Workflow

The AccountChek Point of Sale (POS) Workflow provides a basic workflow for creating and building an AccountChekOrder, and then displaying the AccountChek Borrower UI/UX inside of your platform to allow the Borrower to link their accounts.

This workflow uses our Verifier API (Specifications).

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

  1. Create an AccountChekOrder
  2. Attach Services to the Order
  3. Set the Order to Opened
  4. Borrower Enrollment
  5. Obtain and Present Data
  6. Update an AccountChekOrder

Create an AccountChekOrder

The first step of any AccountChek Order Workflow begins with creating an AccountChekOrder with some Borrower information. Before looking at how to create an order, please read the next section with important notes on field behavior. Once that has been read, see further for more details on the request and response.

AccountChekOrder fields that affect POS Workflow behavior

It is important to understand which fields for an AccountChekOrder can affect the POS workflow and how they do so. Below we outline these fields, their behaviors in the AccountChek system, and the recommended best practices for addressing those behaviors in order to make sure your platform achieves the desired workflow.

email and phoneNumber

The email and phoneNumber fields are the Borrower’s email address and phone number. This is the email address and phone number the AccountChek system will use to send communications to. The email field is required as part of order creation while the phone number is optional.

When the AccountChekOrder is created and then set to opened, a communication is sent to the email address and phone number (via text) with an invitation link to the AccountChek UI/UX.

The AccountChek system will also use this email address and phone number to prompt the Borrower when the connection to a Financial Institution linked to the AccountChekOrder is lost. This communication provides a link to the AccountChek UI/UX to have the Borrower re-establish the connection with the Financial Institution.

Assuming you are displaying the AccountChek UI/UX on your POS platform, the initial behavior of sending an invitation link when the order is opened may lead to confusion for the Borrower since they will already be in the POS workflow on your platform.

The method for working around this is to provide a fake email address and not provide a phone number when initially creating the order. Doing so will make the AccountChek system send the communication to a fake email address and will not send the text message. The example request further below this section illustrates this in the payload.

After the order has been set to the aforementioned opened status (see Set the Order to Opened for details on this step), you are able to update the email and phoneNumber fields without the AccountChek system sending that initial invitation link. See Update an AccountChekOrder for more details on how to make this update.

referenceNumber

The referenceNumber field is a way to connect your platform’s chosen ID for the order to the AccountChek system. The field is required as part of order creation and can be any string value you want to populate it with (up to a max of 256 characters).

Depending on your business needs, you may choose to assign the loan number to this order as many of our clients do. However, if there is no loan number assigned in your system at the time the order needs to be created, you may need to temporarily assign a value and update it later. If this is the case, you are able to update the referenceNumber when the loan number is available. See Update an AccountChekOrder for more details.

notificationUrl

The notificationUrl field is used to send a webhook postback from our system to this specified URL to share VOA and report status notifications related to the order. If you would like to be notified of these status updates on where the Borrower is in the VOA process and when the account data is available, you will need to set up a self-hosted application for receiving and handling these postbacks from the AccountChek Webhook.

Please see our Webhook Postbacks Documentation for more details and resources.

How To Create the AccountChekOrder

Once you have read the above and determined how you want to handle the POS workflow, see below for details on the request and response to make an AccountChekOrder.

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": "fake@domain.com",
    "last4SSN": "6789",
    "referenceNumber": "1122334455",
    "firstName": "John",
    "lastName": "Doe",
    "notificationUrl": "https://example.com/accountchek/webhooks",
    "returnUrl": null,
    "phoneNumber": null,
    "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": null,
    "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 response. 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 the AccountChekOrder is finalized, the Borrower can be directed to accept the AccountChek Terms of Service (TOS) and complete their steps in an embedded AccountChek UI/UX in your platform.

Our TOS is not included in the embedded AccountChek UI/UX but this provides an opportunity for greater flexibility in your platform’s workflow.

Include the TOS

To have the proper disclosures about use of the AccountChek service, any platform that uses the embedded AccountChek UI/UX workflow must incorporate our most current Terms of Service (TOS).

If you are using the Enrollment Widget or IFrame to add AccountChek to your platform’s workflow, AccountChek requires that your platform incorporates a checkbox with adjacent language to ensure that the Borrower attests to reading the TOS. This checkbox must be selected by the Borrower before proceeding to the AccountChek service. AccountChek also requires that you capture and log the timestamp (date and time) that the Borrower selected the checkbox in your platform.

The required language adjacent to the checkbox is shown below and must contain a link to the current AccountChek TOS which can be found at https://verifier.accountchek.com/tos.

It is important to note that this required language is subject to change at the discretion of AccountChek.

I agree to the Terms of Service and request that AccountChek® act as an intermediary on my behalf to furnish information to a prospective creditor in order to further my application.

Example:

Checkbox for Accepting TOS

Display the AccountChek UI/UX

You can choose to embed the AccountChek UI/UX in your POS platform in one of two ways:

  1. (Option 1) Display AccountChek UI/UX via the Enrollment Widget
  2. (Option 2) Display AccountChek UI/UX via an IFrame

(Option 1) Display AccountChek via the Enrollment Widget

If you would like to embed the AccountChek UI/UX within your POS platform using a widget, we provide a pre-built iframe code via an API call. You then embed the html response within your POS platform.

IMPORTANT: The widget response may only be used one time. Once the widget has been displayed once, you must make another API call for a new widget.

You can get the widget by calling the GET operation of the /v1/accountchekorders/{id}/enrollmentWidget. An example of the request is below. The response for this operation will be of type text/html.

Request

GET to /v1/accountchekorders/{orderId}/enrollmentWidget

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.

<script language="javascript">
	const iframeId = 'AccountChekIFRAME';
const ready = fn => {
if (document.readyState !== 'loading') fn();
else document.addEventListener('DOMContentLoaded', fn);};
const closeACFrame = event => {
const {data: message } = event;
if (typeof message !== 'string') return;
if (!message.includes('close')) return;
const iframe = document.getElementById(iframeId);
iframe?.parentNode?.removeChild(iframe);
if (typeof AC_Complete === 'function') AC_Complete();};
const baseScriptMain = () => {
window.addEventListener('message', closeACFrame);};
ready(baseScriptMain);
</script>
<div id="frameWrap" style="position:relative; border:0; ">
	<img id="loader1" style=" position:absolute;    left:40%;    top:35%;   padding:25px;" src="https://cdn.accountchek.com/cdn/widget-loader.gif" width="32" height="32" aria-hidden="true"/><iframe
		id="AccountChekIFRAME"
		src="https://redirect.accountchek.net/Account/Login?ssokey=57d450f8-54ae-4f63-9e3f-ae1f00651e97&widget=1"
		style=" height: 100%;    width: 100%;    margin:0;    padding:0;    border:0;"></iframe></div>
<script language="javascript">
	const closeSpinScriptMain = () => {
const iframe = document.getElementById(iframeId);
iframe?.addEventListener('load', () => {
const loader = document.getElementById('loader1');
if (loader) loader.style.visibility = 'hidden';});};
ready(closeSpinScriptMain);
</script>

If the above request is unsuccessful, you may receive a HTTP Status 404 - Not Found. This means the orderId does not exist in the system.

When the Borrower has completed their steps or has been timed out from AccountChek, the widget will be sent a postMessage method from the AccountChek system. The widget html code above includes pre-built logic to handle listening for this message and will execute an undefined function called AC_Complete() once that message is received. We strongly suggest you create and define this function in your system to leverage the widget closing event and move the Borrower to any necessary follow-up steps/pages (if needed) for a smoother Borrower experience.

(Option 2) Display AccountChek via an IFrame

If you would like to embed the AccountChek UI/UX within your POS platform using an IFrame, you can do so using a SSO URL and using it as the source for an embedded IFrame.

IMPORTANT: The SSO URL only lasts for 2 minutes and may only be used once. Once the SSO URL has run out of time or has been displayed once, you must make another API call for a new one.

You can get the SSO URL by calling the GET or POST operation of the /v1/accountchekorders/{id}/ssoURL endpoint. An example of the request and response for each is below.

Request

GET to /v1/accountchekorders/{orderId}/ssoUrl

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.

  {
    "url":"https://mobile2.accountchek.net/Account/Login?ssokey=aef98924-1663-484b-9242-6ee2cf630776"
  }

If the above request is unsuccessful, you may receive a HTTP Status 404 - Not Found. This means the orderId does not exist in the system.

Once you have the SSO URL, you can create the IFrame by passing it as the src attribute for the IFrame html code (see below example). When the IFrame is closed or the Borrower is logged out, you must get a new SSO URL. See the IMPORTANT note above for more details.

Example
<iframe src="https://borrower.accountchek.com/Account/Login?ssokey=ad527898-a628-4883-b879-dc91f9c50f67" ...>

When the Borrower has completed their steps or has been timed out from AccountChek, the IFrame will use a postMessage method from the AccountChek system to send a closeFrame message. We strongly recommend you build a listener to watch for that message to let the platform know to close the IFrame and move the Borrower to any necessary follow-up steps/pages (if needed) for a smoother Borrower experience.

Obtain and Present Data

At some point, you will want to access the Borrower data submitted via your platform. Our VOA lite data is available immediately as soon as the Borrower completes their steps. For the full Borrower data (such as the VOA or VOIE Report), our system needs time to generate it and as such it is not typically available immediately after the Borrower is done.

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

Check the Full Data 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.

During the report generation process, the order’s report(s) will go through a series of status changes; however, the service on the order will need to receive a specific status before you can pull in the full report data for the given service.

To get the status of a given service, you can make a API request.

For VOA: Check VOA Status

For VOIE: Check VOIE Status (see note below)

Additionally, we provide functionality for webhook postbacks for VOA. 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). Our recommendation for handling of automated VOIE report pulling can be found HERE.

Pull the Report

Once the report status has been updated to show a successful report generation, you can pull the full report data for the given service. Please refer to the latter half of our LOS workflow for the related how-to steps:

Update an AccountChekOrder

If you need to update the order (eg. phoneNumber, email, referenceNumber), our API provides that ability. Keep in mind that changes can not be made to read-only fields and any updates made to other fields will replace the previously held value of that field in the original AccountChekOrder.

Get the Existing Order Values

Since you will need to provide the entire AccountChekOrder for the update, you will first need to make a GET call to get the existing values for the order. This will ensure you preserve fields you aren’t attempting to update after the request is made. Examples are below.

Request

GET to /v1/accountchekorders/{orderId}

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.

{
    "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": null,
    "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 404 - Not Found. This means the orderId does not exist in the system.

Update the AccountChekOrder

The next step requires you to provide the previously received AccountChekOrder fields (excluding read-only fields) with the desired modified values. You are able to modify whichever fields you need to as long as it is not a read-only field (see schema for details). These read-only fields cannot be changed in the modified AccountChekOrder and should not be included in the request body as a result.

Once your changes are submitted, you can use the PUT call available in the Verifier API to replace the original order with the modified values. See below for examples of the request and response updating the phoneNumber from the prior step’s example.

Request

PUT to /v1/accountchekorders/{orderId}

Specification Details

Remember - do not include the read-only fields in the AccountChekOrder body request for this call.

{
    "isArchived": false,
    "status": "opened",
    "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"
    }
}

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 may receive a HTTP Status 404 - Not Found. This means the orderId does not exist in the system.

You may also get 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"
        }
    ]
}
Client Testing (CTE) Domains
  • https://verifierapi.accountchek.net
  • https://validatorapi.accountchek.net
Production Domains
  • https://verifierapi.accountchek.com
  • https://validatorapi.accountchek.com
AccountChek Statuses