DoneTalk Developers Sign in

Segments

List segments

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

Path parameters

FieldNotes
slugThe company's identifier in DoneTalk (the key's own).

Request example

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

Response 200

{
  "segments": [
    {
      "id": "01a1a0b0-1c2d-7e3f-8a9b-0c1d2e3f4a5b",
      "name": "Clientes do plano anual",
      "conditions": [
        {
          "field": "field.plano",
          "op": "eq",
          "value": "anual"
        }
      ],
      "count": 312,
      "updatedAt": "2026-10-23T13:02:11.000Z"
    }
  ]
}

Possible errors

  • 401 unauthorized
  • 403 insufficient_scope
  • 422 validation_failed
  • 429 rate_limited

Create a segment

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

A group of contacts by conditions: tag, source, last outcome, days since the last conversation or since created, marketing consent, name, WhatsApp and any field (field.<key>).

Path parameters

FieldNotes
slugThe company's identifier in DoneTalk (the key's own).

Request body

FieldTypeRequiredNotes
namestringyesup to 120 characters
conditionslist of objectyesup to 20
conditions[].fieldstringyesup to 80 characters
conditions[].opone of eq, neq, has, not_has, contains, empty, not_empty, gt, lt, noneyes
conditions[].valuestring · number · boolean · one of nullno

Request example

curl -X POST "https://api.donetalk.com/v1/c/demo/segments" \
  -H "Authorization: Bearer $DONETALK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Clientes do plano anual",
  "conditions": [
    {
      "field": "field.plano",
      "op": "eq",
      "value": "anual"
    }
  ]
}'

Response 201

{
  "segment": {
    "id": "01a1a0b0-1c2d-7e3f-8a9b-0c1d2e3f4a5b"
  }
}

Possible errors

  • 401 unauthorized
  • 403 insufficient_scope
  • 422 validation_failed
  • 429 rate_limited

Edit a segment

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

Path parameters

FieldNotes
slugThe company's identifier in DoneTalk (the key's own).
idThe record's id.

Request body

FieldTypeRequiredNotes
namestringyesup to 120 characters
conditionslist of objectyesup to 20
conditions[].fieldstringyesup to 80 characters
conditions[].opone of eq, neq, has, not_has, contains, empty, not_empty, gt, lt, noneyes
conditions[].valuestring · number · boolean · one of nullno

Request example

curl -X PUT "https://api.donetalk.com/v1/c/demo/segments/:id" \
  -H "Authorization: Bearer $DONETALK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Clientes do plano anual",
  "conditions": [
    {
      "field": "field.plano",
      "op": "eq",
      "value": "anual"
    }
  ]
}'

Response 200

{
  "ok": true
}

Possible errors

  • 401 unauthorized
  • 403 insufficient_scope
  • 422 validation_failed
  • 429 rate_limited

Delete a segment

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

Path parameters

FieldNotes
slugThe company's identifier in DoneTalk (the key's own).
idThe record's id.

Request example

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

Response 200

{
  "ok": true
}

Possible errors

  • 401 unauthorized
  • 403 insufficient_scope
  • 422 validation_failed
  • 429 rate_limited

Count who matches

POST /v1/c/{slug}/segments/count · Scopes: contacts:read · campaigns:write

Path parameters

FieldNotes
slugThe company's identifier in DoneTalk (the key's own).

Request body

FieldTypeRequiredNotes
conditionslist of objectyesup to 20
conditions[].fieldstringyesup to 80 characters
conditions[].opone of eq, neq, has, not_has, contains, empty, not_empty, gt, lt, noneyes
conditions[].valuestring · number · boolean · one of nullno

Request example

curl -X POST "https://api.donetalk.com/v1/c/demo/segments/count" \
  -H "Authorization: Bearer $DONETALK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "conditions": [
    {
      "field": "tag",
      "op": "has",
      "value": "01a12150-3610-7c00-b680-188c2b4c7313"
    }
  ]
}'

Response 200

{
  "count": 312
}

Possible errors

  • 401 unauthorized
  • 403 insufficient_scope
  • 422 validation_failed
  • 429 rate_limited

Search contacts by conditions

POST /v1/c/{slug}/contacts/search · Scopes: contacts:read

Path parameters

FieldNotes
slugThe company's identifier in DoneTalk (the key's own).

Request body

FieldTypeRequiredNotes
segmentIdstring (uuid)no
conditionslist of objectnoup to 20; default []
conditions[].fieldstringyesup to 80 characters
conditions[].opone of eq, neq, has, not_has, contains, empty, not_empty, gt, lt, noneyes
conditions[].valuestring · number · boolean · one of nullno
qstringnoup to 100 characters
limitintegernoup to 200; at least 1; default 50
offsetintegernoup to 1000000; default 0

Request example

curl -X POST "https://api.donetalk.com/v1/c/demo/contacts/search" \
  -H "Authorization: Bearer $DONETALK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "conditions": [
    {
      "field": "marketing",
      "op": "eq",
      "value": "opted_in"
    }
  ],
  "limit": 50
}'

Response 200

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

Possible errors

  • 401 unauthorized
  • 403 insufficient_scope
  • 422 validation_failed
  • 429 rate_limited

This page as Markdown