Verification of Income and Employment (VOIE/VOE) API Calls

Service-related statuses can be found on the AccountChek statuses page:
VOIE/VOE Statuses, VOIE/VOE Report Statuses

The VOIE/VOE service endpoints listed below use our Verifier API (Specifications).

1. Attach Service
2. Check Status
   • Checking if Report is Ready
3. List Reports
4. Pull Report
5. Generate Report

Attach Service

Once the AccountChekOrder is successfully created, you will receive a unique orderId in the response. You can use this orderId to attach the VOIE service to the AccountChekOrder by making the following request.

Note: The service can be attached as long as the order is not canceled or closed, but at least one service must be attached before an AccountChekOrder can be set to opened.

Request

POST to /v1/accountchekorders/{orderId}/voe

Specification Details

{ }

Note: this call requires a request body but it should be empty as shown above (i.e. { }).

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.

{
    "aggregationRequested": true,
    "directRequested": true,
    "paystubUploadRequested": true,
    "status": "created"
}

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"
        }
    ]
}

Check Status

To check the status of a VOIE service on an order, you can use the orderId and call the following endpoint.

Request

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

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.

{
    "aggregationRequested": true,
    "directRequested": true,
    "paystubUploadRequested": true,
    "status": ""
}

If the above request is unsuccessful, you will receive a HTTP Status 404 - Not Found. This means the orderId does not exist in the AccountChek system, you do not have visibility to the order or no VOE is attached to the order.

VOIE/VOE Status Codes

Checking if Report is Ready

If your POS platform needs to check if the VOIE report is completed and ready to pull for automated report pulling, we recommend implementing the following procedure:

1. Show Borrower UI as normal to borrower (i.e. detailed in POS workflow).
2. When Borrower completes, times out or closes Borrower UI, our system will sent an HTTP postMessage indicating the UI has been closed.
   • Widget method integrations will need to use the function provided in the widget code.
   • SSO Url method integrations will need to build/change their postMessage event listener.
3. Upon receipt of this postMessage, start polling the VOIE List Reports endpoint with a reasonable time interval (ex. every 1 minute for 10 minutes).
4. On each poll attempt:
   • If a report is returned in the API response:
     1. If report status is created or inprogress, continue polling.
     2. If report status is completed, cease polling and make API call to Pull the Report using the returned reportId.
     3. If report status is completewitherrors, failed, credentialupdaterequired or harvestfailure, you’ll need to handle the errors accordingly based on the listed VOE Report Statuses.
   • If polling has hit the set time interval and no report has been returned, cease polling.

List Reports

To get the list of reports on the VOIE service and get the reportId for the desired report, see the below request for details.

Request

GET to /v1/accountchekorders/{orderId}/voe/reports

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": "b4d8c9a0-1e0a-4702-813e-a1bf7c84d3da",
        "status": "created",
        "createdAt": "2021-03-24T15:25:18Z",
        "generatedAt": "2021-03-24T15:25:18Z",
        "providers": [ ],
        "requestorName": "John Doe",
        "requestorCompanyName": "AccountChek"
    }
]

If the above request is unsuccessful, you will receive a HTTP Status 404 - Not Found. This means the orderId does not exist in the AccountChek system, you do not have visibility to the order or no VOE is attached to the order.

Pull Report

With pulling the list of VOIE Reports, you are able to retrieve a specific VOIE Report in either JSON or PDF by using its reportId. The report must be in a complete status before being able to pull the full version of the report.

VOIE/VOE Report Statuses

Request

GET to /v1/accountchekorders/{orderId}/voe/reports/{reportId}/summary

Specification Details

This endpoint will accept two different Accept Headers to allow for the API user to say what type of response they want to receive back. Below are the two acceptable Accept Headers and what they will return in the response.

• application/json - This will inform the Verifier API to return the VOE Report as a JSON object.
• application/pdf - This will inform the Verifier API to return the VOE Report as a PDF document.

Response

If the above request is successful, you will receive a HTTP Status 200 - Ok. Depending on the Accept Header you provide in the request, you will either receive the Report as JSON or PDF.

If the above request is unsuccessful, you will receive a HTTP Status 404 - Not Found. This means the orderId and/or reportId does not exist in the AccountChek system, you do not have visibility to the order or no VOE is attached to the order.

Generate Report

Once you have a VOIE Report, you may want to generate a new one with updated data. This action can only be done if the AccountChek order status is inprogress.

Request

POST to /v1/accountchekorders/{orderId}/voe/reports

Specification Details

{ }

Note: this call requires a request body but it should be empty as shown above (i.e. { }).

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": "b4d8c9a0-1e0a-4702-813e-a1bf7c84d3da",
    "status": "created",
    "createdAt": "2021-03-24T15:25:18Z",
    "generatedAt": "2021-03-24T15:25:18Z",
    "providers": [ ],
    "requestorName": "John Doe",
    "requestorCompanyName": "AccountChek"
}

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, you do not have visibility to the order or no VOE is attached 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"
        }
    ]
}

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