# contacts

> Customers: identities, consent, tags, stages, merge, erase.

Customers: identities, consent, tags, stages, merge, erase.

| Method | Path | Operation | Scope | Test mode |
|---|---|---|---|---|
| GET | `/v1/contacts` | `contacts_list`: List and filter contacts | `contacts:read` | yes |
| POST | `/v1/contacts` | `contacts_create`: Create a contact | `contacts:write` | yes |
| POST | `/v1/contacts:bulk-assign` | `contacts_bulk_assign`: Give many customers to one staff member | `contacts:write` | - |
| POST | `/v1/contacts:upsert` | `contacts_upsert`: Create or update a contact by identity (idempotent) | `contacts:write` | yes |
| DELETE | `/v1/contacts/{contact_id}` | `contacts_delete`: Erase a contact (DSR: tombstone content, keep billing metadata) | `contacts:delete` | yes |
| GET | `/v1/contacts/{contact_id}` | `contacts_get`: Get a contact | `contacts:read` | yes |
| PATCH | `/v1/contacts/{contact_id}` | `contacts_update`: Update a contact (JSON Merge Patch) | `contacts:write` | yes |
| GET | `/v1/contacts/{contact_id}/attribution` | `contacts_get_attribution`: Click-to-WhatsApp / lead-ad attribution | `contacts:read` | - |
| GET | `/v1/contacts/{contact_id}/consents` | `contacts_list_consents`: Consent records | `contacts:read` | yes |
| POST | `/v1/contacts/{contact_id}/consents` | `contacts_record_consent`: Record an opt-in or opt-out with proof | `contacts:write` | yes |
| GET | `/v1/contacts/{contact_id}/identities` | `contacts_list_identities`: List a contact's identities | `contacts:read` | - |
| POST | `/v1/contacts/{contact_id}/identities` | `contacts_add_identity`: Add an identity (phone, email, BSUID, IG/Messenger id) | `contacts:write` | - |
| DELETE | `/v1/contacts/{contact_id}/identities/{identity_id}` | `contacts_remove_identity`: Remove an identity | `contacts:write` | - |
| POST | `/v1/contacts/{contact_id}/merge` | `contacts_merge`: Merge duplicates into this contact | `contacts:write` | - |
| POST | `/v1/contacts/{contact_id}/opt-out` | `contacts_opt_out`: Record a staff opt-out (marketing) and request the confirmation message | `contacts:write` | yes |
| POST | `/v1/contacts/{contact_id}/stage` | `contacts_set_stage`: Move the contact to a pipeline stage (writes stage history) | `contacts:write` | - |
| GET | `/v1/contacts/{contact_id}/stage-history` | `contacts_stage_history`: All stage transitions (retained for the life of the contact) | `contacts:read` | - |
| GET | `/v1/contacts/{contact_id}/summary` | `contacts_summary`: What a customer owes, has paid, ordered and booked, and what is next | `contacts:read` | - |
| POST | `/v1/contacts/{contact_id}/tags` | `contacts_add_tags`: Add tags (by id or name; missing names are created) | `contacts:write` | yes |
| DELETE | `/v1/contacts/{contact_id}/tags/{tag_id}` | `contacts_remove_tag`: Remove a tag from a contact | `contacts:write` | yes |
| GET | `/v1/contacts/{contact_id}/timeline` | `contacts_timeline`: Activity timeline (notes, stage changes, consent, opt-outs, conversations, orders, payments, bookings, calls, automations) | `contacts:read` | yes |
| POST | `/v1/contacts/bulk` | `contacts_bulk_upsert`: Bulk create/update contacts (up to 1,000) | `contacts:write` | yes |
| POST | `/v1/contacts/bulk-delete` | `contacts_bulk_delete`: Erase many contacts by ids or segment (second confirmation required) | `contacts:delete` | - |
| GET | `/v1/contacts/duplicates` | `contacts_find_duplicates`: Duplicate candidates (same phone, same email, same name) | `contacts:read` | - |
| POST | `/v1/contacts/merge-preview` | `contacts_merge_preview`: Preview a merge without changing anything | `contacts:read` | - |

Request and response schemas: the interactive reference at `https://api.wapitick.com/docs`, or `docs/api/openapi.json`.
