---
api: 'Business API'
---

# Create a counterparty

Create a new counterparty to transact with.

### Revtags in Sandbox

In the Sandbox environment, you cannot add real people and businesses as Revolut counterparties.
To help you simulate adding counterparties using Revtag, we created some test accounts of profile type `personal` that you can use.

<details id='test-accounts-for-sandbox'>
  <summary> 
  <b>Test accounts for Sandbox</b>
  </summary>

  To add a counterparty via Revtag, use one of these pairs for the `name` and `revtag` fields respectively:
  - `Test User 1` & `john1pvki`
  - `Test User 2` & `john2pvki`
  -    ...
  - `Test User 9` & `john9pvki`

</details>

### Address field recommendations

Some payment rails may have stricter requirements regarding the `address` field – for example, by also requiring the `region` field.  
This is why we recommend that you use **all** available address fields (including `street_line1`, `region` and `city`) when creating a counterparty.

This significantly reduces the risk of any disruption to payments made via the API.

### Multiple counterparties with the same details

You cannot create multiple counterparties with the same Revtag.
This restriction does not apply to other details. 
For example:
- **Revtag**: If you've already added `johnsmith` as a Revolut counterparty, you can't add another counterparty with the `johnsmith` Revtag.
  If you try to do so, you'll get an error.
- **Other details**: If you've added John Smith as an individual UK counterparty using GBP with `sort_code=54-01-05` and `account_no=12345678`, you can still use the same details to create another counterparty.

### Counterparty name

When creating a counterparty, ensure that you use the correct field to define the counterparty's name.

<table>
  <thead>
    <tr>
      <th rowSpan="2"> Counterparty type</th>
      <th colSpan="2">Name field to use when added with:</th>
    </tr>
    <tr>
      <th>Revtag</th>
      <th>Other details</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <th>Individual</th>
      <td><code>name</code> (string)</td>
      <td><code>individual_name</code> (<b>object</b> with string subfields for first and last name)</td>
    </tr>
    <tr>
      <th>Company</th>
      <td><code>name</code> (string)</td>
      <td><code>company_name</code> (string)</td>
    </tr>
  </tbody>
</table>

---

For more information, see the guides: [Create a counterparty](/docs/guides/manage-accounts/counterparties/create-a-counterparty).

## Endpoint

POST `/counterparty`

## Request body

Counterparty to add

### Attributes

- `profile_type` (enum, optional)
    The type of the Revolut profile.
    Indicates whether the counterparty is a personal or business account.
    Provide it when adding a Revolut counterparty via Revtag.
    Possible enum values:

    - `personal`
    - `business`
- `revtag` (string, optional)
    The [Revtag](https://help.revolut.com/help/transfers/internal-transfers/username-payments/revtags/) of the counterparty to add.
- `name` (string, optional)
    The name of the counterparty, provided when the counterparty is being added via **Revtag**.
    
    If specified, `individual_name` and `company_name` must be empty.
    
    :::note
    The name that you provide must match or closely match the actual name associated with the account that you're trying to add.
    Otherwise, the creation fails and a `404` error is returned.
    :::
- `company_name` (string, optional)
    The name of the counterparty, provided when the counterparty is a **company** (business account type) and is **not** being added via Revtag.
    
    If specified, `individual_name` and `name` must be empty.
    
    :::warning
    The `company_name` must contain at least 2 letters (not just characters).
    For example, names like `12` will fail validation because they are two characters but not two letters.
    :::
- `individual_name` (object, optional)
    The name of the counterparty, provided when the counterparty is an **individual** (personal account type) and is **not** being added via Revtag.
    
    If specified, `company_name` and `name` must be empty.
  - `individual_name.first_name` (string, optional)
      The first name of the individual counterparty.
  - `individual_name.last_name` (string, optional)
      The last name of the individual counterparty.
- `bank_country` (string, optional)
    The country of the bank, provided as a 2-letter [ISO 3166](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes) code.
- `currency` (string, optional)
    [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code in upper case.
- `account_no` (string, optional)
    The bank account number of the counterparty.
- `iban` (string, optional)
    The IBAN number of the counterparty's account. This field is displayed for IBAN countries.
- `sort_code` (string, optional)
    The sort code of the counterparty's account. This field is required for GBP accounts.
- `routing_number` (string, optional)
    The routing number of the counterparty's account. This field is required for USD accounts.
- `bic` (string, optional)
    The BIC number of the counterparty's account. This field is required for non-SEPA IBAN/SWIFT.
- `clabe` (string, optional)
    The CLABE number of the counterparty's account. This field is required for SWIFT MX.
- `ifsc` (string, optional)
    The IFSC number of the counterparty's account. This field is required for INR accounts.
- `bsb_code` (string, optional)
    The BSB number of the counterparty's account. This field is required for AUD accounts.
- `address` (object, optional)
    The address of the counterparty.
  - `address.street_line1` (string, optional)
      Street line 1 information.
  - `address.street_line2` (string, optional)
      Street line 2 information.
  - `address.region` (string, optional)
      The name of the region (state or province), for example, Ontario for Canada.
  - `address.city` (string, optional)
      The name of the city.
  - `address.country` (string)
      The country of the counterparty, provided as a 2-letter [ISO 3166](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes) code.
  - `address.postcode` (string)
      The postcode of the counterparty address.

## Returns

### 200

Added counterparty

#### Response attributes

- `id` (string)
    The ID of the counterparty.
- `name` (string)
    The name of the counterparty.
- `revtag` (string, optional)
    The [Revtag](https://help.revolut.com/help/transfers/internal-transfers/username-payments/revtags/) of the counterparty.
- `profile_type` (enum, optional)
    The type of the counterparty.
    Indicates whether the recipient is an individual or a company.
    Possible enum values:

    - `personal`
    - `business`
- `country` (string, optional)
    The counterparty's bank country, provided as a 2-letter [ISO 3166](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes) code.
- `state` (enum)
    Indicates the state of the counterparty.
    Possible enum values:

    - `created`
    - `draft`
    - `deleted`
- `created_at` (string)
    The date and time the counterparty was created in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.
- `updated_at` (string)
    The date and time the counterparty was last updated in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.
- `accounts` (array of object, optional)
    The list of public accounts associated with this counterparty.
  - `accounts[].id` (string)
      The ID of the counterparty's account.
  - `accounts[].name` (string, optional)
      The name of the counterparty.
  - `accounts[].bank_country` (string, optional)
      The country of the bank, provided as a 2-letter [ISO 3166](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes) code.
  - `accounts[].currency` (string)
      [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code in upper case.
  - `accounts[].type` (enum)
      Indicates the type of account.
      Possible enum values:

      - `revolut`
      - `external`
  - `accounts[].account_no` (string, optional)
      The bank account number of the counterparty.
  - `accounts[].iban` (string, optional)
      The IBAN number of the counterparty's account if applicable.
  - `accounts[].sort_code` (string, optional)
      The sort code of the counterparty's account if applicable.
  - `accounts[].routing_number` (string, optional)
      The routing number of the counterparty's account if applicable.
  - `accounts[].bic` (string, optional)
      The BIC number of the counterparty's account if applicable.
  - `accounts[].clabe` (string, optional)
      The CLABE number of the counterparty's account if applicable.
  - `accounts[].ifsc` (string, optional)
      The IFSC number of the counterparty's account if applicable.
  - `accounts[].bsb_code` (string, optional)
      The BSB number of the counterparty's account if applicable.
  - `accounts[].recipient_charges` (enum, optional)
      Indicates the possibility of the recipient charges.
      
      :::warning
      This field is deprecated and should be disregarded.
      It is returned for legacy purposes only.
      :::
      Possible enum values:

      - `no`
      - `expected`
- `cards` (array of object, optional)
    The list of cards associated with this counterparty.
  - `cards[].id` (string)
      The ID of the counterparty's card.
  - `cards[].name` (string)
      The name of the counterparty.
  - `cards[].last_digits` (string)
      The last four digits of the card number.
  - `cards[].scheme` (enum)
      The card brand.
      Possible enum values:

      - `visa`
      - `mastercard`
  - `cards[].country` (string)
      The country of the card issuer, provided as a 2-letter [ISO 3166](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes) code.
  - `cards[].currency` (string)
      [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code in upper case.

## Error responses

| HTTP status code | Description |
| --- | --- |
| 400 | Bad Request  Returned, for example, when the provided IBAN is invalid. |
| 404 | Not Found  Returned, for example, when the counterparty that you're trying to add doesn't exist, or when the name that you provide for the Revtag counterparty doesn't match the actual name on the account. |
| 422 | Unprocessable Content  Returned, for example, when the Revolut counterparty that you're trying to add using Revtag already exists, or when the counterparty cannot be added. |