> ## Documentation Index > Fetch the complete documentation index at: https://docs.keebai.com/llms.txt > Use this file to discover all available pages before exploring further. # PATCH /v1/contacts/:id > Partially update a contact's profile data and custom fields. Updates the profile fields of a contact. Only the fields you send are touched; everything else is left alone. The channel identity — `channel_type`, `user_id`, and `channel` — is immutable. If you got it wrong, delete the contact and create it again. ## Endpoint ``` PATCH https://api.keebai.com/v1/contacts/{id} ``` ## Required scope `contacts:write` ## Headers | Header | Required | Value | | --------------- | -------- | ------------------------ | | `Authorization` | Yes | `Bearer kbai_pk_` | | `Content-Type` | Yes | `application/json` | ## Path parameters | Field | Type | Required | Description | | ----- | -------- | -------- | -------------------------- | | `id` | `string` | Yes | `ObjectId` of the contact. | ## Body | Field | Type | Required | Description | | --------------- | -------- | -------- | ------------------------------------------------------------------ | | `username` | `string` | No | Handle on the channel. Up to 200 characters. | | `first_name` | `string` | No | Up to 200 characters. | | `last_name` | `string` | No | Up to 200 characters. | | `phone` | `string` | No | Phone number in E.164, with the `+`. | | `email` | `string` | No | Valid email address. | | `profile_pic` | `string` | No | HTTPS URL of the avatar. | | `custom_fields` | `object` | No | Merged into the stored object key by key — it does not replace it. | ## Example request ```bash curl theme={null} curl -X PATCH https://api.keebai.com/v1/contacts/65a1f2b3c4d5e6f7a8b9c0d1 \ -H "Authorization: Bearer kbai_pk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "email": "juan.perez@example.com", "custom_fields": { "plan": "enterprise" } }' ``` ```js JavaScript theme={null} const response = await fetch( `https://api.keebai.com/v1/contacts/${contactId}`, { method: "PATCH", headers: { Authorization: `Bearer ${process.env.KEEBAI_API_TOKEN}`, "Content-Type": "application/json", }, body: JSON.stringify({ email: "juan.perez@example.com", custom_fields: { plan: "enterprise" }, }), }, ); const { contact } = await response.json(); ``` ```python Python theme={null} import os, requests resp = requests.patch( f"https://api.keebai.com/v1/contacts/{contact_id}", headers={"Authorization": f"Bearer {os.environ['KEEBAI_API_TOKEN']}"}, json={ "email": "juan.perez@example.com", "custom_fields": {"plan": "enterprise"}, }, timeout=10, ) resp.raise_for_status() contact = resp.json()["contact"] ``` ## Response ### 200 OK ```json theme={null} { "contact": { "_id": "65a1f2b3c4d5e6f7a8b9c0d1", "channel_type": "whatsapp", "user_id": "56912345678", "first_name": "Juan", "last_name": "Pérez", "phone": "+56912345678", "email": "juan.perez@example.com", "custom_fields": { "plan": "enterprise" }, "tags": [], "is_attended": false, "first_seen_at": "2026-04-18T09:12:44.010Z", "last_seen_at": "2026-05-02T14:31:07.221Z", "created_at": "2026-04-18T09:12:44.010Z", "updated_at": "2026-05-02T15:02:18.900Z" } } ``` ### 400 Bad Request A malformed `email` or `profile_pic`, or a property the endpoint does not accept — including `channel_type`, `user_id`, `company`, and `project`. ### 401 Unauthorized Missing, invalid, revoked, or expired token. ### 403 Forbidden The token does not have the `contacts:write` scope. ### 404 Not Found No contact with that id, or the contact belongs to a different company. ### 502 Bad Gateway The messaging service could not complete the write. ## Operational notes * **You cannot clear a field.** Sending `""` or `null` leaves the previous value in place — the update only overwrites a field when the new value is non-empty. To empty a field, set it to a placeholder your integration recognises. * **`custom_fields` is merged, not replaced.** Sending `{"plan": "enterprise"}` updates `plan` and leaves every other key untouched. There is no way to remove a key through this endpoint. * **Every change is logged.** Updating `first_name`, `last_name`, `username`, `phone`, `email`, `profile_pic`, or any custom field writes an entry to the contact's history, attributed to the user who owns the token. * **Tags are not editable here.** Setting a contact's tags requires tag ids, and there is no public endpoint yet to discover them. ## OpenAPI ````yaml PATCH /v1/contacts/{id} openapi: 3.0.0 info: title: Keebai Public API description: Superficie pública REST autenticada con Personal Access Tokens (PAT). version: 1.0.0 contact: {} servers: - url: https://api.keebai.com description: Production security: [] tags: [] paths: /v1/contacts/{id}: patch: tags: - contacts summary: Actualizar un contacto description: >- Actualización parcial. Enviar una cadena vacía no limpia el campo, y custom_fields se mergea con lo existente. operationId: PublicContactsController_update parameters: - name: id required: true in: path schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PublicContactUpdateDto' responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/PublicContactEnvelopeDto' security: - PAT: [] components: schemas: PublicContactUpdateDto: type: object properties: username: type: string first_name: type: string last_name: type: string phone: type: string description: Teléfono en formato E.164 email: type: string profile_pic: type: string description: URL de la foto de perfil custom_fields: type: object description: >- Se mergea con los campos existentes; no reemplaza el objeto completo. PublicContactEnvelopeDto: type: object properties: contact: $ref: '#/components/schemas/PublicContactResponseDto' required: - contact PublicContactResponseDto: type: object properties: _id: type: string description: ObjectId del contacto channel_type: type: string enum: - web - whatsapp - whatsapp_qr - facebook - messenger - instagram - tiktok - telegram - email - phone description: Canal por el que existe el contacto user_id: type: string description: Identificador del contacto dentro de su canal channel_id: type: string description: ObjectId del canal concreto external_id: type: string description: Identificador en un sistema externo username: type: string first_name: type: string last_name: type: string phone: type: string email: type: string profile_pic: type: string custom_fields: type: object description: Campos personalizados de la company tags: description: Ids de tags type: array items: type: string is_attended: type: boolean description: true cuando un agente humano tomó la conversación last_attended_at: type: string format: date-time first_seen_at: type: string format: date-time last_seen_at: type: string format: date-time last_user_message_at: type: string format: date-time last_bot_response_at: type: string format: date-time last_agent_response_at: type: string format: date-time created_at: type: string format: date-time updated_at: type: string format: date-time required: - _id - channel_type - user_id - custom_fields - tags - is_attended - first_seen_at - created_at - updated_at securitySchemes: PAT: scheme: bearer bearerFormat: kbai_pk_ type: http description: >- Personal Access Token con prefijo `kbai_pk_`. Generar desde el portal con permiso `developer.manage_tokens`. ````