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.

Sandbox Testing

The sandbox reserves a small set of routing numbers that return a fixed result. Use them to build and test against each outcome so you can see how real results will behave. These reserved routing numbers apply across the Risk API, including both the Account Intelligence and Transaction Intelligence models. Sandbox base URL: https://risk-api-sandbox.grailpay.com

There Are No Test Account Numbers

Selection is driven by the routing_number alone. The account number can be any value that passes standard validation — numeric, 17 digits or fewer, and not all zeros. For example, 000000001 paired with any valid account number returns the full-match result. Pairing that same account number with 000000003 returns the high-risk result.

Test Routing Numbers

Routing Number	Scenario	HTTP Status
`000000001`	Low risk, full match	`200`
`000000002`	Medium risk, match not available	`200`
`000000003`	High risk, negative history	`200`
`000000004`	Close taxpayer match	`200`
empty / missing	Validation-style errors	`400`
`999999999`	Upstream unavailable	`503`
Any other value	Falls through to live sandbox decisioning	live

What Each Routing Number Returns

For calls to POST /api/v3/accounts/validate, each reserved routing number returns the following values:

Routing Number	`confidence_score`	`name_match`	`name_match_score`	`taxpayer_number_match`
`000000001`	`0.91`	`yes`	`0.98`	`yes`
`000000002`	`0.53`	`not_available`	`0.0`	`not_available`
`000000003`	`0.12`	`no`	`0.14`	`no`
`000000004`	`0.65`	`not_available`	`0.0`	`close_match`

confidence_score is returned at the top level of the response. name_match, name_match_score, and taxpayer_number_match are returned under decisioning_insights.

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 actions are 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 either action, include it in the actions object of your request payload:

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

Each enabled action runs an additional identity check that contributes directly to the confidence score and surfaces a corresponding attribute in the decisioning_insights object. Enabling name_match returns name_match and name_match_score; enabling taxpayer_number_match returns taxpayer_number_match. 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 an ACH debit or credit will be processed successfully without an operational return. Higher is better — a score of 0.95 indicates high confidence that the account is open, active, and able to transact, 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. As a general guide, the score maps to the following confidence levels:

Confidence Level	Score Range
Very High	`0.90` – `1.00`
Good	`0.70` – `0.89`
OK	`0.40` – `0.69`
Risky	`0.00` – `0.39`

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	What It Means	Why It Matters	Typical Interpretation	Possible Values
`valid_routing_number`	Confirms the routing number belongs to a legitimate, active financial institution.	An invalid routing number will generally cause the payment to fail.	`true` = valid routing number. `false` = do not process without review.	Boolean, `true` / `false`
`name_match`	Compares the provided account owner’s name to the name associated with the account.	Helps confirm the person or business owns the account.	`yes` = positive. `no` = name does not appear to match the account owner; review for possible incorrect information or identity concerns. `not_available` = no comparison possible.	String: `yes`, `no`, `not_available`. Returned only when `name_match` is enabled in the request `actions` object.
`name_match_score`	Measures how closely the names match on a scale from `0.00` to `1.00`.	Provides additional detail beyond a simple yes/no result.	Near `1.00` = strong match. Around `0.80` = minor differences. Lower scores = weak match.	Number, `0.00` to `1.00`. Returns `0.00` when no name was supplied, or when no identity data source could evaluate the name.
`days_since_first_seen`	How long the account has existed in GrailPay’s data network.	Older accounts generally provide more confidence.	Higher values = more established. `-1` = no history available.	Integer. `-1` if unknown.
`days_since_last_transaction`	Number of days since the account was last active.	Active accounts tend to be lower risk than dormant accounts.	Lower values = recently active. Higher values = less recent activity.	Integer. `-1` if unknown.
`positive_transactions_seen`	Indicates successful historical transactions.	Past successful payments increase confidence.	`true` = positive history.	Boolean, `true` / `false`
`negative_transactions_seen`	Indicates returned payments or other negative events.	Past issues may increase risk.	`true` = review more closely.	Boolean, `true` / `false`
`paid_transactions_seen`	Shows whether previously returned transactions were later resolved.	Shows that past payment issues were actively addressed and resolved, which may reduce the concern associated with previous returns.	`true` = past issues resolved.	Boolean, `true` / `false`
`phone_number_present`	Indicates a phone number is associated with the account.	Adds another identity signal.	`true` = slightly stronger identity confidence.	Boolean, `true` / `false`
`account_duplicate`	Shows whether the account has been seen before in GrailPay’s network.	Prior history provides additional context.	`true` = existing account history.	Boolean, `true` / `false`
`taxpayer_number_match`	Compares the provided SSN/EIN with records associated with the account.	Strong identity verification signal.	`yes` = strong match. `close_match` = minor discrepancy. `no` = significant concern. `not_available` = comparison unavailable.	String: `yes`, `no`, `close_match`, `not_available`. Returned only when `taxpayer_number_match` is enabled in the request `actions` object.

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

Sandbox Testing

There Are No Test Account Numbers

Test Routing Numbers

What Each Routing Number Returns

Actions

Response Attributes

Confidence Score

Decisioning Insights

Feedback

When to Submit Feedback

Request Fields

Required Fields

Optional Fields

Usage Recommendations

Questions?

​Overview

​Sandbox Testing

​There Are No Test Account Numbers

​Test Routing Numbers

​What Each Routing Number Returns

​Actions

​Response Attributes

​Confidence Score

​Decisioning Insights

​Feedback

​When to Submit Feedback

​Request Fields

​Required Fields

​Optional Fields

​Usage Recommendations

​Questions?

Overview

Sandbox Testing

There Are No Test Account Numbers

Test Routing Numbers

What Each Routing Number Returns

Actions

Response Attributes

Confidence Score

Decisioning Insights

Feedback

When to Submit Feedback

Request Fields

Required Fields

Optional Fields

Usage Recommendations

Questions?