Create Contact

Required scope: contact:create

Creates a contact from the supplied fields. At least one of name, email, or phone is required.

This operation is get-or-create: if the email or phone already identifies a contact in the workspace, the existing contact is returned instead of creating a duplicate. That makes create idempotent by identifier and safe to retry. phone is accepted in local or international form and normalized to E.164; pass phoneCountry (an ISO 3166-1 alpha-2 code such as NL) to resolve a local number.

Generated Reference

POST /public-api/publicapi.v1.Contact/CreateContact

Creates a contact, or returns the existing contact when the supplied email or phone already identifies one. At least one of name, email, or phone is required. Because a matching identifier returns the existing contact, this operation is idempotent by identifier.

Request CreateContactRequest

Response CreateContactResponse

CreateContactRequest

Field	Type	Description
name	string	Display name. At least one of name, email, or phone is required.
email	string	Email address. Matching an existing contact by email returns that contact.
phone	string	Phone number in any common format; normalized to E.164 server-side. Matching an existing contact by phone returns that contact.
phone_country	string	Two-letter ISO 3166-1 country code used to normalize a national phone number, for example "NL". Ignored when phone is already in E.164 format.
locale	string	BCP 47 locale tag, for example "en" or "nl-NL".

CreateContactResponse

Field	Type	Description
contact	Contact	The created or matched contact.

Related Types

Contact

Field	Type	Description
id	string	Stable contact identifier.
name	string	Display name, if set.
email	string	Email address, if set.
phone_e164	string	Phone number in E.164 format, if set.
customer_number	string	Human-facing customer number when the contact is linked to a customer.
locale	string	BCP 47 locale tag, for example "en" or "nl-NL", if set.
created_at	int64	Creation time as a Unix timestamp in seconds.
updated_at	int64	Last-update time as a Unix timestamp in seconds.

Request

{
  "name": "Alex Jansen",
  "email": "[email protected]",
  "phone": "0612345678",
  "phoneCountry": "NL",
  "locale": "nl-NL"
}

Example

curl https://portal.heyx.app/public-api/publicapi.v1.Contact/CreateContact \
  -H "Authorization: Bearer hx_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Alex Jansen",
    "email": "[email protected]",
    "phone": "0612345678",
    "phoneCountry": "NL"
  }'

Response

Successful requests return 201 Created with the created (or matched) contact.

{
  "contact": {
    "id": "<contact-id>",
    "name": "Alex Jansen",
    "email": "[email protected]",
    "phoneE164": "+31612345678",
    "locale": "nl-NL",
    "createdAt": 1726300000,
    "updatedAt": 1726300000
  }
}