Account Intelligence

Overview

The Account Intelligence v3 endpoint is part of GrailPay’s real-time bank account validation system. It allows you to determine whether a user’s bank account is valid, active, and safe to use — helping you reduce fraud, prevent returns, and accelerate decision-making. With a single API call, the endpoint returns a confidence_score along with detailed decisioning_insights based on the identity and bank account data you provide. These insights can be used to drive onboarding, funding, and payout workflows with higher accuracy and lower risk. When constructing your request, you’ll pass an identity object that contains either an individual or an organization. These two are mutually exclusive — the request will fail if both are included. Use organization for validating business entities and individual for people. While the only required fields are account and routing numbers, we strongly recommend providing as much identity data as possible. More complete input data results in more meaningful confidence scores and more actionable insights.

This API is only available for U.S. bank accounts.

For complete request and response definitions, visit the Account Intelligence OpenAPI Documentation.

Actions

By default, every call to this endpoint performs core validation checks on the routing and account numbers. To enrich the results further, you can optionally include an actions object in your request to enable additional validation layers. Currently, the following action is supported:

name_match: Compares the provided name in the identity object with the account holder’s name on file.
taxpayer_number_match: Compares the provided taxpayer identifier in the identity object with the account holder’s tax ID on file.

To enable name matching, include the following in your request payload:

{
  "actions": {
    "name_match": true,
    "taxpayer_number_match": true
  }
}

This triggers GrailPay’s proprietary name-matching engine, which contributes directly to the confidence score and provides additional clarity on identity matching. For full request and response examples, see the Account Intelligence API reference.

Response Attributes

Every call to the Account Intelligence endpoint returns a confidence_score alongside a set of structured decisioning_insights. Together, these give you both a single risk signal and the explainable attributes behind it, so you can plug them directly into your own models or rules-based decisioning.

Confidence Score

The confidence_score is a number between 0.00 and 1.00 representing the likelihood that a bank account is operational and capable of completing an ACH transaction successfully. Higher is better — a score of 0.95 indicates high confidence that the account is active and functional, while a score of 0.30 indicates significant risk of an ACH return. The score is produced by a proprietary machine learning model trained on millions of historical ACH transactions and their outcomes. The model takes the account and routing number, enriches it with third-party data sources and GrailPay’s own first-party intelligence, and returns a calibrated probability.

Decisioning Insights

The decisioning_insights object contains explainable attributes returned alongside the score. Each attribute is designed to be consumed directly by your risk engine — as an input to your own models or as a building block for rules-based logic.

Attribute	Type	Description
`valid_routing_number`	boolean	Whether the routing number is a valid, active ABA routing number registered with a financial institution. A `false` here is an immediate red flag — the account cannot process ACH transactions regardless of any other signal.
`name_match`	string	Returned upon optional use of the name match flag. Whether the name provided in the request matches the name on file across our identity network. Possible values: `yes`, `no`, `not_available`. A `no` indicates the account may not belong to the entity claiming it — a potential indicator of fraud. `not_available` means no match result was returned for this account.
`name_match_score`	number	Returned upon optional use of the name match flag. A calibrated score between `0.00` and `1.00` representing how confidently the provided name matches the name on file at the receiving bank. `1.00` is an exact, high-confidence match; values in the `0.80s` indicate a close but non-exact match (e.g., a minor spelling variation or a business name vs. DBA); values below `0.80` indicate a non-match. Pairs with `name_match` to quantify the strength of the result. Returns `0.00` when no name was supplied or no data source could evaluate it.
`days_since_first_seen`	integer	How many days ago this account was first observed in our network. A high number (e.g., `400+`) indicates a well-established account with a long track record. A low number (e.g., `3`) means the account is new to the payments ecosystem, carrying higher inherent uncertainty. Returns `-1` when no prior history exists.
`days_since_last_transaction`	integer	How many days since the most recent transaction was observed on this account. A low number means the account is actively transacting. A high number may indicate the account has gone dormant, which correlates with higher return risk. Returns `-1` when unknown.
`positive_transactions_seen`	boolean	Whether the account has a history of successfully completed transactions that settled without returns. `true` is a positive signal that the account can complete payments.
`negative_transactions_seen`	boolean	Whether the account has a history of negative activity, such as unpaid items, returned transactions, or reported negative events. `true` is a risk signal that should be weighed in decisioning.
`paid_transactions_seen`	boolean	Whether the account has a history of transactions that were initially returned but subsequently resolved. `true` indicates the account holder has resolved past issues — a nuanced signal that sits between purely positive and purely negative history.
`phone_number_present`	boolean	Whether a phone number is associated with the account on file. Presence adds a layer of identity verification; absence does not necessarily indicate risk, but presence strengthens confidence in the account holder’s identity.
`account_duplicate`	boolean	Whether this account and routing number pair has been seen before in our proprietary database.
`taxpayer_number_match`	string	Returned upon optional use of the taxpayer number match flag. Whether the taxpayer identification number (SSN for individuals, EIN for businesses) provided in the request matches the taxpayer number on file. Possible values: `yes`, `no`, `close_match`, `not_available`. A `yes` is a strong positive identity signal; a `no` is a strong fraud indicator; a `close_match` means the tax ID is off by one or two digits; `not_available` means no taxpayer number was provided or our network lacks coverage for it.

Feedback

Account Intelligence is a continuously improving system, and its accuracy depends on real-world outcome data from your integration. The Feedback endpoint allows you to report return events that occurred despite receiving an acceptable risk score, closing the loop between prediction and outcome. Submitting feedback is a critical part of getting the most out of Account Intelligence. Feedback data is used for analytics, model evaluation, and ongoing training — directly improving the accuracy of future risk scores across your account portfolio. Integrations that consistently submit feedback benefit from more precise, tailored risk assessments over time.

We strongly recommend incorporating feedback submission into your standard return-handling workflow. Consistent feedback is the single most effective way to improve the accuracy of your Account Intelligence results.

For complete request and response definitions, visit the Account Intelligence Feedback OpenAPI Documentation.

When to Submit Feedback

You should submit feedback when:

A transaction results in an unexpected return despite receiving a low-risk Account Intelligence score
You want to improve the accuracy of future risk evaluations for your account portfolio
You need to report false negatives for internal tracking and model monitoring

Request Fields

When submitting feedback, your request payload should include details about the account, the return event, and a reference to the original Account Intelligence evaluation. Required fields ensure we can accurately link your feedback to the original prediction, while optional fields provide additional context that strengthens model analysis.

Required Fields

The following fields are required to link your feedback to the original Account Intelligence evaluation and the associated return event.

Field	Type	Description
`account_number`	string	The account number from the original evaluation
`routing_number`	string	The routing number from the original evaluation
`outcome_status`	string	The outcome status of the transaction. Possible values: `settled`, `returned`
`return_code`	string	The ACH return code received (e.g., `R01`, `R02`, `R03`)
`name_match_requested`	boolean	Whether name matching was enabled in the original request

Additionally, you must include one of the following to link to the original prediction:

Field	Type	Description
`inference_request_id`	UUID	The request ID returned by GrailPay in the original Account Intelligence response (preferred)
`inference_timestamp`	timestamp	The UTC timestamp of the original request, if the request ID is unavailable

Providing the inference_request_id is strongly recommended as it ensures accurate linkage to the original risk evaluation.

Optional Fields

The following fields are not required but provide additional context that strengthens model analysis when available.

Field	Type	Description
`returned_at`	timestamp	When the return was received
`transaction_initiated_at`	timestamp	When the transaction was initiated (client-side)
`sec_code`	string	The SEC code of the transaction (e.g., `WEB`, `CCD`, `PPD`)
`amount`	decimal	The transaction amount
`direction`	string	Transaction direction: `credit` or `debit`

Usage Recommendations

Always pass complete and accurate identity data to maximize result quality.
Use the confidence_score and decisioning_insights to guide onboarding and risk workflows.
Review fields such as name_match, valid_routing_number, and negative_transactions_seen closely when the score is low.
Submit feedback promptly after a return event occurs to ensure accurate timestamps and traceability.
Always include the inference_request_id when available for precise linkage to the original prediction.
Provide optional fields like amount, sec_code, and direction when possible to enrich the feedback data.

Questions?

If you’re encountering any issues, please reach out to [email protected].

Getting Started

Bank Accounts

Transactions

Account Intelligence

Overview

Actions

Response Attributes

Confidence Score

Decisioning Insights

Feedback

When to Submit Feedback

Request Fields

Required Fields

Optional Fields

Usage Recommendations

Questions?

​Overview

​Actions

​Response Attributes

​Confidence Score

​Decisioning Insights

​Feedback

​When to Submit Feedback

​Request Fields

​Required Fields

​Optional Fields

​Usage Recommendations

​Questions?

Overview

Actions

Response Attributes

Confidence Score

Decisioning Insights

Feedback

When to Submit Feedback

Request Fields

Required Fields

Optional Fields

Usage Recommendations

Questions?