---
title: "Verify an external account"
description: "Resolves and verifies a recipient's account with the destination institution before you add them as an external account. Use it to confirm the account holder's name and that the account is reachable, so you can show the resolved name and avoid failed transfers."
protocol: rest
method: POST
endpoint: "/v1/external-accounts/verify"
baseUrl: "https://api.gravv.xyz"
group: "External accounts"
auth:
  label: "Api-Key"
  name: "Api-Key"
  in: header
---

# Verify an external account

<Endpoint method="POST" path="/v1/external-accounts/verify" />

Resolves and verifies a recipient's account with the destination
institution before you add them as an external account. Use it to
confirm the account holder's name and that the account is reachable, so
you can show the resolved name and avoid failed transfers.

Pass at least one identifier: `account_number`, `iban`, `phone`, or
`clabe`. The service detects the account type, validates its format,
then resolves the name with the institution.

- **`is_verified: true`** — the account resolved. `account_name` holds
  the confirmed holder name.
- **`is_verified: false`** — the account could not be resolved. Any
  institutions that matched the identifier are returned in
  `institutions` so the user can pick one and retry.

Verification is supported for bank accounts and mobile money today.
Other types (IBAN, SWIFT) return `is_verified: false`.

## Request Body

<ParamField name="account_number" body="account_number" type="string">
  Bank account number.
</ParamField>

<ParamField name="institution_id" body="institution_id" type="string">
  Institution UUID from GET /v1/external-accounts/institutions. Speeds up and disambiguates resolution.
</ParamField>

<ParamField name="phone" body="phone" type="string">
  Mobile money number in international format.
</ParamField>

<ParamField name="iban" body="iban" type="string">
</ParamField>

<ParamField name="bic" body="bic" type="string">
</ParamField>

<ParamField name="clabe" body="clabe" type="string">
  Mexican CLABE account number.
</ParamField>

<ParamField name="routing_number" body="routing_number" type="string">
</ParamField>

<ParamField name="country_code" body="country_code" type="string">
  ISO 3166-1 alpha-2 country code.
</ParamField>

<ParamField name="account_owner_type" body="account_owner_type" type="string">
  Beneficiary owner type. Lets the institution pick the right flow for business versus individual recipients.

  Possible values: `individual`, `business`
</ParamField>

### Request Examples

<RequestExample>

```json title="GlobalBankAccount"
{
  "account_number": "1776218486",
  "institution_id": "c0cb83fa-8116-4744-8bc8-0c1cba405400",
  "country_code": "NG"
}
```

```json title="MobileMoney"
{
  "phone": "+233241234567",
  "institution_id": "5c8d94fb-a927-5fed-b19d-1454c8f142a9",
  "country_code": "GH"
}
```

</RequestExample>

## Responses

| Status | Description |
| --- | --- |
| `200` | Verification result. Check `is_verified` for the outcome. |
| `400` | No account identifier supplied, or the identifier failed format validation. |

### 200 response

<ResponseField name="data" type="object">

  <Expandable title="properties">
    <ResponseField name="is_verified" type="boolean" required>
      True when the account resolved with the institution.
    </ResponseField>

    <ResponseField name="account_name" type="string">
      Resolved account holder name. Present when is_verified is true.
    </ResponseField>

    <ResponseField name="account_number" type="string" required>
    </ResponseField>

    <ResponseField name="account_status" type="string">

      Possible values: `active`, `inactive`, `blocked`
    </ResponseField>

    <ResponseField name="account_type" type="string">
    </ResponseField>

    <ResponseField name="bank_name" type="string">
    </ResponseField>

    <ResponseField name="bank_code" type="string">
    </ResponseField>

    <ResponseField name="address" type="any">
    </ResponseField>

    <ResponseField name="institutions" type="array,null">
      Candidate institutions that matched the identifier. Returned when is_verified is false so the caller can disambiguate and retry.
    </ResponseField>

  </Expandable>
</ResponseField>

<ResponseField name="error" type="any">
</ResponseField>

### 400 response

<ResponseField name="data" type="any">
</ResponseField>

<ResponseField name="error" type="string">
</ResponseField>

## Authorization

- **ApiKeyAuth**