Skip to content
Select theme

Account Intelligence Global

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/global

The 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.


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.

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.

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.

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.

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.
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 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.

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 a 422.
  • name_match: Compares the name in identity with the account holder’s name on file. Standard only.
  • taxpayer_number_match: Compares the tax_id in identity with 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.

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"
}
}

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

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.

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.

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.


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.

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.

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.

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.

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.

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 base URL: https://risk-api-sandbox.grailpay.com

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.

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.


  • Integrate once against POST /api/v3/accounts/validate/global, using the same request body for every account.
  • Set actions.version to "standard" for scoring and insights on U.S. accounts, or "international" for international accounts. Omitting it gives you Standard.
  • Read valid first. It means the same thing on every version. Then read results, whose shape follows version.
  • On International, read name_match alongside valid whenever it matters who owns the account.
  • Treat not_found as 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 in member_id. For a GB IBAN, send the full IBAN as both account_number and member_id.
  • On Standard, send as much identity data as you have; it makes the score and insights more meaningful.
  • Keep the request_id from 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.

If you’re encountering any issues, please reach out to support@grailpay.com.


Maintained by EkLine