contacts

Create a contact

Changed on Nov 12, 2026

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

Request

The document declares no server URL.
Auth
HTTP bearer
TypeScript
https://skmtc.dev/hevn-inc/apis/hevn-api/docs/contacts/post.ts
A function with typed inputs. Its response is checked against the schema.

Headers

X-Hevn-Accountstring nullable

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

Example:cl_9f2c1ab84d7e4f1fa3c65b0e7d9a2c41

Idempotency-Keystring nullable

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

Request body

namestring

Human-readable contact name.

iconstring nullable

HTTPS image URL or emoji://<emoji> reference displayed for this contact.

currencystring nullable

Destination currency.

emailstring nullable

Email used to resolve an existing HEVN contact.

isExternalboolean nullable

Whether the contact is outside the selected account.

Response

Successful Response

idstring required

Stable public identifier for this contact.

namestring required

Human-readable contact name.

iconstring nullable

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

isExternalboolean required

Whether the contact is outside the selected account.

createdAtstring date-time required

UTC timestamp when the contact was created.

lastUsedAtstring date-time nullable

UTC timestamp when this contact was last used for a transfer or a successful fiat payout quote.

emailstring nullable

Email associated with an existing HEVN contact.

userIdstring uuid nullable

Account behind an existing HEVN contact.

Example response

{
  "id": "ct_9f2c1ab84d7e4f1fa3c65b0e7d9a2c41",
  "bank": {
    "minimumDeposit": "500.00"
  }
}

Changes

Nov 12, 2026299a3aa6f521 Revision changes
- breaking
  removed from the // request property anyOf list
- breaking
  removed from the /// request property anyOf list
- breaking
  removed from the // request property anyOf list
- breaking
  removed from the request property anyOf list
- breaking
  removed from the /// request property anyOf list
- warning
  added the new FDIC_EUR enum value to the /// response property for the response status
- warning
  added the new verification_not_applicable enum value to the / response property for the response status
- info
  added to the // request property anyOf list
- info
  added to the /// request property anyOf list
- info
  added to the // request property anyOf list
- info
  added to the request property anyOf list
- info
  added to the /// request property anyOf list
- info
  added to the // response property anyOf list for the response status
- info
  added to the // response property anyOf list for the response status
- info
  added to the response property anyOf list for the response status
- info
  added to the /// response property anyOf list for the response status
- info
  removed from the // response property anyOf list for the response status
- info
  removed from the // response property anyOf list for the response status
- info
  removed from the response property anyOf list for the response status
- info
  removed from the /// response property anyOf list for the response status
- info
  the response property /// became required for the status
- info
  the response property /// became required for the status
- info
  the response property /// became required for the status
- info
  the response property /// became required for the status
- info
  the response property /// became required for the status
- info
  the response property /// became required for the status
- info
  the response property /// became required for the status
- info
  the response property /// became required for the status
- info
  the response property /// became required for the status
- info
  the response property /// became required for the status
- info
  the response property /// became required for the status
- info
  the response property /// became required for the status
- info
  the response property /// became required for the status
- info
  the response property /// became required for the status
- info
  the response property /// became required for the status
- info
  the response property /// became required for the status
- info
  the response property /// became required for the status
- info
  the response property /// became required for the status
- info
  the response property /// became required for the status
- info
  removed the phone_required enum value from the / response property for the response status
- info
  removed the rail_requirements_unmet enum value from the / response property for the response status
Oct 23, 2026a02795de2d2b Revision changes
- warning
  deleted the header request parameter x-api-key
- warning
  added the new KYC_CARDS enum value to the /// response property for the response status
- warning
  added the new RD enum value to the /// response property for the response status
- warning
  added the new USDC_ARB enum value to the /// response property for the response status
- warning
  added the new client_already_linked enum value to the / response property for the response status
- warning
  added the new kyb_documents_processing enum value to the / response property for the response status
- warning
  added the new link_code_expired enum value to the / response property for the response status
- warning
  added the new link_code_invalid enum value to the / response property for the response status
- warning
  added the new payout_not_awaiting_signature enum value to the / response property for the response status
- warning
  added the new redirect_uri_not_allowed enum value to the / response property for the response status
- warning
  added the new sandbox_amount_limit_exceeded enum value to the / response property for the response status
- warning
  added the new sandbox_faucet_balance_too_high enum value to the / response property for the response status
- info
  added the new optional request property
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  removed the client_policy_not_enabled enum value from the / response property for the response status
- info
  removed the client_request_conflict enum value from the / response property for the response status
- info
  removed the email_in_use enum value from the / response property for the response status
- info
  removed the integrator_inactive enum value from the / response property for the response status
- info
  removed the name_in_use enum value from the / response property for the response status

Operation history (10 revisions)