Skip to content
HeyX API

Lookup Customers By Identifier

Required scope: customer:read

Use this endpoint to resolve an inbound email address or phone number to the customers it belongs to — for example when a message, call, or webhook arrives and you need the customer before taking further action. Each match includes the customer’s current journey statuses.

Set identifierType to PUBLIC_LOOKUP_IDENTIFIER_TYPE_EMAIL or PUBLIC_LOOKUP_IDENTIFIER_TYPE_PHONE. Phone numbers may be supplied in common formats and are normalized server-side; the normalized value is returned as normalizedIdentifier.

Results are limited to customers the API key can access. An empty customers list therefore means “no accessible match”, which is not the same as “no such customer”.

Generated Reference
POST /public-api/publicapi.v1.Customer/LookupCustomersByIdentifier

Looks up customers by an email address or phone number, returning each matching customer with its current journey statuses. Results are limited to customers the API key can access, so an empty list does not prove the identifier is unknown.

Request LookupCustomersByIdentifierRequest
Response LookupCustomersByIdentifierResponse

LookupCustomersByIdentifierRequest

Field Type Description
identifier_type LookupIdentifierType Which kind of identifier is being looked up.
identifier string The email address or phone number to match. Phone numbers may be supplied in common formats and are normalized server-side.

LookupCustomersByIdentifierResponse

Field Type Description
normalized_identifier string The identifier after server-side normalization, for example E.164 for phone numbers.
customers repeated IdentifierCustomer Customers matching the identifier that the API key can access. Empty when nothing matches or no matches are within the key's accessible customers.

Related Types

IdentifierCustomer

Field Type Description
customer_id string Stable customer identifier.
title string Customer title or display name.
reference_number string Human-facing reference number.
journey_statuses repeated IdentifierJourneyStatus Current journey status for each track the customer is on.

IdentifierJourneyStatus

Field Type Description
track_id string Journey track identifier.
track_name string Journey track name.
status_id string Current status identifier on the track.
status_name string Current status name on the track.
color string Presentation color as a hex string, for example "#3366FF".

Request

Section titled “Request”
{
  "identifierType": "PUBLIC_LOOKUP_IDENTIFIER_TYPE_EMAIL",
  "identifier": "[email protected]"
}

Example

Section titled “Example”
Terminal window
curl https://portal.heyx.app/public-api/publicapi.v1.Customer/LookupCustomersByIdentifier \
  -H "Authorization: Bearer hx_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "identifierType": "PUBLIC_LOOKUP_IDENTIFIER_TYPE_PHONE",
    "identifier": "+31 970 123 45678"
  }'

Response

Section titled “Response”
{
  "normalizedIdentifier": "+3197012345678",
  "customers": [
    {
      "customerId": "be85f4d1-b680-4964-bf62-9828fdf4ce04",
      "title": "Solar installation lead",
      "referenceNumber": "P-000456",
      "journeyStatuses": [
        {
          "trackId": "0f1c2d3e-4a5b-6c7d-8e9f-0a1b2c3d4e5f",
          "trackName": "Sales pipeline",
          "statusId": "9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d",
          "statusName": "Quote sent",
          "color": "#3366FF"
        }
      ]
    }
  ]
}
HeyX API