02 · Core Actions
Create/Update Lead, Lead Stages, Calls, Sales — required vs optional fields and idempotency.
The core write actions
Five actions cover most integrations: Create Lead, Update Lead, send Lead Stage, track Calls, and track Sales. A lead is created with an email OR a phone number, and that identifier is the join key. Creating and updating a lead are effectively the same call — Hyros upserts on email/phone.
Required vs optional fields
Leads require an email OR a phone number; firstName, lastName, tags, and stage are optional. Orders/sales require the line items (items[] with name/price) plus the lead's email (or phone). Calls require a name and email. Take exact field names from the Hyros API reference — the Request Explorer ships them verified.
Idempotency — re-sending updates, never duplicates
Re-sending the same email (or phone) updates the existing lead rather than creating a duplicate — Hyros never creates duplicate leads. There is no reliable "already exists" error, so design for upsert, not duplicate detection. Tags are additive: sending a tag adds it, and Hyros de-duplicates so you never get repeats. For orders, re-sending the same orderId updates the existing sale instead of double-counting revenue. Tag prefixes carry meaning: ! = action tags, $ = product tags, @ = source tags.