Update a contact

Update fields present in the request. Omitted fields are retained; immutable payment-routing identity cannot be replaced through this operation.

PATCH /contacts/{contactId}

Update a contact

cURL

curl --request PATCH \
  --url https://api.example.com/contacts/{contactId} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{}'

200

{
  "id": "ct_9f2c1ab84d7e4f1fa3c65b0e7d9a2c41",
  "name": "<string>",
  "isExternal": true,
  "createdAt": "2023-11-07T05:31:56Z",
  "icon": "<string>",
  "lastUsedAt": "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"

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"

Path Parameters

contactId · string · required

Body

application/json

name · string | null

Updated contact name.

Required string length: 1 - 200

icon · string | null

Updated HTTPS image URL or emoji:// reference; null removes it.

address · UserAddress · object | null

Updated postal address.

Show child attributes

isExternal · boolean | null

Whether the contact is outside the selected account.

holder · ContactHolderUpdate · object | null

Updated payment-account holder identity.

Show child attributes

intermediaryBank · IntermediaryBank · object | null

Updated intermediary institution; send null to remove it.

Show child attributes

bankAddress · BankAddress · object | null

Updated postal address of the destination institution, replacing the stored one in full.

Show child attributes

Response

200

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.

icon · string | null

HTTPS image URL or emoji:// contact icon reference.

lastUsedAt · string<date-time> | null

UTC timestamp when this contact was last used for a transfer.

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