Introduction
Verifying ownership of a financial account is an important part of initiating payments and transfers. Quovo’s Auth API provides valuable information about a financial account - type, routing and account numbers, and balance - in order to confirm that a user is in fact the owner of that account. Our standard credentials-based syncing process pulls this information and makes it available through the Auth endpoints described in this documentation.
/auth
The /auth
endpoint will yield any information needed for ACH transfers or instant account verification. This includes bank account numbers, routing numbers, and other details like current balances.
Get Auth info for an Account
curl -X GET -H "Authorization: Bearer a724809d37d0a21b7e9257f45cee416f5aec61993ab4b09e" "https://api.quovo.com/v2/accounts/1029277/auth"
Authorization: Bearer a724809d37d0a21b7e9257f45cee416f5aec61993ab4b09e
Content-Type: application/json
Status: 200 OK
{
"auth": {
"balance": 2113.06,
"brokerage": 21700,
"brokerage_name": "Test Bank Institution",
"id": 1029277,
"last_good_auth": "2016-07-29T17:13:48.457",
"portfolios": [
{
"balance": 2113.06,
"details": {
"address": {
"data": {
"city": "New York",
"state": "NY",
"street": "29 West 30th Street 2nd Floor",
"zip": "10001-4404"
},
"error": null
},
"dob": {
"data": "1947-01-08",
"error": null
},
"email": {
"data": "nice.email@example.com",
"error": null
},
"phone": {
"data": "5556430695",
"error": null
}
},
"id": 1056003,
"name": "597716304411",
"owner_names": ["Shelia Riggs"],
"portfolio_category": "Banking",
"portfolio_type": "Checking",
"portfolio_type_confidence": "High",
"routing": "306061549",
"wire_routing": null
}
],
"updated": "2016-07-29T17:13:48.457",
"user": 162703,
"username": "quovo_test_user"
}
}
GET https://api.quovo.com/v2/accounts/{account_id}/auth
Description
Retrieves account verification info for an Account.
Response Fields
Name | Type | Description |
---|---|---|
balance | decimal | The total Account balance across all of its Portfolios. |
brokerage | integer | The Quovo institution ID associated with the Account. |
brokerage_name | string | The name of the associated financial institution. |
id | integer | The unique Quovo identifier for the Account. |
last_good_auth | string | A timestamp of the last time an auth sync completed successfully, i.e. returned a status of “good” with valid Portfolios. |
portfolios | object | The individual Portfolios within the Account. These Portfolios will contain the actual account and routing numbers of any available sub-accounts. See below for the fields in the Portfolio objects. |
updated | string | A timestamp of the last time there was a sync attempt. This is set regardless if the sync returned a “good” or non-“good” status. The Account’s balance will generally correspond to this datetime. |
user | integer | The User ID that owns the Account. |
username | string | The username of the associated User. |
portfolios
Object
Name | Type | Description |
---|---|---|
balance | decimal | The total balance of the Portfolio. |
details | object | Additional details about the account owners, such as their address or email address. These fields are restricted by default. See below for the fields in the details object. |
id | integer | The unique Quovo identifier for the Portfolio. |
name | string | The account number as represented at the financial institution. |
owner_names | array | The account owners’ names as represented at the financial institution. |
portfolio_category | string | A grouping of the Portfolio according to broader industry attributes, as identified by Quovo. Possible values include “Banking”, “Investment”, “Insurance”, and “Loan”. Categories can have multiple corresponding Portfolio types, while Portfolio types can only have one category. |
portfolio_type | string | The type of Portfolio as identified by Quovo, based on its holdings, transactions, and tax eligibility. Possible values for portfolio_type include “Checking”, “401k”, “IRA”, and more. |
portfolio_type_confidence | string | The level of confidence in the accuracy of the portfolio_type . Confidence levels are split into four tiers: “Very High”, “High”, “Moderate”, and “Low”. This value can be used to decide whether you should use the portfolio_type , or ignore it due to its low confidence level. |
routing | string | A nine-digit sequence used to identity the financial institution. This is also known as the ABA number. |
wire_routing | string | A nine-digit numeric code used for wire transfers or routing. |
details
Object
Name | Type | Description |
---|---|---|
address | object | The mailing address connected to the bank account. See below for the fields in the address object. |
dob | string | The date of birth of the account owner. |
string | The email address associated with the bank account. | |
phone | string | The telephone number associated with the bank account. |
address
Object
Name | Type | Description |
---|---|---|
city | string | The city of the address. |
state | string | The state of the address, represented as the two-letter postal code. |
street | string | Any part of the address that does not fall under the other fields, including the street number and street name. |
zip | string | The postal zip code of the address. This may include the additional “+4” digits, e.g., “12345-6789” vs “12345”. |
Auth Workflow - Intro
The account verification workflow is similar to the standard Quovo Account syncing workflow. There are a few key differences between the two workflows, which are summarized below.
By default, all Quovo Accounts may perform both aggregation and authentication syncs. Any Account with aggregation enabled will also be targeted in our nightly aggregation process, during which Accounts are synced and kept up-to-date nightly.
By contrast, authentication syncs are only run on-demand. If you would like an Account to be excluded from our nightly aggregation process, and thus enabled only for account verification, set the is_auth
flag to true
while creating the Account.
To find institutions with instant account verification enabled, pass the flag
can_auth
to theGET /v2/brokerages
call, e.g.GET /v2/brokerages?can_auth=true
. Any institution with Auth enabled will havecan_auth
set totrue
.To indicate an Account is for account verification only and does not need any aggregation data, set
is_auth
totrue
while creating the Account. If you would like the Account to perform both aggregation syncs and authentication syncs, simply omit theis_auth
flag.
curl -X POST -H "Authorization: Bearer a724809d37d0a21b7e9257f45cee416f5aec61993ab4b09e" -H "Content-Type: application/json" -d '{"is_auth": true}' "https://api.quovo.com/v2/accounts/1029277/sync"
{
"sync": {
"account": 1029277,
"has_realtime": false,
"progress": null,
"status": "good"
}
}
- To trigger an account verification sync, set the
is_auth
flag totrue
while initiating a sync, e.g.POST /v2/accounts/{account_id}/sync?is_auth=true
curl -X GET -H "Authorization: Bearer a724809d37d0a21b7e9257f45cee416f5aec61993ab4b09e" "https://api.quovo.com/v2/accounts/1029277/auth"
{
"auth": {
"balance": 2113.06,
"brokerage": 21700,
"brokerage_name": "Test Bank Institution",
"id": 1029277,
"last_good_auth": "2016-07-29T17:13:48.457",
"portfolios": [
{
"balance": 2113.06,
"details": {
"address": {
"data": {
"city": "New York",
"state": "NY",
"street": "29 West 30th Street 2nd Floor",
"zip": "10001-4404"
},
"error": null
},
"dob": {
"data": "1947-01-08",
"error": null
},
"email": {
"data": "nice.email@example.com",
"error": null
},
"phone": {
"data": "5556430695",
"error": null
}
},
"id": 1056003,
"name": "597716304411",
"owner_names": ["Shelia Riggs"],
"portfolio_category": "Checking",
"portfolio_type": "Banking",
"portfolio_type_confidence": "High",
"routing": "306061549",
"wire_routing": null
}
],
"updated": "2016-07-29T17:13:48.457",
"user": 162703,
"username": "quovo_test_user"
}
}
To see the account verification information on an Account, call
GET /v2/accounts/{account_id}/auth
If you would like to trigger both an aggregation and authentication sync at the same time, set
is_both
totrue
while initiating the sync, e.g.POST /v2/accounts/{account_id}/sync?is_both=true
- The sync should be treated as a normal aggregation-only sync, and follow the Account aggregation workflow.
- The Account will continue to automatically sync nightly as a typical aggregation-enabled Account.
- If an Account has been marked as Auth-only (i.e.
is_auth
is set totrue
on the Account), you may still manually perform aggregation syncs on the Account. Simply callPOST /v2/accounts/{account_id}/sync
to trigger an aggregation sync.- This will implicitly turn off the Auth-only flag on the Account (i.e.
is_auth
will be set tofalse
). From now on, the Account will automatically sync nightly as a normal aggregation account. - The Account’s Portfolios, positions, and history will be available through the standard
GET
calls.
- This will implicitly turn off the Auth-only flag on the Account (i.e.
Auth Workflow
This is a full, sample walkthrough of the Quovo account verification process.
For this workflow example, we assume that an access token has been generated and a User has been created. For information on these steps see these workflows. For ease, we will not mention passing the access token with each request, but make sure to do so in your actual requests.
Curly braces { } represent variables and should not be included in the actual request
1. Fetch Available Institutions
curl -X GET -H "Authorization: Bearer a724809d37d0a21b7e9257f45cee416f5aec61993ab4b09e" "https://api.quovo.com/v2/brokerages?can_auth=true"
{
"brokerages": [
{
"can_auth": true,
"country_code": "USA",
"id": 12,
"is_test": false,
"name": "Chase Bank",
"notes": "For investment accounts, please sync using the \"Chase Investments\" connection.",
"password": null,
"popularity_score": 10,
"status": "available",
"username": null,
"website": "https://www.chase.com/"
},
{
"can_auth": true,
"country_code": "USA",
"id": 34,
"is_test": false,
"name": "Bank of America",
"notes": null,
"password": "Passcode",
"popularity_score": 10,
"status": "available",
"username": "Online ID",
"website": "bankofamerica.com"
}
]
}
To retrieve a full list of institutions available for account verification, call GET https://api.quovo.com/v2/brokerages?can_auth=true
. This will return the list of institutions where can_auth
is true
.
To search for a specific account verification-enabled institution, call GET https://api.quovo.com/v2/brokerages?can_auth=true&query={search_term}
, where {search_term}
is a search term related to the desired institution, e.g., its name or its website domain.
Response Fields
Name | Type | Description |
---|---|---|
can_auth | boolean | If can_auth is true , the institution is currently enabled for account verification. |
country_code | string | The country in which the institution resides (in ISO 3166-1 alpha-3 format). |
id | integer | The unique Quovo identifier for the financial institution. |
is_test | boolean | Several Brokerages are fake institutions meant to help simulate various API responses and workflows. These are for development purposes and should not be displayed to end users. |
name | string | The name of the financial institution. |
notes | string | Brokerage-specific information to help users successfully sync to the institution. These notes can and should be displayed, when available, to the end user. |
password | string | Display text for the password field. This field is used when the “password” field at the institution actually represents another input field, such as a PIN Number. If available, be sure to show this to the end user instead of “Password.” |
popularity_score | integer | A measure of the institution’s popularity based on broad groupings of all Quovo institutions according to their size. This score is useful for ordering available institutions, ensuring the more popular and typical institutions are seen first. Scores range from 1-10, with 10 being the most popular and 1 being the least. |
status | string | The availability status of the institution. status will be “available” if the institution is currently accepting sync requests or “unavailable” if it is not. |
username | string | Display text for the username field. This field is used when the “username” field at the institution actually represents another input field, such as Account Number. If available, be sure to show this to the end user instead of “Username.” |
website | string | The financial institution’s website. This may be helpful to display to end users as they have another field, aside from Brokerage name, to help verify the correct Brokerage. |
2. Create an Account
curl -X POST -H "Authorization: Bearer a724809d37d0a21b7e9257f45cee416f5aec61993ab4b09e" -H "Content-Type: application/json" -d '{"brokerage": 21700, "username": "testusername", "password": "testpass"}' "https://api.quovo.com/v2/users/524162/accounts"
{
"account": {
"brokerage": 21700,
"brokerage_name": "Test Bank Institution",
"config_instructions": null,
"failures": 0,
"id": 1029277,
"is_inactive": false,
"last_good_sync": null,
"opened": "2016-07-29T17:19:45.780",
"nickname": null,
"status": null,
"updated": "2016-07-29T17:19:45.780",
"update_count": 0,
"user": 524162,
"username": "quovo_test_user_2",
"value": null
}
}
To create an Account, send a POST
request to https://api.quovo.com/v2/users/{user_id}/accounts
. Use the User ID of one of your available users.
In the request body, send:
- brokerage - The Quovo Brokerage ID of the relevant financial institution. We will use 21700 in this sample workflow, which is the “Test Bank Institution”. Accounts synced to this fake institution will yield sample bank Portfolios.
- username - The login username used by the end user at their institution login. For “Test Bank Institution”, neither the username nor password matter, as long as something is passed for both fields.
- password - The login password used by the end user at their institution login. Again, the credentials do not matter for this sample workflow and test Brokerage.
- is_auth - (optional) This flag indicates the Account is for account verification only, i.e. the account will not run nightly aggregation syncs. If the Account is meant for both aggregation and authentication syncs, do not pass the
is_auth
flag. We will omit this flag for this sample workflow.
3. Trigger an Account Verification Sync
curl -X POST -H "Authorization: Bearer a724809d37d0a21b7e9257f45cee416f5aec61993ab4b09e" -H "Content-Type: application/json" -d '{"is_auth": true}' "https://api.quovo.com/v2/accounts/1029277/sync"
{
"sync": {
"account": 1029277,
"has_realtime": false,
"progress": null,
"status": "good"
}
}
To trigger the sync, send a POST
request to https://api.quovo.com/v2/accounts/{account_id}/sync
. Use the Account ID you created in the previous step for {account_id}
.
In the request body, send:
- is_auth - Set to
true
, this flag indicates the sync request is for account verification, not aggregation.
The sample response breakdown
Name | Type | Description |
---|---|---|
account | integer | The Quovo Account that is being synced. |
config_instructions | string | (Only available if the final sync status is “config”.) Institution-specific instructions for the end user, which need to be completed before the Account can successfully sync. The end user will usually need to perform some action on their institution’s website, such as enabling an option in their user settings. |
has_realtime | boolean | Indicates whether the account currently has real-time MFA Challenges that need to be answered. |
progress | object | Typically used to indicate the current sync status. Account verification syncs return after the sync is completed, rather than while the sync is ongoing, so this will be null . |
status | string | The sync status of the Account. After the sync ends, this field will indicate whether the Account was synced successfully (“good”), or if the Account has MFA Challenges to answer (“questions”), and more. See here for a full list of Account sync statuses. |
4. Answer MFA Challenges (optional)
Some institutions may require answering MFA before we can fetch account verification information.
{
"challenges": [
{
"account": 1029277,
"id": 20131,
"is_answered": false,
"last_asked": true,
"question": "How are you?",
"should_answer": true,
"type": "question"
}
],
"sync": {
"account": 1029277,
"has_realtime": false,
"progress": null,
"status": "questions"
}
}
If there are MFA Challenges that need to be answered on an Account, the sync response from step 3 will return a status of “questions”, along with any available MFA challenges. The challenges
list will be the same as the response from calling GET /accounts/{account_id}/challenges
.
To answer the MFA Challenges, simply request another auth sync, passing along the answers to the MFA challenges. Pass the answers as you would in the call to POST /accounts/{account_id}/challenges
.
In the request body, send:
- is_auth - Again, set to
true
, this flag indicates the sync request is for account verification, not aggregation. - questions - The answer(s) to the MFA question(s), along with the relevant Challenge Id. For this sample walkthrough, we will be passing
[{"id": 20131, "answer": "great"}]
.
If the MFA questions were answered correctly, the sync response will return a status
of “good”.
curl -X POST -H "Authorization: Bearer a724809d37d0a21b7e9257f45cee416f5aec61993ab4b09e" -H "Content-Type: application/json" -d '{"is_auth": true, "questions": [{"answer": "great", "id": 20131}]}' "https://api.quovo.com/v2/accounts/1029277/sync"
{
"sync": {
"account": 1029277,
"has_realtime": false,
"progress": null,
"status": "good"
}
}
5. Retrieve the Account Verification Info
curl -X GET -H "Authorization: Bearer a724809d37d0a21b7e9257f45cee416f5aec61993ab4b09e" "https://api.quovo.com/v2/accounts/1029277/auth"
{
"auth": {
"balance": 2113.06,
"brokerage": 21700,
"brokerage_name": "Test Bank Institution",
"id": 1029277,
"last_good_auth": "2016-07-29T17:13:48.457",
"portfolios": [
{
"balance": 2113.06,
"details": {
"address": {
"data": {
"city": "New York",
"state": "NY",
"street": "29 West 30th Street 2nd Floor",
"zip": "10001-4404"
},
"error": null
},
"dob": {
"data": "1947-01-08",
"error": null
},
"email": {
"data": "nice.email@example.com",
"error": null
},
"phone": {
"data": "5556430695",
"error": null
}
},
"id": 1056003,
"name": "597716304411",
"owner_names": ["Shelia Riggs"],
"portfolio_category": "Checking",
"portfolio_type": "Banking",
"portfolio_type_confidence": "High",
"routing": "306061549",
"wire_routing": null
}
],
"updated": "2016-07-29T17:13:48.457",
"user": 162703,
"username": "quovo_test_user"
}
}
To view the available account verification info on an Account, make a GET
request to https://api.quovo.com/v2/accounts/{account_id}/auth
. Use the same {account_id}
as in previous steps.
Response Fields
Name | Type | Description |
---|---|---|
balance | decimal | The total Account balance across all of its Portfolios. |
brokerage | integer | The Quovo institution ID associated with the Account. |
brokerage_name | string | The name of the associated financial institution. |
id | integer | The unique Quovo identifier for the Account. |
last_good_auth | string | A timestamp of the last time an auth sync completed successfully, i.e. returned a status of “good” with valid Portfolios. |
portfolios | object | The individual Portfolios within the Account. These Portfolios will contain the actual account and routing numbers of any available sub-accounts. See below for the fields in the Portfolio objects. |
updated | string | A timestamp of the last time there was a sync attempt. This is set regardless if the sync returned a “good” or non-“good” status. The Account’s balance will generally correspond to this datetime. |
user | integer | The User ID that owns the Account. |
username | string | The username of the associated User. |
portfolios
Object
Name | Type | Description |
---|---|---|
balance | decimal | The total balance of the Portfolio. |
details | object | Additional details about the account owners, such as their address or email address. These fields are restricted by default. See below for the fields in the details object. |
id | integer | The unique Quovo identifier for the Portfolio. |
name | string | The account number as represented at the financial institution. |
owner_names | array | The account owners’ names as represented at the financial institution. |
portfolio_category | string | A grouping of the Portfolio according to broader industry attributes, as identified by Quovo. Possible values include “Banking”, “Investment”, “Insurance”, and “Loan”. Categories can have multiple corresponding Portfolio types, while Portfolio types can only have one category. |
portfolio_type | string | The type of Portfolio as identified by Quovo, based on its holdings, transactions, and tax eligibility. Possible values for portfolio_type include “Checking”, “401k”, “IRA”, and more. |
portfolio_type_confidence | string | The level of confidence in the accuracy of the portfolio_type . Confidence levels are split into four tiers: “Very High”, “High”, “Moderate”, and “Low”. This value can be used to decide whether you should use the portfolio_type , or ignore it due to its low confidence level. |
routing | string | A nine-digit sequence used to identity the financial institution. This is also known as the ABA number. |
wire_routing | string | A nine-digit numeric code used for wire transfers or routing. |
details
Object
Name | Type | Description |
---|---|---|
address | object | The mailing address connected to the bank account. See below for the fields in the address object. |
dob | string | The date of birth of the account owner. |
string | The email address associated with the bank account. | |
phone | string | The telephone number associated with the bank account. |
address
Object
Name | Type | Description |
---|---|---|
city | string | The city of the address. |
state | string | The state of the address, represented as the two-letter postal code. |
street | string | Any part of the address that does not fall under the other fields, including the street number and street name. |
zip | string | The postal zip code of the address. This may include the additional “+4” digits, e.g., “12345-6789” vs “12345”. |
6. Trigger an Aggregation Sync (optional)
curl -X POST -H "Authorization: Bearer a724809d37d0a21b7e9257f45cee416f5aec61993ab4b09e" "https://api.quovo.com/v2/accounts/1029277/sync"
{
"sync": {
"account": 1029277,
"has_realtime": false,
"progress": {
"message": "queued",
"percent": 0.0,
"state": "queued"
},
"status": "syncing"
}
}
Any Auth-enabled Account may still perform aggregation syncs. Simply send a POST
sync request to https://api.quovo.com/v2/accounts/{account_id}/sync
.
/auth_deposits
Quovo provides Auth Deposit verification for any institution not covered by instant account verification. Auth Deposits leverage Quovo account aggregation to automatically verify that micro-deposits (sent by Quovo) have cleared at a specified bank account.
After initiating the Auth Deposit process, Quovo will deposit two small amounts into the targeted bank account. By checking the relevant bank account’s transaction history, Quovo will automatically verify whether or not the micro-deposits went through. This facilitates a smoother account verification workflow, less dependant on end user confirmation. However, if you would like to enforce end user confirmation in your workflow, you may still manually verify the Auth Deposits.
Check all Auth Deposits
curl -X GET -H "Authorization: Bearer a724809d37d0a21b7e9257f45cee416f5aec61993ab4b09e" \
"https://api.quovo.com/v2/auth_deposits"
Authorization: Bearer a724809d37d0a21b7e9257f45cee416f5aec61993ab4b09e
Content-Type: application/json
Status: 200 OK
{
"auth_deposits": [
{
"account": 1163268,
"account_status": "good",
"created": "2017-08-25T16:51:13Z",
"error": null,
"id": 42521,
"portfolio": 1760061,
"status": "verified",
"updated": "2017-08-26T16:58:07Z"
},
{
"account": 3531576,
"account_status": "good",
"created": "2017-08-30T17:12:06Z",
"error": {
"id": "invalid_account_number",
"message": "The account number is not recognized by the end institution."
},
"id": 31339,
"portfolio": 5511435,
"status": "failed",
"updated": "2017-09-05T17:12:06Z"
}
]
}
GET https://api.quovo.com/v2/auth_deposits
Description
Checks the status of all Auth Deposits across all Portfolios.
Request Parameters
Name | Type | Description |
---|---|---|
status | string | Filter results by the Auth Deposits’ status field. All Auth Deposits returned will have the given status . |
updated_after | string | Filter results by the Auth Deposits’ updated field. All Auth Deposits returned will have been updated after the given datetime (in ISO 8601 format). |
Response Fields
Name | Type | Description |
---|---|---|
account | integer | The Quovo Account that the associated Portfolio belongs to. |
account_status | string | The status of the Account. |
created | string | A timestamp that indicates when the Auth Deposit process was initiated (in UTC time). |
error | object | An object containing an id and message field. This illustrates why a micro-deposit might have failed, e.g. invalid_routing_number or invalid_bank_account . |
id | integer | The ID of the Auth Deposit. This is created and assigned by Quovo. |
portfolio | integer | The Quovo Portfolio the Auth Deposits are targeting. |
status | string | The ongoing status of the Auth Deposit. |
updated | string | A timestamp that indicates the last time the Auth Deposit was updated (in UTC time). |
Check a Portfolio’s Auth Deposits
curl -X GET -H "Authorization: Bearer a724809d37d0a21b7e9257f45cee416f5aec61993ab4b09e" \
"https://api.quovo.com/v2/portfolios/1760061/auth_deposits"
Authorization: Bearer a724809d37d0a21b7e9257f45cee416f5aec61993ab4b09e
Content-Type: application/json
Status: 200 OK
{
"auth_deposits": [
{
"account": 1163268,
"account_status": "good",
"created": "2017-08-25T16:51:13Z",
"error": null,
"id": 42521,
"portfolio": 1760061,
"status": "verified",
"updated": "2017-08-26T16:58:07Z"
}
]
}
GET https://api.quovo.com/v2/portfolios/{portfolio_id}/auth_deposits
Description
Checks the status of Auth Deposits on a single Portfolio.
Request Parameters
Name | Type | Description |
---|---|---|
status | string | Filter results by the Auth Deposits’ status field. All Auth Deposits returned will have the given status . |
updated_after | string | Filter results by the Auth Deposits’ updated field. All Auth Deposits returned will have been updated after the given datetime (in ISO 8601 format). |
Response Fields
Name | Type | Description |
---|---|---|
account | integer | The Quovo Account that the associated Portfolio belongs to. |
account_status | string | The status of the Account. |
created | string | A timestamp that indicates when the Auth Deposit process was initiated (in UTC time). |
error | object | An object containing an id and message field. This illustrates why a micro-deposit might have failed, e.g. invalid_routing_number or invalid_bank_account . |
id | integer | The ID of the Auth Deposit. This is created and assigned by Quovo. |
portfolio | integer | The Quovo Portfolio the Auth Deposits are targeting. |
status | string | The ongoing status of the Auth Deposit. |
updated | string | A timestamp that indicates the last time the Auth Deposit was updated (in UTC time). |
Initiate Auth Deposits
curl -X POST -H "Authorization: Bearer a724809d37d0a21b7e9257f45cee416f5aec61993ab4b09e" \
-H "Content-Type: application/json" \
-d '{"name": "569339485397", "routing": "306061549"}' \
"https://api.quovo.com/v2/portfolios/1760061/auth_deposits"
Authorization: Bearer a724809d37d0a21b7e9257f45cee416f5aec61993ab4b09e
Content-Type: application/json
Content-Type: application/json
Status: 201 Created
{
"auth_deposit": {
"account": 1466468,
"account_status": "good",
"created": "2017-09-05T21:23:09Z",
"error": null,
"id": 42535,
"portfolio": 1767962,
"status": "requested",
"updated": "2017-09-05T21:23:09Z"
}
}
POST https://api.quovo.com/v2/portfolios/{portfolio_id}/auth_deposits
Description
Initiates the Auth Deposit process on a Portfolio.
Request Parameters
Name | Type | Description |
---|---|---|
name* | string | The bank account number as represented at the financial institution. |
routing* | string | A nine-digit sequence used to identity the financial institution. This is also known as the ABA number. |
Response Fields
Name | Type | Description |
---|---|---|
account | integer | The Quovo Account that the associated Portfolio belongs to. |
account_status | string | The status of the Account. |
created | string | A timestamp that indicates when the Auth Deposit process was initiated (in UTC time). |
error | object | An object containing an id and message field. This illustrates why a micro-deposit might have failed, e.g. invalid_routing_number or invalid_bank_account . |
id | integer | The ID of the Auth Deposit. This is created and assigned by Quovo. |
portfolio | integer | The Quovo Portfolio the Auth Deposits are targeting. |
status | string | The ongoing status of the Auth Deposit. |
updated | string | A timestamp that indicates the last time the Auth Deposit was updated (in UTC time). |
Check an Auth Deposit
curl -X GET -H "Authorization: Bearer a724809d37d0a21b7e9257f45cee416f5aec61993ab4b09e" \
"https://api.quovo.com/v2/auth_deposits/42535"
Authorization: Bearer a724809d37d0a21b7e9257f45cee416f5aec61993ab4b09e
Content-Type: application/json
Status: 200 OK
{
"auth_deposits": [
{
"account": 1163268,
"account_status": "good",
"created": "2017-08-25T16:51:13Z",
"error": null,
"id": 42535,
"portfolio": 1760061,
"status": "verified",
"updated": "2017-08-26T16:58:07Z"
}
]
}
GET https://api.quovo.com/v2/auth_deposits/{auth_deposit_id}
Description
Checks the status of a single Auth Deposit.
Response Fields
Name | Type | Description |
---|---|---|
account | integer | The Quovo Account that the associated Portfolio belongs to. |
account_status | string | The status of the Account. |
created | string | A timestamp that indicates when the Auth Deposit process was initiated (in UTC time). |
error | object | An object containing an id and message field. This illustrates why a micro-deposit might have failed, e.g. invalid_routing_number or invalid_bank_account . |
id | integer | The ID of the Auth Deposit. This is created and assigned by Quovo. |
portfolio | integer | The Quovo Portfolio the Auth Deposits are targeting. |
status | string | The ongoing status of the Auth Deposit. |
updated | string | A timestamp that indicates the last time the Auth Deposit was updated (in UTC time). |
Verify Auth Deposits
curl -X POST -H "Authorization: Bearer a724809d37d0a21b7e9257f45cee416f5aec61993ab4b09e" \
-H "Content-Type: application/json" \
-d '{"amounts": [0.06, 0.02]}' \
"https://api.quovo.com/v2/auth_deposits/42535"
Authorization: Bearer a724809d37d0a21b7e9257f45cee416f5aec61993ab4b09e
Content-Type: application/json
Content-Type: application/json
Status: 200 OK
{
"auth_deposit": {
"account": 1466468,
"account_status": "good",
"created": "2017-09-01T21:25:10Z",
"error": null,
"id": 42535,
"portfolio": 1767962,
"status": "verified",
"updated": "2017-09-05T22:28:38Z"
}
}
POST https://api.quovo.com/v2/auth_deposits/{auth_deposit_id}
Description
Manually verify the Auth Deposits sent.
Request Parameters
Name | Type | Description |
---|---|---|
amounts* | array | An array containing all of the deposit values. |
Response Fields
Name | Type | Description |
---|---|---|
account | integer | The Quovo Account that the associated Portfolio belongs to. |
account_status | string | The status of the Account. |
created | string | A timestamp that indicates when the Auth Deposit process was initiated (in UTC time). |
error | object | An object containing an id and message field. This illustrates why a micro-deposit might have failed, e.g. invalid_routing_number or invalid_bank_account . |
id | integer | The ID of the Auth Deposit. This is created and assigned by Quovo. |
portfolio | integer | The Quovo Portfolio the Auth Deposits are targeting. |
status | string | The ongoing status of the Auth Deposit. |
updated | string | A timestamp that indicates the last time the Auth Deposit was updated (in UTC time). |
Auth Deposits Workflow
1. Sync an Account
Auth Deposits must target a Quovo Portfolio. To get started, create and sync a Quovo Account following the normal aggregation workflow. After successfully syncing the Account, check its available Portfolios by calling GET https://api.quovo.com/v2/accounts/{account_id}/portfolios
Syncing the Account and its Portfolios will allow Quovo to track the relevant bank account’s transaction history and auto-verify any incoming Auth Deposits.
2. Initiate the Auth Deposits
curl -X POST -H "Authorization: Bearer a724809d37d0a21b7e9257f45cee416f5aec61993ab4b09e" \
-H "Content-Type: application/json" \
-d '{"name": "569339485397", "routing": "306061549"}' \
"https://api.quovo.com/v2/portfolios/1760061/auth_deposits"
{
"auth_deposit": {
"account": 1466468,
"account_status": "good",
"created": "2017-09-05T21:23:09Z",
"error": null,
"id": 52121,
"portfolio": 1760061,
"status": "requested",
"updated": "2017-09-05T21:23:09Z"
}
}
To initiate the Auth Deposits process on a Portfolio, send a POST
request to https://api.quovo.com/v2/portfolios/{portfolio_id}/auth_deposits
.
In the request body, send:
- name - The bank account number as represented at the financial institution.
- routing - A nine-digit sequence used to identity the financial institution. This is also known as the ABA number.
This will send two small amounts to the bank account detailed above. It may take several days for the micro-deposits to travel through the ACH network and appear in the bank account’s transaction history. Once the deposits do appear, Quovo will auto-verify them, requiring no additional action by you nor the end user.
3. Check the Ongoing Status
curl -X GET -H "Authorization: Bearer a724809d37d0a21b7e9257f45cee416f5aec61993ab4b09e" \
"https://api.quovo.com/v2/auth_deposits?updated_after=2017-09-05T21:25:10Z"
{
"auth_deposits": [
{
"account": 1466468,
"account_status": "good",
"created": "2017-09-05T21:23:09Z",
"error": null,
"id": 52121,
"portfolio": 1760061,
"status": "verified",
"updated": "2017-09-06T23:11:32Z"
},
{
"account": 3531576,
"account_status": "good",
"created": "2017-09-05T21:23:09Z",
"error": {
"id": "invalid_account_number",
"message": "The account number is not recognized by the end institution."
},
"id": 53598,
"portfolio": 5511435,
"status": "failed",
"updated": "2017-09-06T01:12:06Z"
}
]
}
To check the ongoing status of all Auth Deposits, make a GET
call to https://api.quovo.com/v2/auth_deposits
. This will return all available Auth Deposits, whether they have been updated recently or verified months ago. It is therefore recommended to use the updated_after
filter to only fetch Auth Deposits that have been updated since your last /auth_deposits
status check. This will notify you of any Auth Deposits that have been recently verified or have recently failed.
In the GET
request, send:
- updated_after - All Auth Deposits returned will have been updated after the given datetime (in ISO 8601 format).
Response Fields
Name | Type | Description |
---|---|---|
account | integer | The Quovo Account that the associated Portfolio belongs to. |
account_status | string | The status of the Account. |
created | string | A timestamp that indicates when the Auth Deposit process was initiated (in UTC time). |
error | object | An object containing an id and message field. This illustrates why a micro-deposit might have failed, e.g. invalid_routing_number or invalid_bank_account . |
id | integer | The ID of the Auth Deposit. This is created and assigned by Quovo. |
portfolio | integer | The Quovo Portfolio the Auth Deposits are targeting. |
status | string | The ongoing status of the Auth Deposit. |
updated | string | A timestamp that indicates the last time the Auth Deposit was updated (in UTC time). |
4. Fetch the Verified Banking Info
curl -X GET -H "Authorization: Bearer a724809d37d0a21b7e9257f45cee416f5aec61993ab4b09e" \
"https://api.quovo.com/v2/accounts/1466468/auth"
{
"auth": {
"balance": 12129.96,
"brokerage": 21700,
"brokerage_name": "Test Bank Institution",
"id": 1466468,
"last_good_auth": null,
"portfolios": [
{
"balance": 12129.96,
"details": {
"address": {
"data": null,
"error": {
"id": "not_found",
"message": "Not found."
}
},
"dob": {
"data": null,
"error": {
"id": "not_found",
"message": "Not found."
}
},
"email": {
"data": null,
"error": {
"id": "not_found",
"message": "Not found."
}
},
"phone": {
"data": null,
"error": {
"id": "not_found",
"message": "Not found."
}
}
},
"id": 1760061,
"name": "569339485397",
"owner_names": null,
"portfolio_category": "Checking",
"portfolio_type": "Banking",
"portfolio_type_confidence": "Very High",
"routing": "306061549",
"wire_routing": null
}
],
"updated": "2017-09-05T23:14:09Z",
"user": 155029,
"username": "quovo_test_user"
}
}
As with instant account verification, all verified bank account information is available via the /auth
endpoint. To view the bank account number and routing number, make a GET
request to https://api.quovo.com/v2/accounts/{account_id}/auth
.
Response Fields
Name | Type | Description |
---|---|---|
balance | decimal | The total Account balance across all of its Portfolios. |
brokerage | integer | The Quovo institution ID associated with the Account. |
brokerage_name | string | The name of the associated financial institution. |
id | integer | The unique Quovo identifier for the Account. |
last_good_auth | string | A timestamp of the last time an auth sync completed successfully, i.e. returned a status of “good” with valid Portfolios. |
portfolios | object | The individual Portfolios within the Account. These Portfolios will contain the actual account and routing numbers of any available sub-accounts. See below for the fields in the Portfolio objects. |
updated | string | A timestamp of the last time there was a sync attempt. This is set regardless if the sync returned a “good” or non-“good” status. The Account’s balance will generally correspond to this datetime. |
user | integer | The User ID that owns the Account. |
username | string | The username of the associated User. |
portfolios
Object
Name | Type | Description |
---|---|---|
balance | decimal | The total balance of the Portfolio. |
details | object | Additional details about the account owners, such as their address or email address. These fields are restricted by default. See below for the fields in the details object. |
id | integer | The unique Quovo identifier for the Portfolio. |
name | string | The account number as represented at the financial institution. |
owner_names | array | The account owners’ names as represented at the financial institution. |
portfolio_category | string | A grouping of the Portfolio according to broader industry attributes, as identified by Quovo. Possible values include “Banking”, “Investment”, “Insurance”, and “Loan”. Categories can have multiple corresponding Portfolio types, while Portfolio types can only have one category. |
portfolio_type | string | The type of Portfolio as identified by Quovo, based on its holdings, transactions, and tax eligibility. Possible values for portfolio_type include “Checking”, “401k”, “IRA”, and more. |
portfolio_type_confidence | string | The level of confidence in the accuracy of the portfolio_type . Confidence levels are split into four tiers: “Very High”, “High”, “Moderate”, and “Low”. This value can be used to decide whether you should use the portfolio_type , or ignore it due to its low confidence level. |
routing | string | A nine-digit sequence used to identity the financial institution. This is also known as the ABA number. |
wire_routing | string | A nine-digit numeric code used for wire transfers or routing. |
/auth_deposit_portfolios
There may be scenarios where Quovo cannot automatically verify a bank account using Auth Deposits, e.g. the end user does not want to link their bank accounts or Quovo does not currently support the account’s institution. For these use cases, you can use the /auth_deposit_portfolios
endpoint to begin a more manual verification process, similar to a standard micro-deposits workflow. Using this endpoint, you can create Portfolios specifically for the Auth Deposits process.
Get all Auth Deposit Portfolios
curl -X GET -H "Authorization: Bearer a724809d37d0a21b7e9257f45cee416f5aec61993ab4b09e" \
"https://api.quovo.com/v2/auth_deposit_portfolios"
Authorization: Bearer a724809d37d0a21b7e9257f45cee416f5aec61993ab4b09e
Content-Type: application/json
Status: 200 OK
{
"auth_deposit_portfolios": [
{
"account": 3773372,
"brokerage": 22134,
"brokerage_name": "Manual Auth Deposits",
"id": 5982662,
"last_change": "2017-10-17T13:29:47.250",
"portfolio_name": "Auth Deposit Bank Account",
"user": 162703,
"username": "quovo_test_user"
},
{
"account": 3773377,
"brokerage": 22134,
"brokerage_name": "Manual Auth Deposits",
"id": 5982669,
"last_change": "2017-10-17T13:30:48.420",
"portfolio_name": "Auth Deposit Bank Account",
"user": 162703,
"username": "quovo_test_user"
},
{
"account": 3773443,
"brokerage": 22134,
"brokerage_name": "Manual Auth Deposits",
"id": 5982800,
"last_change": "2017-10-17T13:44:12.233",
"portfolio_name": "Auth Deposit Bank Account",
"user": 5303243,
"username": "quovo_test_user_2"
}
]
}
GET https://api.quovo.com/v2/auth_deposit_portfolios
Description
Fetches all Auth Deposit Portfolios across all Users.
Response Fields
Name | Type | Description |
---|---|---|
account | integer | The Quovo Account the Auth Deposit Portfolio belongs to. |
brokerage | integer | The Quovo Brokerage the Account is associated with. All Auth Deposit Portfolios will be on Brokerage 22134. |
brokerage_name | string | The name of the associated financial institution. All Auth Deposit Portfolios will be on the institution “Manual Auth Deposits”. |
id | integer | The unique Quovo identifier for the Portfolio. |
last_change | string | A timestamp of the last time the Auth Deposit Portfolio was updated. This will usually be set to the Portfolio’s creation date. |
portfolio_name | string | The full Portfolio name as entered by the end user. The name will default to “Auth Deposit Bank Account” if no name was given when creating the Portfolio. |
user | integer | The Quovo User the Portfolio belongs to. |
username | string | The username of the associated Quovo User. |
Get a User’s Auth Deposit Portfolios
curl -X GET -H "Authorization: Bearer a724809d37d0a21b7e9257f45cee416f5aec61993ab4b09e" \
"https://api.quovo.com/v2/users/162703/auth_deposit_portfolios"
Authorization: Bearer a724809d37d0a21b7e9257f45cee416f5aec61993ab4b09e
Content-Type: application/json
Status: 200 OK
{
"auth_deposit_portfolios": [
{
"account": 3773372,
"brokerage": 22134,
"brokerage_name": "Manual Auth Deposits",
"id": 5982662,
"last_change": "2017-10-17T13:29:47.250",
"portfolio_name": "Auth Deposit Bank Account",
"user": 162703,
"username": "quovo_test_user"
},
{
"account": 3773377,
"brokerage": 22134,
"brokerage_name": "Manual Auth Deposits",
"id": 5982669,
"last_change": "2017-10-17T13:30:48.420",
"portfolio_name": "Auth Deposit Bank Account",
"user": 162703,
"username": "quovo_test_user"
}
]
}
GET https://api.quovo.com/v2/users/{user_id}/auth_deposit_portfolios
Description
Fetches the User’s Auth Deposit Portfolios.
Response Fields
Name | Type | Description |
---|---|---|
account | integer | The Quovo Account the Auth Deposit Portfolio belongs to. |
brokerage | integer | The Quovo Brokerage the Account is associated with. All Auth Deposit Portfolios will be on Brokerage 22134. |
brokerage_name | string | The name of the associated financial institution. All Auth Deposit Portfolios will be on the institution “Manual Auth Deposits”. |
id | integer | The unique Quovo identifier for the Portfolio. |
last_change | string | A timestamp of the last time the Auth Deposit Portfolio was updated. This will usually be set to the Portfolio’s creation date. |
portfolio_name | string | The full Portfolio name as entered by the end user. The name will default to “Auth Deposit Bank Account” if no name was given when creating the Portfolio. |
user | integer | The Quovo User the Portfolio belongs to. |
username | string | The username of the associated Quovo User. |
Create an Auth Deposit Portfolio
curl -X POST -H "Authorization: Bearer a724809d37d0a21b7e9257f45cee416f5aec61993ab4b09e" \
"https://api.quovo.com/v2/users/162703/auth_deposit_portfolios"
Authorization: Bearer a724809d37d0a21b7e9257f45cee416f5aec61993ab4b09e
Content-Type: application/json
Status: 201 Created
{
"auth_deposit_portfolio": {
"account": 3782006,
"brokerage": 22134,
"brokerage_name": "Manual Auth Deposits",
"id": 1760131,
"last_change": "2017-10-18T17:46:59.660",
"portfolio_name": "Auth Deposit Bank Account",
"user": 162703,
"username": "quovo_test_user"
}
}
POST https://api.quovo.com/v2/users/{user_id}/auth_deposit_portfolios
Description
Creates an Auth Deposit Portfolio.
Request Parameters
Name | Type | Description |
---|---|---|
name | string | (optional) The name of the Auth Deposit Portfolio. This will typically describe the user’s target bank account. If not given, the Portfolio’s name will default to “Auth Deposit Bank Account”. |
Response Fields
Name | Type | Description |
---|---|---|
account | integer | The Quovo Account the Auth Deposit Portfolio belongs to. |
brokerage | integer | The Quovo Brokerage the Account is associated with. All Auth Deposit Portfolios will be on Brokerage 22134. |
brokerage_name | string | The name of the associated financial institution. All Auth Deposit Portfolios will be on the institution “Manual Auth Deposits”. |
id | integer | The unique Quovo identifier for the Portfolio. |
last_change | string | A timestamp of the last time the Auth Deposit Portfolio was updated. This will usually be set to the Portfolio’s creation date. |
portfolio_name | string | The full Portfolio name as entered by the end user. The name will default to “Auth Deposit Bank Account” if no name was given when creating the Portfolio. |
user | integer | The Quovo User the Portfolio belongs to. |
username | string | The username of the associated Quovo User. |
Get a single Auth Deposit Portfolio
curl -X GET -H "Authorization: Bearer a724809d37d0a21b7e9257f45cee416f5aec61993ab4b09e" \
"https://api.quovo.com/v2/auth_deposit_portfolios/1760131"
Authorization: Bearer a724809d37d0a21b7e9257f45cee416f5aec61993ab4b09e
Content-Type: application/json
Status: 200 OK
{
"auth_deposit_portfolio": {
"account": 3782006,
"brokerage": 22134,
"brokerage_name": "Manual Auth Deposits",
"id": 1760131,
"last_change": "2017-10-18T17:46:59.660",
"portfolio_name": "Auth Deposit Bank Account",
"user": 162703,
"username": "quovo_test_user"
}
}
GET https://api.quovo.com/v2/auth_deposit_portfolios/{portfolio_id}
Description
Fetches a single Auth Deposit Portfolio.
Response Fields
Name | Type | Description |
---|---|---|
account | integer | The Quovo Account the Auth Deposit Portfolio belongs to. |
brokerage | integer | The Quovo Brokerage the Account is associated with. All Auth Deposit Portfolios will be on Brokerage 22134. |
brokerage_name | string | The name of the associated financial institution. All Auth Deposit Portfolios will be on the institution “Manual Auth Deposits”. |
id | integer | The unique Quovo identifier for the Portfolio. |
last_change | string | A timestamp of the last time the Auth Deposit Portfolio was updated. This will usually be set to the Portfolio’s creation date. |
portfolio_name | string | The full Portfolio name as entered by the end user. The name will default to “Auth Deposit Bank Account” if no name was given when creating the Portfolio. |
user | integer | The Quovo User the Portfolio belongs to. |
username | string | The username of the associated Quovo User. |
Delete an Auth Deposit Portfolio
curl -X DELETE -H "Authorization: Bearer a724809d37d0a21b7e9257f45cee416f5aec61993ab4b09e" \
"https://api.quovo.com/v2/auth_deposit_portfolios/1760131"
Authorization: Bearer a724809d37d0a21b7e9257f45cee416f5aec61993ab4b09e
Status: 204 No Content
DELETE https://api.quovo.com/v2/auth_deposit_portfolios/{portfolio_id}
Description
Deletes an existing Auth Deposit Portfolio.
Manual Auth Deposits Workflow
For any use case where Quovo cannot automatically verify a bank account, you can still let users manually verify their accounts. This workflow is similar to the standard micro-deposits process, during which the end user must enter the Auth Deposit amounts sent to their target bank account.
1. Create an Auth Deposits-only Portfolio
curl -X POST -H "Authorization: Bearer a724809d37d0a21b7e9257f45cee416f5aec61993ab4b09e" \
"https://api.quovo.com/v2/users/162703/auth_deposit_portfolios"
{
"auth_deposit_portfolio": {
"account": 3782006,
"brokerage": 22134,
"brokerage_name": "Manual Auth Deposits",
"id": 1760131,
"last_change": "2017-10-18T17:46:59.660",
"portfolio_name": "Auth Deposit Bank Account",
"user": 162703,
"username": "quovo_test_user"
}
}
Since Auth Deposits must target a Quovo Portfolio, we need to first create a Quovo Portfolio. Unlike other Quovo Portfolios created during the syncing process, these manually created Portfolios are not tied to a linked bank account, and thus will not contain any synced banking data like transaction history.
To make a Portfolio for Auth Deposit verification, send a POST
request to https://api.quovo.com/v2/users/{user_id}/auth_deposit_portfolios
. This will create a new Quovo Portfolio and a new Quovo Account, the former of which can be used for Auth Deposits.
2. Initiate the Auth Deposits
curl -X POST -H "Authorization: Bearer a724809d37d0a21b7e9257f45cee416f5aec61993ab4b09e" \
-H "Content-Type: application/json" \
-d '{"name": "569339485397", "routing": "306061549"}' \
"https://api.quovo.com/v2/portfolios/1760131/auth_deposits"
{
"auth_deposit": {
"account": 3782006,
"account_status": "good",
"created": "2017-10-18T18:23:09Z",
"error": null,
"id": 52121,
"portfolio": 1760131,
"status": "requested",
"updated": "2017-10-18T18:23:09Z"
}
}
To initiate the Auth Deposits, send a POST
request to https://api.quovo.com/v2/portfolios/{portfolio_id}/auth_deposits
.
In the request body, send:
- name - The bank account number as represented at the financial institution.
- routing - A nine-digit sequence used to identity the financial institution. This is also known as the ABA number.
This will send two small amounts to the bank account detailed above. It may take several days for the micro-deposits to travel through the ACH network and appear in the bank account’s available transaction history.
3. Check the Ongoing Status
curl -X GET -H "Authorization: Bearer a724809d37d0a21b7e9257f45cee416f5aec61993ab4b09e" \
"https://api.quovo.com/v2/auth_deposits?updated_after=2017-09-05T21:25:10Z"
{
"auth_deposits": [
{
"account": 3782006,
"account_status": "good",
"created": "2017-10-22T18:23:09Z",
"error": null,
"id": 52121,
"portfolio": 1760131,
"status": "submitted",
"updated": "2017-10-23T14:05:54Z"
},
{
"account": 3531576,
"account_status": "good",
"created": "2017-10-19T18:23:09Z",
"error": {
"id": "invalid_account_number",
"message": "The account number is not recognized by the end institution."
},
"id": 53598,
"portfolio": 5511435,
"status": "failed",
"updated": "2017-10-23T06:11:01Z"
}
]
}
To check the ongoing status of all Auth Deposits, make a GET
call to https://api.quovo.com/v2/auth_deposits
. This will return all available Auth Deposits, whether they have been updated recently or verified months ago. It is therefore recommended to use the updated_after
filter to only fetch Auth Deposits that have been updated since your last /auth_deposits
status check. This will notify you of any Auth Deposits that have been recently transferred or recently sent, i.e. they now have a status
of “transferred” or “submitted”, respectively. Auth Deposits can only be manually verified if they have a current status
of “transferred” or “submitted”.
In the GET
request, send:
- updated_after - All Auth Deposits returned will have been updated after the given datetime (in ISO 8601 format).
Response Fields
Name | Type | Description |
---|---|---|
account | integer | The Quovo Account that the associated Portfolio belongs to. |
account_status | string | The status of the Account. |
created | string | A timestamp that indicates when the Auth Deposit process was initiated (in UTC time). |
error | object | An object containing an id and message field. This illustrates why a micro-deposit might have failed, e.g. invalid_routing_number or invalid_bank_account . |
id | integer | The ID of the Auth Deposit. This is created and assigned by Quovo. |
portfolio | integer | The Quovo Portfolio the Auth Deposits are targeting. |
status | string | The ongoing status of the Auth Deposit. |
updated | string | A timestamp that indicates the last time the Auth Deposit was updated (in UTC time). |
4. Manually verify the Auth Deposit
curl -X POST \
-H 'Authorization: Bearer a724809d37d0a21b7e9257f45cee416f5aec61993ab4b09e' \
-H 'Content-Type: application/json' \
-d '{
"amounts": [0.01, 0.02]
}' \
https://api.quovo.com/v2/auth_deposits/52121
{
"id": "invalid_parameter",
"message": "The values given do not match the deposits sent.",
"status": 400
}
curl -X POST \
-H 'Authorization: Bearer a724809d37d0a21b7e9257f45cee416f5aec61993ab4b09e' \
-H 'Content-Type: application/json' \
-d '{
"amounts": [0.09, 0.02]
}' \
https://api.quovo.com/v2/auth_deposits/52121
{
"auth_deposit": {
"account": 3782006,
"account_status": "good",
"created": "2017-10-20T21:17:59Z",
"error": null,
"id": 52121,
"portfolio": 1760131,
"status": "verified",
"updated": "2017-10-24T18:08:30Z"
}
}
Once the micro-deposits have been sent, i.e. the Auth Deposit has a status of “submitted”, the end user may manually verify the Auth Deposit. It may take 3-4 business days for the deposits to appear in the target bank account, so be sure to make the messaging clear to your end users that they must check their bank accounts over the next few days. You can also wait to message the end user until after the Auth Deposit’s status has been updated to “transferred”. This better ensures the micro-deposit is currently visible in the target bank account when you notify the end user about their ongoing Auth Deposit.
Once your end users are ready to verify the micro-deposits, send a POST
request to https://api.quovo.com/v2/auth_deposits/{auth_deposit_id}
with the deposit amounts.
- In the request body, pass:
- amounts - An array containing the Auth Deposit amounts sent by Quovo.
Response Fields
Name | Type | Description |
---|---|---|
account | integer | The Quovo Account that the associated Portfolio belongs to. |
account_status | string | The status of the Account. |
created | string | A timestamp that indicates when the Auth Deposit process was initiated (in UTC time). |
error | object | An object containing an id and message field. This illustrates why a micro-deposit might have failed, e.g. invalid_routing_number or invalid_bank_account . |
id | integer | The ID of the Auth Deposit. This is created and assigned by Quovo. |
portfolio | integer | The Quovo Portfolio the Auth Deposits are targeting. |
status | string | The ongoing status of the Auth Deposit. |
updated | string | A timestamp that indicates the last time the Auth Deposit was updated (in UTC time). |
5. Fetch the Verified Banking Info
curl -X GET -H "Authorization: Bearer a724809d37d0a21b7e9257f45cee416f5aec61993ab4b09e" \
"https://api.quovo.com/v2/accounts/3782006/auth"
{
"auth": {
"balance": null,
"brokerage": 22134,
"brokerage_name": "Manual Auth Deposits",
"id": 3782006,
"last_good_auth": null,
"portfolios": [
{
"balance": null,
"details": {
"address": {
"data": null,
"error": {
"id": "not_found",
"message": "Not found."
}
},
"dob": {
"data": null,
"error": {
"id": "not_found",
"message": "Not found."
}
},
"email": {
"data": null,
"error": {
"id": "not_found",
"message": "Not found."
}
},
"phone": {
"data": null,
"error": {
"id": "not_found",
"message": "Not found."
}
}
},
"id": 1760131,
"name": "569339485397",
"owner_names": null,
"portfolio_category": "Unknown",
"portfolio_type": "Unknown",
"portfolio_type_confidence": null,
"routing": "306061549",
"wire_routing": null
}
],
"updated": "2017-10-23T16:24:05.710",
"user": 162703,
"username": "quovo_test_user"
}
}
As with instant account verification, all verified bank account information is available via the /auth
endpoint. To view the bank account number and routing number, make a GET
request to https://api.quovo.com/v2/accounts/{account_id}/auth
, where {account_id}
is the ID of the Auth Deposit Portfolio’s Account.
Response Fields
Name | Type | Description |
---|---|---|
balance | decimal | The total Account balance across all of its Portfolios. |
brokerage | integer | The Quovo institution ID associated with the Account. |
brokerage_name | string | The name of the associated financial institution. |
id | integer | The unique Quovo identifier for the Account. |
last_good_auth | string | A timestamp of the last time an auth sync completed successfully, i.e. returned a status of “good” with valid Portfolios. |
portfolios | object | The individual Portfolios within the Account. These Portfolios will contain the actual account and routing numbers of any available sub-accounts. See below for the fields in the Portfolio objects. |
updated | string | A timestamp of the last time there was a sync attempt. This is set regardless if the sync returned a “good” or non-“good” status. The Account’s balance will generally correspond to this datetime. |
user | integer | The User ID that owns the Account. |
username | string | The username of the associated User. |
portfolios
Object
Name | Type | Description |
---|---|---|
balance | decimal | The total balance of the Portfolio. |
details | object | Additional details about the account owners, such as their address or email address. These fields are restricted by default. See below for the fields in the details object. |
id | integer | The unique Quovo identifier for the Portfolio. |
name | string | The account number as represented at the financial institution. |
owner_names | array | The account owners’ names as represented at the financial institution. |
portfolio_category | string | A grouping of the Portfolio according to broader industry attributes, as identified by Quovo. Possible values include “Banking”, “Investment”, “Insurance”, and “Loan”. Categories can have multiple corresponding Portfolio types, while Portfolio types can only have one category. |
portfolio_type | string | The type of Portfolio as identified by Quovo, based on its holdings, transactions, and tax eligibility. Possible values for portfolio_type include “Checking”, “401k”, “IRA”, and more. |
portfolio_type_confidence | string | The level of confidence in the accuracy of the portfolio_type . Confidence levels are split into four tiers: “Very High”, “High”, “Moderate”, and “Low”. This value can be used to decide whether you should use the portfolio_type , or ignore it due to its low confidence level. |
routing | string | A nine-digit sequence used to identity the financial institution. This is also known as the ABA number. |
wire_routing | string | A nine-digit numeric code used for wire transfers or routing. |
Auth Deposit Statuses and Error Codes
Auth Deposit Statuses
Name | Description |
---|---|
deposit_failed | The micro-deposits could not be sent properly. The error field in the Auth Deposit will contain an error code, better detailing why the transaction failed. |
requested | The micro-deposits have not yet been sent through the ACH network. |
submitted | Quovo has sent the micro-deposits through the ACH network. This does not necessarily mean the micro-deposits have been successfully made. The attempted micro-deposits may still encounter an error due to issues like incorrect routing or account numbers. |
transferred | Quovo is reasonably sure the micro-deposits have been successfully transferred to the target Portfolio, i.e. we have not received notice of any ACH-related errors. |
verification_failed | The end user failed to manually verify the Auth Deposit amounts too many times or Quovo was unable to verify the deposits within a reasonable time frame. |
verified | The Auth Deposits have been confirmed by either Quovo or the end user. |
Auth Deposit Error Codes
These error codes typically only appear if the Auth Deposit’s status
is deposit_failed
. The error will further detail why the ACH transfer failed.
Id | Description |
---|---|
invalid_account_number | The account number is not recognized by the end institution. The Auth Deposit process should be reinitiated with a corrected bank account number. |
invalid_bank_account | The targeted bank account cannot complete ACH transfers at this time. This usually indicates the bank account is unsuitable for any incoming ACH transfers and cannot be used for Auth Deposit verification. |
invalid_routing_number | The routing number does not belong to a valid ACH-enabled institution. The Auth Deposit process should be reinitiated with a corrected routing number. |
process_error | There was a Quovo-side issue attempting the ACH transfer. We will attempt to resolve the issue and automatically resend the micro-deposits. |