Change a contact

Changes the fields you send and leaves the rest. tags and custom_fields replace the whole list or set. The handle can’t change, since the contact’s texts are filed under it. Use the stop list operations to stop or start texting somebody.

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

Path parameters

• idstringrequired

  The contact’s id.

  Starts with ct_.

Request body

• first_namestring or null

  The first name. Send null or an empty string to clear it.

  Up to 100 characters.

• last_namestring or null

  The last name. Send null or an empty string to clear it.

  Up to 100 characters.

• companystring or null

  The company. Send null or an empty string to clear it.

  Up to 200 characters.

• tagsarray of strings

  Tags, at most 50 of up to 50 characters each. Capitals are kept but a tag counts once however it is spelled.

  Up to 50 items.

• custom_fieldsmap of string

  Your own fields for templates, at most 50. Names are made template-safe (Showing address becomes showing_address); an empty value drops the field.

Example

curl -X PATCH "https://usebluebot.com/api/v1/contacts/ct_1Hq2LxW9cVbN3mKpRtYs0a" \
  -H "Authorization: Bearer $BLUEBOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tags": [
      "buyer",
      "closed"
    ],
    "custom_fields": {
      "showing": "412 Oak St",
      "closing": "Dec 3"
    }
  }'

Response

200: The contact after the change.

• 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.

{
  "id": "ct_1Hq2LxW9cVbN3mKpRtYs0a",
  "object": "contact",
  "handle": "+15555550123",
  "kind": "phone",
  "first_name": "Maria",
  "last_name": "Alvarez",
  "company": null,
  "tags": [
    "buyer",
    "closed"
  ],
  "custom_fields": {
    "showing": "412 Oak St",
    "closing": "Dec 3"
  },
  "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"
}

Errors

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

Try it