Create a contact

Create an idempotent reusable contact from either payment-account or on-chain details. Fields are validated for the selected account type before persistence.

POST /contacts

Create a contact

cURL

curl --request POST \
  --url https://api.example.com/contacts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "currency": "<string>",
  "email": "<string>",
  "address": {
    "streetAddress": "<string>",
    "addressLine2": "<string>",
    "city": "<string>",
    "state": "<string>",
    "zip": "<string>"
  }
}
'

201

{
  "id": "ct_9f2c1ab84d7e4f1fa3c65b0e7d9a2c41",
  "name": "<string>",
  "isExternal": true,
  "createdAt": "2023-11-07T05:31:56Z",
  "email": "<string>",
  "address": {
    "streetAddress": "<string>",
    "addressLine2": "<string>",
    "city": "<string>",
    "state": "<string>",
    "country": "AF",
    "zip": "<string>"
  },
  "bank": {
    "method": "<string>",
    "currency": "<string>",
    "fields": {
      "iban": "<string>",
      "bic": "<string>",
      "accountNumber": "<string>",
      "routingNumber": "<string>",
      "pixKey": "<string>",
      "pixKeyType": "phone",
      "paymentKey": "<string>",
      "financialInstitutionId": "<string>",
      "branchNumber": "<string>",
      "accountKind": "checking",
      "phoneNumber": "<string>"
    },
    "holder": {
      "type": "individual",
      "firstName": "<string>",
      "lastName": "<string>",
      "businessName": "<string>",
      "address": {
        "streetAddress": "<string>",
        "addressLine2": "<string>",
        "city": "<string>",
        "state": "<string>",
        "country": "AF",
        "zip": "<string>"
      },
      "idType": "passport",
      "idNumber": "<string>",
      "taxId": "<string>",
      "nationality": "<string>"
    },
    "state": "active",
    "bankName": "<string>",
    "bankAddress": {
      "addressLine1": "<string>",
      "city": "<string>",
      "state": "<string>",
      "postalCode": "<string>",
      "country": "<string>"
    },
    "intermediaryBank": {
      "bic": "<string>",
      "name": "<string>",
      "address": {
        "addressLine1": "<string>",
        "city": "<string>",
        "state": "<string>",
        "postalCode": "<string>",
        "country": "<string>"
      },
      "accountNumber": "<string>"
    },
    "paymentReference": "<string>",
    "destinationAccount": "USDC",
    "minimumDeposit": "500.00"
  },
  "crypto": {
    "address": "<string>",
    "chain": "<string>",
    "token": "<string>"
  },
  "userId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "user": {
    "avatar": "<string>",
    "name": "<string>"
  }
}

Authorizations

Authorization · string · header · required

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

Headers

X-Hevn-Account · string | null

The client account to act for, as a cl_… id. Omit it to act as yourself.

Example:

"cl_9f2c1ab84d7e4f1fa3c65b0e7d9a2c41"

x-api-key · string | null

Idempotency-Key · string | null

Your own key for this write, ^[A-Za-z0-9._:-]{1,128}$. A retry with the same key replays the first answer; the same key with a different request is refused.

Example:

"po-inv-2026-114"

Body

application/json

name · string · default: ""

Human-readable contact name.

Maximum string length: 200

currency · string | null

Destination currency.

Required string length: 3 - 4

email · string | null

Email used to resolve an existing HEVN contact.

crypto · ContactCryptoInput · object | null

Legacy on-chain destination details.

Show child attributes

account · PlatformOnchainAccountInput · object

Typed payment-account, email or on-chain destination.

PlatformOnchainAccountInput

PlatformEmailAccountInput

BankAccountInput

Show child attributes

bank · ContactPaymentAccount · object | null

Legacy payment-account destination details.

Show child attributes

address · UserAddress · object | null

Postal address of the contact or account holder.

Show child attributes

isExternal · boolean | null

Whether the contact is outside the selected account.

Response

201

application/json

Successful Response

id · string · required

Stable public identifier for this contact.

Pattern: ^(?:ct_)?[A-Za-z0-9._:\-]{1,216}$

Example:

"ct_9f2c1ab84d7e4f1fa3c65b0e7d9a2c41"

name · string · required

Human-readable contact name.

isExternal · boolean · required

Whether the contact is outside the selected account.

createdAt · string<date-time> · required

UTC timestamp when the contact was created.

email · string | null

Email associated with an existing HEVN contact.

address · UserAddress · object | null

Postal address of the contact or account holder.

Show child attributes

bank · ContactPaymentAccountView · object | null

Payment-account destination details.

Show child attributes

crypto · ContactCryptoView · object | null

On-chain destination details.

Show child attributes

userId · string<uuid> | null

Account behind an existing HEVN contact.

user · ContactLinkedUserView · object | null

Profile of the linked HEVN account.

Show child attributes