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

# Create a new counterparty

`POST /v1/entities/counterparties`

## Request

- Base URL: `https://api.tesser.xyz`
- URL: `https://api.tesser.xyz/v1/entities/counterparties`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/tesser/apis/tesser-api/docs/v1/entities/counterparties/post.ts> (a function with typed inputs; its response is checked against the schema)

Create a new counterparty for your workspace or a specific tenant.

## Request body

- CreateCounterpartyRequestDto
  - `classification` 'individual' | 'business', required: Classification: 'individual' or 'business'.
  - `tenant_id` string, uuid, nullable: ID of the tenant entity (optional).
  - `individual_first_name` string, nullable: First name (required if classification is 'individual'). Secure field, returned based on include_secure.
  - `individual_last_name` string, nullable: Last name (required if classification is 'individual'). Secure field, returned based on include_secure.
  - `individual_address_country` string, nullable: ISO 3166-1 alpha-2 or alpha-3 country code.
  - `individual_date_of_birth` string, nullable: Date of birth (for individuals).
  - `individual_national_identification_number` string, nullable: National identification number (for individuals). Secure field, returned based on include_secure.
  - `individual_street_address1` string, nullable: Street address line 1 (for individuals). Secure field, returned based on include_secure.
  - `individual_street_address2` string, nullable: Street address line 2 (for individuals). Secure field, returned based on include_secure.
  - `individual_city` string, nullable: City (for individuals). Secure field, returned based on include_secure.
  - `individual_state` string, nullable: State/region (for individuals). Secure field, returned based on include_secure.
  - `individual_postal_code` string, nullable: Postal code (for individuals). Secure field, returned based on include_secure.
  - `business_legal_name` string, nullable: Legal business name (required if classification is 'business').
  - `business_dba` string, nullable: Doing Business As name (optional).
  - `business_address_country` string, nullable: ISO 3166-1 alpha-2 or alpha-3 country code.
  - `business_street_address1` string, nullable: Street address line 1 (for businesses).
  - `business_street_address2` string, nullable: Street address line 2 (for businesses).
  - `business_city` string, nullable: City (for businesses).
  - `business_state` string, nullable: State/region (for businesses).
  - `business_legal_entity_identifier` string, nullable: Legal Entity Identifier (for businesses). Secure field, returned based on include_secure.

## Response `201`

Counterparty created successfully

- CreateCounterpartyResponseDto
  - `data` CounterpartyData, required
    - `id` string, required: Unique identifier for the counterparty
    - `workspace_id` string, required: Workspace ID the counterparty belongs to
    - `classification` 'individual' | 'business' | 'wallet_cluster', required: Classification: individual (person), business (company), or wallet_cluster (a group of on-chain addresses Tesser screened whose owner is unknown; system-created only)
    - `name` string, required: Display name: a business's legal name (or DBA), an individual's first and last name, or a wallet cluster's label. Empty when none is recorded.
    - `tenant_id` string, nullable: Optional reference to a tenant entity this counterparty belongs to
    - `individual_first_name` string, nullable: First name (for individuals)
    - `individual_last_name` string, nullable: Last name (for individuals)
    - `individual_address_country` string, nullable: Country code in ISO 3166-1 format (for individuals)
    - `individual_date_of_birth` string, nullable: Date of birth (for individuals)
    - `individual_national_identification_number` string, nullable: National identification number (for individuals)
    - `individual_street_address1` string, nullable: Street address line 1 (for individuals)
    - `individual_street_address2` string, nullable: Street address line 2 (for individuals)
    - `individual_city` string, nullable: City (for individuals)
    - `individual_state` string, nullable: State/region (for individuals)
    - `individual_postal_code` string, nullable: Postal code (for individuals)
    - `business_legal_name` string, nullable: Legal business name (for businesses)
    - `business_dba` string, nullable: DBA - Doing Business As (for businesses)
    - `business_address_country` string, nullable: Country code in ISO 3166-1 format (for businesses)
    - `business_street_address1` string, nullable: Street address line 1 (for businesses)
    - `business_street_address2` string, nullable: Street address line 2 (for businesses)
    - `business_city` string, nullable: City (for businesses)
    - `business_state` string, nullable: State/region (for businesses)
    - `business_legal_entity_identifier` string, nullable: Legal Entity Identifier (for businesses)
    - `created_by` 'CUSTOMER' | 'SYSTEM', required: Whether the customer created this counterparty (CUSTOMER) or Tesser synthesized it (SYSTEM, e.g. a screening-minted counterparty).
    - `created_at` string, required: Creation timestamp in ISO 8601 format
    - `updated_at` string, required: Last update timestamp in ISO 8601 format

## Other responses

- `400`: Invalid request data
- `401`: Authentication required or invalid credentials
- `500`: Internal server error

---

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