Create Customer

Required scope: customer:create

customFields is keyed by the DataField name returned by ListDataFields. HeyX stores canonical DataField IDs internally, but this public endpoint deliberately accepts and returns names for compatibility. Unknown names are preserved.

Generated Reference

POST /public-api/publicapi.v1.Customer/CreateCustomer

Creates a customer from the supplied fields. Contacts are not a public API resource.

Request CreateCustomerRequest

Response CreateCustomerResponse

CreateCustomerRequest

Field	Type	Description
`title`	`string`
`custom_fields`	`map<string, string>`	Keys are DataField names from ListDataFields. The public API maps these to canonical internal IDs and continues returning names for compatibility.
`expected_close_date`	`optional int64`
`customer_name`	`optional string`
`email`	`optional string`
`phone`	`optional string`	Accepts an international number or a local number when phone_country is set.
`phone_country`	`optional string`	ISO 3166-1 alpha-2 country code used to normalize a local phone number.

CreateCustomerResponse

Field	Type
`customer`	`Customer`

Related Types

Customer

Field	Type	Description
`id`	`string`
`title`	`string`
`custom_fields`	`map<string, string>`	Name-keyed compatibility representation; keys are not internal UUIDs.
`reference_number`	`string`
`created_at`	`int64`
`updated_at`	`int64`

Request

{
  "title": "Solar installation lead",
  "customerName": "Alex Jansen",
  "email": "[email protected]",
  "phone": "0612345678",
  "phoneCountry": "NL",
  "customFields": {
    "lead_source": "website"
  }
}

Example

curl https://portal.heyx.app/public-api/publicapi.v1.Customer/CreateCustomer \
  -H "Authorization: Bearer hx_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Solar installation lead",
    "customerName": "Alex Jansen",
    "email": "[email protected]",
    "phone": "0612345678",
    "phoneCountry": "NL",
    "customFields": {
      "lead_source": "website"
    }
  }'

Response

Successful requests return 201 Created with the created customer.

{
  "customer": {
    "id": "be85f4d1-b680-4964-bf62-9828fdf4ce04",
    "title": "Solar installation lead",
    "customFields": {
      "customer_name": "Alex Jansen",
      "email": "[email protected]"
    },
    "referenceNumber": "P-000456"
  }
}