# Account Intelligence Global

## 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/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](/api/risk/#tag/account-intelligence/POST/api/v3/accounts/validate/global).

:::note
Account Intelligence Global is a separate endpoint from [Account Intelligence](/docs/risk/bank-accounts/account-intelligence)
(`POST /api/v3/accounts/validate`), which validates U.S. accounts only. Lite is available only on that endpoint.
:::

---

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

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

:::caution
A version that does not fit the account's country is a `422`, never a silent downgrade. Send `international` for a U.S.
account, or `standard` for a UK account, and the request is rejected on `actions.version`.
:::

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

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`

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

| 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

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

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](/docs/risk/bank-accounts/account-intelligence#actions).

### 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](/api/risk/#tag/account-intelligence/POST/api/v3/accounts/validate/global).

```json
{
  "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

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

Standard returns a calibrated confidence score and the explainable insights behind it — the same score and insights
as Standard on [Account Intelligence](/docs/risk/bank-accounts/account-intelligence), nested under `results`, with a
`valid` verdict on top.

### `valid`

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`

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](/docs/risk/bank-accounts/account-intelligence#confidence-score).

### `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](/docs/risk/bank-accounts/account-intelligence#decisioning-insights) for what each attribute
means.

---

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

```json
{
  "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`

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

| 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

`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

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

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.

```json
{
  "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

Sandbox base URL: `https://risk-api-sandbox.grailpay.com`

### Standard

Standard requests use the same
[Standard test routing numbers](/docs/risk/bank-accounts/account-intelligence#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](/docs/risk/bank-accounts/account-intelligence#standard-test-routing-numbers). The Lite
test routing numbers do not apply, because Lite is not available on this endpoint.

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

:::caution
Scenarios apply only in the sandbox. In production, a `client_reference_id` starting with `scenario:` is treated as an
ordinary reference, and the account is validated live.
:::

---

## Usage Recommendations

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

---

## Questions?

If you're encountering any issues, please reach out to [support@grailpay.com](mailto:support@grailpay.com).

---