IotaBot logo
API documentation

Contacts API

Read, create and update the customers your workspace knows across channels, including their opt-outs.

GET/v1/contactscontacts:readThe API key needs the contacts:read permission. Without it the call is refused with 403 insufficient_scope.Sign in to try

Contacts across channels, newest first

Contacts belong to the whole workspace, so keys limited to some websites cannot use them.

Parameters
emailQuery
phoneQuery
updated_sinceQuery
limitQuery
starting_afterQuery
Request
curl -X GET "https://api.iotabot.com/v1/contacts" \
  -H "Authorization: Bearer $IOTABOT_API_KEY"
Response · 200
{
  "data": {
    "items": [
      {
        "id": "6a4b9e00c3f1a2b3c4d5e600",
        "object": "contact",
        "name": "Priya Sharma",
        "email": "priya@example.com",
        "phone": "+919812345678",
        "instagram_user_id": null,
        "opt_outs": {
          "whatsapp": false,
          "email": false,
          "instagram": false
        },
        "email_suppressed": null,
        "first_seen_channel": "whatsapp",
        "source": "captured",
        "created_at": "2026-09-12T10:00:00.000Z",
        "last_seen_at": "2026-10-01T09:15:02.881Z"
      }
    ],
    "has_more": false,
    "next_cursor": null
  }
}
Errors
contacts_need_all_websitesinvalid_phone
GET/v1/contacts/{id}contacts:readThe API key needs the contacts:read permission. Without it the call is refused with 403 insufficient_scope.Sign in to try

One contact

Parameters
idrequiredIn the path
Request
curl -X GET "https://api.iotabot.com/v1/contacts/CONTACT_ID" \
  -H "Authorization: Bearer $IOTABOT_API_KEY"
Response · 200
{
  "data": {
    "ok": true
  }
}
Errors
contact_not_found
POST/v1/contactscontacts:writeThe API key needs the contacts:write permission. Without it the call is refused with 403 insufficient_scope.Sign in to try

Create a contact (email or phone)

Request
curl -X POST "https://api.iotabot.com/v1/contacts" \
  -H "Authorization: Bearer $IOTABOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Priya Sharma",
  "email": "priya@example.com",
  "phone": "+919812345678"
}'
Response · 201
{
  "data": {
    "id": "6a4b…",
    "name": "Priya Sharma",
    "email": "priya@example.com",
    "phone": "+919812345678"
  }
}
Errors
contact_existsinvalid_phone
PATCH/v1/contacts/{id}contacts:writeThe API key needs the contacts:write permission. Without it the call is refused with 403 insufficient_scope.Sign in to try

Update a contact or its opt-outs

Parameters
idrequiredIn the path
Request
curl -X PATCH "https://api.iotabot.com/v1/contacts/CONTACT_ID" \
  -H "Authorization: Bearer $IOTABOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Priya S.",
  "whatsapp_opt_out": true
}'
Response · 200
{
  "data": {
    "id": "6a4b…",
    "name": "Priya S.",
    "whatsapp_opt_out": true
  }
}
Errors
contact_not_foundcontact_exists