Skip to main content
PUT
Upsert a customer by externalId

Authorizations

Authorization
string
header
required

Use a workspace API key in the Authorization header. Keys use pk_live_<key_id> for production and pk_test<key_id>_ for test mode.

Headers

Idempotency-Key
string

Optional retry key for safely replaying create requests. Reusing the same key with a different request body returns 409.

Required string length: 8 - 255
Example:

"8db8e596-7c1a-4fd5-a728-4d6c99f4e66b"

Body

application/json

externalId is the natural key and is required. On update, only the provided fields are written; omitted fields are left unchanged.

externalId
string
required

Your stable id for this customer; the upsert key.

Example:

"renter_123"

name
string
Example:

"Maya"

email
string<email>
Example:

"maya@example.com"

phone
string
Example:

"+628123456789"

company
string
Example:

"Bali Villa Hub"

language
string
Example:

"id"

timezone
string
Example:

"Asia/Jakarta"

metadata
object

Replaces the full customer metadata object. Evelin reads account context only from the reserved tenant object and only permits id, name, plan, status, domain, region, createdAt, and updatedAt.

Example:

Response

Existing customer patched.

Every key is always present; optional fields are null when unset (never empty strings).

id
string
required
Example:

"cus_x6q5vl75f5d53m7oet2k4r5w6a"

externalId
string | null
required
Example:

"renter_123"

name
string
required
Example:

"Maya"

email
string | null
required
Example:

"maya@example.com"

phone
string | null
required
Example:

"+628123456789"

company
string | null
required
Example:

"Bali Villa Hub"

language
string | null
required
Example:

"id"

timezone
string | null
required
Example:

"Asia/Jakarta"

avatarUrl
string | null
required
Example:

"https://cdn.example.com/avatars/maya.png"

claimedEmail
string | null
required

An email the customer claimed but that is not verified.

emailStatus
string | null
required

Email deliverability/suppression state (e.g. active, unsubscribed, bounced).

lastActiveChannel
string | null
required
Example:

"whatsapp"

firstContactAt
string<date-time> | null
required
lastSeenAt
string<date-time> | null
required
tags
string[]
required
metadata
object
required
createdAt
string<date-time>
required
updatedAt
string<date-time>
required
conversationCount
integer

Number of conversations for this customer. Present on list responses only.