--- title: "Create a counterparty" method: POST path: "/counterparty" tags: ["Counterparties"] --- # Create a counterparty `POST /counterparty` ## Request - Base URL: `https://b2b.revolut.com/api/1.0` - URL: `https://b2b.revolut.com/api/1.0/counterparty` - Auth: HTTP bearer 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.
Test accounts for Sandbox 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`
### 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.
Counterparty type Name field to use when added with:
Revtag Other details
Individual name (string) individual_name (object with string subfields for first and last name)
Company name (string) company_name (string)
--- For more information, see the guides: [Create a counterparty](https://developer.revolut.com/docs/guides/manage-accounts/counterparties/create-a-counterparty). ## Request body - CreateCounterpartyRequest - `profile_type` 'personal' | 'business': 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. - `revtag` string: The [Revtag](https://help.revolut.com/help/transfers/internal-transfers/username-payments/revtags/) of the counterparty to add. - `name` string: 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: 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` IndividualName: 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. - `first_name` string: The first name of the individual counterparty. - `last_name` string: The last name of the individual counterparty. - `bank_country` string: 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: [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code in upper case. - `account_no` string: The bank account number of the counterparty. - `iban` string: The IBAN number of the counterparty's account. This field is displayed for IBAN countries. - `sort_code` string: The sort code of the counterparty's account. This field is required for GBP accounts. - `routing_number` string: The routing number of the counterparty's account. This field is required for USD accounts. - `bic` string: The BIC number of the counterparty's account. This field is required for non-SEPA IBAN/SWIFT. - `clabe` string: The CLABE number of the counterparty's account. This field is required for SWIFT MX. - `ifsc` string: The IFSC number of the counterparty's account. This field is required for INR accounts. - `bsb_code` string: The BSB number of the counterparty's account. This field is required for AUD accounts. - `address` BeneficiaryAddress: The address of the counterparty. - `street_line1` string: Street line 1 information. - `street_line2` string: Street line 2 information. - `region` string: The name of the region (state or province), for example, Ontario for Canada. - `city` string: The name of the city. - `country` string, required: The country of the counterparty, as a 2-letter [ISO 3166](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes) code. - `postcode` string, required: The postcode of the counterparty address. - `route` 'ach' | 'fedwire' | 'swift': Routing method for US USD transfers. When omitted, defaults to `ach` for US-registered businesses and `fedwire` for non-US businesses. Required when `bank_country` is `US` and the desired routing method differs from the default. - `bank_number` string: Brazilian bank identification code (COMPE). Required for BR counterparties. - `branch_code` string: Brazilian branch (agência) code. Required for BR counterparties. - `account_type` 'checking' | 'savings': Bank account type. Defaults to `checking` for US ACH transfers when omitted. Required for BR, CO, and CL counterparties. - `tax_id` string: Tax identification number. Required and routed based on `bank_country` and recipient type: | Country | Recipient type | Tax ID type | Format | Example | |-----------|----------------------------------|-----------------------------------------------|-----------------------------------------------------|------------------------------------------| | **BR** | **Individual** | CPF (Cadastro de Pessoas Físicas) | `^\d{11}$` or `^\d{3}\.\d{3}\.\d{3}-\d{2}$` | `52998224725` or `529.982.247-25` | | **BR** | **Company** | CNPJ (Cadastro Nacional da Pessoa Jurídica) | `^\d{14}$` or `^\d{2}\.\d{3}\.\d{3}/\d{4}-\d{2}$` | `12345678000195` or `12.345.678/0001-95` | | **CO** | **Company** | NIT (Número de Identificación Tributaria) | `^\d{10}$` | `9012345678` | | **CL** | **Individual**, **Company** | RUT (Rol Único Tributario) | `^\d{7,8}[0-9Kk]$` | `12345678K` | - `national_id` string: National identification number. Required when `bank_country` is `CO` and `profile_type` is `personal`, must specify Colombian Cédula de Ciudadanía. - `phone` string: The phone number of the counterparty in [E.164](https://en.wikipedia.org/wiki/E.164) format. - For internal (Revolut) counterparties: the recipient's Revolut phone number used to look them up. - For external counterparties in CO, KR, and LK: the bank account phone number. Required when `bank_country` is `CO`, `KR`, or `LK`. Country-specific formats: | Country | Format description | Format | Example | |---------|-----------------------------|-----------------|-----------------| | **CO** | `+57` followed by 10 digits | `^\+?57\d{10}$` | `+573001234567` | | **KR** | `+82` followed by 10 digits | `^\+?82\d{10}$` | `+821012345678` | | **LK** | `+94` followed by 10 digits | `^\+?94\d{10}$` | `+941234567890` | - `business_registration_id` string: Company registration number. Required for business LK counterparties (`profile_type`: `business`). ## Response `200` Added counterparty - Counterparty - `id` string, uuid, required: The ID of the counterparty. - `name` string, required: The name of the counterparty. - `revtag` string: The [Revtag](https://help.revolut.com/help/transfers/internal-transfers/username-payments/revtags/) of the counterparty. - `profile_type` 'personal' | 'business': The type of the counterparty. Indicates whether the recipient is an individual or a company. - `country` string: 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` 'created' | 'draft' | 'deleted', required: Indicates the state of the counterparty. - `created_at` string, date-time, required: The date and time the counterparty was created in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. - `updated_at` string, date-time, required: The date and time the counterparty was last updated in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. - `accounts` CounterpartyAccount[]: The list of public accounts associated with this counterparty. - `id` string, uuid, required: The ID of the counterparty's account. - `name` string: The name of the counterparty. - `bank_country` string: 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, required: [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code in upper case. - `type` 'revolut' | 'external', required: Indicates the type of account. - `account_no` string: The bank account number of the counterparty. - `iban` string: The IBAN number of the counterparty's account if applicable. - `sort_code` string: The sort code of the counterparty's account if applicable. - `routing_number` string: The routing number of the counterparty's account if applicable. - `bic` string: The BIC number of the counterparty's account if applicable. - `clabe` string: The CLABE number of the counterparty's account if applicable. - `ifsc` string: The IFSC number of the counterparty's account if applicable. - `bsb_code` string: The BSB number of the counterparty's account if applicable. - `route` 'ach' | 'fedwire' | 'swift': Routing method for US/USD transfers. Defaults to `ach` for US-registered businesses and `fedwire` for non-US businesses. - `bank_number` string: Brazilian bank identification code (COMPE). Returned for BR counterparties. - `branch_code` string: Brazilian branch (agência) code. Returned for BR counterparties. - `account_type` 'checking' | 'savings': Bank account type. Returned for BR, CO, and CL counterparties. Defaults to `checking` for US ACH transfers. - `tax_id` string: Tax identification number. Routed based on `bank_country` and recipient type: | Country | Recipient type | Tax ID type | Format | Example | |-----------|----------------------------------|-----------------------------------------------|-----------------------------------------------------|------------------------------------------| | **BR** | **Individual** | CPF (Cadastro de Pessoas Físicas) | `^\d{11}$` or `^\d{3}\.\d{3}\.\d{3}-\d{2}$` | `52998224725` or `529.982.247-25` | | **BR** | **Company** | CNPJ (Cadastro Nacional da Pessoa Jurídica) | `^\d{14}$` or `^\d{2}\.\d{3}\.\d{3}/\d{4}-\d{2}$` | `12345678000195` or `12.345.678/0001-95` | | **CO** | **Company** | NIT (Número de Identificación Tributaria) | `^\d{10}$` | `9012345678` | | **CL** | **Individual**, **Company** | RUT (Rol Único Tributario) | `^\d{7,8}[0-9Kk]$` | `12345678K` | - `national_id` string: National identification number. Specifies Colombian Cédula de Ciudadanía when `bank_country` is `CO` and `profile_type` is `personal`. - `phone` string: The phone number of the counterparty in [E.164](https://en.wikipedia.org/wiki/E.164) format. Country-specific formats: | Country | Format description | Format | Example | |---------|-----------------------------|-----------------|-----------------| | **CO** | `+57` followed by 10 digits | `^\+?57\d{10}$` | `+573001234567` | | **LK** | `+94` followed by 10 digits | `^\+?94\d{10}$` | `+941234567890` | | **KR** | `+82` followed by 10 digits | `^\+?82\d{10}$` | `+821012345678` | - `business_registration_id` string: Company registration number. Used for business LK counterparties. - `recipient_charges` 'no' | 'expected': Indicates the possibility of the recipient charges. :::warning This field is deprecated and should be disregarded. It is returned for legacy purposes only. ::: - `address` CounterpartyAddress: The address of the counterparty's account. - `street_line1` string: Street line 1 information. - `street_line2` string: Street line 2 information. - `region` string: The name of the region (state or province), for example, Ontario for Canada. - `city` string: The name of the city. - `country` string, required: The country of the counterparty, as a 2-letter [ISO 3166](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes) code. - `postcode` string: The postcode of the counterparty address. - `cards` CounterpartyCard[]: The list of cards associated with this counterparty. - `id` string, uuid, required: The ID of the counterparty's card. - `name` string, required: The name of the counterparty. - `last_digits` string, required: The last four digits of the card number. - `scheme` 'visa' | 'mastercard', required: The card brand. - `country` string, required: 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. - `currency` string, required: [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code in upper case. ## Other responses - `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. - `default`: Unexpected error --- [API](https://skmtc.dev/revolut/apis/business-api.md) - [All operations](https://skmtc.dev/revolut/apis/business-api/llms.txt) - [OpenAPI document](https://skmtc.dev/revolut/apis/business-api/revisions/be089d9fa8b4?raw)