API Documentation

Verification of Assets (VOA) API Calls

Service-related statuses can be found on the AccountChek statuses page:
VOA Statuses, VOA Report Statuses

The VOA service endpoints listed below use our Verifier API (Specifications).

  1. Attach Service
  2. Check Status
  3. Pull Lite Data
  4. List Reports
  5. Pull Report
  6. 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 VOA 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}/voa

Specification Details

{
    "requestType": "full",
    "accountMonitoring": 30,
    "expectedAccounts": [
        {
            "accountNumber": "string",
            "fiName": "string",
            "nickName": "string"
        }
    ],
    "daysBack": 90,
    "reportType": "voa"
}

See the table below for a list of fields, a description of each field, and whether they are required or not.

Field Description Required/Optional
requestType The type of the VOA request. lite - Only top level account information is available in JSON format (ex. account number and balance). full - Detailed information about the accounts is available in both PDF and JSON report formats. Required
accountMonitoring This field determines how many days the AccountChek order will remain open for the client to re-verify assets. During the account monitoring period, also known as the refresh period, AccountChek will check nightly for a successful connection to the Borrower’s accounts. The values allowed in this field can be determined by calling the company/refreshperiods endpoint. Most companies start out with the values of 30, 60, and 90 days. If field is empty, the company’s default value will be used. Optional
expectedAccounts DEPRECATED A list of accounts for which to prompt the Borrower. Optional
daysBack This field determines how much transaction history will be requested on the initial AccountChek VOA Report. The values allowed in this field can be determined by calling the company/daysback endpoint. Most companies start out with the values of 30, 60, and 90 days. If field is empty, the company’s default value will be used. Optional
reportType The type of report. This is used to determine which type of VoaReport to generate when a report is created. This field can be toggled between the available types at any time during the lifespan of the AccountChek order. Note: ‘dvoe’ report type cannot be selected if VOA is set to ‘lite’ request type. If field is empty, default will be ‘voa’. 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.

{
    "requestType": "full",
    "status": "500",
    "accountMonitoring": 30,
    "expectedAccounts": [],
    "reportType": "voa"
}

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 VOA service on an order, you can use the orderId and call the following endpoint. If you need to implement polling, this is also the endpoint you would use.

Request

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

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.

{
    "requestType": "",
    "status": "",
    "accountMonitoring": ,
    "expectedAccounts": [],
    "reportType": "voa"
}

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 VOA is attached to the order.

VOA Status Codes

Pull Lite Data

To see a summary of VOA data, you can request the VOA lite data. The added benefit of the lite data compared to the full data report is that it is available immediately after a Borrower completes their steps. See below details on making the request.

Request

GET to /v1/accountchekorders/{orderId}/voa/lite

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.

[
    {
        "accountId": "ACT-d7085d3e-c119-48ae-bc8f-4dc7033f6316",
        "accountType": "DDA",
        "accountName": "CHECKING",
        "accountNumber": "3000849594",
        "accountHolder": "John Homeowner",
        "fiName": "Chase Bank",
        "fiAccountType": "None",
        "fiPlanName": null,
        "balance": 283.0100,
        "balanceDate": "2019-12-02T21:40:33Z"
    },
    {
        "accountId": "ACT-50450f9c-faee-4f8c-972f-f5747946e1c8",
        "accountType": "DDA",
        "accountName": "SAVINGS",
        "accountNumber": "0562495745",
        "accountHolder": "John Homeowner",
        "fiName": "Simple",
        "fiAccountType": "None",
        "fiPlanName": null,
        "balance": 50.0000,
        "balanceDate": "2019-12-02T21:35:54Z"
    }
]

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.

List Reports

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

Request

GET to /v1/accountchekorders/{orderId}/voa/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": "ba4012a4-3f44-4e21-8959-883b4aa4d188",
        "employerName": "Informative Research",
        "daysBack": 60,
        "accountIds": [
            "ACT-dad2ae0a-4246-4e2b-a309-097211bfc1aa"
        ],
        "dataHarvested": true,
        "currentAsOfDate": "2019-10-25T19:27:57Z",
        "historyStartDate": "2019-10-25T19:27:57Z",
        "requestDate": "2019-10-25T19:30:48.303Z",
        "reportDate": "2019-10-25T19:31:07.407Z",
        "requestorName": "Bob Verifier",
        "requestorCompanyName": "AccountChek",
        "status": 507,
        "reportType": "voa"
    }
]

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 VOA is attached to the order.

Pull Report

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

VOA Report Statuses

Request

GET to /v1/accountchekorders/{orderId}/voa/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 VOA Report as a JSON object.
  • application/pdf - This will inform the Verifier API to return the VOA 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.

VOA Report JSON Schema

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 VOA is attached to the order.

Generate Report

Once you have a VOA 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.

NOTE: The type of report generated from this API call is based on the reportType field on the VOA Service object (set initially when the service was attached to the order). If a different reportType is needed, you must change it via the Update VOA endpoint first before following the steps below.

For the accountsIds body field, you can pass an empty array or a null value to generate a new report with all available Borrower accounts.

However, if you would instead like to provide specific Borrower accounts to generate the report (ex. in order to omit a specific bank on the report), you will need to pass an array of string values representing the specific IDs in the accountIds body field. The available Borrower account IDs can be retrieved via the VOA Lite Report endpoint.

Below is an example of the request using a specific Borrower account as an accountIds value:

Request

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

Specification Details

{
    "employerName": "Informative Research",
    "daysBack": 60,
    "accountIds": [
        "ACT-d7085d3e-c119-48ae-bc8f-4dc7033f6316"
    ],
    "dataHarvested": true
}

See the table below for a list of fields, a description of each field, and whether they are required or not.

Field Description Required/Optional
employerName Name of the employer for the Borrower. AccountChek will search for this value attempting to find it in transactions. Optional
daysBack This is the number of days of history you would like to be present on the report. The values available for use by your company can be find by calling the company/daysback endpoint. Typically, the default values are 30, 60, and 90 days. Required
accountIds A list of accountIds you want in the report. Do not include the array if you want all accounts listed. These must be valid account ids as returned in a *LiteAccountInfo object, acquired via the VOA Lite Report* Optional
dataHarvested If true, a harvest was run to get new transaction and account balance information for the generated report. On creation: When set to true a new harvest is guaranteed to run; when false a harvest may run if no harvest has run before. Required

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": "5fed8e2a-eac2-426a-8507-b8d12623631f",
    "employerName": "Informative Research",
    "daysBack": 60,
    "accountIds": [
        "ACT-d7085d3e-c119-48ae-bc8f-4dc7033f6316"
    ],
    "dataHarvested": true,
    "currentAsOfDate": "2019-10-28T20:48:24Z",
    "historyStartDate": "2019-10-28T20:48:24Z",
    "requestDate": "2019-10-28T20:48:24Z",
    "reportDate": "2019-10-28T20:48:24Z",
    "requestorName": "John Lender",
    "requestorCompanyName": "AccountChek",
    "status": 400,
    "reportType": "voa"
}

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 VOA 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 VOA report has been successfully created and is run, you will be able to pull it by Obtaining the reportId and pulling the VOA 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