Customer profiles & context

Look up the customer you already know

GET /customers/lookup accepts exactly one email, phone or external_id. It uses exact normalized identity matching. External IDs are trimmed, whitespace-normalized and case-insensitive; choose stable IDs that remain distinct after normalization. Phone matching removes formatting and treats an international 00 prefix as +.

A missing or merged profile returns 404. Lookups never search another workspace. Profile reads include canonical attributes and widget_context: up to five recent snapshots of attributes supplied by the website. Website values are useful context, not verified claims.

curl --get "https://trucom.app/api/v1/rest/customers/lookup" \
  --data-urlencode "external_id=account-1042" \
  -H "Authorization: Bearer $TRUCOM_API_KEY"

Create or update by external ID

PUT /customers creates a customer when the external ID is new and updates that same customer on later calls. A new profile returns 201; an update returns 200. Omitted fields stay unchanged.

POST /customers creates a new profile and requires an Idempotency-Key. Use PATCH /customers/{customer} when you already have the TruCom public customer ID. Conflicting email, phone or external ID identities return 422; the API does not silently merge customers.

curl -X PUT "https://trucom.app/api/v1/rest/customers" \
  -H "Authorization: Bearer $TRUCOM_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: account-1042-profile-v3" \
  -d '{"external_id":"account-1042","name":"Alex Morgan","email":"[email protected]","attributes":{"plan":"Business","orders":12}}'

Update only what you mean to change

Profile fields are name, email, phone, company and external_id. Null clears a nullable field. At least one of name, email, phone or external_id is required when creating with POST; external_id is required for PUT. Empty PATCH requests are rejected.

Attributes merge by key. Send null to remove an attribute. Use a flat object with strings, numbers or booleans: up to 50 keys, 1,000 characters per string and 20 KB for the complete stored collection. Keys start with a letter and use letters, numbers, periods, underscores or hyphens, up to 64 characters. prototype, constructor and __proto__ are reserved.

Canonical attributes written by your backend remain separate from website widget_context. Unknown top-level write fields are rejected. Billing limits and customer identity rules apply just as they do inside the workspace.

{"attributes":{"plan":"Enterprise","legacy_plan":null}}

Read the full customer response

A profile includes public ID, contact details, company, external ID, attributes, tags, source, anonymity and timestamps. Lists omit widget_context to keep pagination efficient. The show, lookup and write endpoints include it.