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.
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.
To enable name matching, include the following in your request payload:
{
"actions": {
"account_intelligence": {
"version": "v3",
"name_match": true
}
}
}
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.
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 |
return_code | string | The ACH return code received |
name_match_requested | boolean | Whether name matching was enabled in the original request |
| 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 |
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].
