List contacts

Your contacts, the most recently texted first. q finds people by name, company, phone number or email, and a few digits of a number work. Filter by tag, or by stopped for the stop list.

Needs a key with the contacts:read scope. Keys and scopes

Query parameters

• qstring

  Find people by name, company, phone number or email. Part of one works, and each word can match a different one, so Dana Oak finds Dana at Oak Realty.

  Up to 100 characters.

• tagstring

  Only people with this tag.

  Up to 50 characters.

• stoppedstring

  true for only people on your stop list, false for only people who aren’t.

  One of true, false.

• limitinteger

  How many to return, 1 to 100. Default 25.

  1 to 100.Default 25.

• cursorstring

  The next_cursor of the page before. Leave it out for the first page.

  Up to 200 characters.

Example

curl "https://usebluebot.com/api/v1/contacts" \
  -H "Authorization: Bearer $BLUEBOT_API_KEY"

Response

200: A page of contacts.

• object"list"required
• dataarray of Contactrequired
  Show its 17 fieldsHide its fields

  • idstringrequired

    A ct_ id.

    Starts with ct_.

  • object"contact"required
  • handlestringrequired

    A phone number in E.164 (+15555550123) or an email address an Apple ID uses (iMessage only).

  • kindstringrequired

    phone or email.

    One of phone, email.

  • first_namestring or nullrequired
  • last_namestring or nullrequired
  • companystring or nullrequired
  • tagsarray of stringsrequired

    The contact’s tags.

  • custom_fieldsmap of stringrequired

    Your own fields, for templates.

  • stoppedbooleanrequired

    True when the person is on your stop list. Texts to them are canceled.

  • stopped_attimestamp or nullrequired

    When they were put on the stop list.

  • stop_sourcestring or nullrequired

    How: reply (they texted a stop word), dashboard, api, import or admin.

    One of reply, dashboard, api, import, admin.

  • last_servicestring or nullrequired

    The service of the newest text with them.

    One of imessage, sms.

  • first_message_attimestamp or nullrequired

    The first text either way. Null for somebody you have never texted with, who counts as a new person.

  • last_message_attimestamp or nullrequired

    The newest text either way.

  • created_viastringrequired

    What first added them.

    One of message, inbound, import, api, dashboard, widget, hook, mcp, assistant.

  • created_attimestamprequired

    When the contact was added.

• has_morebooleanrequired

  Whether another page follows.

• next_cursorstring or nullrequired

  Send as cursor for the next page; null on the last.

{
  "object": "list",
  "data": [
    {
      "id": "ct_1Hq2LxW9cVbN3mKpRtYs0a",
      "object": "contact",
      "handle": "+15555550123",
      "kind": "phone",
      "first_name": "Maria",
      "last_name": "Alvarez",
      "company": null,
      "tags": [
        "buyer"
      ],
      "custom_fields": {
        "showing": "412 Oak St"
      },
      "stopped": false,
      "stopped_at": null,
      "stop_source": null,
      "last_service": "imessage",
      "first_message_at": "2026-11-02T15:20:00.000Z",
      "last_message_at": "2026-11-13T19:41:00.000Z",
      "created_via": "message",
      "created_at": "2026-11-02T15:20:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Errors

Every refusal has the same envelope and a page of its own. These are the ones this operation can give.

Try it