# Contacts and leads

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

Source: https://www.ordstage.com/docs/contacts-and-leads/

| 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.

```bash [curl]
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.

```json
{ "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.