---
title: "Update a contact"
method: PATCH
path: "/v1/contacts/{contact_id}"
tags: ["email-contacts"]
---

# Update a contact

`PATCH /v1/contacts/{contact_id}`

## Request

- Base URL: `https://us1.platform.bird.com`
- URL: `https://us1.platform.bird.com/v1/contacts/{contact_id}`
- Auth: one of:
  - HTTP bearer
  - API key in cookie `bird_session`

Updates a contact. Supplied fields are changed and omitted fields are left unchanged; set `first_name`, `last_name`, or `external_id` to `null` to clear them. Custom values in `data` are merged: keys you supply are set, keys set to `null` are removed, and keys you omit are unchanged.

Changing the email address, phone number, or `external_id` to a value already used by another contact returns a conflict error. A contact always keeps at least one identifier. Clearing both email and phone in the same contact is rejected.

## Path parameters

- `contact_id` string, required

## Headers

- `Idempotency-Key` string
- `X-Workspace-Id` string
- `X-Organization-Id` string

## Request body

- ContactUpdateRequest
  - `email` string, email, nullable: New email address for the contact. Trimmed and lowercased before it is stored and checked for uniqueness. Must not be in use by another contact in the workspace. Omit to keep the current address; set to `null` to remove it, as long as the contact keeps at least one identifier.
  - `phone_number` string, nullable: New phone number for the contact, in E.164 format with the leading `+` and country code. Spaces and punctuation are accepted and stripped. Stored in its canonical form, which may differ from what you send, and unique within the workspace. Omit to keep the current number; set to `null` to remove it, as long as the contact keeps at least one identifier. An empty string behaves as `null`.
  - `first_name` string, nullable: The contact's first name. Set to `null` to clear.
  - `last_name` string, nullable: The contact's last name. Set to `null` to clear.
  - `external_id` string, nullable: Your own identifier for this contact. Unique within the workspace when set. Set to `null` to clear.
  - `data` object: Custom property values to merge into the contact's existing data. Supplied keys are set, keys with a `null` value are removed, and omitted keys remain unchanged. Each key must be a registered contact property, including an archived one. Each value must match the property's declared type: string, number, boolean, or RFC 3339 datetime. Strings can contain up to `500` characters. An unregistered key returns a validation error. The serialized result is limited to 2 KB.

## Response `200`

The updated contact.

- Contact
  - `id` string, required
  - `email` string, email, nullable, required: The contact's email address, in its stored form, trimmed and lowercased before uniqueness is checked. Unique within the workspace. `null` when the contact has no email address.
  - `phone_number` string, nullable, required: The contact's phone number in normalized international form: a leading `+` and four to 15 digits. We normalize formatting but do not verify the number against numbering-plan metadata. The number is unique within the workspace. Because carriers recycle disconnected numbers, use `external_id` as the durable key for your own records. `null` when the contact has no phone number.
  - `first_name` string, nullable: The contact's first name. Available in broadcast templates as `bird.contact.first_name`.
  - `last_name` string, nullable: The contact's last name. Available in broadcast templates as `bird.contact.last_name`.
  - `external_id` string, nullable: Your own identifier for this contact, such as a user ID in your system. Unique within the workspace when set.
  - `data` object: Custom property values for this contact, available in broadcast templates as `bird.contact.<key>`. Each key is a property created via the contact properties API, and each value is a string, number, boolean, or RFC 3339 datetime matching the property's declared type (strings up to `500` characters). Total size is capped at 2 KB serialized. Values stored under a property that was later archived remain readable here.
  - `audiences` AudienceRef[]: The audiences this contact belongs to, most-recently-joined first. Only present when listing contacts; omitted from every other contact operation.
    - `id` string, required
    - `name` string, required: The audience's display name.
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required

## Other responses

- `400`: Bad request
- `401`: Authentication required
- `403`: Insufficient permissions
- `404`: Resource not found
- `409`: Resource conflict
- `422`: The request has invalid field values, violates a business rule, or carries a query parameter the endpoint does not declare. Field validation errors use `type: validation_error` and include the affected fields in `details`. Business-rule errors identify the failed rule in `type`.
- `429`: Rate limit exceeded
- `500`: Internal server error
- `503`: The service is temporarily unavailable. If `Retry-After` is present, wait for that delay before retrying; otherwise, retry with exponential backoff. Reuse the same idempotency key and request when retrying a mutation.

---

[API](https://skmtc.dev/messagebird/apis/bird-api.md) · [All operations](https://skmtc.dev/messagebird/apis/bird-api/llms.txt) · [OpenAPI document](https://skmtc.dev/messagebird/apis/bird-api/revisions/6dfce1179799?raw)