HIFI Docs

POST

/

v3

/

counter-parties

curl --request POST \
  --url https://production.hifi.com/v3/counter-parties \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "userId": "usr_3Kf9dQ2mNpXwZ7bV1aLcs",
  "type": "INDIVIDUAL",
  "firstName": "Jane",
  "lastName": "Doe",
  "phoneNumber": "+14155552671",
  "email": "jane.doe@example.com",
  "dateOfBirth": "1990-01-15",
  "taxId": "123-45-6789",
  "nationality": "USA",
  "address": {
    "addressLine1": "123 Main Street",
    "city": "New York",
    "stateProvinceRegion": "NY",
    "postalCode": "10001",
    "country": "USA"
  }
}
'

{
  "id": "cpty_7dLpR2mNpXwZ7bV1aQz3x",
  "userId": "usr_3Kf9dQ2mNpXwZ7bV1aLcs",
  "type": "INDIVIDUAL",
  "firstName": "Jane",
  "lastName": "Doe",
  "phoneNumber": "+14155552671",
  "email": "jane.doe@example.com",
  "taxId": "123-45-6789",
  "dateOfBirth": "1990-01-15",
  "nationality": "USA",
  "address": {
    "addressLine1": "123 Main Street",
    "city": "New York",
    "stateProvinceRegion": "NY",
    "postalCode": "10001",
    "country": "USA"
  },
  "status": "ACTIVE",
  "createdAt": "2026-07-01T10:30:00.000Z",
  "updatedAt": "2026-07-01T10:30:00.000Z"
}

{
  "type": "VALIDATION_ERROR",
  "message": "One or more fields are invalid or missing.",
  "fields": [
    {
      "code": "invalid_value",
      "message": "Must be a valid email address",
      "field": "email"
    }
  ]
}

{
  "type": "UNAUTHORIZED",
  "message": "Authentication required"
}

{
  "type": "INTERNAL_SERVER_ERROR",
  "message": "An internal server error occurred"
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Counter party details. The type field selects whether the counter party is an individual or a business, which determines the required fields.

Individual
Business

An individual counter party. Only userId, type, firstName, and lastName are always required; the other fields become required depending on what is later attached (external wallet needs the name only; external account needs phoneNumber, email, dateOfBirth, taxId, taxIdType, nationality, address).

userId

string

required

Public ID of the user this counter party belongs to (prefixed with usr_).

Example:

"usr_3Kf9dQ2mNpXwZ7bV1aLcs"

type

enum<string>

required

Available options:

INDIVIDUAL

Example:

"INDIVIDUAL"

firstName

string

required

Example:

"Jane"

lastName

string

required

Example:

"Doe"

phoneNumber

string

Phone number.

Example:

"+14155552671"

email

string<email>

Example:

"jane.doe@example.com"

dateOfBirth

string<date>

Date of birth in YYYY-MM-DD format.

Example:

"1990-01-15"

taxId

string

Tax identification number. If the user does not have a tax identification number for valid reasons, please pass nine nines "999999999".

Example:

"123-45-6789"

taxIdType

string

Type of tax identifier (e.g. SSN, ITIN).

Example:

"SSN"

taxIdCountry

string

ISO 3166-1 alpha-3 country that issued the tax ID.

Example:

"USA"

nationality

string

ISO 3166-1 alpha-3 country code.

Example:

"USA"

address

object

Address of the counter party.

Show child attributes

Response

Counter party created successfully.

A counter party.

id

string

Public ID of the counter party (prefixed with cpty_).

Example:

"cpty_7dLpR2mNpXwZ7bV1aQz3x"

userId

string

Public ID of the user this counter party belongs to (prefixed with usr_).

Example:

"usr_3Kf9dQ2mNpXwZ7bV1aLcs"

type

enum<string>

Available options:

INDIVIDUAL,

BUSINESS

Example:

"INDIVIDUAL"

category

string

Business category. Present for business counter parties.

Example:

"software"

firstName

string

Present for individual counter parties.

Example:

"Jane"

lastName

string

Present for individual counter parties.

Example:

"Doe"

businessName

string

Present for business counter parties.

Example:

"Acme Corp"

phoneNumber

string

Example:

"+14155552671"

email

string<email>

Example:

"jane.doe@example.com"

taxId

string

Tax identification number.

Example:

"123-45-6789"

dateOfBirth

string<date> | null

Date of birth. Present for individual counter parties.

Example:

"1990-01-15"

incorporationDate

string<date> | null

Date of incorporation. Present for business counter parties.

Example:

"2015-06-01"

nationality

string

ISO 3166-1 alpha-3 country code. Present for individual counter parties.

Example:

"USA"

address

object

Address of the counter party.

Show child attributes

status

enum<string>

Available options:

ACTIVE,

INACTIVE

Example:

"ACTIVE"

createdAt

string<date-time>

Example:

"2026-07-01T10:30:00.000Z"

updatedAt

string<date-time>

Example:

"2026-07-01T10:30:00.000Z"

⌘I

curl --request POST \
  --url https://production.hifi.com/v3/counter-parties \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "userId": "usr_3Kf9dQ2mNpXwZ7bV1aLcs",
  "type": "INDIVIDUAL",
  "firstName": "Jane",
  "lastName": "Doe",
  "phoneNumber": "+14155552671",
  "email": "jane.doe@example.com",
  "dateOfBirth": "1990-01-15",
  "taxId": "123-45-6789",
  "nationality": "USA",
  "address": {
    "addressLine1": "123 Main Street",
    "city": "New York",
    "stateProvinceRegion": "NY",
    "postalCode": "10001",
    "country": "USA"
  }
}
'

{
  "id": "cpty_7dLpR2mNpXwZ7bV1aQz3x",
  "userId": "usr_3Kf9dQ2mNpXwZ7bV1aLcs",
  "type": "INDIVIDUAL",
  "firstName": "Jane",
  "lastName": "Doe",
  "phoneNumber": "+14155552671",
  "email": "jane.doe@example.com",
  "taxId": "123-45-6789",
  "dateOfBirth": "1990-01-15",
  "nationality": "USA",
  "address": {
    "addressLine1": "123 Main Street",
    "city": "New York",
    "stateProvinceRegion": "NY",
    "postalCode": "10001",
    "country": "USA"
  },
  "status": "ACTIVE",
  "createdAt": "2026-07-01T10:30:00.000Z",
  "updatedAt": "2026-07-01T10:30:00.000Z"
}

{
  "type": "VALIDATION_ERROR",
  "message": "One or more fields are invalid or missing.",
  "fields": [
    {
      "code": "invalid_value",
      "message": "Must be a valid email address",
      "field": "email"
    }
  ]
}

{
  "type": "UNAUTHORIZED",
  "message": "Authentication required"
}

{
  "type": "INTERNAL_SERVER_ERROR",
  "message": "An internal server error occurred"
}