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).
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
{
"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
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.
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
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
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.
Request
GET
to /v1/accountchekorders/{orderId}/voa/reports/{reportId}/summary
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.
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
{
"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 accountId s 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