---
title: "Create counterparty"
method: POST
path: "/v1/counterparties"
tags: ["Counterparties"]
---

# Create counterparty

`POST /v1/counterparties`

## Request

- Base URL: `https://api.augustus.com`
- URL: `https://api.augustus.com/v1/counterparties`
- Auth: HTTP bearer

Creates a counterparty owned by the merchant.

## Headers

- `Idempotency-Key` string, required

## Request body

- CreateCounterpartyBodyDto
  - `name` string: Name of the counterparty.
  - `physical_address` object: Physical address of the counterparty.
    - `line_1` string, nullable: Primary street address. Optional; omit or send null if not recorded.
    - `line_2` string, nullable: Secondary street address. Optional; omit or send null if not recorded.
    - `city` string, required: City or locality.
    - `postal_code` string, nullable: Postal or ZIP code. Optional; omit or send null if not recorded.
    - `state` string, nullable: State, province, or region. Optional; omit or send null if not recorded.
    - `country_code` 'AF' | 'AL' | 'DZ' | 'AS' | 'AD' | 'AO' | 'AI' | 'AQ' | 'AG' | 'AR' | 'AM' | 'AW' | 'AU' | 'AT' | 'AZ' | 'BS' | 'BH' | 'BD' | 'BB' | 'BY' | 'BE' | 'BZ' | 'BJ' | 'BM' | 'BT' | 'BO' | 'BA' | 'BW' | 'BV' | 'BR' | 'IO' | 'BN' | 'BG' | 'BF' | 'BI' | 'KH' | 'CM' | 'CA' | 'CV' | 'KY' | 'CF' | 'TD' | 'CL' | 'CN' | 'CX' | 'CC' | 'CO' | 'KM' | 'CG' | 'CD' | 'CK' | 'CR' | 'CI' | 'HR' | 'CU' | 'CY' | 'CZ' | 'DK' | 'DJ' | 'DM' | 'DO' | 'EC' | 'EG' | 'SV' | 'GQ' | 'ER' | 'EE' | 'ET' | 'FK' | 'FO' | 'FJ' | 'FI' | 'FR' | 'GF' | 'PF' | 'TF' | 'GA' | 'GM' | 'GE' | 'DE' | 'GH' | 'GI' | 'GR' | 'GL' | 'GD' | 'GP' | 'GU' | 'GT' | 'GN' | 'GW' | 'GY' | 'HT' | 'HM' | 'VA' | 'HN' | 'HK' | 'HU' | 'IS' | 'IN' | 'ID' | 'IR' | 'IQ' | 'IE' | 'IL' | 'IT' | 'JM' | 'JP' | 'JO' | 'KZ' | 'KE' | 'KI' | 'KP' | 'KR' | 'KW' | 'KG' | 'LA' | 'LV' | 'LB' | 'LS' | 'LR' | 'LY' | 'LI' | 'LT' | 'LU' | 'MO' | 'MG' | 'MW' | 'MY' | 'MV' | 'ML' | 'MT' | 'MH' | 'MQ' | 'MR' | 'MU' | 'YT' | 'MX' | 'FM' | 'MD' | 'MC' | 'MN' | 'MS' | 'MA' | 'MZ' | 'MM' | 'NA' | 'NR' | 'NP' | 'NL' | 'NC' | 'NZ' | 'NI' | 'NE' | 'NG' | 'NU' | 'NF' | 'MP' | 'MK' | 'NO' | 'OM' | 'PK' | 'PW' | 'PS' | 'PA' | 'PG' | 'PY' | 'PE' | 'PH' | 'PN' | 'PL' | 'PT' | 'PR' | 'QA' | 'RE' | 'RO' | 'RU' | 'RW' | 'SH' | 'KN' | 'LC' | 'PM' | 'VC' | 'WS' | 'SM' | 'ST' | 'SA' | 'SN' | 'SC' | 'SL' | 'SG' | 'SK' | 'SI' | 'SB' | 'SO' | 'ZA' | 'GS' | 'ES' | 'LK' | 'SD' | 'SR' | 'SJ' | 'SZ' | 'SE' | 'CH' | 'SY' | 'TW' | 'TJ' | 'TZ' | 'TH' | 'TL' | 'TG' | 'TK' | 'TO' | 'TT' | 'TN' | 'TR' | 'TM' | 'TC' | 'TV' | 'UG' | 'UA' | 'AE' | 'GB' | 'US' | 'UM' | 'UY' | 'UZ' | 'VU' | 'VE' | 'VN' | 'VG' | 'VI' | 'WF' | 'EH' | 'YE' | 'ZM' | 'ZW' | 'AX' | 'BQ' | 'CW' | 'GG' | 'IM' | 'JE' | 'ME' | 'BL' | 'MF' | 'RS' | 'SX' | 'SS' | 'XK', required
  - `financial_address` union, required: Financial address of the counterparty.
    - AbaFinancialAddressRequest
      - `type` 'aba', required: Discriminator for ABA wire financial address.
      - `routing_number` string, required: ABA routing number (9 digits).
      - `account_number` string, required: Bank account number.
      - `account_holder_name` string, required: Name of the account holder.
      - `account_type` 'checking' | 'savings' | 'null', nullable: Whether the account is a checking or a savings account. Optional; omit or send null if not provided. Some destination countries require it (for example the Dominican Republic, Honduras and Jamaica) and ACH uses it for the transaction code. A payment to an account without one is sent as checking.
    - IbanFinancialAddressRequest
      - `type` 'iban', required: Discriminator for IBAN financial address.
      - `iban` string, required: International Bank Account Number.
      - `account_holder_name` string, required: Name of the account holder.
      - `bic` string, nullable: Bank Identifier Code. Optional; omit or send null if not provided.
      - `account_type` 'checking' | 'savings' | 'null', nullable: Whether the account is a checking or a savings account. Optional; omit or send null if not provided. Some destination countries require it (for example the Dominican Republic, Honduras and Jamaica) and ACH uses it for the transaction code. A payment to an account without one is sent as checking.
    - SortCodeFinancialAddressRequest
      - `type` 'sort_code', required: Discriminator for UK sort code financial address.
      - `sort_code` string, required: UK sort code (6 digits).
      - `account_number` string, required: UK account number (8 digits).
      - `account_holder_name` string, required: Name of the account holder.
    - BicFinancialAddressRequest
      - `type` 'bic', required: Discriminator for BIC + local account financial address.
      - `bic` string, required: ISO 9362 Bank Identifier Code (8 or 11 characters).
      - `account_number` string, required: Local-format bank account number (1-34 alphanumeric characters).
      - `account_holder_name` string, required: Name of the account holder.
      - `local_bank_code` string, nullable: Domestic bank or branch code where the destination country uses one (for example the BSB in Australia). Optional; omit or send null where the country has none.
      - `account_type` 'checking' | 'savings' | 'null', nullable: Whether the account is a checking or a savings account. Optional; omit or send null if not provided. Some destination countries require it (for example the Dominican Republic, Honduras and Jamaica) and ACH uses it for the transaction code. A payment to an account without one is sent as checking.
    - CryptoWalletFinancialAddress
      - `type` 'crypto_wallet', required: Discriminator for crypto wallet financial address.
      - `address` string, required: Wallet address on the specified blockchain.
      - `blockchain` 'bitcoin' | 'ethereum' | 'solana' | 'polygon' | 'bitcoin_testnet4' | 'ethereum_sepolia' | 'solana_devnet' | 'polygon_amoy', required: Blockchain network for the crypto wallet.
  - `date_of_birth` string, date: Date of birth in YYYY-MM-DD format.
  - `phone` string: Phone number of the counterparty. Stored for operational contact only; it is not sent with payments.
  - `email` string, email: Email address of the counterparty. Stored for operational contact only; it is not sent with payments.
  - `legal_id` string: National tax or identity number of the counterparty, as issued in its country: CPF or CNPJ in Brazil, Cédula or NIT in Colombia, CUIL or CUIT in Argentina, DNI or RUC in Peru, RUT in Chile. Free text, up to 127 characters.
  - `entity_type` 'business' | 'individual' | 'non_profit' | 'sole_proprietor': Classification of the counterparty. Defaults to business.
  - `is_self_owned` boolean: Whether the counterparty is self-owned. `false` if the counterparty is not owned by you, `true` if it is.
  - `metadata` object, nullable: Set of up to 50 key-value string pairs you can attach to store structured information, such as correlating this resource with an object in your own system. Keys may be up to 40 characters and values up to 500 characters.

## Response `200`

The created counterparty

- CounterpartyResourceDto
  - `status` 'pending' | 'active' | 'rejected', required: Counterparty lifecycle status. Blocking is separate.
  - `id` string, uuid, required: Unique identifier of the counterparty.
  - `type` 'counterparty', required: Resource type discriminator.
  - `name` string, nullable, required: Name of the counterparty, or null if not recorded.
  - `entity_type` 'business' | 'individual' | 'non_profit' | 'sole_proprietor', required: Classification of the counterparty.
  - `physical_address` object, nullable, required: Physical address of the counterparty, or null if not recorded.
    - `line_1` string, nullable, required: Primary street address, or null if not recorded.
    - `line_2` string, nullable, required: Secondary street address, or null if not recorded.
    - `city` string, required: City or locality.
    - `postal_code` string, nullable, required: Postal or ZIP code, or null if not recorded.
    - `state` string, nullable, required: State, province, or region, or null if not recorded.
    - `country_code` 'AF' | 'AL' | 'DZ' | 'AS' | 'AD' | 'AO' | 'AI' | 'AQ' | 'AG' | 'AR' | 'AM' | 'AW' | 'AU' | 'AT' | 'AZ' | 'BS' | 'BH' | 'BD' | 'BB' | 'BY' | 'BE' | 'BZ' | 'BJ' | 'BM' | 'BT' | 'BO' | 'BA' | 'BW' | 'BV' | 'BR' | 'IO' | 'BN' | 'BG' | 'BF' | 'BI' | 'KH' | 'CM' | 'CA' | 'CV' | 'KY' | 'CF' | 'TD' | 'CL' | 'CN' | 'CX' | 'CC' | 'CO' | 'KM' | 'CG' | 'CD' | 'CK' | 'CR' | 'CI' | 'HR' | 'CU' | 'CY' | 'CZ' | 'DK' | 'DJ' | 'DM' | 'DO' | 'EC' | 'EG' | 'SV' | 'GQ' | 'ER' | 'EE' | 'ET' | 'FK' | 'FO' | 'FJ' | 'FI' | 'FR' | 'GF' | 'PF' | 'TF' | 'GA' | 'GM' | 'GE' | 'DE' | 'GH' | 'GI' | 'GR' | 'GL' | 'GD' | 'GP' | 'GU' | 'GT' | 'GN' | 'GW' | 'GY' | 'HT' | 'HM' | 'VA' | 'HN' | 'HK' | 'HU' | 'IS' | 'IN' | 'ID' | 'IR' | 'IQ' | 'IE' | 'IL' | 'IT' | 'JM' | 'JP' | 'JO' | 'KZ' | 'KE' | 'KI' | 'KP' | 'KR' | 'KW' | 'KG' | 'LA' | 'LV' | 'LB' | 'LS' | 'LR' | 'LY' | 'LI' | 'LT' | 'LU' | 'MO' | 'MG' | 'MW' | 'MY' | 'MV' | 'ML' | 'MT' | 'MH' | 'MQ' | 'MR' | 'MU' | 'YT' | 'MX' | 'FM' | 'MD' | 'MC' | 'MN' | 'MS' | 'MA' | 'MZ' | 'MM' | 'NA' | 'NR' | 'NP' | 'NL' | 'NC' | 'NZ' | 'NI' | 'NE' | 'NG' | 'NU' | 'NF' | 'MP' | 'MK' | 'NO' | 'OM' | 'PK' | 'PW' | 'PS' | 'PA' | 'PG' | 'PY' | 'PE' | 'PH' | 'PN' | 'PL' | 'PT' | 'PR' | 'QA' | 'RE' | 'RO' | 'RU' | 'RW' | 'SH' | 'KN' | 'LC' | 'PM' | 'VC' | 'WS' | 'SM' | 'ST' | 'SA' | 'SN' | 'SC' | 'SL' | 'SG' | 'SK' | 'SI' | 'SB' | 'SO' | 'ZA' | 'GS' | 'ES' | 'LK' | 'SD' | 'SR' | 'SJ' | 'SZ' | 'SE' | 'CH' | 'SY' | 'TW' | 'TJ' | 'TZ' | 'TH' | 'TL' | 'TG' | 'TK' | 'TO' | 'TT' | 'TN' | 'TR' | 'TM' | 'TC' | 'TV' | 'UG' | 'UA' | 'AE' | 'GB' | 'US' | 'UM' | 'UY' | 'UZ' | 'VU' | 'VE' | 'VN' | 'VG' | 'VI' | 'WF' | 'EH' | 'YE' | 'ZM' | 'ZW' | 'AX' | 'BQ' | 'CW' | 'GG' | 'IM' | 'JE' | 'ME' | 'BL' | 'MF' | 'RS' | 'SX' | 'SS' | 'XK', required
  - `financial_address` union, required: Financial address of the counterparty.
    - AbaFinancialAddress
      - `type` 'aba', required: Discriminator for ABA wire financial address.
      - `routing_number` string, required: ABA routing number (9 digits).
      - `account_number` string, required: Bank account number.
      - `account_holder_name` string, required: Name of the account holder.
      - `account_type` 'checking' | 'savings' | 'null', nullable, required: Whether the account is a checking or a savings account, or null if not provided.
    - IbanFinancialAddress
      - `type` 'iban', required: Discriminator for IBAN financial address.
      - `iban` string, required: International Bank Account Number.
      - `account_holder_name` string, required: Name of the account holder.
      - `bic` string, nullable, required: Bank Identifier Code, or null if not provided.
      - `account_type` 'checking' | 'savings' | 'null', nullable, required: Whether the account is a checking or a savings account, or null if not provided.
    - SortCodeFinancialAddress
      - `type` 'sort_code', required: Discriminator for UK sort code financial address.
      - `sort_code` string, required: UK sort code (6 digits).
      - `account_number` string, required: UK account number (8 digits).
      - `account_holder_name` string, required: Name of the account holder.
    - BicFinancialAddress
      - `type` 'bic', required: Discriminator for BIC + local account financial address.
      - `bic` string, required: ISO 9362 Bank Identifier Code (8 or 11 characters).
      - `account_number` string, required: Local-format bank account number.
      - `account_holder_name` string, required: Name of the account holder.
      - `local_bank_code` string, nullable, required: Domestic bank or branch code where the destination country uses one (for example the BSB in Australia), or null.
      - `account_type` 'checking' | 'savings' | 'null', nullable, required: Whether the account is a checking or a savings account, or null if not provided.
    - CryptoWalletFinancialAddress
      - `type` 'crypto_wallet', required: Discriminator for crypto wallet financial address.
      - `address` string, required: Wallet address on the specified blockchain.
      - `blockchain` 'bitcoin' | 'ethereum' | 'solana' | 'polygon' | 'bitcoin_testnet4' | 'ethereum_sepolia' | 'solana_devnet' | 'polygon_amoy', required: Blockchain network for the crypto wallet.
  - `date_of_birth` string, date, nullable, required: Date of birth in YYYY-MM-DD format, or null if not recorded.
  - `phone` string, nullable, required: Phone number of the counterparty, or null if not recorded.
  - `email` string, nullable, required: Email address of the counterparty, or null if not recorded.
  - `legal_id` string, nullable, required: National tax or identity number of the counterparty, or null if not recorded.
  - `is_self_owned` boolean, required: Whether the counterparty is self-owned. `false` if the counterparty is not owned by you, `true` if it is.
  - `blocked` boolean, required: Whether payments to or from this counterparty are currently blocked.
  - `metadata` object, required: Set of up to 50 key-value string pairs you can attach to store structured information, such as correlating this resource with an object in your own system. Keys may be up to 40 characters and values up to 500 characters.

## Changes

- **2026-10-26** `618f161fdba7`: 1 warning
  - changed the pattern of the request property `email` from `^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$` to `^(?:[A-Za-z0-9_'+\-]+\.)*[A-Za-z0-9_'+\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$`
- **2026-10-16** `f7ded6c181ab`: 1 info
  - endpoint added
- **2026-08-31** `e0010b51834a`: 4 info
  - added the new optional request property `entity_type`
  - added `#/components/schemas/BicFinancialAddressRequest` to the `financial_address` request property `anyOf` list
  - added `#/components/schemas/BicFinancialAddress` to the `financial_address` response property `anyOf` list for the response status `200`
  - added the required property `entity_type` to the response with the `200` status
- **2026-08-27** `8e304f78f67e`: 1 breaking, 1 info
  - removed `#/components/schemas/IbanFinancialAddress` from the `financial_address` request property `anyOf` list
  - added `#/components/schemas/IbanFinancialAddressRequest` to the `financial_address` request property `anyOf` list
- **2026-08-26** `ca35cff0b637`: 1 info
  - added the required property `blocked` to the response with the `200` status

[Operation history](https://skmtc.dev/augustus/apis/ivy-api/changes/v1/counterparties/post.md)

---

[API](https://skmtc.dev/augustus/apis/ivy-api.md) - [All operations](https://skmtc.dev/augustus/apis/ivy-api/llms.txt) - [OpenAPI document](https://skmtc.dev/augustus/apis/ivy-api/revisions/e87bdcac11cc?raw)