Verification options
Manual Verification parameter
The manual_verification option enables you to add or remove partners that perform manual income verifications. When manual_verification=false, Income will exclude all partners performing manual VOI. This limits the search for partners performing VOI, and also reduces the time it takes to complete a VOI.
Exclude Borrower parameter
The exclude_borrower option enables you to remove the borrower from the VOI loop. When exclude_borrower=false, the borrower must provide credentials for Income verification prior to the partner performing the VOI. This increases borrower interaction, and also increases the chance that the VOI will be successfully completed.
The borrower needs to authorize the verification by entering payroll provider or bank credentials to the URL (widget_url) provided in the verification response. Call Retrieve Partners to retrieve test credentials for partners that have the borrower in the loop.
Instant Verification parameter
The instant_verification option enables you to add or remove partners that perform instant verifications. When instant_verification=true, Income will use all partners performing instant verification. This can limit the search for partners performing VOI, and also reduces the time it takes to complete a VOI.
Partner name parameter
The partner_name option enables you to select a preferred partner, or use "default" as the value. If you use "default" as the partner_name, Income will find the best match and use that partner for verification process. If you want to use a specific partner, call Retrieve Partners to see all income verification partners.
Callback URL parameter
The callback_url option enables you to send a URL with the request. This URL will be used to send a callback when the verification process status changes, including changes in status of underlying service invocations.
Send SMS parameter
The send_sms option enables you to send an SMS to the borrower when an authorization for the verification is needed. The default SMS text is "Lender has provided verification link to your E-mail address, please open link in browser, and finish verification process", if you wish to change the default SMS text you can send an optional sms_text parameter with your custom text message.
Send Email parameter
The send_email option enables you to email the borrower when an authorization for the verification is needed. The Email will be sent to the email address specified in the input collection. The Email uses the standard email template voi_email_template, if you wish to update the template please refer to the Update Email Template documentation. Please note that the template takes in two passed variables, which are the applet URL and employer_name, and those are required variables and should not be altered, for more info check the Email Product section.
Redirect URL parameter
Providing the redirect_url is optional and allows you to redirect the borrower to a URL of your choosing after linking the borrower's income verification. If left empty or no options parameter is passed, this URL defaults to the Staircase homepage.
If the waterfall feature is enabled, partner is selected based on the partner ordering.
To use the waterfall feature set the partner name to default. This way verification will be executed following the ordering for all available data partners. Use Update Partners Ordering and Retrieve Partners Ordering to set and get the orderings. If two data partners share the same legal entity full name the verification will be done based on the ordering of data partners.
Verify Income returns, as a synchronous acknowledgement, a new collection_id. The new collection_id represents an empty container which will hold the partner's response once processing has completed.
Some Partners require the borrower to authenticate, if the response contains the url property then the URL should be forwarded to the borrower and authenticated. The url is valid until the expiration_time which is denoted in EST.
Use the newly returned collection_id together with transaction_id in Retrieve Collection to get verification result.
Monitoring the health of the Income product
The Income product is integrated with the Health product, a cloud-based DevOps service that monitors the health of APIs.
With the help of Health product, you can monitor the process of verification.
To check the health of the Income product, you can use the create async health query execution API.
This API allows you to specify a time period, a response collection ID ("id" returned as result of Income verification), and a product or API identifier.
Here are the relevant product and API identifiers for the Income product:
- Income Product Identifier: 64b4b099-2ec6-448c-a33e-8c15dd167ab1
- Income Verification API ID: d1b1e55b-7398-4cb6-9e6f-d7ab3e5b83d4
To check the health after submitting a new Income verification request, you can use the following request payload:
{
"start_date": "2023-01-28T00:00:00",
"end_date": "2023-12-29T23:59:59",
"response_collection_id": "01GNPTVCE9E737Y7HFEK9QKQRV",
"product_identifier": "64b4b099-2ec6-448c-a33e-8c15dd167ab1",
"product_api_identifier": "d1b1e55b-7398-4cb6-9e6f-d7ab3e5b83d4",
}
To check the overall health of your income transaction, you can use the following request payload:
{
"start_date": "2023-01-28T00:00:00",
"end_date": "2023-12-29T23:59:59",
"response_collection_id": "01GNPTVCE9E737Y7HFEK9QKQRV",
"product_identifier": "d1b1e55b-7398-4cb6-9e6f-d7ab3e5b83d4"
}
To retrieve the results of your health query, use the get async health query result API. This API takes the query execution ID returned by the create async health query execution API as a parameter.
When you retrieve the results of your health query, you should see at least one health metric with corresponding status information (e.g. "SUCCEEDED", "FAILED").
Setting up alarms
You can set up alarms to be notified when the health of the Income product. To do this, use the create_health_alarm API.
This API allows you to specify a threshold value and a notification method.
