---
title: "External Accounts overview"
description: "Manage recipients outside Gravv."
---

# External Accounts overview

Use the External Accounts API to add and verify transfer recipients, retrieve external accounts, and discover supported institutions.

<CardGroup cols={2}>
  <Card title="Browse external account endpoints" icon="code" href="/api-reference/external-accounts/post-v1-external-accounts">
    Add an external account or browse the operations in this category.
  </Card>
  <Card title="External accounts guide" icon="book" href="/platform/external-accounts/overview">
    Review recipient setup and verification flows.
  </Card>
</CardGroup>

## How it works

External accounts are recipient bank accounts, mobile-money accounts, or other destinations **outside** Gravv that your customers send money to. The recommended flow is:

1. **Verify first** — call [`POST /v1/external-accounts/verify`](/api-reference/external-accounts/post-v1-external-accounts-verify) with at least one identifier (`account_number`, `iban`, `phone`, or `clabe`) to resolve the account holder's name with the destination institution before saving the recipient. This lets you show the resolved name to your user and avoid failed transfers.
2. **Add the recipient** — call [`POST /v1/external-accounts`](/api-reference/external-accounts/post-v1-external-accounts) to register the account with Gravv's payment partners.
3. **Transfer** — once the external account is `active`, use it as the destination in the [Transfers API](/api-reference/transfer/overview).

## Async registration contract

Registering an external account with payment partners runs asynchronously. The response status code tells you the outcome:

| Response | Meaning |
|---|---|
| `200 OK` | Fully registered with at least one partner — `status` is `active`, transfers can start immediately |
| `202 Accepted` | Registration is still in progress — poll [`GET /v1/external-accounts/{external_account_id}`](/api-reference/external-accounts/get-v1-external-accounts-external-account-id) until `status` becomes `active` |

You can also subscribe to [external account webhook events](/platform/webhooks/external-account-events) instead of polling.

## Endpoints

| Endpoint | Description |
|---|---|
| [`POST /v1/external-accounts`](/api-reference/external-accounts/post-v1-external-accounts) | Add an external account (async partner registration) |
| [`GET /v1/external-accounts`](/api-reference/external-accounts/get-v1-external-accounts) | List external accounts with pagination |
| [`POST /v1/external-accounts/verify`](/api-reference/external-accounts/post-v1-external-accounts-verify) | Resolve and verify a recipient account before adding it |
| [`GET /v1/external-accounts/{external_account_id}`](/api-reference/external-accounts/get-v1-external-accounts-external-account-id) | Retrieve a single external account and its registration `status` |
| [`GET /v1/external-accounts/institutions`](/api-reference/external-accounts/get-v1-external-accounts-institutions) | List supported financial institutions |

## Authentication

All requests use `https://api.gravv.xyz/v1/` and authenticate with the `Api-Key` header. Write requests require an `Idempotency-Key` header — the playground generates one automatically and lets you replace it.