Skip to content
HeyX API

Patch Customer Data Fields

Required scope: customer_datafield:write

Use this endpoint when an external system needs to set or clear specific customer data fields. Keys are DataField names returned by ListDataFields. Requests and responses remain name-keyed even though HeyX stores canonical DataField IDs internally.

Patch semantics:

  • Omitted key: leave unchanged.
  • String value: set that data field.
  • null value: clear that data field.

Currency values are integer-cent strings. Send "25000" for EUR 250.00; do not send a decimal major-unit value such as "250.00".

Location values are sent as a JSON-encoded string because customer data field values use a string contract. Every location property is optional. Latitude and longitude, when used, must be supplied together and be within their normal ranges.

{
  "installation_location": "{\"street\":\"Keizersgracht\",\"house_number\":\"123\",\"zipcode\":\"1015 CJ\",\"city\":\"Amsterdam\",\"country\":\"NL\",\"latitude\":52.3751,\"longitude\":4.8837,\"full_address\":\"Keizersgracht 123, 1015 CJ Amsterdam, NL\"}"
}

Company values are also JSON-encoded strings. They support company_name, registration_number, and vat_number. Include at least one nonempty string; unknown properties, null values, and non-string property values are rejected:

{
  "primary_company": "{\"company_name\":\"Acme Installations B.V.\",\"registration_number\":\"12345678\",\"vat_number\":\"NL123456789B01\"}"
}
Generated Reference
POST /public-api/publicapi.v1.Customer/PatchCustomerDataFields

Patches customer data fields without replacing unspecified fields.

Request PatchCustomerDataFieldsRequest
Response PatchCustomerDataFieldsResponse

PatchCustomerDataFieldsRequest

Field Type
customer_id string
fields map<string, google.protobuf.Value>

PatchCustomerDataFieldsResponse

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

Section titled “Request”
{
  "customerId": "be85f4d1-b680-4964-bf62-9828fdf4ce04",
  "fields": {
    "external_status": "received",
    "source": "erp",
    "legacy_code": null
  }
}

Example

Section titled “Example”
Terminal window
curl https://portal.heyx.app/public-api/publicapi.v1.Customer/PatchCustomerDataFields \
  -H "Authorization: Bearer hx_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "be85f4d1-b680-4964-bf62-9828fdf4ce04",
    "fields": {
      "external_status": "received",
      "source": "erp",
      "legacy_code": null
    }
  }'

Response

Section titled “Response”
{
  "customer": {
    "id": "be85f4d1-b680-4964-bf62-9828fdf4ce04",
    "title": "Solar installation lead",
    "customFields": {
      "external_status": "received",
      "source": "erp"
    },
    "referenceNumber": "P-000456"
  }
}
HeyX API