Account Intelligence Global
Overview
Section titled “Overview”Account Intelligence Global validates bank accounts at home and abroad through a single endpoint. You integrate once, send one request body whatever the account’s country, and read one verdict that means the same thing on every account.
POST /api/v3/accounts/validate/globalThe endpoint is offered in two versions. Which one you receive is set by actions.version in the request body, not by
the path you call. Omit it and the request resolves to Standard. Standard covers U.S. bank accounts; International
covers bank accounts outside the United States.
International launches with accounts in Great Britain, and more countries are coming soon.
| Standard (default) | International | |
|---|---|---|
version |
"standard", or omitted |
"international" |
| Accounts | U.S. only | International; Great Britain at launch |
| Input | Bank account required; full identity recommended | Bank account, institution, and the account holder’s identity |
| Output | valid, plus results.confidence_score and results.decisioning_insights |
valid, plus results.account_status and results.name_match |
| Best for | Composable insights that drive tailored workflows | Confirming an international account exists and belongs to your counterparty |
For complete request and response definitions, visit the Account Intelligence Global OpenAPI Documentation.
The Request Body
Section titled “The Request Body”Both versions post the same body to the same path. The body has five parts: client_reference_id, bank_account,
identity, location, and actions. bank_account is always required; what else you send depends on the version.
What Each Version Requires
Section titled “What Each Version Requires”| Part | Standard | International |
|---|---|---|
bank_account |
Required | Required |
identity |
Optional; required for a match action | Required |
location |
Optional | Optional |
actions.version |
"standard", or omitted |
"international" |
actions.name_match, actions.taxpayer_number_match |
Optional | Rejected |
client_reference_id |
Optional | Optional |
Rejected means the request fails with a 422 if the field is present. International always checks the account
holder’s name, so it has no match actions to switch on.
Bank Account and Institution
Section titled “Bank Account and Institution”One structure describes every bank account. The institution is identified by a clearing system and the member ID within it — a routing number in the United States, a sort code in the UK. For account formats that identify the bank themselves, such as an IBAN, the scheme is the clearing system and the account number is repeated as the member ID.
| Field | Type | Description |
|---|---|---|
account_number |
string | Required. U.S.: numeric, 17 digits or fewer, and not all zeros. UK sort code accounts: the eight-digit account number. IBAN: the full IBAN. |
account_type |
string | Optional. checking or savings. |
institution.clearing_system |
string | Required. USABA for U.S. accounts. GBDSC (sort code) or IBAN for UK accounts. |
institution.member_id |
string | Required. The nine-digit routing number for USABA, the sort code for GBDSC, or the full IBAN again for IBAN. |
institution.country_code |
string | Required. The ISO 3166-1 alpha-2 country code, US or GB. Decides which version the account can use. |
Spaces are removed from account_number and member_id, and country codes are uppercased, before the request is
validated. A GB IBAN must be valid, and must match member_id exactly; a request where the two differ is rejected with
a 422.
Identity
Section titled “Identity”The identity object describes the account holder. It accepts an individual or an organization; the two are
mutually exclusive, and a request that includes both is rejected. Identity is optional on Standard and required on
International, where the account holder is what gets verified.
identity.individual
Section titled “identity.individual”| Field | Type | Description |
|---|---|---|
first_name, last_name |
string | Required when individual is sent. 100 characters or fewer each. |
prefix, middle_name, suffix |
string | Optional. |
date_of_birth |
string | Optional. YYYY-MM-DD. |
phone_number |
string | Optional. E.164 format, such as +447700900123. |
email |
string | Optional. |
tax_id, tax_id_type |
string | Optional. Send both or neither. On Standard, tax_id_type is ssn, itin, or ein. |
identity.organization
Section titled “identity.organization”| Field | Type | Description |
|---|---|---|
legal_name |
string | Required when organization is sent. 100 characters or fewer. |
dba |
string | Optional. The “doing business as” name. |
tax_id, tax_id_type |
string | Optional. Send both or neither. On Standard, tax_id_type is ein. |
On Standard, identity becomes required when you switch on a match action: a name for name_match, and a tax_id for
taxpayer_number_match. Even when it is optional, the more identity data you send, the more meaningful the results.
Location
Section titled “Location”Location is optional on both versions. It describes where the account holder is, and is used alongside the account and identity data.
| Field | Type | Description |
|---|---|---|
address.line_1, line_2, line_3 |
string | Street lines. |
address.city |
string | City or town. |
address.region |
string | State, county, or other subdivision. |
address.postal_code |
string | Postal code. |
address.country_code |
string | ISO 3166-1 alpha-2. Defaults to institution.country_code when omitted. |
ip_address |
string | The account holder’s IP address. |
geolocation.latitude, geolocation.longitude |
number | Decimal degrees. Send both when you send geolocation. |
Actions
Section titled “Actions”The optional actions object selects the version and, on Standard, switches on additional identity checks.
version:"standard"or"international". Defaults to"standard"when omitted. Any other value, including"lite", is rejected with a422.name_match: Compares the name inidentitywith the account holder’s name on file. Standard only.taxpayer_number_match: Compares thetax_idinidentitywith the tax ID on file. Standard only.
On Standard, each enabled action adds an attribute to results.decisioning_insights and contributes to the confidence
score, just as it does on Account Intelligence.
Example Request
Section titled “Example Request”An International request for a UK account held by an individual. For complete request definitions and more examples, see the Account Intelligence Global OpenAPI Documentation.
{ "client_reference_id": "CLIENT-REF-12346", "bank_account": { "account_number": "31926819", "institution": { "clearing_system": "GBDSC", "member_id": "601613", "country_code": "GB" } }, "identity": { "individual": { "first_name": "Emma", "last_name": "Clarke" } }, "actions": { "version": "international" }}The Response
Section titled “The Response”Every successful response has the same five top-level fields, whichever version you asked for. The first four are
common to both. The fifth, results, holds the version-specific detail, and version tells you how to read it.
Read valid first. It means the same thing on every version, so you can branch on it without knowing which
version produced it. Then read results for the detail behind it.
| Field | Type | Description |
|---|---|---|
version |
string | The version that produced the response: standard or international. |
request_id |
string (UUID) | Identifies this validation. The same value is returned in the X-RI-Request-ID response header. Keep it for support. |
client_reference_id |
string, null | The value you sent, or null if you sent none. |
valid |
string | The verdict on the account: likely, unlikely, or indeterminate. |
results |
object | Version-specific detail. Always present; its shape follows version. |
| Version | results contains |
|---|---|
standard |
confidence_score and decisioning_insights |
international |
account_status and name_match |
Reading a Standard Response
Section titled “Reading a Standard Response”Standard returns a calibrated confidence score and the explainable insights behind it — the same score and insights
as Standard on Account Intelligence, nested under results, with a
valid verdict on top.
On Standard, valid is derived from the confidence score, so a Standard response reads like an International one:
| Confidence Level | Score Range | valid |
|---|---|---|
| Very High | 0.90 – 1.00 |
likely |
| Good | 0.70 – 0.89 |
likely |
| OK | 0.40 – 0.69 |
indeterminate |
| Risky | 0.00 – 0.39 |
unlikely |
An invalid routing number overrides the score: when decisioning_insights.valid_routing_number is false, valid is
unlikely. For example, a score of 0.87 falls in the Good band, so valid is likely.
results.confidence_score
Section titled “results.confidence_score”A calibrated probability from 0.00 to 1.00 that an ACH payment will settle without an operational return. Higher is
better. See Confidence Score.
results.decisioning_insights
Section titled “results.decisioning_insights”Structured, explainable attributes you can feed directly into your risk engine. name_match, name_match_score, and
taxpayer_number_match appear only when the matching action is enabled on the request. See
Decisioning Insights for what each attribute
means.
Reading an International Response
Section titled “Reading an International Response”International answers two questions about a UK bank account: does it exist, and does it belong to the person or
business you named? valid and results.account_status answer the first; results.name_match answers the second.
{ "version": "international", "request_id": "0192f3c2-7a4e-7c3b-9f1e-1b2c3d4e5f60", "client_reference_id": "CLIENT-REF-12346", "valid": "likely", "results": { "account_status": "active", "name_match": "yes" }}International returns no confidence score, no decisioning insights, and no supplemental codes.
valid and results.account_status
Section titled “valid and results.account_status”account_status is the reason behind valid. Both are decided together by GrailPay’s model from the account
data, so they usually pair as shown below:
account_status |
Usually paired with | What It Means |
|---|---|---|
active |
likely |
The account exists and is open. |
closed |
unlikely |
The account existed but is closed. |
not_found |
indeterminate |
No record of the account was found. |
indeterminate |
indeterminate |
The account could not be assessed. |
not_found is not a verdict that the account is bad. A new account, or one outside the data available for its bank,
may have no record yet — which is why it pairs with indeterminate rather than unlikely. Treat it as a reason to
verify the account another way, not to reject it.
results.name_match
Section titled “results.name_match”| Value | What It Means |
|---|---|
yes |
The name you supplied is the account holder. Close matches — a nickname, an initial, a minor spelling variance — count as yes. |
no |
The name you supplied does not match the account holder. |
not_available |
Ownership could not be assessed for this account. |
These are the same values as the name_match insight on Standard.
Read Both Fields When Ownership Matters
Section titled “Read Both Fields When Ownership Matters”valid tracks the account, not the owner. An open account whose holder does not match is still a valid account, so
read both fields whenever it matters who owns the account.
valid |
account_status |
name_match |
What It Means |
|---|---|---|---|
likely |
active |
yes |
The account is open and belongs to your counterparty. |
likely |
active |
no |
The account is open, but the name you supplied is not on it. Treat this as an ownership mismatch, not an invalid account. |
unlikely |
closed |
no |
The account is closed. |
Errors
Section titled “Errors”Every error returns a JSON body. Error bodies do not carry the common response fields, but every response, successful
or not, carries the X-RI-Request-ID header, so you can always quote the request to support.
| HTTP Status | When |
|---|---|
401 |
The access token is missing, invalid, expired, or revoked. |
409 |
The X-Idempotency-Key header was already used with a different endpoint or a different request body. |
422 |
The request failed validation, including a version that is not available for the account’s country. |
429 |
Too many requests. Wait for the time given in the Retry-After header before retrying. |
503 |
Validation is temporarily unavailable. The body is {"message": "…"}. Retry the request. |
Validation Errors
Section titled “Validation Errors”A 422 returns an errors array. Each entry gives the type of problem (missing or value_error), the field in
loc, a readable msg, and the value you sent in input. Several fields can fail in one response, so read every
entry rather than only the first.
{ "errors": [ { "type": "value_error", "loc": "body.actions.version", "msg": "standard is only available for US accounts", "input": "standard" } ]}These are the rules specific to Account Intelligence Global. Each error’s loc is the field path prefixed with
body., such as body.actions.version.
| Field | msg |
|---|---|
actions.version |
standard is only available for US accounts |
actions.version |
international is not available for US accounts |
bank_account.institution.clearing_system |
Clearing system must be USABA for standard |
bank_account.institution.clearing_system |
Clearing system is not valid for the country |
bank_account.institution.member_id |
member_id must equal account_number for self-clearing schemes |
identity |
identity.individual or identity.organization is required for international |
actions.name_match |
actions.name_match is not supported when actions.version is international |
actions.taxpayer_number_match |
actions.taxpayer_number_match is not supported when actions.version is international |
Match on loc and type in your code; msg is for people, and its wording may change.
Sandbox Testing
Section titled “Sandbox Testing”Sandbox base URL: https://risk-api-sandbox.grailpay.com
Standard
Section titled “Standard”Standard requests use the same
Standard test routing numbers as
POST /api/v3/accounts/validate. Send the routing number as bank_account.institution.member_id, with
clearing_system set to USABA and country_code set to US, paired with any account number that passes
validation. Each returns a fixed result:
| Routing Number | results.confidence_score |
valid |
|---|---|---|
000000001 |
0.91 |
likely |
000000002 |
0.53 |
indeterminate |
000000003 |
0.12 |
unlikely |
000000004 |
0.65 |
indeterminate |
999999999 |
— | Returns a 503 |
The name_match, name_match_score, and taxpayer_number_match each one returns are listed with the
Standard test routing numbers. The Lite
test routing numbers do not apply, because Lite is not available on this endpoint.
International
Section titled “International”In the sandbox, International requests return a fixed result chosen by a test scenario, so you can rehearse every
outcome with any UK account. To pick a scenario, set client_reference_id to scenario: followed by the scenario
name, for example "client_reference_id": "scenario:closed".
client_reference_id |
valid |
account_status |
name_match |
|---|---|---|---|
scenario:active-match |
likely |
active |
yes |
scenario:active-no-match |
likely |
active |
no |
scenario:active-name-indeterminate |
likely |
active |
not_available |
scenario:closed |
unlikely |
closed |
no |
scenario:not-found |
indeterminate |
not_found |
not_available |
scenario:indeterminate |
indeterminate |
indeterminate |
not_available |
Each scenario returns a 200. A request with no scenario, or with a scenario name not in this table, returns the
scenario:active-match result. The client_reference_id comes back in the response exactly as you sent it.
The request is still validated first, so it needs a well-formed UK account and an identity, and an invalid one is
rejected with a 422 just as it would be in production.
Usage Recommendations
Section titled “Usage Recommendations”- Integrate once against
POST /api/v3/accounts/validate/global, using the same request body for every account. - Set
actions.versionto"standard"for scoring and insights on U.S. accounts, or"international"for international accounts. Omitting it gives you Standard. - Read
validfirst. It means the same thing on every version. Then readresults, whose shape followsversion. - On International, read
name_matchalongsidevalidwhenever it matters who owns the account. - Treat
not_foundas a reason to verify the account another way, not as proof the account is bad. - Send U.S. routing numbers as
clearing_system: "USABA", with the routing number inmember_id. For a GB IBAN, send the full IBAN as bothaccount_numberandmember_id. - On Standard, send as much identity data as you have; it makes the score and insights more meaningful.
- Keep the
request_idfrom each response for support and traceability. - Test every outcome in the sandbox before you go live: the Standard test routing numbers for U.S. accounts, and the scenarios for UK accounts.
Questions?
Section titled “Questions?”If you’re encountering any issues, please reach out to support@grailpay.com.
Maintained by EkLine

