---
title: "External accounts and counterparties"
description: "Learn how external accounts relate to counterparties, how accounts take part in transfers, and what you can add or amend after registration."
url: "/guides/transfers/external-accounts/first-party-and-third-party-accounts/"
index: "/llms.txt"
---

# External accounts and counterparties

An external account is a bank account or crypto wallet outside Nodu that you register for [transfers](/guides/transfers/how-transfers-work/index.md). Its owner is the customer or someone else, and it takes one of two sides in a transfer. Learn both before you [find the destinations and requirements](/guides/transfers/external-accounts/destinations-and-requirements/index.md) of an account or [declare the originator of a crypto funding](/guides/transfers/external-accounts/declare-the-originator-of-a-crypto-funding/index.md).

## External accounts and counterparties

| Object | What it is | What it holds |
|---|---|---|
| External account | The bank account or crypto wallet itself. | A `paymentRail`, which is the bank payment scheme or blockchain network of the account. A `currency`. The `accountRequisites`: for example an IBAN, or the address of a crypto wallet. |
| Counterparty | The person or business that owns an external account, when the owner is not the customer. | A `type` (`individual` or `business`), a name, an address and identity details. |

You register both objects for a particular customer. One counterparty can own several external accounts, for example a supplier with a bank account and a crypto wallet. You use the `id` of the external account when you create a transfer.

The account details depend on the rail. One rail can accept more than one scheme, which is a set of account details. For example, Faster Payments accepts a sort code with an account number (the scheme `bban`) or an IBAN (the scheme `iban`). [Get external account requirements](/api/tag/external-accounts/get-v1-external-accounts-requirements.md) returns the schemes and their fields for a customer: see [Build the form](/guides/transfers/external-accounts/destinations-and-requirements/index.md#build-the-form).

## First-party and third-party accounts

Every external account has an owner. You state the owner with `selfOwned` when you create the account.

| | First-party account | Third-party account |
|---|---|---|
| The account belongs to | The customer. | Someone else, such as a supplier or a family member. |
| `selfOwned` | `true` | `false` |
| `counterparty` | Leave it out. Nodu takes the owner's details from the customer's own profile. | Required. Send the details of a new counterparty, or the `id` of an existing one: see [below](#create-the-counterparty-with-the-account-or-reuse-one). |

You cannot change `selfOwned` after you create the account.

A transfer that uses a third-party account, on either side, must carry a payment message in `destination.message`. The message has 6 to 140 characters. On a bank rail, the recipient sees it as the reference text of the payment. Without it, Nodu refuses the transfer with a validation error on `destination.message`.

For a third-party crypto wallet, Nodu also needs to know who controls it: see [Travel Rule: what Nodu needs to know, and why](/guides/transfers/travel-rule/what-nodu-needs-to-know/index.md).

## Create the counterparty with the account, or reuse one

For a third-party account, the request to [create an external account](/api/tag/external-accounts/post-v1-external-accounts.md) carries a `counterparty` object. It works in one of two ways:

- **Create a new counterparty in the same request.** Send `counterparty.type` and the counterparty's details. Nodu creates the counterparty together with the external account. You can add `counterparty.clientReferenceId`, your own reference for the counterparty. Nodu refuses a second counterparty with the same reference.
- **Reuse an existing counterparty.** Send `counterparty.id`. Next to `id`, you can send only details that the counterparty still lacks: `address`, `registrationNumber`, `dateOfBirth`, `placeOfBirth`, `idDocNumber` and `occupation`. If you also send `type`, `firstName`, `lastName`, `companyName` or `clientReferenceId`, Nodu refuses the request with a validation error.

The response contains the `counterparty` with its `id`. Store the `id` to reuse the counterparty for the owner's next account.

This request creates a counterparty and a US bank account for it:

```bash
curl https://api.sandbox.nodu.fi/v1/external-accounts \
  --header 'Authorization: Bearer <your-api-key>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <new-uuid>' \
  --data '{
    "customerId": "019634b8-f479-7001-84ce-2e15ced821e2",
    "selfOwned": false,
    "counterparty": {
      "type": "individual",
      "firstName": "John",
      "lastName": "Smith",
      "address": {
        "country": "US",
        "addressLine1": "1 Main St",
        "city": "New York",
        "state": "NY",
        "postalCode": "10001"
      }
    },
    "paymentRail": "ach",
    "currency": "usd",
    "accountRequisites": {
      "bankCountry": "US",
      "aba": "021000021",
      "accountNumber": "12345678"
    }
  }'
```

This request registers a UK bank account for an existing counterparty:

```bash
curl https://api.sandbox.nodu.fi/v1/external-accounts \
  --header 'Authorization: Bearer <your-api-key>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <new-uuid>' \
  --data '{
    "customerId": "019634b8-f479-7001-84ce-2e15ced821e2",
    "selfOwned": false,
    "counterparty": {
      "id": "019ab6fd-a337-7aaf-9847-138efd21e3a6"
    },
    "paymentRail": "faster_payments",
    "currency": "gbp",
    "accountRequisites": {
      "bankCountry": "GB",
      "sortCode": "040004",
      "accountNumber": "12345678"
    }
  }'
```

You can also create a counterparty on its own, before any account, with [Create a counterparty](/api/tag/external-accounts/post-v1-counterparties.md).

## The two sides of a transfer

An external account takes one of two roles in a transfer:

- **Beneficiary side**: the account receives the payout. This is the usual role, and the default.
- **Originator side**: the account sends crypto that funds a transfer. You register a third-party account for this side when someone else sends crypto for your customer: see [Declare who sends incoming crypto](/guides/transfers/external-accounts/declare-the-originator-of-a-crypto-funding/index.md).

A transfer names the crypto wallet that funds it in `source.externalAccountId`. You send this field in two cases:

- A third party sends the crypto. Send the third-party account registered for the originator side.
- The customer sends the crypto from their own wallet at an exchange or custodian. Send the customer's first-party account for that crypto wallet: see [Wallets at an exchange or custodian (hosted)](/guides/transfers/travel-rule/wallets-at-an-exchange-or-custodian/index.md).

When the customer sends crypto from their own self-custody wallet, leave `source.externalAccountId` out.

Incoming bank payments need no originator declaration. You do not register the bank account that a customer pays from.

The field `supportedSides` lists the sides for which Nodu has validated the account. When you send it, Nodu checks the account against the requirements of each side. If the account does not meet them, the request fails with a validation error that names the missing fields. Without the field, Nodu validates the beneficiary side only. The originator side usually needs more details about the counterparty.

[Validate an external account for a transfer side](/api/tag/external-accounts/get-v1-external-accounts-externalaccountid-validation.md) checks an existing account against one side. It returns the fields that are missing.

## Statuses

The statuses in this table apply to external accounts. A counterparty uses `active` and `archived` in the same way.


| `status` | Meaning | What you do |
|---|---|---|
| `active` | You can use the object. | Nothing. |
| `update_required` | Nodu's requirements changed after Nodu validated the external account. | Add the missing details. Then call [Update an external account](/api/tag/external-accounts/patch-v1-external-accounts-externalaccountid.md) with `supportedSides`, so that Nodu validates the account again. The account then returns to `active`. |
| `archived` | The object is archived. | Create a new object if you still need one. |

Nodu refuses a new transfer that uses an external account whose `status` is not `active`.

## What you can add or amend later

After you create an external account, you can add details that it lacks and amend a few others. For example, before a crypto wallet that you registered earlier can send crypto on the originator side, you can add where it is held and the counterparty details that the side needs. The details that route the money are fixed.

| Object | You can add or amend | You cannot change |
|---|---|---|
| External account | `alias`, a display name of your choice. `supportedSides`, to have the account validated for another side. For a crypto wallet, `accountRequisites.walletType` and `accountRequisites.vaspId`, which say where the crypto wallet is held: see [Declare an existing crypto wallet](#declare-an-existing-crypto-wallet). For a third-party account, the missing details of its counterparty. | `selfOwned`, `paymentRail`, `currency`, and the routing details in `accountRequisites`, such as the IBAN or the address of the crypto wallet. |
| Counterparty | `address`, `registrationNumber`, `dateOfBirth`, `placeOfBirth`, `idDocNumber` and `occupation`. | `type`, `firstName`, `lastName`, `companyName` and `clientReferenceId`. |

- To change a routing detail, archive the external account. Then create a new external account with the updated details.
- [Update a counterparty](/api/tag/external-accounts/patch-v1-counterparties-counterpartyid.md) replaces each supplied value, including individual fields inside `address`. Omitted fields retain their values; this endpoint does not clear fields. The update affects every external account owned by that counterparty.
- To add details about a third-party account's counterparty, send them in the request's `counterparty` object when you call [Update an external account](/api/tag/external-accounts/patch-v1-external-accounts-externalaccountid.md). A first-party account has no counterparty. If you send `counterparty` for a first-party account, Nodu refuses the request with `rule=cannot_enrich_self_owned_external_account`.

### Complete an account that needs an update

1. Retrieve the account and identify every side you still need in `supportedSides`.
2. [Validate the account for each side](/api/tag/external-accounts/get-v1-external-accounts-externalaccountid-validation.md) to find missing fields.
3. Update the permitted details, then send the complete `supportedSides` list with [Update an external account](/api/tag/external-accounts/patch-v1-external-accounts-externalaccountid.md) to validate it again.
4. Use the account for new transfers only after the returned `status` is `active`.

For example, if the stored address is `{"country":"GB","city":"London","postalCode":"SW1A 1AA"}`, a counterparty patch of `{"address":{"postalCode":"SW1A 2AA"}}` changes only the postal code. The country and city remain. Before updating a shared counterparty, account for every external account that uses its details.

### Declare an existing crypto wallet

To add or change the [custody declaration](/guides/transfers/reference/external-account-requirements/index.md#crypto-wallet-custody) on an existing crypto wallet, call [Update an external account](/api/tag/external-accounts/patch-v1-external-accounts-externalaccountid.md):

```bash
curl --request PATCH 'https://api.sandbox.nodu.fi/v1/external-accounts/<external-account-id>' \
  --header 'Authorization: Bearer <your-api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "accountRequisites": {"walletType": "hosted", "vaspId": "<vasp-id>"}
  }'
```

The rules:

- Nodu replaces `walletType` and `vaspId` together. To keep the current `vaspId`, send it again.
- To remove the declaration, send `walletType=unknown`. Nodu then also removes `vaspId`.
- You cannot change the address of the crypto wallet. Nodu refuses a request that contains `wallet`.

## Archive an account or a counterparty

[Archive an external account](/api/tag/external-accounts/delete-v1-external-accounts-externalaccountid.md) removes the account from use. [Archive a counterparty](/api/tag/external-accounts/delete-v1-counterparties-counterpartyid.md) also archives every external account of that counterparty.

- Nodu refuses an update to an archived object. If you need the account again, create a new one.
- Existing transfers keep their original account details.
- [List external accounts](/api/tag/external-accounts/get-v1-external-accounts.md) and [List counterparties](/api/tag/external-accounts/get-v1-counterparties.md) leave archived objects out, unless you ask for them with `statuses[]=archived`.

## Next steps

- [Find destinations and requirements](/guides/transfers/external-accounts/destinations-and-requirements/index.md): find the fields of the external account that a transfer pays out to.
- [Declare who sends incoming crypto](/guides/transfers/external-accounts/declare-the-originator-of-a-crypto-funding/index.md): declare a third party that sends crypto for your customer.
- [External account requirements by rail](/guides/transfers/reference/external-account-requirements/index.md): the fields that the most common rails need.
- [Simulate funding in the sandbox](/guides/sandbox/simulate-funding/index.md): test a transfer to an external account.
