Retrieve external accounts

Read one payee, list a customer's payees, and look for an existing payee before saving a new one.

This page shows how to read one payee to check its status, and how to list a customer's payees to find one that already exists. Look before you save a new payee:

• Gravv refuses a payee that matches an existing one.
• Deleted and failed payees still count as matches.
• The duplicate check can miss a match when the bank renamed the holder.

Example. Before saving Northwind Supply's account 000555777999 for wires, your app lists the customer's payees with search=000555777999. It finds an ACH payee for that account, so it saves only the wire payee and keeps both ids with their rails.

Retrieve one external account

Send GET /v1/external-accounts/{external_account_id}:

curl --request GET \
     --url https://api.gravv.xyz/v1/external-accounts/1b4e28ba-2fa1-41d2-883f-0016d3cca427 \
     --header 'Api-Key: <API_KEY>'

{
  "data": {
    "account_name": "MAYA CHEN",
    "account_number": "000123456789",
    "account_owner_type": "individual",
    "address": {
      "address_line1": "350 Fifth Avenue",
      "city": "New York",
      "country": "US",
      "postal_code": "10118",
      "state": "NY"
    },
    "currency": "USD",
    "customer_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "date_created": "2026-10-13T22:38:41.310614Z",
    "id": "1b4e28ba-2fa1-41d2-883f-0016d3cca427",
    "institution_name": "JPMorgan Chase Bank",
    "payee_type": "ach_wire",
    "routing_number": "021000021",
    "status": "active"
  },
  "error": null
}

• The response leaves out fields that do not apply to a payee. It does not send them as null.
• status is pending, active, setup_failed, archived or deleted. You can pay only an active payee.
• A setup_failed payee also has error_message. See Update an external account.
• The response does not return the rail you saved an ach_wire payee for. Keep it on your side.
• For an unknown id, the API returns HTTP 400.

List a customer's external accounts

Send GET /v1/external-accounts with these filters:

Filter	Use
customer_id	Returns one customer's payees
search	Matches part of the holder name, account number or phone number, such as search=000555777999
payee_type	Filters by ach_wire, swift, sepa, fps, bank_account or mobile_money
currency	Filters by a currency, such as USD
internal_account_id	Returns payees registered against one of your bank-held accounts
page, items_per_page	Pages through the results

curl --request GET \
     --url 'https://api.gravv.xyz/v1/external-accounts?customer_id=7c9e6679-7425-40de-944b-e07fc1f90ae7&search=000555777999' \
     --header 'Api-Key: <API_KEY>'

There is no status filter, so check status on each item. If an item matches the account and bank you are about to save and is active, reuse its id. If it is setup_failed, correct it instead of saving a new one.

Duplicates

If you save a payee that matches one the customer has, the API returns HTTP 400 with the existing id in data.payee_id (a recipient with the same account name, account number and bank already exists). For US payees, the rail is part of the match, so one account can have one payee per rail. See Add an external account.