> ## Documentation Index
> Fetch the complete documentation index at: https://developers.cloudtalk.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Contact Webhook Events: Payloads for the contact.* Triggers
> Reference for CloudTalk's contact webhook events (contact.created, contact.updated, and contact.deleted) with example payloads and field definitions.
Contact events keep external systems in sync with your CloudTalk contact list. `contact.created` and `contact.updated` carry the full contact card; `contact.deleted` carries only the id. These are account-level webhooks, delivered to the endpoints you register under **Account → Webhooks**. See the [overview](/guides/webhooks/overview).
All examples show the full request body, including the [envelope](/guides/webhooks/overview#the-event-envelope). Fields with empty values are omitted from payloads: they are never sent as `null`. Fields shown in **bold** are always present. A bold field nested inside an optional object is always present whenever that object is. Everything else is optional.
## contact.created
Fires when a new contact is added to your account: created manually, imported, or added through an integration or the API. Use it to keep your CRM, helpdesk, or data warehouse in sync as new contacts appear.
```json Example theme={"system"}
{
"event_id": "018f4c2a-9b1d-8e3f-9a2b-6c5d4e3f2a10",
"type": "contact.created",
"version": "v1",
"occurred_at": "2026-08-17T09:34:21.512Z",
"company_id": "123456",
"data": {
"id": "44210",
"type": "contact",
"name": "Jane Doe",
"company": "Acme Inc.",
"title": "Head of Procurement",
"industry": "Manufacturing",
"website": "https://acme.example.com",
"address": "1 Market Street",
"city": "San Francisco",
"state": "CA",
"zip": "94105",
"phones": ["+12025550143", "+13105550166"],
"emails": ["jane.doe@example.com", "j.doe@acme.example.com"],
"country": { "name": "United States", "country_code": "US" },
"tags": ["vip", "priority"],
"custom_fields": { "crm_id": "CRM-00042", "segment": "enterprise" },
"external_urls": [{ "name": "CRM profile", "url": "https://crm.example.com/contacts/42" }],
"source": "api",
"created_at": "2026-08-17T09:34:21.500Z",
"modified_at": "2026-08-17T09:34:21.500Z",
"favorite_user": {
"id": "7",
"name": "Ada Bennett",
"first_name": "Ada",
"last_name": "Bennett",
"email": "ada.bennett@example.com",
"role": "agent",
"language": "en",
"extension": "1007"
}
}
}
```
| Field | Type | Description |
| --------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **`id`** | string | The contact's id in CloudTalk. |
| `type` | string | The contact kind: `contact` or `lead`. |
| `name` | string | The contact's display name. |
| `company` | string | Company name on the contact card. |
| `title` | string | Job title. |
| `industry` | string | Industry label. |
| `website` | string | Website URL. |
| `address` | string | Street address. Related fields: `city`, `state`, `zip`. |
| `phones` | string\[] | The contact's phone numbers, in E.164 format. |
| `emails` | string\[] | The contact's email addresses. |
| `country` | object | The contact's country: `{ "name": "United States", "country_code": "US" }`. |
| `tags` | string\[] | Tag names on the contact. |
| `custom_fields` | object | Your custom fields as a key-value map of strings. |
| `external_urls` | object\[] | Named external links on the contact. Each item: `{ "name": "...", "url": "..." }`. |
| `source` | string | Where the contact record originated. |
| `created_at` | string | When the contact was created. |
| `modified_at` | string | When the contact was last modified. |
| `favorite_user` | User | The user assigned to the contact as their favorite (preferred) agent, when one is set. Same shape as [the user object](/guides/webhooks/events/calls#the-user-object) on call events. Omitted when the contact has no favorite user or that user has since been deleted. |
## contact.updated
Fires whenever an existing contact's details change: a renamed contact, an added phone number or email, edited tags and custom fields, or a change of favorite user.
The payload carries the contact's **full, current profile** (the same shape as [`contact.created`](#contact-created)), not just the fields that changed. You can simply overwrite your stored copy. To find out exactly what changed, compare the payload with the version you previously stored.
```json Example theme={"system"}
{
"event_id": "018f4c2a-9b1d-8f7a-9c3d-2e1f0a9b8c76",
"type": "contact.updated",
"version": "v1",
"occurred_at": "2026-08-17T10:05:42.318Z",
"company_id": "123456",
"data": {
"id": "44210",
"type": "contact",
"name": "Jane Doe",
"company": "Acme Inc.",
"title": "VP of Procurement",
"phones": ["+12025550143"],
"emails": ["jane.doe@example.com"],
"country": { "name": "United States", "country_code": "US" },
"tags": ["vip", "priority", "renewal-q3"],
"custom_fields": { "crm_id": "CRM-00042", "segment": "enterprise" },
"source": "api",
"created_at": "2026-08-17T09:34:21.500Z",
"modified_at": "2026-08-17T10:05:42.300Z",
"favorite_user": {
"id": "7",
"name": "Ada Bennett",
"first_name": "Ada",
"last_name": "Bennett",
"email": "ada.bennett@example.com",
"role": "agent",
"language": "en",
"extension": "1007"
}
}
}
```
Because empty fields are omitted, a field cleared by an update simply disappears from the payload. Treat absence as empty when overwriting your copy.
## contact.deleted
Fires when a contact is removed from your account. Because the record no longer exists, the payload contains only the deleted contact's id. Use it to delete or archive the matching record in your connected systems.
```json Example theme={"system"}
{
"event_id": "018f4c2b-1c2d-8a4b-9e5f-7a6b5c4d3e21",
"type": "contact.deleted",
"version": "v1",
"occurred_at": "2026-08-17T11:12:03.044Z",
"company_id": "123456",
"data": {
"id": "44210"
}
}
```
| Field | Type | Description |
| -------- | ------ | ----------------------------------------------------------------------------------------------------- |
| **`id`** | string | The deleted contact's id: matches the id from earlier `contact.created` and `contact.updated` events. |
Treat a delete as terminal for that contact. Events are not guaranteed to arrive in order, so an earlier `contact.updated` can occasionally be delivered after the `contact.deleted`: order by `occurred_at`.
## Related topics
- [Call Webhook Events: Payloads for the call.* Triggers](/guides/webhooks/events/calls.md)
- [Message Webhook Events: Payloads for the message.* Triggers](/guides/webhooks/events/messages.md)
- [User Webhook Events: Payloads for the user.* Triggers](/guides/webhooks/events/users.md)