Contacts

List contacts

GET /v1/c/{slug}/contacts · Scopes: contacts:read

Most active first. q searches name or phone; tag filters by tag; before (the last one's lastActivityAt) brings the next page.

Path parameters

Field	Notes
`slug`	The company's identifier in DoneTalk (the key's own).

Query parameters

Field	Type	Required	Notes
`q`	string	no	up to 200 characters
`limit`	integer	no	up to 100; at least 1; default `50`
`before`	string (date-time)	no
`tag`	string (uuid)	no

Request example

curl -X GET "https://api.donetalk.com/v1/c/demo/contacts" \
  -H "Authorization: Bearer $DONETALK_KEY"

Response 200

{
  "contacts": [
    {
      "id": "01a0d05a-3ee3-75bd-9db5-dc9856f079c8",
      "displayName": "Ana Souza",
      "address": "5548999990001",
      "channelKind": "whatsapp",
      "source": "api",
      "externalRef": "erp-88213",
      "fields": {
        "cpf": "529.982.247-25",
        "plano": "anual"
      },
      "isBlocked": false,
      "lastActivityAt": "2026-10-22T18:40:02.000Z",
      "createdAt": "2026-09-23T22:19:30.396Z",
      "tags": [
        {
          "id": "01a12150-3610-7c00-b680-188c2b4c7313",
          "name": {
            "pt-BR": "VIP",
            "en": "VIP",
            "es": "VIP"
          },
          "color": "#92400e"
        }
      ]
    }
  ]
}

Possible errors

401 unauthorized
403 insufficient_scope
422 validation_failed
429 rate_limited

Create a contact

POST /v1/c/{slug}/contacts · Scopes: contacts:write

To create or update many at once (or one that may exist), use POST /contacts/import.

Path parameters

Field	Notes
`slug`	The company's identifier in DoneTalk (the key's own).

Request body

Field	Type	Required	Notes
`displayName`	string	yes	up to 200 characters
`phone`	string	yes
`locale`	one of `pt-BR`, `es`, `en`	no
`fields`	object	no
`externalRef`	string	no	up to 200 characters

Request example

curl -X POST "https://api.donetalk.com/v1/c/demo/contacts" \
  -H "Authorization: Bearer $DONETALK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "displayName": "Ana Souza",
  "phone": "+5548999990001",
  "externalRef": "erp-88213",
  "fields": {
    "cpf": "529.982.247-25"
  }
}'

Response 201

{
  "contact": {
    "id": "01a0d05a-3ee3-75bd-9db5-dc9856f079c8",
    "displayName": "Ana Souza",
    "address": "5548999990001"
  }
}

Possible errors

401 unauthorized
403 insufficient_scope
409 contact_exists
422 validation_failed
429 rate_limited

Create or update contacts (up to 1,000)

POST /v1/c/{slug}/contacts/import · Scopes: contacts:write

By phone: existing contacts are updated (name, fields, tags), new ones created. Each row comes back with the contact's id. A bad row does not stop the others.

Path parameters

Field	Notes
`slug`	The company's identifier in DoneTalk (the key's own).

Request body

Field	Type	Required	Notes
`rows`	list of object	yes	up to 1000
`rows[].phone`	string	yes	up to 40 characters
`rows[].name`	string	no	up to 200 characters
`rows[].fields`	object	no
`rows[].tags`	list of string	no	up to 20
`rows[].externalRef`	string	no	up to 200 characters
`rows[].marketingOptIn`	boolean	no

Request example

curl -X POST "https://api.donetalk.com/v1/c/demo/contacts/import" \
  -H "Authorization: Bearer $DONETALK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "rows": [
    {
      "phone": "+5548999990001",
      "name": "Ana Souza",
      "tags": [
        "VIP"
      ],
      "externalRef": "erp-88213"
    },
    {
      "phone": "48 99999-0002",
      "name": "Bruno Lima",
      "fields": {
        "plano": "mensal"
      },
      "marketingOptIn": true
    }
  ]
}'

Response 200

{
  "created": 1,
  "updated": 1,
  "errors": [
    {
      "row": 2,
      "reason": "invalid_phone"
    }
  ],
  "contacts": [
    {
      "row": 0,
      "contactId": "01a0d05a-3ee3-75bd-9db5-dc9856f079c8",
      "created": false
    },
    {
      "row": 1,
      "contactId": "01a0d05a-3ee3-75bd-9db5-dc9856f079c9",
      "created": true
    }
  ]
}

Possible errors

401 unauthorized
403 insufficient_scope
422 validation_failed
429 rate_limited

Get a contact

GET /v1/c/{slug}/contacts/{id} · Scopes: contacts:read

The contact with its fields, numbers, consents, last conversations and tags, plus the company's field definitions.

Path parameters

Field	Notes
`slug`	The company's identifier in DoneTalk (the key's own).
`id`	The record's id.

Request example

curl -X GET "https://api.donetalk.com/v1/c/demo/contacts/:id" \
  -H "Authorization: Bearer $DONETALK_KEY"

Response 200

{
  "contact": {
    "id": "01a0d05a-3ee3-75bd-9db5-dc9856f079c8",
    "displayName": "Ana Souza",
    "address": "5548999990001",
    "channelKind": "whatsapp",
    "source": "api",
    "externalRef": "erp-88213",
    "fields": {
      "cpf": "529.982.247-25",
      "plano": "anual"
    },
    "isBlocked": false,
    "lastActivityAt": "2026-10-22T18:40:02.000Z",
    "createdAt": "2026-09-23T22:19:30.396Z",
    "firstName": "Ana",
    "lastName": "Souza",
    "locale": "pt-BR",
    "timezone": null,
    "blockedReason": null
  },
  "identities": [
    {
      "id": "01a0d05a-3ee3-75bd-9db5-dc9856f079c9",
      "channel_kind": "whatsapp",
      "address": "5548999990001",
      "external_id": null,
      "provider_display_name": "Ana",
      "is_primary": true,
      "last_seen_at": "2026-10-22T18:40:02.000Z"
    }
  ],
  "consents": [
    {
      "purpose": "marketing",
      "channel_kind": "whatsapp",
      "status": "opted_in",
      "source": "api",
      "occurred_at": "2026-10-01T10:00:00.000Z"
    }
  ],
  "conversations": [
    {
      "id": "01a3c0de-7a11-7b22-8c33-9d44e55f6677",
      "status": "closed",
      "source_kind": "campaign",
      "imported_from": null,
      "created_at": "2026-10-24T12:00:04.000Z",
      "closed_at": "2026-10-24T12:20:41.000Z",
      "channel_id": "01a0cccc-0000-7000-8000-000000000002",
      "outcome_code": "converted",
      "is_success": true
    }
  ],
  "tags": [
    {
      "id": "01a12150-3610-7c00-b680-188c2b4c7313",
      "name": {
        "pt-BR": "VIP",
        "en": "VIP",
        "es": "VIP"
      },
      "color": "#92400e"
    }
  ],
  "fieldDefinitions": [
    {
      "key": "cpf",
      "label": {
        "pt-BR": "CPF",
        "en": "CPF",
        "es": "CPF"
      },
      "type": "cpf",
      "options": null,
      "ai_extractable": true,
      "required": false,
      "sort": 1
    }
  ]
}

Possible errors

401 unauthorized
403 insufficient_scope
404 contact_not_found
422 validation_failed
429 rate_limited

Edit a contact

PATCH /v1/c/{slug}/contacts/{id} · Scopes: contacts:write

fields merges with the contact's fields; send null in a field to clear it.

Path parameters

Field	Notes
`slug`	The company's identifier in DoneTalk (the key's own).
`id`	The record's id.

Request body

Field	Type	Required	Notes
`displayName`	string	no	up to 200 characters
`firstName`	string	no	up to 100 characters; null
`lastName`	string	no	up to 100 characters; null
`locale`	one of `pt-BR`, `es`, `en`	no	null
`externalRef`	string	no	up to 200 characters; null
`fields`	object	no
`isBlocked`	boolean	no
`blockedReason`	string	no	up to 200 characters; null

Request example

curl -X PATCH "https://api.donetalk.com/v1/c/demo/contacts/:id" \
  -H "Authorization: Bearer $DONETALK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "fields": {
    "plano": "anual"
  },
  "externalRef": "erp-88213"
}'

Response 200

{
  "ok": true
}

Possible errors

401 unauthorized
403 insufficient_scope
404 contact_not_found
422 validation_failed
429 rate_limited

POST /v1/c/{slug}/contacts/{id}/consents · Scopes: contacts:write

Opt-in or opt-out per purpose (service, utility, marketing). A marketing opt-out keeps the contact out of marketing campaigns.

Path parameters

Field	Notes
`slug`	The company's identifier in DoneTalk (the key's own).
`id`	The record's id.

Request body

Field	Type	Required	Notes
`purpose`	one of `service`, `utility`, `marketing`	yes
`status`	one of `opted_in`, `opted_out`	yes
`source`	one of `form`, `import`, `api`, `message`, `keyword`	no	default `"form"`
`evidence`	object	no

Request example

curl -X POST "https://api.donetalk.com/v1/c/demo/contacts/:id/consents" \
  -H "Authorization: Bearer $DONETALK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "purpose": "marketing",
  "status": "opted_in",
  "source": "api"
}'

Response 201

{
  "ok": true
}

Possible errors

401 unauthorized
403 insufficient_scope
404 contact_not_found
422 validation_failed
429 rate_limited

Add a tag

PUT /v1/c/{slug}/contacts/{id}/tags/{tagId} · Scopes: contacts:write

May start the flows that begin when this tag is added.

Path parameters

Field	Notes
`slug`	The company's identifier in DoneTalk (the key's own).
`id`	The record's id.
`tagId`	The tag's id.

Request example

curl -X PUT "https://api.donetalk.com/v1/c/demo/contacts/:id/tags/:tagId" \
  -H "Authorization: Bearer $DONETALK_KEY"

Response 200

{
  "ok": true
}

Possible errors

401 unauthorized
403 insufficient_scope
422 validation_failed
429 rate_limited

Remove a tag

DELETE /v1/c/{slug}/contacts/{id}/tags/{tagId} · Scopes: contacts:write

Path parameters

Field	Notes
`slug`	The company's identifier in DoneTalk (the key's own).
`id`	The record's id.
`tagId`	The tag's id.

Request example

curl -X DELETE "https://api.donetalk.com/v1/c/demo/contacts/:id/tags/:tagId" \
  -H "Authorization: Bearer $DONETALK_KEY"

Response 200

{
  "ok": true
}

Possible errors

401 unauthorized
403 insufficient_scope
422 validation_failed
429 rate_limited

Context cards

GET /v1/c/{slug}/contacts/{id}/context-cards · Scopes: contacts:read

Path parameters

Field	Notes
`slug`	The company's identifier in DoneTalk (the key's own).
`id`	The record's id.

Request example

curl -X GET "https://api.donetalk.com/v1/c/demo/contacts/:id/context-cards" \
  -H "Authorization: Bearer $DONETALK_KEY"

Response 200

{
  "cards": [
    {
      "key": "erp",
      "source": "ERP Captei",
      "title": "Cliente desde 2023",
      "status": "Plano anual",
      "tone": "success",
      "fields": [
        {
          "label": "Pedidos",
          "value": "14"
        }
      ],
      "link": {
        "url": "https://erp.captei.com.br/clientes/88213",
        "label": "Abrir no ERP"
      },
      "updatedAt": "2026-10-23T13:02:11.000Z"
    }
  ]
}

Possible errors

401 unauthorized
403 insufficient_scope
422 validation_failed
429 rate_limited

Show a card to the attendant

PUT /v1/c/{slug}/contacts/{id}/context-cards/{key} · Scopes: contacts:write

A card from your system shown beside the conversation (plan, orders, balance). The same key replaces the previous one.

Path parameters

Field	Notes
`slug`	The company's identifier in DoneTalk (the key's own).
`id`	The record's id.
`key`	The key (of the field or the card).

Request body

Field	Type	Required	Notes
`title`	string	yes	up to 120 characters
`source`	string	no	up to 60 characters
`status`	string	no	up to 60 characters; null
`tone`	one of `neutral`, `success`, `warning`, `danger`, `info`	no	default `"neutral"`
`fields`	list of object	no	up to 12; default `[]`
`fields[].label`	string	yes	up to 60 characters
`fields[].value`	string	yes	up to 300 characters
`link`	object	no	null
`link.url`	string (uri)	yes	up to 2000 characters
`link.label`	string	no	up to 60 characters

Request example

curl -X PUT "https://api.donetalk.com/v1/c/demo/contacts/:id/context-cards/:key" \
  -H "Authorization: Bearer $DONETALK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "title": "Cliente desde 2023",
  "source": "ERP Captei",
  "status": "Plano anual",
  "tone": "success",
  "fields": [
    {
      "label": "Pedidos",
      "value": "14"
    }
  ],
  "link": {
    "url": "https://erp.captei.com.br/clientes/88213",
    "label": "Abrir no ERP"
  }
}'

Response 200

{
  "card": {
    "key": "erp",
    "source": "ERP Captei",
    "title": "Cliente desde 2023",
    "status": "Plano anual",
    "tone": "success",
    "fields": [
      {
        "label": "Pedidos",
        "value": "14"
      }
    ],
    "link": {
      "url": "https://erp.captei.com.br/clientes/88213",
      "label": "Abrir no ERP"
    },
    "updatedAt": "2026-10-23T13:02:11.000Z"
  }
}

Possible errors

401 unauthorized
403 insufficient_scope
422 validation_failed
429 rate_limited

Remove a card

DELETE /v1/c/{slug}/contacts/{id}/context-cards/{key} · Scopes: contacts:write

Path parameters

Field	Notes
`slug`	The company's identifier in DoneTalk (the key's own).
`id`	The record's id.
`key`	The key (of the field or the card).

Request example

curl -X DELETE "https://api.donetalk.com/v1/c/demo/contacts/:id/context-cards/:key" \
  -H "Authorization: Bearer $DONETALK_KEY"

Response 200

{
  "ok": true
}

Possible errors

401 unauthorized
403 insufficient_scope
422 validation_failed
429 rate_limited

Erase the contact's data (LGPD)

POST /v1/c/{slug}/contacts/{id}/erase · Scopes: contacts:delete

At the person's request: the contact and their messages are anonymised for good. It cannot be undone.

Path parameters

Field	Notes
`slug`	The company's identifier in DoneTalk (the key's own).
`id`	The record's id.

Request example

curl -X POST "https://api.donetalk.com/v1/c/demo/contacts/:id/erase" \
  -H "Authorization: Bearer $DONETALK_KEY"

Response 200

{
  "ok": true
}

Possible errors

401 unauthorized
403 insufficient_scope
404 contact_not_found
422 validation_failed
429 rate_limited

This page as Markdown

Contacts

List contacts

Path parameters

Query parameters

Request example

Response 200

Possible errors

Create a contact

Path parameters

Request body

Request example

Response 201

Possible errors

Create or update contacts (up to 1,000)

Path parameters

Request body

Request example

Response 200

Possible errors

Get a contact

Path parameters

Request example

Response 200

Possible errors

Edit a contact

Path parameters

Request body

Request example

Response 200

Possible errors

Record consent

Path parameters

Request body

Request example

Response 201

Possible errors

Add a tag

Path parameters

Request example

Response 200

Possible errors

Remove a tag

Path parameters

Request example

Response 200

Possible errors

Context cards

Path parameters

Request example

Response 200

Possible errors

Show a card to the attendant

Path parameters

Request body

Request example

Response 200

Possible errors

Remove a card

Path parameters

Request example

Response 200

Possible errors

Erase the contact's data (LGPD)

Path parameters

Request example

Response 200

Possible errors