support@chirp.digital

1. Introduction

Welcome to the Chirp Developer Guide!

In this document, you will find all the resources you need to learn about, quickly integrate with, and get started using Chirp.

Chirp solutions provide you with features and data you need to build an Instant Financial Verification process and associated workflows for your unique underwriting process. Chirp makes it easy for you to connect to your customers' financial accounts to collect, analyze, and make more informed decisions based on transactional data.

1.1. About Chirp

Chirp is a web-based service with a full set of APIs that provides Instant Financial Verification Data for lenders to mitigate their risk using financial activity of their end customers.

Chirp IFV has real-time access to over 10,000 financial institutions. Chirp enables your business to verify your customers financial information quickly, securely and easily by providing the ability to see real-time financial transactions. Transaction data for a customer is capped at 180 days and 1,500 transactions.

Lenders will be able to create and manage Instant Financial Verification right from their Chirp portal account or from their Loan Management System through Chirp’s API.

2. Working with Chirp APIs

To access the Chirp APIs, you will need an account with Chirp with at least one approved Entity, Profile and User. If you have an active account, you can login to the Chirp Portal to retrieve Sandbox and Production API keys. Please refer here to know more about Chirp’s API tokens.

2.1. Using Chirp Sandbox APIs for Development and Testing

The Chirp Sandbox environment allows you to use the “Sandbox API token” for development and testing. The Sandbox environment limits developers to 5 financial institutions and with a total of 30 users. When production access is enabled all sandbox users are automatically removed by the system.

There are two options to consider when connecting to Sandbox:

  • Using the “Chirp Test Bank” financial institution which is preloaded with test users and test data.
    • This option allows for testing with sample data and scenarios without creating users and connection to a live bank.
  • There are a few supported financial institutions in the Chirp Sandbox environment.
    • This option allows for further testing with live financial account data. This option requires a person, with an active online financial institution profile, to participate in the Instant Financial Verification process.
    • These financial institutions can be used for testing using real bank credentials in the Sandbox environment.

Note: A request created with a Sandbox token is accessible only in Sandbox environment.

2.1.1. Test credentials for using the “Chirp Test Bank”

This allows for quick testing of different scenarios without creating real financial institution requests. These Test Credentials can only be used when the requests are created in the Sandbox environment using the “Chirp Test Bank”.

Username Password Description
test_chirp password Verification without MFA challenges
test_chirp challenge Load Multi-Factor Authentication (MFA) challenges. Anwering with the word 'correct' will get through the MFA successfully
test_chirp image Load image challenge for MFA. Anwering with the word 'correct' will get through the MFA successfully
test_chirp options Load other available MFA challenges for verification
test_chirp UNAUTHORIZED For simulating the verification process with invalid credentials
test_chirp SERVER_ERROR For simulating financial institution with a server error

If you want to work with one of the 5 financial institutions available in the Sandbox environment, the actual user credentials associated with the selected financial institution account must be used. For instance, if you are selecting USAA Bank, the real credentials for a USAA Bank account must be used.

After the requests and responses are successful in Sandbox Environment, you can request to enable Production Access to Chirp API. Chirp by default disables Production access for all Entities. Please contact Chirp to get the production environment enabled for your Entity. You will see the Production token in your Profile details page once Production access is enabled for your Entity. Now all that is needed is just replace the Production token with the Sandbox token and voila! you have successfully switched to Chirp Production environment.

Note: Any information created in Sandbox environment cannot be accessed in Production environment and vice versa.

2.2.1. IP Whitelisting

The Production environment is restricted to work only for whitelisted IPs. You can either contact support at support@chirp.digital to whitelist an IP or login to the Portal as the Entity admin and request an ip to whitelist under the WhiteListing menu API. The requested IP will be approved or denied by chirp and you can see the approved whitelisted IP list from the table. Please refer to the screenshot below for further assistance.

Figure 13: Managing IP Whitelisting

2.3. Consuming Chirp API Services

The following sections provide more information about consuming Chirp API services. For additional technical specifications, please check the Chirp API documents in Postman via this link:

https://documenter.getpostman.com/view/24377249/2s8YeuKAis

Chirp API supports both JSON and XML type responses. To get your desired type of response, simply pass Accept header with “text/xml” for an XML response and “application/json” for a JSON response. By default, the API sends JSON type response if no Accept header is passed along the request.

2.3.1.1. createRequest

The createRequest endpoint should be used for creating a request for a customer. Once a request is successfully created, a request code is generated for the created request and sent back in the response along with other request specific details.

Payload Field Definition

# Field Name Data Type Description
1 cusFirstName* String First name of the customer
2 cusLastName* String Last name of the customer
3 cusEmail* String Customer’s Email
4 cusAccNumber String Customer’s Account Number
5 cusAbaNumber String Customer’s Routing Number
6 cusAccType* String Customer’s Account Type
7 bankName String Customer’s bank name
8 cusPhone* String Customer’s Phone Number
9 customerId String The customer id can represent the Unique ID of a customer record used in the system that integrates with Chirp that retains a reference back to Chirp’s requestCode. For example, this can be a customer id or any other unique identifier in the system of record for connecting the Chirp request code with that customer.
10 notificationEmail String Notification Email to receive request status notification updates for the request. This email is used to link to the Customer Level REQUEST_STATUS notification created by Chirp.
11 lastFourDigitsOfDebitCard String A four-digit numeric value representing the last four digits of the user's debit card used for payment or identification purposes on the website.
12 productId String The productId can represent a Unique ID in the system integrated with Chirp that retains a reference back to Chirp’s requestCode. For example, this can be a loan id, application id or any other unique identifier in the system of record for connecting the Chirp requestCode with that product.
13 leadId String Lead Id typically refers to a unique identifier assigned for a lead provider in a system.
14 leadProvider String Lead Provider name associated with a particular lead.
15 requestXtraHistory Boolean Request to retrieve up to 24 months of transaction history. Not all financial institutions will support this request. This is an enhanced endpoint and requires activation by Chirp. Please contact Chirp for more information. Requesting Xtra History will not prevent the createRequest action. All status updates will be sent via the XTRAHISTORY_STATUS notification.
16 subtype String This indicates the subtype of the request (SUBSCRIPTION/PAYG). This field will consider if the product of the entity is in the FLEX plan type.
17 requestAccountVerification Boolean Request to retrieve account and routing numbers for a customer's account. Not all financial institutions will support this request. This is an enhanced endpoint and requires activation by Chirp. Please contact Chirp for more information.
18 requestAccountOwner Boolean Request to retrieve account owner data for a customer's account. Not all financial institutions will support this request. This is an enhanced endpoint and requires activation by Chirp. Please contact Chirp for more information.
19 notifyIf Array of Strings This field specifies the conditions for sending request status notification updates. Possible values include:
"ALL" – Sends notifications for all status updates.
"VERIFIED" – Sends notifications only when the request is verified.
"ATTEMPTED" – Sends notifications only when an attempt is made.
If "ALL" is specified, notifications will be sent for all status updates; otherwise, they will be sent only for the specified statuses.
The notificationEmail and notifyIf fields are mandatory to create an automated Customer Level REQUEST_STATUS notification in Chirp.

Fields with * appended are mandatory information to pass for creating a request. Any request passed without mandatory information will be restricted from creating the request and appropriate error code and message will be returned in the response. Please check Understanding Error Messages section to know more about error messages and codes returned for various scenarios.

Sample Request Payload

    {	
        "cusFirstName":"John",
        "cusLastName":"Doe",
        "cusEmail":"johndoe@somedomain.com",
        "cusAccNumber":"546561121",
        "cusAbaNumber": "322070381",
        "cusAccType": "Checking",
        "bankName":"chirp_test_bank",
        "cusPhone": "+10000000000",
        "customerId": "1234",
        "notificationEmail": "support@chirp.digital",
        "notifyIf" : ["ATTEMPTED", "VERIFIED"],
        "lastFourDigitsOfDebitCard" : "1234",
        "productId": "4533",
        "leadId" : "LEAD-123",
        "leadProvider" : "LEAD-ABC",
        "requestXtraHistory" : true,
        "subtype" : "SUBSCRIPTION",
        "requestAccountVerification" : true,
        "requestAccountOwner" : true
        
    }

Note: The above response is just an example. Please do not use the values present in this sample to create a request.

Response Field Definitions

# Field Name Data Type Description
1 RequestCode String Code to uniquely identify the request.
2 RequestId String Unique identifier for request details saved
3 CustomerIdentifier String The customer id can represent the Unique ID of a customer record used in the system that integrates with Chirp that retains a reference back to Chirp’s requestCode. For example, this can be a customer id or any other unique identifier in the system of record for connecting the Chirp request code with that customer
4 EmailAddress String Customer’s email address
5 InstitutionUrl String Customer’s bank website URL
6 WidgetURL String URL to integrate bank verification widget to lender’s website
7 ChirpVerificationURL String URL for customer to undergo bank verification process.
7 LendMateVerificationURL String URL for customer to undergo bank verification process.
8 cusAccNumber String Customer’s bank account number
9 cusAccType String Customer’s bank account type
10 FirstName String Customer’ first name
11 LastName String Customer’ last name
12 AddedOn Date String Timestamp of request created.
13 notificationEmail String Notification email address where notification regarding request updates will be sent.
14 Status Integer Status of the request 0 – unverified, 1 – verified, 2 - rejected, 3 – expired
15 Success Boolean Response result of request creation
16 AddedVia String Mode of the request created which is either API/Portal
17 lastFourDigitsOfDebitCard String A four-digit numeric value representing the last four digits of the user's debit card used for payment or identification purposes on the website.
18 ProductId String The productId can represent a Unique ID in the system integrated with Chirp that retains a reference back to Chirp’s requestCode. For example, this can be a loan id, application id or any other unique identifier in the system of record for connecting the Chirp requestCode with that product.
19 LeadId String Lead Id typically refers to a unique identifier assigned for a lead provider in a system.
20 LeadProvider String Lead Provider name associated with a particular lead.
21 requestXtraHistory Boolean Request to retrieve up to 24 months of transaction history. Not all financial institutions will support this request. This is an enhanced endpoint and requires activation by Chirp. Please contact Chirp for more information.

Understanding error messages for createRequest

# Scenario Error Code Error Message
1 If requested bank is not found 404 Bank not found! Please try again with a different bank name
2 If a request is created using invalid bank name 400 Please check the bank name and try again!
3 If a request is created using invalid email address 400 Please check the email address and try again!
4 If a request is created using invalid account type 400 Please check the account type and try again!
5 If a request is created using invalid first name 400 Please check the first name passed and try again!
6 If a request is created using invalid last name 400 Please check the last name passed and try again!
7 If a request is created using invalid phone number 400 Please check the phone number passed and try again!
8 If a request is created using invalid account number 400 Please check the account number passed and try again!
9 If a request is created using invalid ABA number 400 Please check the ABA number passed and try again!
10 If a request is created using “Chirp Test Bank” with the Production token 406 Please use a Sandbox token for testing using “Chirp Test Bank”.
11 If a request has already been verified with the passed customer details (Customer first name, Customer last name, Customer email, and Customer phone) and does not exceed the configured duplicate prevention period, the request will be considered a duplicate 400 Request is already created for the customer and it has also been verified. Please use the portal to create a new request for the customer.
12 If a request is created using invalid notifyIf field 400 notifyIf can only contain 'ALL', 'ATTEMPTED', or 'VERIFIED'.

2.3.1.2. getRequestDetails

This endpoint returns the below information for all verified requests.

  • Accounts linked to the primarily verified account
  • Transaction data of the account verified
  • Transaction data grouped with transaction type categories
  • Transaction count and number of days for each account
  • Debit card enrichment information
  • The institution name for the account(s) associated

If this endpoint is used for a request which is not successfully verified, the request to get details will be rejected with an error message. Please check the Understanding Error Messages section for more information about handling errors.

The Request details can be retrieved only for Requests that have been authenticated and verified by the customer. For the customer to authenticate and verify their bank account, there needs to be an interface or widget presented to the customer.

Customizing Response

The response transactions of this request can be customized using query parameters in the URL.

Supported Query Parameters

  • numberOfDays: Specifies the total number of days for which transactions should be retrieved. This parameter filters the transactions based on the specified number of days either in ascending or descending order.

    Example URL: https://chirp.digital/api/request/QLU0GU?numberOfDays=30

  • numberOfTransactions: Determines the total number of transactions to be included in the response.

    Example URL: https://chirp.digital/api/request/QLU0GU?numberOfTransactions=50

  • sort: Specifies the sorting order of the transactions. It can be either ascending or descending.

    Example URL: https://chirp.digital/api/request/QLU0GU?sort=ASCENDING

Below is the table explaining the response returned from getRequestDetails,

# Field Name Description
1 Request Code Request code of the respective request
2 Success Response result of the request
3 Accounts All the accounts that are linked with the verified bank account
4 TransactionSummaries Transaction data of the verified account
5 TransactionAnalysisSummaries Transaction data grouped with transaction type categories
6 AccountExpenses Expense breakdown based on transaction data
7 TotalTransactions Transaction count and number of days for each account
8 DebitCardEnrichment Debit card enrichment match details
9 institutionName The institution name for the account(s) associated

Description for fields under Transaction information,

# Field Data Type Description
1 account_guid String A unique identifier for the account to which the transaction belongs.
2 amount Decimal The monetary amount of the transaction. Max length is 10,2.
3 category String The category of the transaction.
4 check_number Integer DEPRECATED. Use check_number_string instead.
5 check_number_string String The check number for the transaction.
6 created_at String The date and time the transaction was stored.
7 currency_code String The three-character ISO 4217 currency code, e.g. USD.
8 date String The date the transaction was created.
9 description String A human-readable version of the original_description field described below, e.g., "Sam's Club," "Johnny's Tavern."
10 guid String A unique identifier for the transaction.
11 is_bill_pay Boolean If the transaction is a bill pay, this field will be true. Otherwise, this field will be false.
12 is_direct_deposit Boolean If the transaction is a direct deposit, this field will be true. Otherwise, this field will be false.
13 is_expense Boolean If the transaction is an expense, this field will be true. Otherwise, this field will be false.
14 is_fee Boolean If the transaction is a fee, this field will be true. Otherwise, this field will be false.
15 is_income Boolean If the transaction is income, this field will be true. Otherwise, this field will be false.
16 is_international Boolean If the transaction is international as defined by the data provider, this field will be true. If the data provider determines it is not international, then it will be false. It will be null if the data provider does not have this information.
17 is_overdraft_fee Boolean If the transaction is an overdraft fee, this field will be true. Otherwise, this field will be false.
18 is_payroll_advance Boolean If the transaction is a payroll advance fee, this field will be true. Otherwise, this field will be false.
19 latitude Decimal The latitude of the location where the transaction occurred. The number is a signed decimal.
20 longitude Decimal The longitude of the location where the transaction occurred. The number is a signed decimal.
21 member_guid String A unique identifier for the member to which the transaction belongs.
22 memo String This field contains additional descriptive information about the transaction.
23 merchant_category_code Integer The ISO 18245 category code for the transaction.
24 merchant_guid String The unique identifier for the merchant associated with this transaction.
25 original_description String The original description of the transaction as provided by our data feed. See description above for more information.
26 posted_at String The date and time the transaction was posted.
27 status String The status of the transaction, i.e., POSTED or PENDING.
28 top_level_category String The parent category that this transaction's category is assigned to.
29 transacted_at String The date and time the transaction took place.
30 type String The type of transaction, i.e., CREDIT or DEBIT.
31 updated_at String The date and time the transaction was updated.
32 user_guid String A unique identifier for the user to which this transaction belongs.
33 is_recurring Boolean Recurring payment or transaction
34 account_id String The identifier for the account associated with the transaction
35 category_guid String The identifier for the category of the transaction
36 id String The unique partner-defined identifier for the transaction. This can only be set for partner-managed transactions. It should be ignored for user-managed transactions, even in occasional cases where it may return with a value
37 is_subscription Boolean If transaction represents a payment for a subscription service such as Netflix or Audible
38 localized_description String A human-readable description of the transaction, provided in a local language
39 localized_memo String Additional descriptive information about the transaction, provided in a local language
40 merchant_location_guid String The identifier for the merchant_location associated with this transaction
41 user_id String The unique identifier for the user associated with the transaction
42 categoryCode String The category code of the transaction
43 parentCategoryCode String The parent category code of the transaction

Description for additional or optional fields under Transaction information,

# Field Data Type Description
1 chirpAccountId String The account's unique identifier, as defined by Chirp
2 chirpTransactionId String The transaction's unique identifier, as defined by Chirp

Description for fields under Account information,

# Field Data Type Description
1 account_number string The account number. This will typically be a masked or partial account number.
2 apr Decimal Annual Percentage Rate. Max length is 10,6.
3 apy Decimal Annual Percentage Yield. Max length is 10,6.
4 available_balance Decimal The balance currently available in an account. Max length is 14,2.
5 available_credit Decimal The currently available credit balance of an account. This field is for accounts with types CREDIT CARD and LINE OF CREDIT.
6 balance Decimal An account's current balance. Max length is 14,2.
7 cash_balance Decimal The cash balance of the account. Max length is 14,2.
8 created_at String The date and time the account was created.
9 credit_limit Decimal The credit limit for the account. Max length is 10,2.
10 currency_code String The three-character ISO 4217 currency code, e.g. USD.
11 guid String Unique identifier for the account.
12 holdings_value Decimal The value of the holdings associated with the account.
13 institution_code String Unique identifier for the financial institution which holds the account.
14 interest_rate Decimal Interest rate. Max length is 10,6.
15 is_closed Boolean If an account is closed, this field will be true. Otherwise, this field will be false.
16 member_guid String Unique identifier for the member to which this account belongs.
17 type String The main type of an account, e.g., INVESTMENT, PREPAID, or SAVINGS.
18 updated_at String The date and time at which the account was last updated.
19 user_guid String A unique identifier for the user to which the account belongs.
20 routing_number String The routing number for the account.
21 insured_name String The date and time the account was created
22 cash_surrender_value Decimal Money paid to the policy holder or annuity holder in the event the policy is voluntarily terminated before it matures, or the insured event occurs
23 day_payment_is_due String The day of the month the payment is due. e.g 14
24 death_benefit Integer The amount paid to the beneficiary of the account upon death of the account owner
25 last_payment Decimal The amount of the recent payment on the account
26 loan_amount Decimal The amount of the loan associated with the account
27 matures_on String The date on which the account matures
28 minimum_balance Decimal The minimum balance of the account
29 minimum_payment Decimal The minimum payment required for an account. This can apply to any debt account
30 name String The human-readable name for the account
31 original_balance Decimal The original balance of the account. This will always be positive
32 pay_out_amount String The amount paid out to the insured person or beneficiary under the conditions of the insurance policy
33 payoff_balance Decimal The payoff balance for a debt account. This will normally be a positive number
34 premium_amount Decimal The insurance policy's premium amount
35 started_on String The date on which a debt account was started
36 total_account_value Decimal The total combining both long and short positions, the sweep account and/or cash balance, and any margin debt linked to a specific account. This figure encompasses the aggregate market value of all positions within the account, offset by any debit balance and the value of short options positions that are profitable. This cumulative value can be negative and should not be misconstrued as an account balance
37 subtype String The account's subtype, e.g., PLAN_401_K, MONEY_MARKET, or HOME_EQUITY
38 last_payment_at String The date and time of the most recent payment on the account
39 payment_due_at String The date and time at which the next payment is due on the account
40 account_id String The unique identifier for the account

Description for additional or optional fields under Account information,

# Field Data Type Description
1 requestCode String Unique code assigned for a customer request
2 entityId String Unique identifier for an entity
3 profileId String Unique identifier for a profile associated with an entity
4 accountMatch Boolean Denotes if the provided account number matches with the account number returned by the financial institution
5 addedOn String The timestamp when the account data for the customer is added in Chirp
6 modifiedOn String The timestamp when the account data for the customer is last modified in Chirp
7 chirpAccountId String The account's unique identifier, as defined by Chirp

Description for fields under TransactionAnalysisSummaries information,

# Field Data Type Description
1 category String A label identifying the type of transaction, for instance, "FEE"
2 total Decimal The total number of transactions within this category
3 amount String The combined total amount for all transactions in this category, for instance, "$32.00"
4 recentTransactionAmount String The amount of the most recent transaction in this category, for instance, "$2.00"
5 recentTransactionCount Decimal The number of recent transactions, for instance, 1
6 categoryName String The more descriptive name of the category, such as "Fees & Charges"
7 transaction Array Transactions associated with the category

Understanding error messages for getRequestDetails

# Scenario Error Code Error Message
1 If requesting details for an expired request 406 Request status is expired. Please try again with a verified request code
2 If requesting details for a rejected request 406 Request status is rejected. Please try again with a verified request code
3 If requesting details from a request code that has not been verified 406 Request status is unverified. Please verify the request and try again

2.3.1.3. getRequestStatus

The getRequestStatus endpoint is used to get the current status of a request along with basic request information. Please check the Understanding Error Messages section for more details about handling errors.

Example success response:

Status code: 200

    {
        "success": true,
        "response": {
            "RequestCode": "QLU0GU",
            "Status": "Attempted",
            "FirstName": "John",
            "LastName": "Doe",
            "Environment": "dev",
            "Mode": "Portal",
            "VerificationLink": "https://chirp.digital/api/verify?requestCode=QLU0GU",
            "SelectedBank": "Chirp Test Bank",
            "isAccountConnected": false,
            "isLinkExpired": false,
            "LastAggregatedAt": "2024-03-12T04:59:15.273Z",
            "connectionStatus": "Subscribed",
            "statusDetails": "Attempted - Credential Error"
        }
    }

Response Field Definitions for getRequestStatus

# Field Name Description
1 RequestCode Request code passed
2 Status Status of the request code passed - “Verified”, “Attempted”, “Rejected”,”Unverified - No Customer Action”, “Unverified - Incomplete Customer Action”, ”Expired”
3 FirstName Customer’s first name
4 LastName Customer’s last name
5 Environment Environment of the request code whether it is dev(Sandbox)/prod(Production)
6 Mode Mode of the request created which is either API/Portal
7 Verification Link Verification link to be used for customer’s financial verification
8 Selected Bank Customer’s Selected bank for verification
9 isAccountConnected Denotes if the customer's account is linked and connected
10 isLinkExpired Denotes if the verification link can be used any further
11 LastAggregatedAt Timestamp when the customer data has been updated. Represented as UTC
12 connectionStatus Connection status of the request. This field returns Subscribed/Unsubscribed or Connected/Disconnected or NA as a value based on the plan type
13 statusDetails Status details of the request code passed - ”Unverified - No Customer Action”, “Unverified - Incomplete Customer Action”, “Attempted - Bank Error”, “Attempted - In Progress”, “Attempted - Credential Error”

2.3.1.4. refreshRequest

The refreshRequest endpoint is used to aggregate and pull updated transactions and account data for a request that has already been successfully verified or refreshed.

The refreshRequest is a synchronous operation. Due to the nature of the synchronous operation the user/process that initiates the refresh should wait for a response before moving on to the next step or moving away from the UI.

Attempting to refresh a request within 3 hours of a successful verification or refresh will not be permitted. Chirp will respond with a “405 not allowed” status message. Please check the “Understanding Error Messages” section for more information about error handling.

# Tag Description
1 bankName Name of the customer’s Institution
2 aggregatedAt Last updated timestamp when aggregation was successful
3 status Last updated status of the request being refreshed
4 isBeingAggregated Denotes if request is still being aggregated in the background
5 denialReason Shows denial reason for a failed bank refresh attempt

Example success response:

Status code: 200

    {
        "success": true,
        "status": "Verified",
        "aggregatedAt": "2020-05-29T07:10:43Z",
        "isBeingAggregated ": true,
        "bankName": "Chirp Test Bank"
    }

Understanding error messages for refreshRequest

# Scenario Error Code Error Message
1 If Bank Refresh is not enabled for this profile. 400 Bank Refresh is not enabled for this profile.
2 If the request code is deleted while refreshRequest is attempted 405 Your request code is deleted. Please contact administrator.
3 If the request code is unsubscribed/disconnected 405 Your request is unsubscribed/disconnected. Please try again with a different request code. Contact Chirp Support for more assistance, support@chirp.digital
4 If the request code is unsubscribed/disconnected while refreshRequest is attempted 405 Your request is unsubscribed/disconnected. Please try again with a different request code. Contact Chirp Support for more assistance, support@chirp.digital
5 If request code is not verified 405 Your request code is not verified. Please complete bank verification and try again.
6 If the request code is expired 405 Your request code is expired. Please create a new request and try again.
7 If refreshRequest is attempted within 3 hrs of a successful verified or refreshed customer. 405 A request to refresh was attempted within 3 hours. Please try again later.

2.3.1.5. unsubscribeRequest

The unsubscribeRequest endpoint is used to unsubscribe Subscription based customers and disconnect PAYG (Pay As You Go) based customers from an Entity. Unsubscribing a customer removes the ability to request a refresh of transactions for that customer. However, the last successful set of transactions that were retrieved for an unsubscribed customer will be retained. Please review the Understanding Error Messages section for more details about handling errors.

Note: This action is permanent and cannot be reverted

Example success response:

Status code: 200

    {
        “success”: “true”,
        “message”: "Customer has been unsubscribed or disconnected successfully"
    }

Understanding error messages for unsubscribeRequest

# Scenario Error Code Error Message
1 If the request code is deleted 405 Your request code is deleted. Please contact administrator.
2 If the request code is unsubscribed/disconnected already 405 Invalid action attempted. Request is unsubscribed/disconnected already.
3 Invalid action 405 Invalid Action Attempted. This request code cannot be unsubscribed/disconnected.
4 If the request code is not eligible to be unsubscribed/disconnected 405 Invalid Action Attempted. Request was never in a subscribed/connected state so it cannot be unsubscribed/disconnected

2.3.1.6. getSummaryInfoByRequestCode

This endpoint returns basic and additional summary information for a verified request. Request code and account number are mandatory fields to pass. Request code can be taken from the response returned by createRequest endpoint. To obtain the accountNumber or chirpAccountId call getRequestAccountDetails. Then use the "account_number" or "chirpAccountId" from the response.

Example success response:

Status code: 200

    {
        "success": true,
        "requestCode": "QLU0GU",
        "availableBalance": "$ 1000.00",
        "asOfdate": "6/21/2022, 1:42 AM",
        "currentBalance": "$ 1000.00",
        "customerFirstName": "John",
        "customerLastName": "Doe",
        "customerEmail": "johndoe@somedomain.com",
        "customerAccountInfo": {
            "account_number": "1027261114",
            "apr": null,
            "apy": null,
            "available_credit": null,
            "cash_balance": null,
            "created_at": "2022-06-21T06:42:19Z",
            "credit_limit": null,
            "currency_code": null,
            "holdings_value": null,
            "interest_rate": null,
            "institution_code": "chirpbank",
            "insured_name": null,
            "is_closed": false,
            "type": "SAVINGS",
            "updated_at": "2022-06-21T06:42:19Z",
            "routing_number": "12345",
            "chirpAccountId": "ACC-2171ee40-1290-11ef-b135-150631c74239",
        },
        "customerAccountMatchStatus": "No Match",
        "customerAccountMatchStatusDescription": "The user entered account number does not match
            the account number returned by the financial institution",
        "customerRoutingNumberMatchStatus": "No Match",
        "customerRoutingNumberMatchStatusDescription": "The user entered routing number does not match
                the routing number returned by the financial institution",
        "activityByMonth": [
            {
                "month": "All",
                "averageDailyBalance": "$ -461.64",
                "averageMonthlyBalance": "$ -461.64",
                "totalCredit": "$ 4219.27",
                "totalDebit": "$ 1843.64",
                "totalpayroll": "$ 0.00",
                "totalNet": "$ 2375.63"
            },
            {
                "month": "Mar, 2022",
                "averageDailyBalance": "$ -1344.60",
                "averageMonthlyBalance": "$ -1344.60",
                "totalCredit": "$ 94.22",
                "totalDebit": "$ 75.01",
                "totalPayroll": "$ 0.00",
                "totalNet": "$ 19.21"
            },
            {
                "month": "Apr, 2022",
                "averageDailyBalance": "$ -1093.16",
                "averageMonthlyBalance": "$ -1093.16",
                "totalCredit": "$ 1484.33",
                "totalDebit": "$ 800.60",
                "totalPayroll": "$ 0.00",
                "totalNet": "$ 683.73"
            },
            {
                "month": "May, 2022",
                "averageDailyBalance": "$ -385.37",
                "averageMonthlyBalance": "$ -385.37",
                "totalCredit": "$ 1226.29",
                "totalDebit": "$ 633.95",
                "totalPayroll": "$ 0.00",
                "totalNet": "$ 592.34"
            },
            {
                "month": "Jun, 2022",
                "averageDailyBalance": "$ 547.83",
                "averageMonthlyBalance": "$ 547.83",
                "totalCredit": "$ 1414.43",
                "totalDebit": "$ 334.08",
                "totalPayroll": "$ 0.00",
                "totalNet": "$ 1080.35"
            }
        ],
        "totalTransactions": 168,
        "numberOfDays": 83,
        "customerEnteredAccountNumber": "546561121",
        "customerEnteredRoutingNumber": "322070381"
    }

Response Field Definitions for getSummaryInfoByRequestCode,

# Field Name Description
1 success Response result of the request
2 requestCode Request code of the respective request
3 availableBalance The balance currently available in an account
4 customerFirstName First name of the customer
5 customerLastName Last name of the customer
6 customerEmail Email of the customer
7 customerAccountInfo Account info of the connected customer
8 asOfdate Request last updated date
9 currentBalance An account's current balance
10 customerAccountMatchStatus The current match status of the account number entered by the user versus the account number returned by the financial institution
11 customerAccountMatchStatusDescription Description of the account number match status value
12 totalTransactions Total number of transactions returned
13 numberOfDays Total number of days of the transactions returned since inception till date
14 customerRoutingNumberMatchStatus The current match status of the routing number entered by the user versus the routing number returned by the financial institution
15 customerRoutingNumberMatchStatusDescription Description of the routing number match status value
16 customerEnteredAccountNumber Customer’s account number entered into Chirp as part of creating the request. Could have been entered in the Portal or sent via API by the integration partner
17 customerEnteredRoutingNumber Customer’s routing number entered into Chirp as part of creating the request. Could have been entered in the Portal or sent via API by the integration partner

Description for fields under customerAccountInfo,

# Field Name Data Type Description
1 account_number String The account number of the customer. This will typically be a masked or partial account number.
2 apr Decimal Annual Percentage Rate
3 apy Decimal Annual Percentage Yield
4 available_credit Decimal The currently available credit balance of an account.
5 cash_balance Decimal The cash balance of the account
6 created_at String The date and time the account was created
7 credit_limit Decimal The credit limit for the account
8 currency_code String The three-character ISO 4217 currency code
9 holdings_value Decimal The value of the holdings associated with the account
10 interest_rate Decimal Interest rate
11 institution_code String Unique identifier for the financial institution which holds the account
12 insured_name String The name of the insured individual
13 is_closed Boolean If an account is closed, this field will be true. Otherwise, this field will be false
14 type String The main type of an account, e.g., INVESTMENT, PREPAID, or SAVINGS
15 updated_at String The date and time at which the account was last updated
16 routing_number String The routing number for the account.

Description for additional or optional fields under customerAccountInfo,

# Field Name Data Type Description
1 chirpAccountId String The account's unique identifier, as defined by Chirp

Description for fields under activityByMonth,

# Field Name Data Type Description
1 averageDailyBalance String Shows month and year for which the activity is calculated. Shows ‘All’ as value for overall time period calculation
2 month String Average daily balance of the customer
3 averageMonthlyBalance String Average monthly balance of the customer
4 totalCredit String Total credit amount returned for the customer
5 totalDebit String Total debit amount returned for the customer
6 totalpayroll String Total payroll amount returned for the customer
7 totalNet String Net amount returned for the customer

Understanding error messages for getSummaryInfoByRequestCode

# Scenario Error Code Error Message
1 If account number field is empty or invalid 400 Account number is mandatory. Please try again with a valid account number.
2 If requesting details for an expired request 406 Request status is expired. Please try again with a verified request code
3 If requesting details for a rejected request 406 Request status is rejected. Please try again with a verified request code
4 If requesting details from a request code that has not been verified 406 Request status is unverified. Please verify the request and try again
5 If the account number passed is invalid 400 Account number passed is invalid. Please try again with a valid account number.

2.3.1.7. generateAuthTokenForReportUI

The generateAuthTokenForReportUI endpoint should be used for generating a one-time usable token for rendering verification reports hosted as an Iframe in a webpage. The token generated is only valid for a single use and any subsequent usage of the same token will result in Authorization errors. This endpoint requires one of the following combinations to be passed in the username and password fields for generating a valid token:
1. Entity username in the username field and Entity password in the password field along with the verification Request Code
2. Entity Client Id in the username field and Profile API Access Token in the password field along with the verification Request Code.

Request Field Definitions

# Field Name Description
1 username* <Entity user's username> or <Entity Client ID>
2 password* <Entity user's password> or <Entity Profile Token>
3 requestCode* Verified request code

Fields appending with an asterisk (*) are required for creating a request. Any request missing required fields will be denied, and the corresponding error code with message will be returned in response. Please check the “Understanding Error Messages” section for more information about error handling.

Sample Request Payload

    {
        "username":"<Entity user's username> or <Entity Client ID>",
        "password":"<Entity user's password> or <Entity Profile Token>",
        "requestCode":"<request code>",
    }

Request Field Definitions

# Field Name Description
1 token One-time usable token generated for rendering a customer report via the hosted render report UI V2
2 validUpto The expiration time until the generated token is valid. Timezone is CST
3 validForRequestCode The request code for which the token is valid

Status code: 200

    {
        "success": true,
        "result":
        {
          "token":"eyJhbGciOiJSUzUxMiIsInR5cCI6IkpXVCJ9.eyJlbnRpdHlJZCI6IjVmZjFl
                   MWQwZDQyMzRiMDJkYTc2ZWJmYiIsInVzZXJJZCI6IjVmZjFlMWQwZDQyMzRiM
                   DJkYTc2ZWJmYSIsInJlcXVlc3RDb2RlIjoiTENVWEk2IiwicHJvZmlsZUlkIj
                   oiNWZmMWUxZDBkNDIzNGIwMmRhNzZlYmZjIiwiaWF0IjoxNjI3OTAyMTA5LC
                   JleHAiOjE2Mjc5MjAxMDl9.Aq_VU0lgNl1v-qI690xRqaxUuEViARdV1JCq9K
                   7v19v2H0wd3V8O4JQLwBkOl-mhqNaO6P9qnnSPREvrANp4nAZhVB3OVfgQKX18
                   eEVVAaIeLf8Cr7GG2ml1jJgasN48ouK9Hs5utVJEGvfKpRT3Qa_EZaw139WzSL
                   GPgDPI120",
           "validUpto": "8/2/2022, 11:01 AM",
           "validForRequestCode": "QLU0GU"
        }
    }

Understanding error messages for generateAuthTokenForReportUI

# Scenario Error Code Error Message
1 If the request code field is empty 400 Request code is missing. Please try again with a valid request code.
2 If the request code is invalid 400 Request code <requestCode> is invalid. Please contact the company you are working with for further assistance.
3 If request code passed is not verified 400 Request must be verified before a token can be generated. Please try again with a verified request.
4 If the Request code is not associated with the entity. 400 Request code is not associated with the entity.
5 If user authorization failed due to invalid creds 401 User authorization failed due to invalid credentials. Please try again with valid credentials.

2.3.1.8. getRequestReportAsPDF

The getRequestReportAsPDF endpoint is used to generate a PDF report for a successfully verified request. The endpoint should only be called after a successful verified request has been completed. If webhooks are not being used the status of a request can be found using the getRequestStatus endpoint.

After calling getRequestReportAsPDF with a successfully completed verification a link to download the generated PDF report is generated and returned in the response. The link can be used to download the generated PDF report. The link and the generated PDF report are valid for 12 hours after being generated. After 12 hours the link and PDF report will be removed from the system.

The request code and account number are mandatory fields to pass. Request code can be taken from the response returned by createRequest endpoint and Account number can be taken from getRequestDetails response.

Example getRequestReportAsPDF Request:

    {
        "requestCode": "QLU0GU",
        "accountNumber": “XXXXXX”
    }

Example Successful Response:

    {
        "success": true,
        "requestCode": "QLU0GU",
        "fileDownloadLink": "https://chirp.digital/public/XXXXXX_2022-06-01T02-12"
    }

Response Field Definitions for getRequestReportAsPDF,

# Field Name Description
1 success Response result of the request
2 requestCode Request code of the respective request
3 fileDownloadLink The Link to download the generated PDF report

Understanding error messages for getRequestReportAsPDF

# Scenario Error Code Error Message
1 If the request code field is empty 400 Request code is missing. Please try again with a valid request code.
2 If account number field is empty or invalid 400 Account number is mandatory. Please try again with a valid account number.
3 If the access is forbidden 400 Access forbidden. Please check the environment of the API token passed and try again!
4 If requesting details for an expired request 406 Request status is expired. Please try again with a verified request code
5 If requesting details for a rejected request 406 Request status is rejected. Please try again with a verified request code
6 If requesting details from a request code that has not been verified 406 Request status is unverified. Please verify the request and try again

2.3.1.9. updateRequestStatus

The updateRequestStatus endpoint is used to update the status of a request. The endpoint currently only supports updating the status of a request from Attempted to Rejected.

Sample Request Payload

    {	
        "requestCode":"QLU0GU",
        "statusToUpdate":"REJECTED",
    }

Example success response:

Status code: 200

    {
        "success": true,
        "message": "The request has been updated to Rejected status successfully"
    }

Understanding error messages for updateRequestStatus

# Scenario Error Code Error Message
1 If status to update is invalid 400 Please check the status to update and try again!
2 If the request code is already rejected 400 Request code <requestCode> cannot set to Rejected beacuse the status is already Rejected
3 Request code needs to be attempted before reject 400 Current status of the request is <status> and cannot be set to rejected.
4 If entered customer not found 404 Customer not found.

2.3.1.10. getRequestTrackInfo

The getRequestTrackInfo endpoint takes upto 1000 request codes per request and returns all relevant track level information. This information can be used to sync the data in the LMS system. The response returns information for only valid and applicable request codes passed while invalid request codes and requests that do not belong to the profile associated with the authorization token are ignored.

Sample Request Payload

    {
        "requestCodes" : "[\"QLU0GU\",\"YYYYYY\",\"ZZZZZZ\"]"
    }

Example success response:

Status code: 200

    {
        "success": true,
        "result": [
          {
            "requestCode": "QLU0GU",
            "customerName": "John Deo",
            "email": "johndoe@somedomain.com",
            "phone": "1111111111",
            "entityName": "Test Entity",
            "profileName": "Test Profile",
            "accessInfo": "Portal",
            "bankName": "Chirp Test Bank",
            "status": "Verified",
            "planType": "FLEX",
            "subtype" : "SUBSCRIPTION",
            "subscriptionStatus": "NA",
            "addedOn": "2022-08-08T12:10:49.826Z",
            "attemptedOn": "2022-08-08T12:11:16.998Z",
            "verifiedOn": "2022-08-08T12:22:16.998Z",
            "rejectedOn": "NA",
            "unsubscribedOn": "2022-08-08T12:11:36.507Z",
            "statusDetails": "NA"
          }
        ]
    }

Note:

1. The requestCodes field in the payload should be stringified.

Response Field Definitions for getRequestTrackInfo,

# Field Name Description
1 requestCode Code to uniquely identify the request
2 customerName Customer’s first and last name
3 email Customer’s email
4 phone Customer’s phone
5 entityName Entity business name to which the customer is associated
6 profileName Profile name to which the customer is associated
7 accessInfo Access of the request created, either API/Portal
8 bankName Customer’s selected bank
9 status Status of the request code - “Unverified”, “verified”, “Attempted”, “Rejected”, “Expired”
10 planType Plan type of the request code - SUBSCRIPTION/PAYG/FLEX
11 subscriptionStatus Subscription of the request code - Subscribed/Unsubscribed
12 addedOn Timestamp when request is added
13 attemptedOn Timestamp when request is attempted
14 verifiedOn Timestamp when request is verified
15 rejectedOn Timestamp when request is rejected
16 unsubscribedOn Timestamp when request is unsubscribed
17 subtype Subtype of the request code - SUBSCRIPTION/PAYG. This field will be returned if the planType is "FLEX"
18 statusDetails Status details of the request code passed - ”Unverified - No Customer Action”, “Unverified - Incomplete Customer Action”, “Attempted - Bank Error”, “Attempted - In Progress”, “Attempted - Credential Error”

Understanding error messages for getRequestTrackInfo

# Scenario Error Code Error Message
1 If the request code field is empty 400 The requestCodes field is mandatory. Please try again with a valid payload in the request body
2 If the parsed stringified data is not an array of strings or invalid 400 The requestCodes field is in invalid format. Please try again with a valid payload in the request body
3 If the payload contains more than 1000 request codes 400 Maximum allowed request code limit is 1000. Please try again with a valid payload in the request body

2.3.1.11. createCustomerNotification

The createCustomerNotification endpoint is used to create a customer level configuration for triggering Chirp notifications. If an entity has its own notification configuration added then the notification configuration added for the customer level will override the entity level notification configuration.

Payload Field Definition for createCustomerNotification,

# Field Data Type Description
1 name* String Name for the customer notification
2 requestCode* String Code to uniquely identify the request.
3 type* String Type of notification
4 rule* String Rule of the notification type
5 amount Number Amount to filter customer’s financial informations
6 webhookUrl Array of strings Webhook url to send chirp notifications(Maximum of 2 URLs can be configured for REQUEST and REFRESH type)
7 emails Array of strings Emails to send chirp notifications
8 notifyViaEmail* Boolean Boolean value to active email notifications
9 notifyViaWebhook* Boolean Boolean value to active webhook notifications
10 active* Boolean Boolean value to make the notification active
11 keywords Array of strings Keywords to match the description of a transaction
12 enableRetryTimeout Boolean Boolean value to activate retrying timeout webhooks
13 retryTimeout Number Automatically retry posting the webhook notification if the initial attempt results in a timeout. This number field denotes the interval for retrying in hours.

Fields with * appended are mandatory information to pass for creating a customer notification. Any request passed without mandatory information will be restricted from creating the customer notification and appropriate error code and message will be returned in the response. Please check Understanding Error Messages section to know more about error messages and codes returned for various scenarios.

Sample Request Payload

    {
        "name":"YYYYYYYY",
        "requestCode" : "QLU0GU",
        "type":"DEPOSIT",
        "rule" : "GREATER_THAN",
        "amount" : 44,
        "emails" : ["johndoa@somedomain.com"],
        "notifyViaEmail" : true,
        "notifyViaWebhook" : true,
        "webhookUrl" : ["https://example.com"],
        "active" : true,
        "enableRetryTimeout" : true,
        "retryTimeout" : 2
    }

Example success response:

Status code: 200

    {
        "success": true,
        "message": "Customer notification configuration added successfully!"
       }

Understanding error messages for createCustomerNotification

# Scenario Error Code Error Message
1 If the request code passed has already customer configuration with passed type 409 This customer already has a notification configuration with the type
2 If the notification channel is not provided 400 Please provide a notification channel and try again!
3 If passed type and rule are inappropriate 400 Please check the type and rule and try again!
4 If entered keywords are invalid 400 Please check the keywords and try again later.
5 If invalid webhook url is passed 400 Please check the webhookUrl and try again
6 If one or more invalid emails are passed 400 Please check the emails and try again
7 If notifyViaWebhook field are invalid 400 Please enable the notifyViaWebhook field and try again
8 If notifyViaEmail field are invalid 400 Please enable the notifyViaEmail field and try again
9 If invalid retryTimeout field is passed 400 Please check the retryTimeout and try again
10 If enableRetryTimeout field is invalid 400 Please enable the enableRetryTimeout field and try again
11 If the request code is other than subscription or flex-subscription plan type 400 Your current plan does not support this type of notification configuration. Please contact support@chirp.digital for more info

2.3.1.12. updateCustomerNotification

The updateCustomerNotification endpoint is used to update an existing customer-level notification in Chirp

Note: If emails are required to be updated then a prior update to the field notifyViaEmail is required to set as true. If the value of notifyViaEmail is already true then no prior update is required for updating the emails fields. This applies to the field webhook also where notifyViaWebhook is the field to update as true.

Payload Field Definition for updateCustomerNotification,

# Field Data Type Description
1 name String Name for the customer notification
2 type String Type of notification
3 rule String Rule of the notification type
4 amount Number Amount to filter customer’s financial informations
5 webhookUrl Array of string Webhook url to send chirp notifications
6 emails Array of strings Emails to send chirp notifications
7 notifyViaEmail Boolean Boolean value to active email notifications
8 notifyViaWebhook Boolean Boolean value to active webhook notifications
9 active Boolean Boolean value to make the notification active
10 keywords Array of strings Keywords to match the description of a transaction
11 enableRetryTimeout Boolean Boolean value to activate retrying timeout webhooks
12 retryTimeout Number Automatically retry posting the webhook notification if the initial attempt results in a timeout. This number field denotes the interval for retrying in hours.

Sample Request Payload

    {
        "name":"YYYYYYYY",
        "type":"DEPOSIT",
        "rule" : "GREATER_THAN",
        "amount" : 44,
        "emails" : ["johndoa@somedomain.com"],
        "notifyViaEmail" : true,
        "notifyViaWebhook" : true,
        "webhookUrl" : ["https://example.com"],
        "active" : true,
        "enableRetryTimeout" : true,
        "retryTimeout" : 2
    }

Example success response:

Status code: 200

    {
        "success": true,
        "message": "Customer notification configuration updated successfully!"
    }

Response Field Definitions for updateCustomerNotification,

# Field Name Description
1 success Response result of the request
2 message Success message

Understanding error messages for updateCustomerNotification

# Scenario Error Code Error Message
1 If the request code passed has already customer configuration with passed type 409 This customer already has a notification configuration with the type
2 If passed type and rule are inappropriate 400 Please check the type and rule and try again!
3 If entered keywords are invalid 400 Please check the keywords and try again later.
4 If invalid webhook url is passed 400 Please check the webhookUrl field and try again
5 If one or more invalid emails are passed 400 Please check the emails and try again
6 If notifyViaWebhook field is invalid 400 Please enable the notifyViaWebhook and try again
7 If notifyViaEmail field is invalid 400 Please enable the notifyViaEmail field and try again
8 If webhook url passed is more than 2 for REQUEST and REFRESH type 400 A maximum of only 2 URLs can be configured
9 If invalid retryTimeout field is passed 400 Please check the retryTimeout and try again
10 If enableRetryTimeout field is invalid 400 Please enable the enableRetryTimeout field and try again

2.3.1.13. getCustomerNotification

The getCustomerNotification endpoint is used to get all customer-level notifications Chirp notifications. Please check the Understanding Error Messages section for more details about handling errors.

Note: If the query param type is passed with an appropriate value then the response is filtered with it. If the request has no type value added as indicated above then all the notifications configured for the customer are returned.

Example Successful Response:

    {
        "success": true,
        "result": [
        {
            "emails": [
                "aaaaa@somedomain.com"
            ],
            "addedOn": "2023-01-04T08:01:09.515Z",
            "modifiedOn": "2023-01-04T08:01:09.515Z",
            "requestCode": "QLU0GU",
            "name": "YYYYYY",
            "cusFirstName": "John",
            "cusLastName": "Deo",
            "type": "ACC_CONNECTION_STATUS",
            "rule": "REMOVED",
            "webhookUrl": "www.example.com",
            "active": true,
            "notifyViaEmail": true,
            "notifyViaWebhook": true,
            "amount": 0,
            "enableRetryTimeout" : true,
            "retryTimeout" : 2
        }
        ] 
        }

Response Field Definitions for getCustomerNotification,

# Field Name Description
1 success Response result of the request
2 result Notification configurations associated with the requestCode

Understanding error messages for getCustomerNotification

# Scenario Error Code Error Message
1 If the customer has no notification added 404 This customer has no notification configuration added!

2.3.1.14. removeCustomerNotification

The removeCustomerNotification endpoint is used to remove the customer-level notification from Chirp.

Example Successful Response:

    {
        "success": true,
        "message": "Customer notification configuration removed successfully!" 
    }

Response Field Definitions for removeCustomerNotification,

# Field Name Description
1 success Response result of the request
2 message Success message

Understanding error messages for removeCustomerNotification

# Scenario Error Code Error Message
1 If the customer has no notification added 404 This customer has no notification configuration added!

2.3.1.15. isRoutingNumberAvailable

This endpoint is used to find if the passed routing number associated with the financial institution is supported by Chirp or not. A simple boolean response is returned to denote the support. This endpoint is secured the same as other endpoints and requires the API token that can be found in the profile details page for authorization. More technical details and sample response information about this and other endpoints can be found on the Postman documentation.
Sandbox token only supports a dummy value such as 000000000 to be passed to help with the integration

Example Successful Response:

true

Understanding error messages for isRoutingNumberAvailable

# Scenario Error Code Error Message
1 If routing number is empty or invalid 400 Routing number is mandatory

2.3.1.16. updateCustomerId

The updateCustomerId endpoint is used to update the customer id of a request. The customer id can represent the Unique ID of a customer record used in the system that integrates with Chirp that retains a reference back to Chirp’s requestCode. For example, this can be a customer id or any other unique identifier in the system of record for connecting the Chirp request code with that customer.

Sample Request Payload

    {
        "customerId": “XXXXXXXXXX”
    }

Example success response:

Status code: 200

    {
        "success": true,
        "message": "Customer Id updated successfully",
    }

Understanding error messages for updateCustomerId

# Scenario Error Code Error Message
1 If the customerId field in the body is missing 400 Customer Id is mandatory. Please try again with a valid customer id.

2.3.1.17. debitCardEnrichment

The endpoint is used to get the debit card enrichment of a customer by filtering transactions with debit card enrichment. Debit Card Enrichment will be performed using the last 4 digits of the debit card provided via the API as well as reporting back the last 4 digits of any additional debit cards that are found.

The transactions associated with the debit card can also be retrieved along with the response by passing the “transaction” query parameter with the value set to true in the request. If omitted from the request the transaction query parameter default value is false.

The debit card enrichment details can also be obtained for each account. To get the account details pass the “byAccount” query parameter with the value set to true in the request. If omitted from the request the “byAccount” query parameter default value is false.

Here is an example url with the query parameter “transactions” added for retrieving transactions - https://chirp.digital/api/debitCardEnrichment/QLU0GU?debitCardNumber=1234&transaction=true

Here is an example url with the query parameters “transaction” and “byAccount” added for retrieving details by account - https://chirp.digital/api/debitCardEnrichment/QLU0GU?debitCardNumber=1234&transaction=true&byAccount=true

Example success response:

Status code: 200

    {
        "success": true,
        "requestCode": "QLU0GU",
          "result": [
        {
            "lastFourDebitCardNumber": "1234",
            "debitCardIndicatorMessage": "2 out of 1000 transaction matches",
            "cardMatches": true,
            "debitCardIndicatorStatus": "Low",
            "autoFlaggedDebit" : false,
	    "transactions": [
                {
                    "category": "Utilities",
                    "created_at": "2023-07-12T10:47:10Z",
                    "date": "2023-07-11",
                    "posted_at": "2023-07-12T12:00:00Z",
                    "status": "POSTED",
                    "top_level_category": "Bills & Utilities",
                    "transacted_at": "2023-07-11T12:00:00Z",
                    "type": "DEBIT",
                    "updated_at": "2023-07-12T10:47:10Z",
                    "account_guid": "ACT-114eddee-27c7-4661-96bb-c3d5343419ed",
                    "account_id": "act-223434333",
                    "amount": 58.92,
                    "category_guid": "CAT-56a2979d-d6df-25da-f357-06282f08208e",
                    "check_number_string": null,
                    "currency_code": "USD",
                    "description": "Questar Gas",
                    "guid": "TRN-e9d83fa5-549e-43d1-afbc-c6651c47c96a",
                    "id": "transfer-6a374f0f-488c-4258-82da-7c2c4ec5fe3f",
                    "is_bill_pay": false,
                    "is_direct_deposit": false,
                    "is_expense": true,
                    "is_fee": false,
                    "is_income": false,
                    "is_international": null,
                    "is_overdraft_fee": false,
                    "is_payroll_advance": false,
                    "is_recurring": null,
                    "is_subscription": false,
                    "latitude": null,
                    "localized_description": null,
                    "localized_memo": null,
                    "longitude": null,
                    "member_guid": "MBR-9ad03e4a-1e1b-420e-984a-7da2c8c8fb7c",
                    "member_is_managed_by_user": true,
                    "memo": null,
                    "merchant_category_code": null,
                    "merchant_guid": null,
                    "merchant_location_guid": null,
                    "original_description": "card 1234",
                    "user_guid": "USR-6b718e0b-b1f1-4819-96c3-dd2a340a9585",
                    "user_id": "6d896b50-20a1-11ee-a149-6fd473c3e4b4",
                    "categoryCode": "UTL",
                    "parentCategoryCode": "BNU",
                    "debitCardNumber": "1234"
                },
                {
                    "category": "Transfer",
                    "created_at": "2023-07-12T10:47:19Z",
                    "date": "2023-07-11",
                    "posted_at": "2023-07-12T12:00:00Z",
                    "status": "POSTED",
                    "top_level_category": "Transfer",
                    "transacted_at": "2023-07-11T12:00:00Z",
                    "type": "DEBIT",
                    "updated_at": "2023-07-12T10:47:19Z",
                    "account_guid": "ACT-164a6ebb-be76-415e-8adc-c27853ef2eb8",
                    "account_id": "act-6744344",
                    "amount": 13.03,
                    "category_guid": "CAT-bce48142-fea4-ff45-20d9-0a642d44de83",
                    "check_number_string": null,
                    "currency_code": "USD",
                    "description": "Transfer From Savings",
                    "guid": "TRN-4ba4626c-607a-4761-8e9a-24e6906085a7",
                    "id": "transfer-7c187810-8704-4288-91f3-d7b4f2f96d5c",
                    "is_bill_pay": false,
                    "is_direct_deposit": false,
                    "is_expense": true,
                    "is_fee": false,
                    "is_income": false,
                    "is_international": null,
                    "is_overdraft_fee": false,
                    "is_payroll_advance": false,
                    "is_recurring": null,
                    "is_subscription": false,
                    "latitude": null,
                    "localized_description": null,
                    "localized_memo": null,
                    "longitude": null,
                    "member_guid": "MBR-9ad03e4a-1e1b-420e-984a-7da2c8c8fb7c",
                    "member_is_managed_by_user": true,
                    "memo": null,
                    "merchant_category_code": null,
                    "merchant_guid": null,
                    "merchant_location_guid": null,
                    "original_description": "DEBIT XXXXXXXXXXXX1234 ",
                    "user_guid": "USR-6b718e0b-b1f1-4819-96c3-dd2a340a9585",
                    "user_id": "6d896b50-20a1-11ee-a149-6fd473c3e4b4",
                    "categoryCode": "UNC",
                    "parentCategoryCode": "TRF",
                    "debitCardNumber": "1234"
                }
            ]
        }
    ]
}

Example success response for each account:

    {
        "success": true,
        "requestCode": "QLU0GU",
        "result": [
            {
                "accountName": "Checking",
                "accountNumber": "12345",
                "debitCardEnrichmentDetails": [
                    {
                        "lastFourDebitCardNumber": "1234",
                        "debitCardIndicatorMessage": "9 out of 168 transaction matches",
                        "cardMatches": true,
                        "autoflaggeddebit": false,
                        "debitCardIndicatorStatus": "High"
                    },
                    {
                        "lastFourDebitCardNumber": "4567",
                        "autoflaggeddebit": true,
                        "debitCardIndicatorMessage": "20 out of 168 transaction matches"
                    },
                    {
                        "lastFourDebitCardNumber": "7890",
                        "autoflaggeddebit": true,
                        "debitCardIndicatorMessage": "28 out of 168 transaction matches"
                    }
                ]
            },
            {
                "accountName": "Credit Card",
                "accountNumber": "XXXX4545",
                "debitCardEnrichmentDetails": [
                    {
                        "lastFourDebitCardNumber": "1234",
                        "debitCardIndicatorMessage": "3 out of 168 transaction matches",
                        "cardMatches": true,
                        "autoflaggeddebit": false,
                        "debitCardIndicatorStatus": "Low"
                    },
                    {
                        "lastFourDebitCardNumber": "4567",
                        "autoflaggeddebit": true,
                        "debitCardIndicatorMessage": "11 out of 168 transaction matches"
                    },
                    {
                        "lastFourDebitCardNumber": "7890",
                        "autoflaggeddebit": true,
                        "debitCardIndicatorMessage": "13 out of 168 transaction matches"
                    }
                ]
            },
            {
                "accountName": "Property",
                "accountNumber": "543545",
                "debitCardEnrichmentDetails": [
                    {
                        "lastFourDebitCardNumber": "1234",
                        "debitCardIndicatorMessage": "0 out of 166 transaction matches",
                        "cardMatches": true,
                        "autoflaggeddebit": false,
                        "debitCardIndicatorStatus": "Zero"
                    }
                ]
            },
            {
                "accountName": "Mortgage",
                "accountNumber": "12987",
                "debitCardEnrichmentDetails": [
                    {
                        "lastFourDebitCardNumber": "1234",
                        "debitCardIndicatorMessage": "0 out of 166 transaction matches",
                        "cardMatches": true,
                        "autoflaggeddebit": false,
                        "debitCardIndicatorStatus": "Zero"
                    }
                ]
            },
            {
                "accountName": "Loan",
                "accountNumber": "177654",
                "debitCardEnrichmentDetails": [
                    {
                        "lastFourDebitCardNumber": "1234",
                        "debitCardIndicatorMessage": "0 out of 166 transaction matches",
                        "cardMatches": true,
                        "autoflaggeddebit": false,
                        "debitCardIndicatorStatus": "Zero"
                    }
                ]
            },
            {
                "accountName": "Investment",
                "accountNumber": "57123",
                "debitCardEnrichmentDetails": [
                    {
                        "lastFourDebitCardNumber": "1234",
                        "debitCardIndicatorMessage": "0 out of 0 transaction matches",
                        "cardMatches": true,
                        "autoflaggeddebit": false,
                        "debitCardIndicatorStatus": "Zero"
                    }
                ]
            },
            {
                "accountName": "Savings",
                "accountNumber": "11119876",
                "debitCardEnrichmentDetails": [
                    {
                        "lastFourDebitCardNumber": "1234",
                        "debitCardIndicatorMessage": "0 out of 166 transaction matches",
                        "cardMatches": true,
                        "autoflaggeddebit": false,
                        "debitCardIndicatorStatus": "Zero"
                    }
                ]
            }
        ]
    }

Response Field Definitions for debitCardEnrichment,

# Field Data Type Description
1 success Boolean Response status of the request
2 requestCode String Request code for a request
3 debitCardIndicatorStatus String Denotes the enrichment of debit card being connected
4 debitCardIndicatorMessage String A detailed message with match count and enrichment indicator definition
5 lastFourDebitCardNumber String Last four digits of the customer's debit card
6 transactions Array Debit Card Number related transactions
7 autoFlaggedDebit Boolean Auto flagged card and associated transactions by the system
8 cardMatches Boolean If the provided last 4 digits of debit card number matches with the flagged transactions

Understanding error messages for debitCardEnrichment

# Scenario Error Code Error Message
1 If invalid debit card number is passed 400 Please provide a valid debit card number and try again
2 If the entity does not have the feature of debit card enrichment 400 This Debit Card Enrichment Feature is no enabled for this entity/profile
3 If requesting details for an expired request 406 Request status is expired. Please try again with a verified request code
4 If requesting details for a rejected request 406 Request status is rejected. Please try again with a verified request code
5 If requesting details from a request code that has not been verified 406 Request status is unverified. Please verify the request and try again

2.3.1.18. updateProductId

The updateProductId endpoint is used to update the productId of a request. The productId can represent a Unique ID in the system integrated with Chirp that retains a reference back to Chirp’s requestCode. For example, this can be a loan id, application id or any other unique identifier in the system of record for connecting the Chirp requestCode with that product.

Sample Request Payload

    {
        "productId": “XXXXXX”
    }

Example success response:

Status code: 200

    {
        "success": true,
        "message": "Product Id updated successfully",
    }

Understanding error messages for updateProductId

# Scenario Error Code Error Message
1 If the productId field in the body is missing 400 Product Id is mandatory. Please try again with a product id.
2 If the requestCode does not exist 400 The request code is not found. Please try again with a valid request code.

2.3.1.19. enableScoringForRequest

The endpoint is used to enable scoring for ON_DEMAND type requests. The url also takes a query param as active to enable or disable the scoring feature for the request. The active query param defaults to true if not passed.

Example success response:

Status code: 200

    {
        "success": true,
        "message": "Scoring is enabled for this request successfully",
    }

Response Field Definitions for enableScoringForRequest,

# Field Data Type Description
1 success Boolean Response status of the request
2 message String Success message

Understanding error messages for enableScoringForRequest

# Scenario Error Code Error Message
1 If the integration settings is not enabled for the entity 400 Scoring is not configured for this entity

2.3.1.20. getScoringForRequest

The getScoringForRequest endpoint is used to retrieve scoring information for a verified request. Additional scoring information can be retrieved as part of the response when the query param extensiveInfo is set to true in the request. The default value for extensiveInfo is false and if extensiveInfo is omitted from the request it will be treated as false. The score data and information is provided by Lokyata.

Here is an example request to get the extensive information from Lokyata BankAnalyze as part of the response - https://chirp.digital/api/getScoringForRequest/QLU0GU?extensiveInfo=true

Example success response for standard request:

Status code: 200

    {
        "success": true,
        "scoringInfo": {
            "score": "0",
            "requestCode": "QLU0GU",
            "reportStatus": "Review",
            "denialReason": [
                {
                    "denial_reason_code": "eligibility",
                    "message": "inadequate and/or irregular income",
                    "type": "INVALID_SCORE"
                }
            ],
            "decision": "Deny"
        }
    }

Example success response for request with extensiveInfo query param passed:

Status code: 200

    {
        "success": true,
        "scoringInfo": {
            "score": "0",
            "requestCode": "QLU0GU",
            "reportStatus": "Review",
            "denialReason": [
                {
                    "denial_reason_code": "eligibility",
                    "message": "inadequate and/or irregular income",
                    "type": "INVALID_SCORE"
                }
            ],
            "decision": "Deny",
            "loan_disbursement_count_total" : 4, 
            "loan_disbursement_amount_total" : 4942.41, 
            "loan_payments_amount_total" : null, 
            "loan_disbursement_amount_15d" : null, 
            "loan_disbursement_count_15d" : 1, 
            "loan_payments_amount_15d" : null, 
            "loan_disbursement_amount_30d" : null, 
            "loan_disbursement_count_30d" : 1, 
            "loan_payments_amount_30d" : null, 
            "income_stability" : 56, 
            "average_monthly_income" : 8563.86666666667, 
            "last_3_paychecks_average_income" : null, 
            "last_pay_date" : null, 
            "last_pay_date_match" : null, 
            "future_pay_date_1" : null, 
            "future_pay_date_2" : null, 
            "balance_payday_1d" : 815.430676691729, 
            "balance_payday_3d" : 409.893063063063, 
            "balance_payday_5d" : 985.317727272727, 
            "minimum_balance" : -262.89, 
            "borrower_name_match" : true, 
            "employer_name_match" : false, 
            "bank_name_match" : null, 
            "net_income_match" : false, 
            "account_number_match" : true, 
            "routing_number_match" : false,

        }
    }

Response Field Definitions for getScoringForRequest,

# Field Data Type Description
1 success Boolean Response status of the request
2 requestCode String Request code for a request
3 score String Denotes the score of the request code
4 reportStatus String Report status of the request code
5 denialReason Array Denial reason of the request code
6 decision String Scoring decision of the request code
7 loan_disbursement_count_total Decimal The total count of loan disbursements in the bank statement
8 loan_disbursement_amount_total Decimal The total amount of loan disbursements in the bank statement
9 loan_payments_amount_total Decimal Total loan repayment amount in the bank statement
10 loan_disbursement_amount_15d Decimal Total loan disbursement amount in the last 15 days from the time bank statement was created
11 loan_payments_amount_15d Decimal Total loan repayment amount in the last 15 days from the time bank statement was created
12 loan_disbursement_amount_30d Decimal Total loan disbursement amount in the last 30 days from the time bank statement was created
13 loan_disbursement_count_30d Decimal The total count of loan disbursements in the last 30 days
14 loan_payments_amount_30d Decimal Total loan repayment amount in the last 30 days from the time bank statement was created
15 income_stability Decimal An estimate of the average monthly income
16 last_3_paychecks_average_income Decimal Average of the transaction amount for last three paychecks
17 last_pay_date String The last date of paycheck and is entered by lead
18 last_pay_date_match Boolean Compare the last pay date entered in lead application and the last pay date we were able to find in bank statement
19 future_pay_date_1 String The 1st next pay date based on past pay dates in the bank statement. Depending on the pay frequency, it will be either day of the week or complete date
20 future_pay_date_2 String The 2nd next pay date based on past pay dates in bank statement, depending on the pay frequency, it will be either day of the week or complete date
21 balance_payday_1d Decimal An estimate of the account balance one day before the next payday
22 balance_payday_3d Decimal An estimate of the account balance three days before the next payday
23 balance_payday_5d Decimal An estimate of the account balance five days before the next payday
24 minimum_balance Decimal The minimum balance of the account
25 borrower_name_match Boolean Denotes the provided borrower name matches the name associated with application
26 employer_name_match Boolean Denotes the provided employer name matches the name associated with application
27 bank_name_match Boolean Compare the bank entered in lead application and bank selected
28 net_income_match Boolean Compare the income entered in lead application and income returned
29 account_number_match Boolean Compare the account number entered in lead application and account number selected
30 routing_number_match Boolean Compare the routing number entered in lead application and routing number selected
31 loan_disbursement_count_15d Decimal The total count of loan disbursements in the last 15 days
32 average_monthly_income Decimal An estimate of the average monthly incom

Understanding error messages for getScoringForRequest

# Scenario Error Code Error Message
1 If the integration settings is not enabled for the entity 400 Scoring is not configured for this entity
2 If the scoring is not found for the request 404 Scoring info not found for this request

2.3.1.21. updateRequestInfo

The updateRequestInfo endpoint is used to update the customer id, product id, lead id or lead provider of a request. While the customer Id, product Id, lead Id, and lead provider fields are all optional in the request body, it is imperative that at least one of these fields is provided for the update to take place.

Sample Request Payload

    {
        "customerId": “XXXXXXXXXX”,
        "productId": “YYYYYYYYY”,
        "leadId": “ZZZZZZZZZZZZ”,
        "leadProvider": “VVVVVVVV”,
    }

Example success response:

Status code: 200

    {
        "success": true,
        "message": "Product Id, Customer Id, Lead Id and Lead Provider updated successfully",
    }

Understanding error messages for updateRequestInfo

# Scenario Error Code Error Message
1 If the productId, customerId, leadId or leadProvider field in the body is empty or null 400 Please try again with a valid <field_name>.

2.3.1.22. getBalanceInfo

The getBalanceInfo endpoint can be used to retrieve the account balance for a customer's account. This is an enhanced endpoint that supports OAuth bank requests and requires activation by Chirp. Please contact Chirp for more information.

Example success response:

Status code: 200

    {
        "success": true,
        "requestCode": "QLU0GU",
        "accounts": [
            {
                "account_number": "1234",
                "available_balance": 0,
                "balance": 0,
                "name": "Chirp Checking",
                "routing_number": null,
                "subtype": null,
                "type": "CHECKING",
                "account_ownership": null,
                "updated_at": "2023-11-29T10:47:50Z"
            }
        ],
        "status" : "AVAILABLE"
    }

Response Field Definitions for getBalanceInfo,

# Field Data Type Description
1 success Boolean Response status of the request
2 requestCode String Request code for a request
3 accounts Array List of user accounts, including balance details and other account-related information.
4 status String Status details of the accounts - ”AVAILABLE” - The requested data is successfully retrieved and included in the response payload, “NOT_RETURNED” - The request was successfully sent to the financial institution, but no data was returned in response., “NOT_ATTEMPTED” - No attempt was made to fetch premium data for the request.

Description for fields under accounts information,

# Field Data Type Description
1 account_number String The account number of the customer
2 available_balance Decimal The balance currently available in an account. Max length is 14,2.
3 balance Decimal An account's current balance. Max length is 14,2.
4 routing_number String The routing number for the account
5 type String The main type of an account, e.g., INVESTMENT, PREPAID, or SAVINGS.
6 subtype String The account's subtype, e.g., PLAN_401_K, MONEY_MARKET, or HOME_EQUITY
7 account_ownership String The type of ownership associated with the account such as UNKNOWN, INDIVIDUAL, JOINT, MULTIPLE, NULL.
8 updated_at String The date and time at which the account was last updated.
9 name String The human-readable name for the account

Understanding error messages for getBalanceInfo

# Scenario Error Code Error Message
1 If Balance Check Feature is not enabled for the entity or if the OAuth bank request is passed. 400 The Balance Check Feature is not enabled for this entity
2 If the request code is unsubscribed/disconnected. 405 Your request is unsubscribed/disconnected. Please try again with a different request code. Contact Chirp Support for more assistance, support@chirp.digital
3 If the request is not verified 406 Request status is <status>. Please verify the request and try again

2.3.1.23. getAccountInfo

The getAccountInfo endpoint can be used to retrieve account and routing numbers for a customer's account. This is an enhanced endpoint and requires activation by Chirp. Please contact Chirp for more information.

Example success response:

Status code: 200

        {
            "success": true,
            "requestCode": "QLU0GU",
            "accountNumber" : [
                {
                    "account_number": "135318520965",
                    "routing_number": "310171902",
                    "transit_number": null,
                    "institution_number": null,
                    "passed_validation": true,
                    "masked_account_number": "20965",
                    "chirpAccountId": "ACC-2171ee40-1290-11ef-b135-150631c74239",
                    "bankName": "Chirp Test Bank",
                    "accountType" : "CHECKING"
                }
            ],
            "status" : "AVAILABLE"
        }

Response Field Definitions for getAccountInfo,

# Field Data Type Description
1 success Boolean Response status of the request
2 requestCode String Request code for a request
3 accountNumber Array List of user accounts, including account number, routing number and other account-related information.
4 status String Status details of the accounts - ”AVAILABLE” - The requested data is successfully retrieved and included in the response payload, “NOT_RETURNED” - The request was successfully sent to the financial institution, but no data was returned in response., “NOT_ATTEMPTED” - No attempt was made to fetch premium data for the request., “NOT_SUPPORTED” - The financial institution does not support the requested feature, so the data cannot be retrieved.

Description for fields under accountNumber information,

# Field Data Type Description
1 account_number String The account number of the customer
2 routing_number String The routing number for the account
3 transit_number Boolean A unique number that represents the bank branch where you opened your account
4 institution_number Boolean A three-digit number that refers to a specific bank
5 passed_validation String Returns status of the validation passed or not
6 masked_account_number String The account number of the customer. This will typically be a masked or partial account number
7 chirpAccountId String The account's unique identifier, as defined by Chirp
8 bankName String Customer’s selected bank
9 accountType String Customer’s bank account type

Understanding error messages for getAccountInfo

# Scenario Error Code Error Message
1 If Account Verification Feature is not enabled for the entity. 400 The Account Verification Feature is not enabled for this entity
2 If the request code is unsubscribed/disconnected. 405 Your request is unsubscribed/disconnected. Please try again with a different request code. Contact Chirp Support for more assistance, support@chirp.digital
3 If the request is not verified 406 Request status is <status>. Please verify the request and try again
4 If the request does not support the premium account information feature 400 The account verification feature is not available for this request
5 If the financial institution does not support the premium account information feature 400 This financial institution does not support the premium account information feature. Please contact Chirp for more information

2.3.1.24. getAccountOwnerInfo

The getAccountOwner endpoint can be used to retrieve account owner data for a customer's account. This is an enhanced endpoint and requires activation by Chirp. Please contact Chirp for more information.

Example success response:

Status code: 200

            {
                "success": true,
                "requestCode": "QLU0GU",
                "accountOwnerInfo": [
                    {
                        "owner_name": "John Doe",
                        "address": "12345 South Rd",
                        "city": "Morning View",
                        "state": "KY",
                        "postal_code": "41063",
                        "country": “US”,
                        "email": "johnDoe@gmail.com",
                        "phone": "111-111-1111",
                        "first_name": “John”,
                        "last_name": “Doe”
                    }
                ],
                "status" : "AVAILABLE"
            }

Response Field Definitions for getAccountOwnerInfo,

# Field Data Type Description
1 success Boolean Response status of the request
2 requestCode String Request code for a request
3 accountOwnerInfo Array List of user accounts, including account owner-related information.
4 status String Status details of the accounts - ”AVAILABLE” - The requested data is successfully retrieved and included in the response payload, “NOT_RETURNED” - The request was successfully sent to the financial institution, but no data was returned in response., “NOT_ATTEMPTED” - No attempt was made to fetch premium data for the request., “NOT_SUPPORTED” - The financial institution does not support the requested feature, so the data cannot be retrieved.

Description for fields under accountOwnerInfo information,

# Field Data Type Description
1 owner_name String Full name of the account owner (first and last names)
2 address String Street address of the account owner
3 city String City where the account owner resides
4 state String State or province of the account owner's location
5 postal_code String Postal or ZIP code for the account owner's address
6 country String Country where the account owner is located
7 email String Email address for communication with the account owner
8 phone String Phone number of the account owner
9 first_name String First name of the account owner
10 last_name String Last name of the account owner

Understanding error messages for getAccountOwnerInfo

# Scenario Error Code Error Message
1 If Account Owner Feature is not enabled for this entity. 400 The Account Owner Feature is not enabled for this entity
2 If the request code is unsubscribed/disconnected. 405 Your request is unsubscribed/disconnected. Please try again with a different request code. Contact Chirp Support for more assistance, support@chirp.digital
3 If the request is not verified 406 Request status is <status>. Please verify the request and try again
4 If the request does not support the premium account owner information feature 400 The account owner feature is not available for this request
5 If the financial institution does not support the premium account owner information feature 400 This financial institution does not support the premium account owner information feature. Please contact Chirp for more information

2.3.1.25. exportRequestDataAsCSV

The exportRequestDataAsCSV endpoint is used to facilitate the generation and delivery of CSV file containing request status information for the last 60 days. Upon completion, a link will be generated and sent through the configured notification channel (new notification hyperlinked will be added here), to download the exported data. The download link automatically expires after 1 hour after the notification has been sent.

Here is an example url generated - https://chirp.digital/api/getExportRequestDataApi/test_1203849125725.csv

If query param “exportByProfile” is set to true, the endpoint will generate a CSV file containing detailed request data specific to the profile for the last 60 days.

Here is an example url with the query parameter “exportByProfile” added for retrieving profile associated request data - https://chirp.digital/api/exportRequestDataAsCSV?exportByProfile=true

If query param “exportByProfile” is set to false or omitted, the CSV file will contain all request data for the entire entity for the past 60 days.

Example success response:

Status code: 200

            {
                "success": true,
                "message": "The request to export the last 60 days of request status data has been initiated. A download link will be sent to the configured EXPORT_DATA notification channel once the file is ready."
            }

Understanding error messages for exportRequestDataAsCSV

# Scenario Error Code Error Message
1 If entity notification is not configured for this entity 404 Notification channel not configured for this entity <entity>
2 If notification is not configured for this profile 404 Notification channel not configured for this profile <profileName>
3 If the download link is expired 404 The download link is expired. Please generate a new request.

2.3.1.26. getXactdatePredictedFundsData

The endpoint is used to get the predicted dates that funds will be available for a verified request. This feature is powered by Xactdate.

Example success response:

Status code: 200

    {
        "success": true,
        "xactdatePredictedFundsData": {
            "requestCode": "QLU0GU",
            "bestDates": [
                "2023-12-18",
                "2023-11-29"
            ],
            "frequency": "TWICE A MONTH",
            "startDate": "2024-01-18",
            "schedulePlan": [
                "2024-01-18",
                "2024-01-29",
                "2024-02-16",
                "2024-02-29",
                "2024-03-18"
            ],
            "accountId": "XXXXXXXXXXXX",
            "lastPayDate": "2024-01-18",
            "daysSinceLastPayroll": 4,
            "payrollAverageIncome": 555.6,
            "employmentStatus": "Yes",
            "usedTransactions": [
                {
                    "date": "2023-10-31",
                    "transactedAt": "2023-10-31",
                    "description": "Dividend (GT18)DIVIDEND",
                    "category": "Dividend & Cap Gains",
                    "status": "POSTED",
                    "amount": 0.02
                },
                {
                    "date": "2023-11-30",
                    "transactedAt": "2023-11-30",
                    "description": "Dividend (GT18)DIVIDEND",
                    "category": "Dividend & Cap Gains",
                    "status": "POSTED",
                    "amount": 0.02
                },
                {
                    "date": "2023-12-31",
                    "transactedAt": "2023-12-31",
                    "description": "Dividend (GT18)DIVIDEND",
                    "category": "Dividend & Cap Gains",
                    "status": "POSTED",
                    "amount": 0.01
                },
                {
                    "date": "2024-01-31",
                    "transactedAt": "2024-01-31",
                    "description": "Dividend (GT18)DIVIDEND",
                    "category": "Dividend & Cap Gains",
                    "status": "POSTED",
                    "amount": 0.01
                }
            ],
            "employmentStatusDetail": { 
                "error": "No payroll transactions in the last 30 days." 
            }, 
            "incomeByMonth": { 
                "2023": {
                    "October": 0.02,
                    "November": 0.02,
                    "December": 0.01
                },
                "2024": {
                    "January": 0.01
                }
            } 
        }
    }

Response Field Definitions for getXactdatePredictedFundsData,

# Field Data Type Description
1 success Boolean Response status of the request
2 requestCode String Request code for a request
3 bestDates Array of strings Denoted best dates when the customer has funds based on the frequency
4 frequency String Denotes when the customer has funds. Eg - Monthly, Bi-Weekly, Weekly or Twice a month.
5 startDate String Possible first future fund availability date
6 SchedulePlans Array of strings Possible future fund availability dates
7 accountId String The identifier for the account associated
8 lastPayDate String The most recent payroll transaction date
9 daysSinceLastPayroll Integer Number of days since the last payroll transaction until now
10 payrollAverageIncome Integer Average income amount from all of used transactions
11 employmentStatus String Represents predicted current employment status
12 usedTransactions Array List of the transactions which were used to compute frequency.
13 employmentStatusDetail Object Extra data about employment status.
14 incomeByMonth Object Income aggregated per month and year, available months will depend on the date range of used transactions.

Understanding error messages for getXactdatePredictedFundsData

# Scenario Error Code Error Message
1 If the integration settings is not enabled for the entity 404 Xactdate is not configured for this entity
2 If no data is available 404 Xactdate data is not available please try again later

2.3.1.27. enableXactdatePredictedFundsData

The endpoint is used to enable fund availability prediction for ON_DEMAND type requests. The url also takes a query param as active to enable or disable the payment plan feature for the request. The active query param defaults to true if not passed. The fund availability prediction feature is powered by Xactdate

Payload Field Definition for enableXactdatePredictedFundsData,

# Field Data Type Description
1 frequency* Array of strings Preference for calculating payment dates. Choices: E (Monthly), B (Bi-Weekly), W (Weekly) and F(Twice a month).
2 paymentDates* Integer Number of future payment days returned based on the frequency detected
3 maximumDissimilarity* Integer Maximum number of days of tolerance a transaction can drift from a periodic frequency

Sample Request Payload

        {
            "frequency" : ["E", "B", "W", "F"],
            "paymentDates" : 8,
            "maximumDissimilarity" : 3    
        }

Example success response:

Status code: 200

    {
        "success": true,
        "message": "Xactdate prediction has been successfully disabled for this request"
    }

Response Field Definitions for enableXactdatePredictedFundsData,

# Field Name Description
1 success Response result of the request
2 message Success message

Understanding error messages for enableXactdatePredictedFundsData

# Scenario Error Code Error Message
1 If the integration settings is not enabled for the entity 404 Xactdate is not configured for this entity
2 If the frequency field in the body is invalid 400 Please check the frequency and try again
3 If the paymentDates field in the body is invalid 400 Please check the payment dates and try again
4 If the maximumDissimilarity field in the body is invalid 400 Please check the maximun dissimilarity and try again

The genAuthTokenForChirpLink endpoint should be used for generating a new one-time token associated with a request code for supplying and loading the ChirpLink™ widget.

Example success response:

Status code: 200

    {
        "success": true,
        "token": "y5yh45h4w5h45h4j4w6j4wj4htrhw6u65h6j56h5y",
        "requestCode": "QLU0GU",
        "validUpto": "8/10/2021, 10:33 PM"
    }

Response Field Definitions for genAuthTokenForChirpLink,

# Field Name Data Type Description
1 success Boolean Response result of the request
2 token String Token generated for initiating a customer verification in entity’s integration
3 requestCode String The request code for which the token is valid
4 validUpto String The expiration time until the generated token is valid. Timezone is CST

2.3.1.29. requestXtraHistory

The requestXtraHistory endpoint is used to request Xtra History for verified requests. The request will attempt to update an already verified requests with up to 24 months of transaction history. Not all financial institutions will support this request. This is an enhanced endpoint that supports OAuth bank requests and requires activation by Chirp. Please contact Chirp for more information.

Example success response:

Status code: 200

    {
        "success": true,
        "message":  "Xtra History™ has been successfully requested for this request"
    }

Response Field Definitions for requestXtraHistory,

# Field Name Data Type Description
1 success Boolean Response status of the request
2 message String Success message
3 status String Status details of the transactions - “NOT_ATTEMPTED” - No attempt was made to fetch premium data for the request., “NOT_SUPPORTED” - The financial institution does not support the requested feature, so the data cannot be retrieved.

Understanding error messages for requestXtraHistory

# Scenario Error Code Error Message
1 If Xtra History is not enabled for the entity 400 Xtra History is not enabled for this entity. Please contact Chirp for more information.
2 If the financial institution does not support Xtra History 400 The financial institution does not support Xtra History. Please contact Chirp for more information.
3 If a rejected request is passed 406 Request status is rejected. The request must be verified. Please contact Chirp for more information.
4 If a expired request is passed 406 Request status is expired. The request must be verified. Please contact Chirp for more information.
5 If a unverfied request is passed 406 Request status is unverfied. The request must be verified. Please contact Chirp for more information.
6 If a attempted request is passed 406 Request status is attempted. The request must be verified. Please contact Chirp for more information.
7 If an already enabled Xtra History request is passed 405 Xtra History Feature is already enabled for this request code
8 If the request code is unsubscribed/disconnected. 405 Your request is unsubscribed/disconnected. Please try again with a different request code. Contact Chirp Support for more assistance, support@chirp.digital
9 If the request does not support the Xtra History feature 405 The Xtra History™ feature is not available for this request
10 If the OAuth bank request is passed 400 The Xtra History™ feature is not available for this request

2.3.1.30. getCustomRequestDetails

This endpoint provides a custom response per the configured response template in the Chirp Portal. This endpoint accepts four parameters:

Click here to review the Portal Documentation for adding and maintaining templates.

Note: This endpoint returns running balance for transactions only if an account number is passed as part of request. Otherwise, this response will not have the running balance.

Example default response:

Status code: 200

    {
        requestCode: "QLU0GU",
        success: true,
        addedOn: "2024-04-10T04:58:30.040Z",
        modifiedOn: "2024-04-10T07:22:08.585Z",
        lastAggregatedAt: "2024-04-10T07:22:08.585Z",
        connectionStatus: "Subscribed",
        institutionName: "Chirp Test Bank",
        accountInfoStatus: "AVAILABLE",
        accountOwnerInfoStatus: "NOT_SUPPORTED",
         "customerInfo": {
            "firstName": "John",
            "lastName": "Doe",
            "email": "chirpdemo@chirp.digital",
            "phoneNumber": "+11111111111",
            "customerEnteredAccountNumber": "123456",
            "customerEnteredRoutingNumber": "0987654"
          },
          accounts: [
          {
            _id: "66163e1c311ed718904b6ed0",
            account_number: "708191771",
            apr: null,
            apy: null,
            available_balance: 1000,
            available_credit: null,
            balance: 1000,
            cash_balance: null,
            cash_surrender_value: null,
            credit_limit: null,
            currency_code: null,
            day_payment_is_due: null,
            death_benefit: null,
            holdings_value: null,
            interest_rate: null,
            institution_code: "chirpbank",
            insured_name: null,
            is_closed: false,
            last_payment: null,
            loan_amount: null,
            matures_on: null,
            minimum_balance: null,
            minimum_payment: null,
            name: "Checking",
            original_balance: null,
            pay_out_amount: null,
            payoff_balance: null,
            premium_amount: null,
            routing_number: "889223786",
            started_on: null,
            total_account_value: null,
            subtype: null,
            type: "CHECKING",
            created_at: "2023-06-30T12:14:11Z",
            last_payment_at: null,
            payment_due_at: null,
            updated_at: "2023-09-21T01:12:26Z",
            account_id: "act-223434333",
            requestCode: " QLU0GU",
            entityId: "5ff1e1d0d4234b02da76ebfb",
            profileId: "5ff1e1d0d4234b02da76ebfc",
            chirpAccountId: "ACC-2171ee40-1290-11ef-b135-150631c74239",
            addedOn: "2024-04-10T07:22:04.856Z",
            modifiedOn: "2024-04-10T07:22:04.856Z",
            __v: 0,
            customerAccountMatchStatus: "No Match",
            customerRoutingNumberMatchStatus: "No Match"
          },
        ],
      
        transactions: [
          {
            category: "Personal Care",
            created_at: "2024-04-10T07:22:04.761Z",
            date: "2024-04-10",
            posted_at: "2024-04-10T07:22:04.760Z",
            status: "POSTED",
            top_level_category: "Personal Care",
            transacted_at: "2024-04-10T07:22:04.760Z",
            type: "DEBIT",
            updated_at: "2024-04-10T07:22:04.761Z",
            account_id: "act-223434333",
            amount: 11.08,
            check_number_string: null,
            currency_code: "USD",
            description: "Bath & Body Works",
            id: "transfer-c44348d1-a79b-476b-8da5-abd175ea805e",
            is_bill_pay: false,
            is_direct_deposit: false,
            is_expense: true,
            is_fee: false,
            is_income: false,
            is_international: null,
            is_overdraft_fee: false,
            is_payroll_advance: false,
            is_recurring: null,
            is_subscription: false,
            latitude: null,
            localized_description: null,
            localized_memo: null,
            longitude: null,
            member_is_managed_by_user: true,
            memo: null,
            merchant_category_code: null,
            original_description: "Bath and Body Works",
            categoryCode: "PRC",
            parentCategoryCode: "PRC",
            running_balance: 1000,
            chirpAccountId: "ACC-2171ee40-1290-11ef-b135-150631c74239",
            chirpTransactionId: "TRN-21721550-1290-11ef-b135-150631c74239"
          },
        ],
      
        transactionAnalysisSummaries: [
          {
            category: "PRC",
            total: 6,
            amount: "$266.01",
            recentTransactionAmount: "$11.08",
            recentTransactionCount: 1,
            categoryName: "Personal Care",
            transaction: [
              {
                category: "Personal Care",
                created_at: "2024-04-10T07:22:04.761Z",
                date: "2024-04-10",
                posted_at: "2024-04-10T07:22:04.760Z",
                status: "POSTED",
                top_level_category: "Personal Care",
                transacted_at: "2024-04-10T07:22:04.760Z",
                type: "DEBIT",
                updated_at: "2024-04-10T07:22:04.761Z",
                account_id: "act-223434333",
                amount: 11.08,
                check_number_string: null,
                currency_code: "USD",
                description: "Bath & Body Works",
                id: "transfer-c44348d1-a79b-476b-8da5-abd175ea805e",
                is_bill_pay: false,
                is_direct_deposit: false,
                is_expense: true,
                is_fee: false,
                is_income: false,
                is_international: null,
                is_overdraft_fee: false,
                is_payroll_advance: false,
                is_recurring: null,
                is_subscription: false,
                latitude: null,
                localized_description: null,
                localized_memo: null,
                longitude: null,
                member_is_managed_by_user: true,
                memo: null,
                merchant_category_code: null,
                original_description: "Bath and Body Works",
                categoryCode: "PRC",
                parentCategoryCode: "PRC",
                running_balance: 1000,
                chirpAccountId: "ACC-2171ee40-1290-11ef-b135-150631c74239",
                chirpTransactionId: "TRN-21721550-1290-11ef-b135-150631c74239"
              },
            ],
          },
        ],
        accountExpenses: [
          {
            amount: "$266.01",
            category: "Personal Care",
            percent: "1.59",
          },
        ],
      
        totalTransactions: [
          {
            accountNumer: "708191771",
            totalTransactions: 168,
            numberOfDays: 460,
          },
        ],
      
        debitCardEnrichment: [
          {
              lastFourDebitCardNumber: "1234",
              autoflaggeddebit: true,
              debitCardIndicatorMessage: "12 out of 1000 transaction matches",
              cardMateches: true,
              debitCardIndicatorStatus: "High"
            },
        ],
        accountInfo: [
                {
                    "account_number": "135318520965",
                    "routing_number": "310171902",
                    "transit_number": null,
                    "institution_number": null,
                    "passed_validation": true,
                    "masked_account_number": "20965",
                    "chirpAccountId": "ACC-2171ee40-1290-11ef-b135-150631c74239",
                    "bankName": "Chirp Test Bank"
                }
            ],
        accountOwnerInfo: [
                    {
                        "owner_name": "John Doe",
                        "address": "12345 South Rd",
                        "city": "Morning View",
                        "state": "KY",
                        "postal_code": "41063",
                        "country": “US”,
                        "email": "johnDoe@gmail.com",
                        "phone": "111-111-1111",
                        "first_name": “John”,
                        "last_name": “Doe”
                    }
                ]

      };

Below is the table explaining the response returned from getCustomRequestDetails,

# Field Name Data Type Description
1 requestCode String Request code of the respective request
2 success Boolean Response result of the request
3 addedOn String Timestamp of request created
4 modifiedOn String Timestamp of request modified
5 lastAggregatedAt Boolean Timestamp when the customer data has been updated
6 verifiedOn Boolean Timestamp when request is verified
7 planType String Plan type of the request code - SUBSCRIPTION/PAYG/FLEX
8 subtype String Subtype of the request code - SUBSCRIPTION/PAYG
9 connectionStatus String Connection status of the request. This field returns Subscribed/Unsubscribed or Connected/Disconnected or NA as a value based on the plan type
10 institutionName String The institution name for the account(s) associated
11 customerInfo Object Customer Details
12 accounts Array All the accounts that are linked with the verified bank account
13 transactions Array Transaction data of the verified account
14 transactionAnalysisSummaries Array Transaction data grouped with transaction type categories
15 accountExpenses Array Expense breakdown based on transaction data
16 totalTransactions Array Transaction count and number of days for each account
17 debitCardEnrichment Array Debit card enrichment match details
18 accountInfoStatus String Status details of the accounts - ”AVAILABLE” - The requested data is successfully retrieved, “NOT_RETURNED” - The request was successfully sent to the financial institution, but no data was returned in response., “NOT_ATTEMPTED” - No attempt was made to fetch premium data for the request., “NOT_SUPPORTED” - The financial institution does not support the requested feature, so the data cannot be retrieved, “NA” - Account Info Feature is not enabled.
19 accountOwnerInfoStatus String Status details of the account owner - ”AVAILABLE” - The requested data is successfully retrieved, “NOT_RETURNED” - The request was successfully sent to the financial institution, but no data was returned in response., “NOT_ATTEMPTED” - No attempt was made to fetch premium data for the request., “NOT_SUPPORTED” - The financial institution does not support the requested feature, so the data cannot be retrieved, “NA” - Account Owner Feature is not enabled.
20 accountInfo Array List of user accounts, including account number, routing number and other account-related information
21 accountOwnerInfo Array List of user accounts, including account owner-related information

Description for fields under consumerInfo information,

# Field Data Type Description
1 firstName String First name of the consumer
2 lastName String Last name of the consumer
3 email String Email address of the consumer
4 phoneNumber String Phone number of the consumer
5 customerEnteredAccountNumber String Customer’s account number entered into Chirp as part of creating the request. Could have been entered in the Portal or sent via API by the integration partner
6 customerEnteredRoutingNumber String Customer’s routing number entered into Chirp as part of creating the request. Could have been entered in the Portal or sent via API by the integration partner

Description for fields under accounts information,

# Field Data Type Description
1 account_number string The account number. This will typically be a masked or partial account number.
2 apr Decimal Annual Percentage Rate. Max length is 10,6.
3 apy Decimal Annual Percentage Yield. Max length is 10,6.
4 available_balance Decimal The balance currently available in an account. Max length is 14,2.
5 available_credit Decimal The currently available credit balance of an account. This field is for accounts with types CREDIT CARD and LINE OF CREDIT.
6 balance Decimal An account's current balance. Max length is 14,2.
7 cash_balance Decimal The cash balance of the account. Max length is 14,2.
8 created_at String The date and time the account was created.
9 credit_limit Decimal The credit limit for the account. Max length is 10,2.
10 currency_code String The three-character ISO 4217 currency code, e.g. USD.
11 holdings_value Decimal The value of the holdings associated with the account.
12 institution_code String Unique identifier for the financial institution which holds the account.
13 interest_rate Decimal Interest rate. Max length is 10,6.
14 is_closed Boolean If an account is closed, this field will be true. Otherwise, this field will be false.
15 type String The main type of an account, e.g., INVESTMENT, PREPAID, or SAVINGS.
16 updated_at String The date and time at which the account was last updated.
17 routing_number String The routing number for the account.
18 insured_name String The date and time the account was created
19 cash_surrender_value Decimal Money paid to the policy holder or annuity holder in the event the policy is voluntarily terminated before it matures, or the insured event occurs
20 day_payment_is_due String The day of the month the payment is due. e.g 14
21 death_benefit Integer The amount paid to the beneficiary of the account upon death of the account owner
22 last_payment Decimal The amount of the recent payment on the account
23 loan_amount Decimal The amount of the loan associated with the account
24 matures_on String The date on which the account matures
25 minimum_balance Decimal The minimum balance of the account
26 minimum_payment Decimal The minimum payment required for an account. This can apply to any debt account
27 name String The human-readable name for the account
28 original_balance Decimal The original balance of the account. This will always be positive
29 pay_out_amount String The amount paid out to the insured person or beneficiary under the conditions of the insurance policy
30 payoff_balance Decimal The payoff balance for a debt account. This will normally be a positive number
31 premium_amount Decimal The insurance policy's premium amount
32 started_on String The date on which a debt account was started
33 total_account_value Decimal The total combining both long and short positions, the sweep account and/or cash balance, and any margin debt linked to a specific account. This figure encompasses the aggregate market value of all positions within the account, offset by any debit balance and the value of short options positions that are profitable. This cumulative value can be negative and should not be misconstrued as an account balance
34 subtype String The account's subtype, e.g., PLAN_401_K, MONEY_MARKET, or HOME_EQUITY
35 last_payment_at String The date and time of the most recent payment on the account
36 payment_due_at String The date and time at which the next payment is due on the account
37 account_id String The unique identifier for the account
38 requestCode String Unique code assigned for a customer request
39 entityId String Unique identifier for an entity
40 profileId String Unique identifier for a profile associated with an entity
41 addedOn String The timestamp when the account data for the customer is added in Chirp
42 modifiedOn String The timestamp when the account data for the customer is last modified in Chirp
43 customerAccountMatchStatus String Will return one of the following options "Full Match" – customer entered and financial returned match fully. "Partial Match" - customer entered and financial returned match partially. "No Match" - customer entered and financial returned do not match at all. "NA" – customer information was not entered.
44 customerRoutingNumberMatchStatus String Will return one of the following options "Full Match" – customer entered and financial returned match fully. "Partial Match" - customer entered and financial returned match partially. "No Match" - customer entered and financial returned do not match at all. "NA" – customer information was not entered.

Description for additional or optional fields under accounts,

# Field Name Data Type Description
1 chirpAccountId String The account's unique identifier, as defined by Chirp

Description for fields under transactions information,

# Field Data Type Description
1 amount Decimal The monetary amount of the transaction. Max length is 10,2.
2 category String The category of the transaction.
3 check_number Integer DEPRECATED. Use check_number_string instead.
4 check_number_string String The check number for the transaction.
5 created_at String The date and time the transaction was stored.
6 currency_code String The three-character ISO 4217 currency code, e.g. USD.
7 date String The date the transaction was created.
8 description String A human-readable version of the original_description field described below, e.g., "Sam's Club," "Johnny's Tavern."
9 is_bill_pay Boolean If the transaction is a bill pay, this field will be true. Otherwise, this field will be false.
10 is_direct_deposit Boolean If the transaction is a direct deposit, this field will be true. Otherwise, this field will be false.
11 is_expense Boolean If the transaction is an expense, this field will be true. Otherwise, this field will be false.
12 is_fee Boolean If the transaction is a fee, this field will be true. Otherwise, this field will be false.
13 is_income Boolean If the transaction is income, this field will be true. Otherwise, this field will be false.
14 is_international Boolean If the transaction is international as defined by the data provider, this field will be true. If the data provider determines it is not international, then it will be false. It will be null if the data provider does not have this information.
15 is_overdraft_fee Boolean If the transaction is an overdraft fee, this field will be true. Otherwise, this field will be false.
16 is_payroll_advance Boolean If the transaction is a payroll advance fee, this field will be true. Otherwise, this field will be false.
17 latitude Decimal The latitude of the location where the transaction occurred. The number is a signed decimal.
18 longitude Decimal The longitude of the location where the transaction occurred. The number is a signed decimal.
19 memo String This field contains additional descriptive information about the transaction.
20 merchant_category_code Integer The ISO 18245 category code for the transaction.
21 original_description String The original description of the transaction as provided by our data feed. See description above for more information.
22 posted_at String The date and time the transaction was posted.
23 status String The status of the transaction, i.e., POSTED or PENDING.
24 top_level_category String The parent category that this transaction's category is assigned to.
25 transacted_at String The date and time the transaction took place.
26 type String The type of transaction, i.e., CREDIT or DEBIT.
27 updated_at String The date and time the transaction was updated.
28 is_recurring Boolean Recurring payment or transaction
29 account_id String The identifier for the account associated with the transaction
30 id String The unique partner-defined identifier for the transaction. This can only be set for partner-managed transactions. It should be ignored for user-managed transactions, even in occasional cases where it may return with a value
31 is_subscription Boolean If transaction represents a payment for a subscription service such as Netflix or Audible
32 localized_description String A human-readable description of the transaction, provided in a local language
33 localized_memo String Additional descriptive information about the transaction, provided in a local language
34 user_id String The unique identifier for the user associated with the transaction
35 categoryCode String The category code of the transaction
36 parentCategoryCode String The parent category code of the transaction
37 member_is_managed_by_user String Whether the member is managed by user or not
38 running_balance String Amount of funds in an account after each transaction has been processed, providing a real-time snapshot of the account's current balance

Description for additional or optional fields under transactions,

# Field Name Data Type Description
1 chirpAccountId String The account's unique identifier, as defined by Chirp
2 chirpTransactionId String The transaction's unique identifier, as defined by Chirp

Description for fields under transactionAnalysisSummaries information,

# Field Data Type Description
1 category String A label identifying the type of transaction, for instance, "FEE"
2 total Decimal The total number of transactions within this category
3 amount String The combined total amount for all transactions in this category, for instance, "$32.00"
4 recentTransactionAmount String The amount of the most recent transaction in this category, for instance, "$2.00"
5 recentTransactionCount Decimal The number of recent transactions, for instance, 1
6 categoryName String The more descriptive name of the category, such as "Fees & Charges"
7 transaction Array Transactions associated with the category

Description for fields under accountExpenses information,

# Field Data Type Description
1 amount String The amount of expenses incurred
2 category String The category of expenses
3 percent String The percentage of expenses relative to total expenses

Description for fields under totalTransactions information,

# Field Data Type Description
1 accountNumber String The account number. This will typically be a masked or partial account number
2 totalTransaction String Total number of transactions returned
3 numberOfDays String Total number of days of the transactions returned since inception till date

Description for fields under debitCardEnrichment information,

# Field Data Type Description
1 lastFourDebitCardNumber String Last four digits of the customer's debit card
2 debitCardIndicatorMessage String A detailed message with match count and enrichment indicator definition
3 cardMatches Boolean If the provided last 4 digits of debit card number matches with the flagged transactions
4 autoflaggeddebit Boolean Auto flagged card and associated transactions by the system
5 debitCardIndicatorStatus String Denotes the enrichment of debit card being connected

Description for fields under accountInfo information,

# Field Data Type Description
1 account_number String The account number of the customer
2 routing_number String The routing number for the account
3 transit_number Boolean A unique number that represents the bank branch where you opened your account
4 institution_number Boolean A three-digit number that refers to a specific bank
5 passed_validation String Returns status of the validation passed or not
6 masked_account_number String The account number of the customer. This will typically be a masked or partial account number
7 chirpAccountId String The account's unique identifier, as defined by Chirp
8 bankName String Customer’s selected bank

Description for fields under accountOwnerInfo information,

# Field Data Type Description
1 owner_name String Full name of the account owner (first and last names)
2 address String Street address of the account owner
3 city String City where the account owner resides
4 state String State or province of the account owner's location
5 postal_code String Postal or ZIP code for the account owner's address
6 country String Country where the account owner is located
7 email String Email address for communication with the account owner
8 phone String Phone number of the account owner
9 first_name String First name of the account owner
10 last_name String Last name of the account owner

Understanding error messages for getCustomRequestDetails

# Scenario Error Code Error Message
1 If requesting details for an expired request 406 Request status is expired. Please try again with a verified request code
2 If requesting details for a rejected request 406 Request status is rejected. Please try again with a verified request code
3 If requesting details from a request code that has not been verified 406 Request status is unverified. Please verify the request and try again
4 If the template Name is invalid or incorrect 404 Template <template-name> not found or is not associated with this Entity <entity-name>
5 If the account number passed is invalid or incorrect 400 Account number passed is invalid. Please try again with a valid account number
6 If the chirp account id passed is invalid or incorrect 400 Chirp account id passed is invalid. Please try again with a valid chirp account id

2.3.1.31. getRequestAccountDetails

This endpoint is used to retrieve all the account information for a verified request. The endpoint requires the request code to be passed. The request must be in a verified status.

Example success response:

Status code: 200

    {
        "success": true,
        "requestCode": "QLU0GU",
        "accounts": [{
        "account_number": "708191771",
        "apr": 334,
        "apy": 158,
        "available_balance": 1000,
        "available_credit": 333,
        "balance": 1000,
        "cash_balance": 544,
        "created_at": "2023-06-30T12:14:11Z",
        "credit_limit": 651,
        "currency_code": "USD",
        "guid": "ACT-79ecc14f-ac33-45ab-b596-1fa997ff11a8",
        "holdings_value": 445.45,
        "institution_code": "chirpbank",
        "interest_rate": 170.4,
        "is_closed": false,
        "member_guid": "MBR-b31f9571-0842-11ef-9433-a5944bf5328f",
        "type": "CHECKING",
        "updated_at": "2023-09-21T01:12:26Z",
        "user_guid": "USR-b31f9570-0842-11ef-9433-a5944bf5328f",
        "routing_number": "889223786",
        "insured_name": "John Doe",
        "cash_surrender_value": 544,
        "day_payment_is_due": "124",
        "death_benefit": 732,
        "last_payment": 352,
        "loan_amount": 651,
        "matures_on": "2023-11-10",
        "minimum_balance": 252,
        "minimum_payment": 518,
        "name": "Checking",
        "original_balance": 981,
        "pay_out_amount": "688",
        "payoff_balance": 87,
        "premium_amount": 334,
        "started_on": "2023-10-11",
        "total_account_value": 961.21,
        "subtype": "NONE",
        "last_payment_at": "2023-11-13T05:03:51.575Z",
        "payment_due_at": "2023-11-13T05:03:51.575Z",
        "account_id": "act-223434333",
        "requestCode": "QLU0GU",
        "entityId": "5ff832f6711af0292e7828f9",
        "profileId": "5ff832f6711af0292e7828fa",
        "chirpAccountId": "ACC-2171ee40-1290-11ef-b135-150631c74239",
        "addedOn": "2024-05-02T05:13:32.029Z",
        "modifiedOn": "2024-05-02T05:13:32.029Z"
        }],
    }

Below is the table explaining the response returned from getRequestAccountDetails,

# Field Name Description
1 requestCode Request code of the respective request
2 success Response result of the request
3 accounts All the accounts that are linked with the verified bank account

Description for fields under accounts information,

# Field Data Type Description
1 account_number string The account number. This will typically be a masked or partial account number.
2 apr Decimal Annual Percentage Rate. Max length is 10,6.
3 apy Decimal Annual Percentage Yield. Max length is 10,6.
4 available_balance Decimal The balance currently available in an account. Max length is 14,2.
5 available_credit Decimal The currently available credit balance of an account. This field is for accounts with types CREDIT CARD and LINE OF CREDIT.
6 balance Decimal An account's current balance. Max length is 14,2.
7 cash_balance Decimal The cash balance of the account. Max length is 14,2.
8 created_at String The date and time the account was created.
9 credit_limit Decimal The credit limit for the account. Max length is 10,2.
10 currency_code String The three-character ISO 4217 currency code, e.g. USD.
11 holdings_value Decimal The value of the holdings associated with the account.
12 institution_code String Unique identifier for the financial institution which holds the account.
13 interest_rate Decimal Interest rate. Max length is 10,6.
14 is_closed Boolean If an account is closed, this field will be true. Otherwise, this field will be false.
15 type String The main type of an account, e.g., INVESTMENT, PREPAID, or SAVINGS.
16 updated_at String The date and time at which the account was last updated.
17 routing_number String The routing number for the account.
18 insured_name String The date and time the account was created
19 cash_surrender_value Decimal Money paid to the policy holder or annuity holder in the event the policy is voluntarily terminated before it matures, or the insured event occurs
20 day_payment_is_due String The day of the month the payment is due. e.g 14
21 death_benefit Integer The amount paid to the beneficiary of the account upon death of the account owner
22 last_payment Decimal The amount of the recent payment on the account
23 loan_amount Decimal The amount of the loan associated with the account
24 matures_on String The date on which the account matures
25 minimum_balance Decimal The minimum balance of the account
26 minimum_payment Decimal The minimum payment required for an account. This can apply to any debt account
27 name String The human-readable name for the account
28 original_balance Decimal The original balance of the account. This will always be positive
29 pay_out_amount String The amount paid out to the insured person or beneficiary under the conditions of the insurance policy
30 payoff_balance Decimal The payoff balance for a debt account. This will normally be a positive number
31 premium_amount Decimal The insurance policy's premium amount
32 started_on String The date on which a debt account was started
33 total_account_value Decimal The total combining both long and short positions, the sweep account and/or cash balance, and any margin debt linked to a specific account. This figure encompasses the aggregate market value of all positions within the account, offset by any debit balance and the value of short options positions that are profitable. This cumulative value can be negative and should not be misconstrued as an account balance
34 subtype String The account's subtype, e.g., PLAN_401_K, MONEY_MARKET, or HOME_EQUITY
35 last_payment_at String The date and time of the most recent payment on the account
36 payment_due_at String The date and time at which the next payment is due on the account
37 account_id String The unique identifier for the account
38 requestCode String Unique code assigned for a customer request
39 entityId String Unique identifier for an entity
40 profileId String Unique identifier for a profile associated with an entity
41 addedOn String The timestamp when the account data for the customer is added in Chirp
42 modifiedOn String The timestamp when the account data for the customer is last modified in Chirp
43 guid String Unique identifier for the account
44 member_guid String Unique identifier for the member to which this account belongs
45 user_guid String A unique identifier for the user to which the account belongs

Description for additional or optional fields under accounts,

# Field Name Data Type Description
1 chirpAccountId String The account's unique identifier, as defined by Chirp

Understanding error messages for getRequestAccountDetails

# Scenario Error Code Error Message
1 If requesting details for an expired request 406 Request status is expired. Please try again with a verified request code
2 If requesting details for a rejected request 406 Request status is rejected. Please try again with a verified request code
3 If requesting details from a request code that has not been verified 406 Request status is unverified/Attempted. Please verify the request and try again

2.3.1.32. updateCustomerProduct

This endpoint allows FLEX plan entities to switch between subtype for their customers

Example success response:

Status code: 200

    {
        "success": true,
        "message": "Requested subtype has been successfully updated from PAYG to Subscription"
    }

Below is the table explaining the response returned from updateCustomerProduct,

# Field Name Description
1 success Response result of the request
3 message Success description of the request subtype change

Understanding error messages for updateCustomerProduct

# Scenario Error Code Error Message
1 If the entity does not have the product plan type FLEX 400 This entity <entityName> does not have the flex plan type for the product Subtype is invalid. Please check the subtype
2 If the subtype entered is other than PAYG or SUBSCRIPTION 400 Subtype is invalid. Please check the subtype
3 If the subtype is already in the same plan type 409 Subtype is already in <productType> plan type

2.3.1.33. enableFraudScoreByVeritrust

The endpoint is used to enable fraud score for ON_DEMAND type requests. The url also takes a query param as active to enable or disable the fraud scoring feature for the request. The active query param defaults to true if not passed.

Example success response:

Status code: 200

    {
        "success": true,
        "message": "Fraud Score is enabled for this request successfully",
    }

Response Field Definitions for enableFraudScoreByVeritrust,

# Field Data Type Description
1 success Boolean Response status of the request
2 message String Success message

Understanding error messages for enableFraudScoreByVeritrust

# Scenario Error Code Error Message
1 If the integration settings is not enabled for the entity 400 Fraud Score is not enabled for this entity

2.3.1.34. getFraudScoreByVeritrust

The getFraudScoreByVeritrust endpoint is used to retrieve fraud score information for a verified request. The fraud score data and information is provided by VeriTrust.

Example success response:

Status code: 200

    {
        "success": true,
        "fraudScoreInfo": {
            "requestCode": "QLU0GU",
            "leadId": "ABCDEF123456",
            "pulse": "33",
            "insight": "22",
            "intent": "16",
            "acuity": "43",
            "status": "S",
            "error": "erroInfo"
        }
    }

Response Field Definitions for getFraudScoreByVeritrust,

# Field Data Type Description
1 success Boolean Response status of the request
2 requestCode String Request code for a request
3 leadId String The unique identifier for the lead
4 pulse String The calculated pulse score for the customer
5 insight String The calculated insight score for the custome
6 intent String The calculated intent score for the customer
7 acuity String The calculated acuity score for the customer
8 status String Status of the fraud score ("S" for success, "E" for error)
9 error String Error message (if any)

Understanding error messages for getFraudScoreByVeritrust

# Scenario Error Code Error Message
1 If the fraud score is not found for the request 404 Fraud score info not found for this request

2.3.1.35. getBankLogoByRequestCode

The getBankLogoByRequestCode endpoint serves bank logos associated with the customer in either "small" or "medium" sizes. The URL includes an optional query parameter, size, to specify the desired logo size. If the size is provided, the corresponding logo image is served directly; otherwise, both the small and medium versions are included in the response. If the customer has not yet selected a bank, Chirp returns a successful response with success: true, status code 200, and the message: "The customer has not selected a financial institution for the verification process yet."

Example success response:

Status code: 200

        {
            "success": true,
            "bankSelected" : true,
            "logoVersion": {
                "small": "https://chirp.digital/api/bankLogo/chirpbank_small.png",
                "medium": "https://chirp.digital/api/bankLogo/chirpbank_medium.png",
            }
        }

Response Field Definitions for getBankLogoByRequestCode,

# Field Data Type Description
1 success Boolean Response status of the request
2 bankSelected Boolean Indicates if the customer has selected a financial institution to verify or not
3 logoVersion Object Bank logo version uri

Understanding error messages for getBankLogoByRequestCode

# Scenario Error Code Error Message
1 If size passed is invalid 400 Please try again with a valid size.

There are three Chirp Widgets that can be utilized to assist customers with the integration of Chirp into their business model. By using the widgets, customers can significantly reduce the level of effort and time it takes to implement Chirp.

The widgets can be implemented together or separately, depending on your unique business model and requirements.

3.1. Configure the Success/Failure Redirections

Part of the Profile configuration for use with Chirp widgets are the success and failure redirect URLs. Be sure to configure the URLs per your business model and process flow. When an end-customer attempts to verify a request, these URLs are sent to the web page where the IFRAME widget is integrated through the PostMessage API with the request code appended. The webpage can then redirect the end-customer based on the success or failure of the verification attempt. No redirection will occur if the redirect URLs are empty.

The following section explains how to implement the various Chirp Widgets for requesting and viewing successful Instant Financial Verification (IFV) results from the customer.

3.2. Request Widget

The Chirp Request Widget can be embedded as an iFrame or loaded into a webpage for requesting financial verification from a customer.

The basic workflow required for the Request Widget:

  • Create a request code via the Chirp API createRequest endpoint
  • Create and load the request widget the request code returned from step 1.

Here are the three possible workflows (assuming all required elements are provided to the widget and no other error conditions occur):

  • Bank name is not passed with createRequest:
    • A new verification request will be generated, and the widget will present the bank search screen to the customer.
  • Bank name is passed with createRequest, but the bank is not found:
    • The API will respond with a “bank not found” error message. At this point, the request can be abandoned or re-sent with or without the bank name.
  • Bank name is passed with createRequest, and the bank name is found:
    • The API will create the request with the bank name pre-selected. Although the bank is pre-filled, if the Entity Profile has enabled the option to "Display Institution search," the customer will be able to search for a different bank and change the bank in the widget presented to them.

3.2.1. Request Widget

A custom request widget than can be loaded in a web page and can be branded to your specifications for interacting with the customer to obtain financial verification.

For instance, if yourloancompany.com is integrated, then “Your Loan Company” can create a web page for loading the request widget.

In this case, let us assume the link of this created page is:

https://yourloancompany.com/customerVerification.

Now when a request is created, a link will be generated and sent in the response as:

https://yourloancompany.com/customerVerification?requestCode=<request_code>

Note: The above links are just examples. You will need to use the URL that you have for your financial verification website.

3.2.1.1. Request Widget Integration and Communication

The method of integrating Request Widget is via iFrame. Communication between the parent page and the integrated iFrame happens via Javascript PostMessage API

Below is a sample JavaScript that creates an iFrame for loading the widget in a webpage. The script also contains code to catch messages from the iFrame via PostMessage API and handles success/failure redirections.

Note: Below provided script is just a sample script which creates and loads the Request Widget via iFrame and appends it to the document body of a webpage. The script can be modified to load or present the IFRAME anywhere that suits best for the applications needs. 

      let requestCode = document.location.search.substr(1).split("&")[0].split('=')[1];
      // addEventListener support for IE8
       function bindEvent(element, eventName, eventHandler) {
           if (element.addEventListener){
               element.addEventListener(eventName, eventHandler, false);
           } else if (element.attachEvent) {
               element.attachEvent('on' + eventName, eventHandler);
           }
       }
       var iframeSource = `https://chirp.digital/api/widget?requestCode=${requestCode}`,
       results = document.getElementById("message");
       // Create iframe
       var iframe = document.createElement('iframe');
           iframe.setAttribute('src', iframeSource);
           // iframe.setAttribute('sandbox', "allow-scripts allow-top-navigation");
           // iframe.setAttribute('sandbox', "allow-top-navigation");
           console.log('doc width ', document.body.offsetWidth);
           iframe.setAttribute('id', 'the_iframe');
           iframe.style.width = document.body.offsetWidth + 'px';
           iframe.style.height = document.body.offsetHeight + 'px';
           iframe.style.border = 'none';
           document.body.appendChild(iframe);
       // Listen to messages from child window
       bindEvent(window, 'message', function (e) {
           console.log("from post message ", e.data)
           console.log("from post message ", e.origin)
           // if(e.origin == "https://chirp.digital"){
               console.log("type of response ", typeof e.data)
               console.log("message from child ", e.data)
               // results.innerHTML = e.data;
               var messageFromParent = e.data
              //  if(messageFromParent.success){
              //      window.top.location.href = e.data.urlToRedirect;
              //  }
           // }        
       });

3.3. Results Widget URL

Chirp provides a Results Widget URL to show the details of a verified request. This is useful for implementations that do not have specific requirements for how the loan underwriting process reviews the financial transaction details. This provides rapid implementation to see the results in an organized and readable format with similar functionality that is already built into the Chirp Portal user interface.

Sample implementation of the Results Widget URL:

https://chirp.digital/api/renderReport/<request_code>?token=<api_token>

Request code and API token should be replaced with the actual request code and the API token.

Sample Results Widget URL page:

Figure 14: Request Widget Details

3.4. Results Widget URL V2

Chirp provides a hosted solution to not just show an extensively detailed view of your customer data but also to effectively manage them with features like Bank Refresh, Download customer reports as PDF, Excel and XML file formats. An LMS can directly integrate with Chirp and show this page in their application via an Iframe. The authorization mechanism used here is slightly different than others. A one-time usable token is required to be generated via generateAuthTokenForReportUI endpoint for loading this widget in an Iframe.

Below are the instructions to integrate this widget in an application,

Note: Request code and API token should be replaced with the actual request code and the API token.

Figure 15: Chirp IFV - Integrating Partner Results View Flow

Figure 16: Request Widget Details

3.5. Stand-Alone Website Integration Widget

Chirp provides a configurable widget that lenders can quickly integrate into their websites to verify their customers instantly when applying for a loan. This reduces the need for sending verification links via text or email to customers for financial institution verification and increases the conversion rate of the verification process. This widget is designed to be embedded as part of the lender’s website to reduce integration complexities and overhead for a lender. By default, the Custom Widget is not enabled for a Chirp Account so contact the Chirp support team if you would like this enabled for your Chirp Account.

If the lender wants the widget to be integrated as part of their workflow, there might be minor development required at the lender's end. The Chirp team can assist in setting up the workflow.

This widget requires basic customer information (first name, last name, email, and phone number) as inputs. Once the basic inputs have been provided, the request code generation process is entirely automated and managed by Chirp on the backend.

3.5.1. Implementing with a Standard Template

The verification widget should be loaded within the IFRAME of a webpage. This widget page can be included as the step next to the Loan Application Page. For example, when a customer fills in a loan application form, the submit option should trigger the page that will have the Chirp custom widget embedded in it. The customer’s first name, last name, email, and cell phone number are the four parameters required to be passed to load the widget.

Sample link for accessing this page:

https://yourwebsite.com/?firstName=<fname>&lastName=<lname>&email=<email>&phone=<phone#>

From this page, customers will be able to search for the Bank Name and then login to their bank account to allow access to their financial data.

Figure 17: Website Verification Widget

3.5.2. Implementing with a Customized Template

The widget look and feel can be modified by the Entity Admin via the Chirp Portal User Interface. Below are the step-by-step instructions to customize the widget.

  • Login to the Chirp Portal as the Entity Admin.
  • Expand “Settings” in the left-hand navigation menu, select "Widget Configuration.”
    • If the "Widget Configuration" option is not available, please contact Chirp support and request it to be enabled.
  • You will be presented with an interface where you can customize the look and feel of the widget.
    • Modify colors as desired and click “Save.”
    • Select the "Show skip button” if you want to allow the customer to skip the verification process.

    • Figure 18: Widget Configuration

  • Select the “Config Tab” (after you finish the design and click “Save”).
    • From the text editor, you will be able to modify the terms & conditions based on your requirements or just accept the standard terms & conditions as-is.
    • Select the Chirp Profile for the customized widget to integrate with.
    • Select Production or Sandbox environment.
    • If you selected the “Show skip button” on the “Design” tab:
      • Enter the redirection URL if the customer skips the verification process.
    • Setup email notifications for your team:
      • Enter one or multiple emails for your team(s) to be notified as the customer interacts with the widget.
        • Customer closes the verification widget
        • Customer skips the verification widget
        • Customer attempts to verify a request
        • Customer verifies a request successfully
  • Click "Save and Generate" once all edits are finalized.
    • This will generate the “Integration Script” on the right side of the interface. Copy the script by clicking on the "Copy" button and use this script appropriately on your website to integrate the widget with Chirp.

Figure 19: Widget Configuration

3.5.3. Stand-Alone Website Integration Widget Sample Process Flow

This section provides a sample process flow for lead providers, loan system providers, and lenders of how the Chirp Stand-Alone Website Integration Widget could be implemented. The integration script can be generated and used from the “Implementing with a Customized Template” section.

Sample Process Flow

  • Customer navigates to or is redirected to a webform
  • The customer completes and submits the webform
    • The form can collect whatever information you would like; however, these basic attributes are required by the widget.
      • First Name
      • Last Name
      • Email
      • Phone
  • The form should redirect the customer to the web page, where the widget will be loaded with the basic info passed in the header/query parameters.
  • Chirp script is included in the lenders' verification webpage. https://lenderssite.com/verification-widget handles extracting information from the headers and loads the verification widget in the place where the script is included.
  • Further illustration:
    • Starting point webform
      • https://leadprovidersite.com/apply
    • Redirected to:
      • https://lenderssite.com/verification-widget
      • With basic info in the headers as follows:
        • https://lenderssite.com/verification-widget?firstName=john&lastName=doe&email=johndoe@somedomain.com&phone=11111111111
  • Customer selects the bank and proceeds with verification.
  • Customer is redirected to success or failure URLs based on the configuration in the Profile used for the verification widget. No redirection will happen if the redirection URLs is saved empty.
  • Customer is allowed to resubmit valid credentials on a failure attempt, and the number of times allowed can be configured in the Profile using "Max Login Attempts" option.

In summary, this widget requires basic customer information (first name, last name, email, and phone number) as inputs. Once the basic inputs have been provided, the request code generation process is entirely automated and managed by Chirp on the backend.

Here are the three possible workflows (assuming all required elements are provided to the widget and no other error conditions occur):

  • The widget is loaded with new basic customer information.
    • A new verification request will be generated, and the widget will present the bank search screen to the customer.
  • The widget is loaded with existing basic customer information, and the verification request has not reached the end of the request lifecycle (verified, rejected, or expired).
    • The existing verification request will be used, and the widget will present the bank login screen to the customer.
  • The widget is loaded with existing basic customer information, and the verification request has reached the end of the request lifecycle (verified, rejected, or expired).
    • A new verification request will be generated, and the widget will present the bank search screen to the customer.

ChirpLink™ is Chirp’s custom and proprietary widget for linking customer financial accounts to merchant applications using a plug-and-play integration setup.

Here’s a sample ChirpLink™ widget integration implementation:

The detailed explanation of all these events and method can be found under the section below

ChirpLink™ CDN Link - https://chirp.digital/cdn/chirplink.js

3.6.1. Customization Options for ChirpLink™

# Option Description
1 token Token generated for initiating a customer verification in the entity's integration. This token is mandatory for ChirpLink™
2 mode Mode of the widget to be rendered as per integration. This is an optional field. The two possible modes supported by the widget currently are “POPUP” and “ADAPTABLE”. This is an optional field and defaults to opening as a POPUP if unspecified or incorrectly spelled
3 onLoad This event is fired as soon as the widget is loaded, it also provides request code and status of the link whether it is expired or not
4 onBankSelect This event is fired when the customer selects the bank they want to link. This event also provides the details of the selected bank
5 onError This event is fired when an error occurs during the verification process. The details of the error are also shared
6 onClose This event is fired when the customer closes the verification widget along with the step number from where the ChirpLink™ widget was closed
7 onSuccess This event is fired once the customer completes the verification process
8 onAttempt This event is fired once the customer attempted to verify during verification process

The events are explained in detail with examples in the Event Callbacks section

3.6.2. Event Callbacks

ChirpLink™ provides six events that you can use to customise the behaviour of the verification widget

3.6.2.1. onLoad

Triggered as soon as the widget is loaded, indicating the widget is loaded and ready. It also returns a payload containing relevant data associated with the loaded widget. The payload structure may include properties such as requestCode and isLinkExpired (whether this link is expired or not), providing valuable information for further processing.

Example payload structure

    {	
        requestCode: "QLU0GU",
        isLinkExpired: true,
        message: "Request code QLU0GU is expired. Please contact <phoneNumber> <profileName> at <supportEmail> with the request code for further assistance."
    }

Payload definition

requestCode: Request code of the verification flow.

isLinkExpired: Status of the link whether it is expired or not.

message: Description of the reason why this link has expired. This field is included only if the link expires.

3.6.2.2. onSuccess

Triggered when a verification operation is completed and the financial account is linked. This event provides an object containing valuable information, offering insights into the success status and a URL for redirection.

Example success payload structure

    {	
        success: true, 
        urlToRedirect: "sampleSuccessURL.com",
        status: "VERIFIED",
        statusDetails: "NA"
    }

Example failure payload structure

    {	
        success: false, 
        urlToRedirect: "sampleFailureURL.com",
        status: "ATTEMPTED",
        statusDetails: "Attempted - Credential Error"
    }

Payload definition

success: A boolean value indicating the success status of the verification process. If true, the verification was successful.

urlToRedirect: A URL to which the user can be redirected after the verification process. This is useful for both success and failure scenarios.

status: Status of the verification request, possible values are "VERIFIED", "REJECTED" or "ATTEMPTED"

statusDetails: Status description of the verification request, possible values are "Attempted - In Progress", "Attempted - Bank Error", "Attempted - Credential Error" or "NA"

3.6.2.3. onError

Triggered when an error occurs during the execution of specific functionalities throughout the verification process. This could include errors related to verification processes and API calls

Example payload structure

    {	
        success: false, 
        errorMessage: "sample error message"

    }

Payload definition

success: A boolean value indicating the success status of the operation. If false, an error occurred.

errorMessage: A string providing an error message explaining the nature of the error.

3.6.2.4. onClose

Triggered when the user closes the verification widget. It serves as a valuable indicator of user interactions and can be used to track the progression or completion of various verification stages like CUSTOMER_CONSENT, BANK_SELECTION, INITIAL_LOGIN, MFA, VERIFIED, EXPIRED, or REJECTED.

CUSTOMER_CONSENT - Initial landing page of the widget

BANK_SELECTION - Page for users to select their bank

INITIAL_LOGIN - Initial login page where users enter their credentials

MFA - Page for additional security verification

VERIFIED - Confirmation page indicating successful completion of the authentication process

EXPIRED - Page notifying users when their session or verification has expired

REJECTED - Page indicating that the given request code is rejected

Example payload structure

    {	
        pageClosed : true,
        closedPage : "CUSTOMER_CONSENT"
    }

Payload definition

pageClosed: A boolean value indicating whether the page was closed. If true, the page was closed.

closedPage: A string specifying the specific page that was closed. Possible values include CUSTOMER_CONSENT, BANK_SELECTION, INITIAL_LOGIN, MFA, VERIFIED, EXPIRED, or REJECTED.

3.6.2.5. onBankSelect

Triggered when the user makes a bank selection, and it provides an object containing details such as whether a bank was selected and the name of the selected bank.

Example payload structure

    {	
        bankSelected: true,
        bankName: "Chirp Test Bank",
        bankUrl: "sampleUrl.com"
    }

Payload definition

bankSelected: A boolean value indicating whether a bank was selected. If true, a bank was selected.

bankName: A string specifying the name of the selected bank.

bankUrl: A string specifying the official site url of the selected bank.

3.6.2.6. onAttempt

Triggered when the user attempts the verification widget. It serves as a valuable indicator of user interactions and can be used to track the attempted progression of various verification attempted stages like CREDENTIAL_ERROR, BANK_ERROR and IN_PROGRESS.

CREDENTIAL_ERROR - Indicates that the credentials supplied for verification are invalid.

BANK_ERROR - Indicates that the error is caused by an issue on the bank's end.

IN_PROGRESS - Indicates that the verification process is currently ongoing.

Example payload structure

    {	
        attempted: true,
        message: "CREDENTIAL_ERROR"
    }

Payload definition

attempted: A boolean value indicating the status of the attempt.

message: A string specifying the attempted message. Possible values include CREDENTIAL_ERROR, BANK_ERROR or IN_PROGRESS.

3.6.3. Close method - close()

The close method should be used for closing the ChirpLink™ widget programmatically as per the integration workflow. Successful execution of this method triggers the onClose event upon completion which also provides more details about the closed page through the field closedPage in the event callback payload.

Before the close() method can be used, the ChirpLink™ widget must have already been initialized like the sample below.

var newChirpLink = new ChirpLink({ …options });

The close button can then be called as needed to close the ChirpLink™ widget programmatically

<button onclick="newChirpLink.close()">Close ChirpLink</button>

3.6.4. Integration Steps in Detail and Sample Script

3.6.4.1. Add ChirpLink™ Script

Include the Chirp script in your website's script file by adding this below mentioned CDN link. ChirpLink™ CDN Link - https://chirp.digital/cdn/chirplink.js

3.6.4.2. genAuthTokenForChirpLink - (POST)

It is used to generate a one-time accessible token associated with a request code for Chirp verification. The endpoint is accessible via a POST request and returns a response containing details about the generated authentication token.

Endpoint : https://chirp.digital/api/genAuthTokenForChirpLink/chirpLink/<request_code>

Headers - Authorization : <profileToken>

Example success response:

Status code: 200

    {	
        "success": true,
        "token": "y5yh45h4w5h45h4j4w6j4wj4htrhw6u65h6j56h5y",
        "requestCode": "QLU0GU",
        "validUpto": "8/10/2021, 10:33 PM"
    }

Response Field Definition:

success: Response result of the request

token: Token generated for initiating a customer verification in entity’s integration

requestCode: The request code for which the token is valid

validUpto: The expiration time until the generated token is valid. Timezone is CST

3.6.4.3. Integration

After successfully retrieving the token using the genAuthTokenForChirpLink endpoint, you must integrate the token into your script. Sample script was mentioned below.

3.6.4.4. View

In desktop mode, the verification widget is displayed as an overlay popup in the center of the screen. Users can interact with the ChirpLink™ widget without navigating away from the current page.

In mobile mode, the verification widget will automatically overlay the full size of the screen.

3.6.4.5. Sample script for events

    var newChirpLink = new ChirpLink({

    token:"y5yh45h4w5h45h4j4w6j4wj4htrhw6u65h6j56h5y",

    onLoad: function (load) {
      console.log('On Load event', load);
    },
    onSuccess: function (success) {
      console.log('On Success ',success);
    },
    onError: function (err) {
      console.log("On Error ", err);
    },
    onClose: function (close) {
      console.log("on Close",close);
    },
    onBankSelect: function (bank) {
      console.log("On Bank Select", bank);
    },
    onAttempt: function (attempt) { 
        console.log("On Attempt", attempt);
      }
  });

3.6.5. Create Custom Customer Messages

A message is shown to the end customer when the request reaches an end state(connected, rejected, or expired). This message can be customized by the Entity in the Chirp Portal. Click here to view the Portal documentation.

3.6.6. Adaptable ChirpLink™

ChirpLink™ can also act as an adaptable widget to be placed anywhere on a webpage. This helps with creating custom workflows and placing the ChirpLink™ widget in a container

3.6.6.1. Setting up the Container

To utilize the adaptable feature of ChirpLink™, you need to designate an HTML element to serve as the container for the widget. Here's how you can create this container: 

<div id="chirpLinkWidget"></div>

Ensure that the container element is placed appropriately and is also properly created within the HTML structure if added dynamically.

3.6.6.2. Integrating Adaptable ChirpLink™

To integrate the ChirpLink™ widget in its adaptable mode, follow these steps:

var newChirpLink = new ChirpLink({
    token:"y5yh45h4w5h45h4j4w6j4wj4htrhw6u65h6j56h5y",
    mode : "ADAPTABLE"
)}

The mode should be set to “ADAPTABLE” as its value for making the widget adaptable to a container. If the mode parameter is not specified or incorrectly spelled, the widget defaults to opening as a popup.

ChirpLink™ provides six events that you can use to customize the behavior of the verification widget. Click here to learn more about these callback events.

4. Chirp Webhooks

Chirp webhooks provide a way for integrating partners to subscribe to real-time, event based,status updates. To be successful the webhook URLs provided by Chirp integrating partners must be an open POST endpoint. Chirp currently offers webhook status updates for REQUEST_STATUS and REFRESH_STATUS.

To configure Webhook URLs visit the Notifications option under the Settings menu and add a new notification as shown in the figure below. The URLs can be configured in a way that is most effective for the integration partners system. For example the REQUEST_STATUS and REFRESH_STATUS can be configured to share a single a URL for either event or each event can be registered with a unique URL.

Figure 20: Chirp Webhooks

4.1. Webhook Events

4.1.1. Request Status

The REQUEST_STATUS webhook event is used to proactively send notifications when actions occur that are specific to changes in the status of a request.

4.1.1.1. action: UPDATED

The Request Status webhook event will send notifications under this action when Chirp detects a change in a request status. For instance – if a request status is updated from Unverified to Attempted a status update event will be posted to the registered POST URL.

{
requestCode: “QLU0GU”,
type: “REQUEST_STATUS”,
action: “UPDATED”,
status: “Verified”,
firstName: “John”,
lastName: “Deo”,
customerId: “YYYYY”,
productId: “ZZZZZ”,
statusDetails: “NA”
}

4.1.2. Refresh Status

The REFRESH_STATUS webhook event will send an update when Chirp detects a change in the refresh status. For instance – if a refresh status is updated from Verified to Rejected a status update event will be posted to the registered POST URL.

{
requestCode: “QLU0GU”,
type: “REFRESH_STATUS”,
action: “UPDATED”,
status: “Success”,
firstName: “John”,
lastName: “Deo”,
customerId: “YYYYY”,
productId: “ZZZZZ”
}

4.2. Webhook Logs

Webhook event requests are logged and can be viewed in the left hand Navigation panel by the Entity Admin and Entity Global users for debugging purposes. The webhook full response can be viewed by clicking View icon.

Figure 21: Webhook Logs

For a comprehensive list of HTTP responses see

https://developer.mozilla.org/en-US/docs/Web/HTTP/Status

5. Integrating Partner Request Management

5.1. Business Case

Chirp integration partners should track each Chirp request code with data from their integrating system and evaluate what action to take with Chirp in the workflow. The most common actions would be 1) create a new request, 2) re-use an open request until that open request reaches the end of the life cycle (verified, rejected, or expired) or 3) display a message that the verification has already been successfully completed.

Consider this lender and borrower example. The LMS would store the Chirp request code and the loan/application information for that request code. When the borrower attempts to visit the IFV page the LMS would evaluate the status of loans/applications against the borrower and take the appropriate steps.

5.1.1. Create New Request Samples

  • A new loan was created for a new borrower with no previous verification.
  • A new loan was created for an existing borrower with a successful verification from a previous loan.
  • A new loan was created and the borrower attempted bank verification for an incorrect bank and would like to select a new bank even though there’s already an open request.

5.1.2. Re-Use Existing Open Request Sample:

  • The borrower re-visits the bank verification page because they lost connection before completing the verification.
  • The borrower re-visits the bank verification page because they didn’t have all of the information to complete verification the first time
  • The borrower re-visits the bank verification because they are not sure if they already completed the bank verification step
  • The borrower re-visits the bank verification page because of a temporary technical issue at the financial institutions end on the previous attempt

5.1.3. Display Request Connection Status on IFV Page

If the borrower re-visits the IFV page and the workflow rules indicate that a successful verification already exists for the borrower/loan combination the LMS should display a message to the borrower that the verification has already been completed. Here's a suggested message to present to the borrower. "Your bank verification information for <bank-name> was successfully completed in an earlier session. You should be hearing from your <lender-name> soon."

Figure 22: Chirp IFV - Integrating Partner Flow

Terms & Conditions | Privacy Policy

Chirp Digital is not a credit reporting agency.

support@chirp.digital

Copyright © 2024 Chirp Digital. All Rights Reserved..