OrdstageDocs

Resources

Contacts and leads

Create, update, tag, merge and delete contacts, and manage leads and their status.

Scope Lets a key
contacts:read / contacts:write List, read, create, update, tag, merge and delete contacts.
leads:read / leads:write List, read, create, update and delete leads. Needs the plan's Leads feature.

Contacts

A contact is someone the business talks to. Contacts are created by the assistant when someone new messages the business, by orders and bookings, and by the API. Each has a name, email, phone, locale, tags and your own attributes (up to 50 keys and 8 KB). At least a name, an email or a phone number is required.

curl -X POST https://api.ordstage.com/v1/contacts \
  -H "Authorization: Bearer $ORDSTAGE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"name": "Mona Adel", "email": "mona@example.com", "tags": ["vip"], "attributes": {"his_patient_id": "P-1042"}}'
  • PATCH /v1/contacts/{contact_id} changes only the fields you send; in attributes, a key set to null is removed and others keep their values.
  • POST /v1/contacts/{contact_id}/tags with {"add": [...], "remove": [...]} changes tags without a read first.
  • GET /v1/contacts?email=…, ?phone=…, ?tag=… or ?q=… finds contacts.
  • POST /v1/contacts/{contact_id}/merge with {"duplicate_id": "…"} moves everything that points at the duplicate (conversations, orders, bookings, leads, channel identities) to this contact, fills its empty fields, joins the tags, and deletes the duplicate, in one step.
  • DELETE /v1/contacts/{contact_id} deletes the contact; its conversations, orders and bookings stay.

Events: contact.created, contact.updated, contact.deleted, contact.merged.

Leads

A lead is someone who asked to be contacted, usually through the assistant. Create one from your own forms (POST /v1/leads with a name, what they need, and an email or phone number), then move it through new, contacted, qualified, won or lost with PATCH /v1/leads/{lead_id}, add a note, or assign a member.

{ "status": "contacted", "note": "Called, sending the price list" }

Events: lead.created, lead.updated, lead.status_changed (with previous_status), lead.deleted. The Leads page in the dashboard shows the same leads and sends the same events.