---
title: "Add an external account"
description: "Adds a new external account for transfers to accounts that are not created with Gravv."
protocol: rest
method: POST
endpoint: "/v1/external-accounts"
baseUrl: "https://api.gravv.xyz"
group: "External accounts"
auth:
  label: "Api-Key"
  name: "Api-Key"
  in: header
---

# Add an external account

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

Adds a new external account for transfers to accounts that are not created with Gravv.

## Async setup contract

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

- **`200 OK`:** The external account is fully registered with at least one
  partner. The `status` field is `active`. You can initiate transfers immediately.
- **`202 Accepted`:** the external account record is created and a background
  worker calls our partners. The `status` field is `pending`.
  To learn when it changes to `active`, either check the status by calling
  `GET /v1/external-accounts/{external_account_id}` until it is `active`, or
  subscribe to the `payee.setup.*` webhook events.
- **`400 Bad Request`:** Input validation failed. Fix the input and retry.

A duplicate POST with the same `account_number` (or `iban`), `currency`, and
`payee_type` for the same customer is idempotent and returns the existing
record.

## Headers

<ParamField name="Idempotency-Key" header="Idempotency-Key" type="string" required>
  A unique key to prevent duplicate requests.
</ParamField>

## Request Body

<ParamField name="account_name" body="account_name" type="string" required>
  Name of the account holder.
</ParamField>

<ParamField name="customer_id" body="customer_id" type="string" required>
  ID of the customer who owns the external account.
</ParamField>

<ParamField name="payment_rail" body="payment_rail" type="string,null">
  Optional. US payment rail to use when `payee_type` is `ach_wire`. Accepted values: `ach` (ACH transfer) or `wire` (domestic wire). Defaults to `wire` when omitted.

  Possible values: `ach`, `wire`
</ParamField>

### Request Examples

<RequestExample>

```json title="USBankAccount"
{
  "payee_type": "ach_wire",
  "account_number": "4401682860",
  "account_name": "Amina Bello",
  "bank_name": "Example Community Bank",
  "currency": "USD",
  "customer_id": "373556ec-74e5-4cde-909c-b94d864915db",
  "routing_number": "101019644",
  "account_owner_type": "individual",
  "account_type": "savings",
  "address": {
    "address_line1": "1800 N Pole St, Orlando, FL 32801",
    "state": "US-FL",
    "country": "US",
    "postal_code": "32801",
    "city": "Orlando"
  }
}
```

```json title="GlobalBankAccountRecipient"
{
  "payee_type": "bank_account",
  "account_number": "1776218486",
  "account_name": "Amina Bello",
  "bank_name": "Access Bank",
  "currency": "NGN",
  "customer_id": "373556ec-74e5-4cde-909c-b94d864915db",
  "institution_id": "c0cb83fa-8116-4744-8bc8-0c1cba405400"
}
```

```json title="GlobalMobileMoneyRecipient"
{
  "payee_type": "mobile_money",
  "phone_number": "+233241234567",
  "account_name": "Kwame Mensah",
  "bank_name": "MTN Mobile Money",
  "currency": "GHS",
  "customer_id": "373556ec-74e5-4cde-909c-b94d864915db",
  "institution_id": "5c8d94fb-a927-5fed-b19d-1454c8f142a9"
}
```

```json title="SepaRecipient"
{
  "payee_type": "sepa",
  "account_owner_type": "individual",
  "iban": "DE89370400440532013000",
  "account_name": "Anna Schmidt",
  "bank_name": "Deutsche Bank",
  "currency": "EUR",
  "customer_id": "373556ec-74e5-4cde-909c-b94d864915db",
  "address": {
    "address_line1": "Unter den Linden 13",
    "city": "Berlin",
    "state": "Berlin",
    "postal_code": "10117",
    "country": "DE"
  }
}
```

```json title="SwiftRecipientAccountNumber"
{
  "payee_type": "swift",
  "account_owner_type": "individual",
  "account_number": "1245909283",
  "account_name": "Amina Bello",
  "bank_name": "Guaranty Trust Bank (GTBank)",
  "bic": "NG2893A",
  "currency": "USD",
  "customer_id": "373556ec-74e5-4cde-909c-b94d864915db",
  "address": {
    "address_line1": "15 Admiralty Way, Lekki Phase 1",
    "house_building_number": "1 B",
    "address_line2": "Suite 202",
    "city": "Lekki",
    "postal_code": "105102",
    "state": "Lagos",
    "country": "NG"
  }
}
```

```json title="SwiftRecipientIban"
{
  "payee_type": "swift",
  "account_owner_type": "individual",
  "iban": "GB33BUKB20201555555555",
  "account_name": "Amina Bello",
  "bank_name": "Guaranty Trust Bank (GTBank)",
  "bic": "NG2893A",
  "currency": "USD",
  "customer_id": "373556ec-74e5-4cde-909c-b94d864915db",
  "address": {
    "address_line1": "15 Admiralty Way, Lekki Phase 1",
    "house_building_number": "1 B",
    "address_line2": "Suite 202",
    "city": "Lekki",
    "postal_code": "105102",
    "state": "Lagos",
    "country": "NG"
  }
}
```

</RequestExample>

## Responses

| Status | Description |
| --- | --- |
| `200` | The external account is fully registered with our payment partners. The `status` field is `active`. |
| `202` | The external account record is created and registration with our payment partners is still in progress. The `status` field is `pending`. To learn when it changes to `active`, either check the status by calling `GET /v1/external-accounts/{external_account_id}` until it is `active`, or subscribe to the `payee.setup.*` webhook events. |
| `400` | Validation failed. |

### 200 response

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

  <Expandable title="properties">
    <ResponseField name="id" type="string" required>
      External account identifier; use this to fetch or initiate transfers.
    </ResponseField>

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

    <ResponseField name="payee_type" type="string" required>

      Possible values: `ach_wire`, `sepa`, `swift`, `bank_account`, `mobile_money`, `fps`
    </ResponseField>

    <ResponseField name="account_number" type="string,null">
    </ResponseField>

    <ResponseField name="iban" type="string,null">
    </ResponseField>

    <ResponseField name="bic" type="string,null">
    </ResponseField>

    <ResponseField name="routing_number" type="string,null">
    </ResponseField>

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

    <ResponseField name="institution_name" type="string,null">
    </ResponseField>

    <ResponseField name="institution_id" type="string,null">
    </ResponseField>

    <ResponseField name="institution_type" type="string,null">
      Category of financial institution linked to this account.

      Possible values: `bank`, `mobile_money`
    </ResponseField>

    <ResponseField name="institution_country_iso_code" type="string,null">
      ISO 3166-1 alpha-2 country code of the linked institution.
    </ResponseField>

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

    <ResponseField name="phone_number" type="string,null">
    </ResponseField>

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

      <Expandable title="properties">
        <ResponseField name="address_line1" type="string" required>
        </ResponseField>

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

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

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

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

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

      </Expandable>
    </ResponseField>

    <ResponseField name="status" type="string" required>
      `active`: The external account is fully registered with our payment partners and is ready to use. `pending`: Registration is still in progress. To learn when it changes to `active`, either check the status by calling `GET /v1/external-accounts/{external_account_id}` until it is `active`, or subscribe to the external account webhook events.

      Possible values: `active`, `pending`
    </ResponseField>

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

  </Expandable>
</ResponseField>

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

### 202 response

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

  <Expandable title="properties">
    <ResponseField name="id" type="string" required>
      External account identifier; use this to fetch or initiate transfers.
    </ResponseField>

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

    <ResponseField name="payee_type" type="string" required>

      Possible values: `ach_wire`, `sepa`, `swift`, `bank_account`, `mobile_money`, `fps`
    </ResponseField>

    <ResponseField name="account_number" type="string,null">
    </ResponseField>

    <ResponseField name="iban" type="string,null">
    </ResponseField>

    <ResponseField name="bic" type="string,null">
    </ResponseField>

    <ResponseField name="routing_number" type="string,null">
    </ResponseField>

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

    <ResponseField name="institution_name" type="string,null">
    </ResponseField>

    <ResponseField name="institution_id" type="string,null">
    </ResponseField>

    <ResponseField name="institution_type" type="string,null">
      Category of financial institution linked to this account.

      Possible values: `bank`, `mobile_money`
    </ResponseField>

    <ResponseField name="institution_country_iso_code" type="string,null">
      ISO 3166-1 alpha-2 country code of the linked institution.
    </ResponseField>

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

    <ResponseField name="phone_number" type="string,null">
    </ResponseField>

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

      <Expandable title="properties">
        <ResponseField name="address_line1" type="string" required>
        </ResponseField>

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

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

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

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

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

      </Expandable>
    </ResponseField>

    <ResponseField name="status" type="string" required>
      `active`: The external account is fully registered with our payment partners and is ready to use. `pending`: Registration is still in progress. To learn when it changes to `active`, either check the status by calling `GET /v1/external-accounts/{external_account_id}` until it is `active`, or subscribe to the external account webhook events.

      Possible values: `active`, `pending`
    </ResponseField>

    <ResponseField name="date_created" type="string" required>
    </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**