Update a contact

PATCH /api/v1/contacts/{phone}

Renames a contact that already exists on the WhatsApp number behind your API key — for example to show your own customer number in the Kanal inbox (Jean → 140 · Jean Dupont). It never creates a contact: an unknown number returns 404.

Path

Param	Notes
`phone`	Contact phone, country code included (`33612345678`, `+33612345678`). Spaces, dashes and `+` are stripped; a French national number (`0612345678`) is also accepted.

Body

At least one field is required. Only the fields you send are changed.

Field	Type	Notes
`name`	string (max 255)	Name shown in the Kanal inbox. Does not touch `first_name` / `last_name`.
`first_name`	string (max 255)	First name, used by personalization variables in templates and automations.
`last_name`	string (max 255)	Last name.

When name is omitted, the inbox name is rebuilt from the contact's first_name + last_name (the stored value fills in the half you don't send).

To prefix the inbox name with your own reference, send it in name, not in first_name — otherwise a template greeting the contact by first name would read "Hello 140 · Jean".

Request

curl -X PATCH https://api.getkanal.com/api/v1/contacts/33612345678 \
  -H "Authorization: Bearer 8fK2pX9mWq4Ld7Vb3Nc6Ts1Z" \
  -H "Content-Type: application/json" \
  -d '{ "name": "140 · Jean Dupont" }'

Response `200 OK`

{
  "contact_id": 7890,
  "phone_number": "33612345678",
  "name": "140 · Jean Dupont",
  "first_name": "Jean",
  "last_name": null
}

Errors

Status	Body	Cause
`401`	`{ "error": "API key is missing" }` / `{ "error": "Invalid API key" }`	Auth.
`403`	`{ "error": "Team has no active subscription" }`	No active subscription.
`404`	`{ "error": "Contact not found" }`	No contact with this number on the key's WhatsApp number.
`422`	`{ "message": "…", "errors": { "name": ["…"] } }`	No `name`, `first_name` or `last_name`, or a value that is not a string / too long.

Overwrites

Kanal integrations keep writing names after your call:

Shopify: every new order from the contact resets the inbox name, first_name and last_name to the Shopify customer name.
Store API (POST /api/v1/stores/{store_id}/…): each ingestion resets first_name / last_name; the inbox name is kept.

If you rename contacts that also come from Shopify, call this endpoint again after their orders.