identify_contact

Upsert a contact by your system’s user id. If a contact with external_user_id exists in this workspace, traits fill any null fields (admin-edited values stick); otherwise a new contact is inserted. Naturally idempotent: same payload, same final state. Prefer over create_contact when you control the external id.

required scope: read:write.

example prompts

• “every time my user logs in, call identify_contact with their plan and mrr so spirby’s customer list stays fresh.”
• “on subscription change, identify the contact with the new plan tier.”

input

field	type	required	notes
external_user_id	string (max 255 chars)	yes
email	string (max 320 chars)	no
name	string (max 200 chars)	no
plan	string (max 100 chars)	no
mrr_cents	integer (0-100,000,000)	no
currency	string (regex)	no
metadata	object	no

notes

• Identify never overwrites a trait with null — pass a real value to update; omit the key to leave it alone.
• mrr_cents and currency must be paired — set both or omit both.
• mrr_cents is capped at 100,000,000 ($1M); email capped at 320 characters; metadata may not exceed 100 keys.
• Identify calls that only update last_seen_at (no trait changes) skip the contact.updated webhook to avoid flooding subscribers on every widget page load.

output

The contact row.