Update a contact

PATCH /v1/contacts/{id}

Changes the fields you send and leaves the others alone.

Needs contacts:write.

Change attributes

curl -X PATCH https://app.soosh.io/v1/contacts/4ea0d485-435d-407f-837a-c7d67095f23a \
  -H "Authorization: Bearer $SOOSH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "attributes": {
      "city": "Mumbai",
      "orders": 4,
      "old_field": null
    }
  }'

const res = await fetch('https://app.soosh.io/v1/contacts/4ea0d485-435d-407f-837a-c7d67095f23a', {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${process.env.SOOSH_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "attributes": {
      "city": "Mumbai",
      "orders": 4,
      "old_field": null
    }
  }),
});
console.log(await res.json());

import os
import requests

res = requests.patch(
    "https://app.soosh.io/v1/contacts/4ea0d485-435d-407f-837a-c7d67095f23a",
    headers={"Authorization": f"Bearer {os.environ['SOOSH_API_KEY']}"},
    json={
        "attributes": {
            "city": "Mumbai",
            "orders": 4,
            "old_field": None,
        },
    },
)
print(res.json())

Response200

{
  "id": "4ea0d485-435d-407f-837a-c7d67095f23a",
  "phone": "+919876543210",
  "whatsapp_user_id": null,
  "name": "Priya Sharma",
  "whatsapp_name": "Priya S",
  "attributes": {
    "customer_id": "8812",
    "city": "Mumbai",
    "orders": 4
  },
  "tags": [
    "VIP"
  ],
  "marketing_opt_out": false,
  "number_id": "0f6d3c1e-5b7a-4c52-9a55-3f6a2d5c8b10",
  "chat": {
    "status": "open",
    "assigned_agent_id": "5b1d7d0e-3c2a-4f61-9a0e-6f8f3b2c1d40",
    "last_message_at": "2026-10-14T09:30:12.481Z",
    "last_inbound_at": "2026-10-14T09:12:40.117Z"
  },
  "created_at": "2026-10-14T09:05:11.420Z",
  "updated_at": "2026-10-14T10:05:27.733Z"
}

Every field of the contact object

Path parameters

id string · uuid

The contact’s ID.

Body

name string

The name your business gives the contact. An empty string takes it off, and the WhatsApp profile name shows again.

Up to 255 characters.

attributes object

Merged into the contact’s attributes. A key you send replaces its value, and a null value removes the key. Names and values follow the same rules as when you create a contact. The result can have at most 50.

A map; each value is a string or number or boolean.

number_id string · uuid

The number to message the contact from, from GET /v1/numbers.

marketing_opt_out boolean

true if the contact opted out of marketing messages, false if they opted back in.

Changing tags

Tags have their own endpoints: PUT /v1/contacts/{id}/tags/{tag} and DELETE /v1/contacts/{id}/tags/{tag}.

Webhooks

contact.updated is sent only if something changed.

Returns

200 The contact object. The contact as it is now.

Errors

Besides the ones every request can get:

422invalid_fieldA field breaks a rule, such as an attribute name with a space or more than 50 attributes.

404not_foundThere is no contact with this ID in your workspace.