> ## Documentation Index
> Fetch the complete documentation index at: https://docs.guayaba.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Update Contact By ID

> Update a contact by ID.

Updates a contact identified by their unique ID. At least one field must be provided in the request body.

## Path Parameters

<ParamField path="id" type="string (UUID)" required>
  The unique identifier of the contact to update.
</ParamField>

## Request Body

<ParamField body="name" type="string">
  Contact name. Maximum 255 characters.
</ParamField>

<ParamField body="phoneNumber" type="string">
  New phone number in E.164 format (e.g., `+11234567890`). Validates the number and checks for duplicates.
</ParamField>

<ParamField body="timezone" type="string">
  IANA timezone string (e.g., `America/New_York`).
</ParamField>

<ParamField body="status" type="string">
  New status for the contact. Use [List Statuses](/api-reference/contacts/statuses) to retrieve valid values.
</ParamField>

<ParamField body="campaignId" type="string (UUID)">
  New campaign to move the contact to.
</ParamField>

<ParamField body="customVariables" type="object">
  Custom key-value data. **Replaces the entire existing object** — merge client-side if you need to preserve existing keys.
</ParamField>

## Behavior Notes

<AccordionGroup>
  <Accordion title="Changing timezone or campaign">
    Changing `timezone` or `campaignId` on an active contact will cancel and reschedule all pending calls and SMS.
  </Accordion>

  <Accordion title="Changing phone number">
    Changing `phoneNumber` validates the new number and checks for duplicates across your team.
  </Accordion>

  <Accordion title="Custom variables replacement">
    `customVariables` replaces the entire object. If you need to update a single key, read the current values first, merge them client-side, and send the full object.
  </Accordion>
</AccordionGroup>

## Response

<ResponseField name="success" type="boolean">
  Always `true` on a successful request.
</ResponseField>

<ResponseField name="message" type="string">
  Human-readable confirmation message.
</ResponseField>

<ResponseField name="contact" type="object">
  The updated contact object.

  <Expandable title="Contact fields">
    <ResponseField name="id" type="string (UUID)">
      Contact unique identifier.
    </ResponseField>

    <ResponseField name="phoneNumber" type="string">
      Phone number in E.164 format.
    </ResponseField>

    <ResponseField name="name" type="string">
      Contact name.
    </ResponseField>

    <ResponseField name="status" type="string">
      Updated contact status.
    </ResponseField>

    <ResponseField name="campaignId" type="string (UUID)">
      Current campaign ID.
    </ResponseField>

    <ResponseField name="customVariables" type="object">
      Custom key-value data stored on the contact.
    </ResponseField>

    <ResponseField name="updatedAt" type="string (ISO 8601)">
      Timestamp of this update.
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X PUT https://api.guayaba.ai/contacts/550e8400-e29b-41d4-a716-446655440000 \
    -H "Content-Type: application/json" \
    -H "X-API-Key: gua_a1b2c3d4_your-api-key-here" \
    -d '{
      "status": "paused",
      "customVariables": {
        "email": "new@example.com"
      }
    }'
  ```

  ```javascript Node.js theme={null}
  const contactId = '550e8400-e29b-41d4-a716-446655440000';

  const response = await fetch(`https://api.guayaba.ai/contacts/${contactId}`, {
    method: 'PUT',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': 'gua_a1b2c3d4_your-api-key-here'
    },
    body: JSON.stringify({
      status: 'paused',
      customVariables: {
        email: 'new@example.com'
      }
    })
  });

  const data = await response.json();
  ```

  ```python Python theme={null}
  import requests

  contact_id = '550e8400-e29b-41d4-a716-446655440000'

  response = requests.put(
      f'https://api.guayaba.ai/contacts/{contact_id}',
      headers={
          'Content-Type': 'application/json',
          'X-API-Key': 'gua_a1b2c3d4_your-api-key-here'
      },
      json={
          'status': 'paused',
          'customVariables': {
              'email': 'new@example.com'
          }
      }
  )

  data = response.json()
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "success": true,
    "message": "Contact updated successfully",
    "contact": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "phoneNumber": "+11234567890",
      "name": "John Doe",
      "status": "paused",
      "campaignId": "d290f1ee-6c54-4b01-90e6-d701748f0851",
      "customVariables": {
        "email": "new@example.com"
      },
      "updatedAt": "2026-01-20T15:00:00.000Z"
    }
  }
  ```

  ```json 400 Bad Request theme={null}
  {
    "error": "Validation error",
    "message": "At least one field must be provided"
  }
  ```

  ```json 404 Not Found theme={null}
  {
    "error": "Not found",
    "message": "Contact not found"
  }
  ```
</ResponseExample>