> ## 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 Phone Number

> Update a contact's status or campaign by phone number.

Updates a contact identified by their phone number — no contact ID required. Use this to change a contact's status or move them to a different campaign from your own systems. Actions are logged as `contacts-actions-by-api` so they're tracked separately from in-app actions.

<Note>
  This endpoint requires an `X-API-Key` header. See [Authentication](/authentication) for details.
</Note>

## Request Body

<ParamField body="phone" type="string" required>
  Phone number of the contact to update, in E.164 format (e.g., `+11234567890`).
</ParamField>

<ParamField body="status" type="string">
  New status for the contact. Use [List Statuses](/api-reference/contacts/statuses) to retrieve valid values. Default system statuses include `active`, `paused`, `fulfilled`, `DNC`, `not-qualifies`, `not-interested`, `not-answering`, `wrong-number`, and `talk-to-human`.
</ParamField>

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

<Info>
  At least one of `status` or `campaignId` must be provided. You can send both in the same request.
</Info>

## Behavior Notes

<AccordionGroup>
  <Accordion title="Terminal statuses cancel outreach">
    Setting a contact to any terminal status (`fulfilled`, `paused`, `DNC`, `not-qualifies`, `not-interested`, `not-answering`, `wrong-number`) automatically cancels all scheduled calls, SMS, WhatsApp messages, and triggers for that contact.
  </Accordion>

  <Accordion title="Re-activating a contact">
    Setting the status back to `active` reschedules outreach based on the contact's campaign configuration.
  </Accordion>

  <Accordion title="Changing campaigns">
    Changing `campaignId` cancels scheduled actions from the old campaign and schedules new actions based on the new campaign's configuration.
  </Accordion>

  <Accordion title="Action logging">
    Updates made through this endpoint are logged as `contacts-actions-by-api` and do not inflate in-app action stats.
  </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="fulfilledAt" type="string (ISO 8601)">
      Timestamp when the contact was marked as fulfilled. Only present when status is `fulfilled`.
    </ResponseField>

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

<RequestExample>
  ```bash Mark as fulfilled theme={null}
  curl -X POST https://api.guayaba.ai/contacts/update \
    -H "Content-Type: application/json" \
    -H "X-API-Key: gua_a1b2c3d4_your-api-key-here" \
    -d '{
      "phone": "+11234567890",
      "status": "fulfilled"
    }'
  ```

  ```bash Move to campaign theme={null}
  curl -X POST https://api.guayaba.ai/contacts/update \
    -H "Content-Type: application/json" \
    -H "X-API-Key: gua_a1b2c3d4_your-api-key-here" \
    -d '{
      "phone": "+11234567890",
      "campaignId": "550e8400-e29b-41d4-a716-446655440000"
    }'
  ```

  ```bash Update both theme={null}
  curl -X POST https://api.guayaba.ai/contacts/update \
    -H "Content-Type: application/json" \
    -H "X-API-Key: gua_a1b2c3d4_your-api-key-here" \
    -d '{
      "phone": "+11234567890",
      "status": "active",
      "campaignId": "550e8400-e29b-41d4-a716-446655440000"
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api.guayaba.ai/contacts/update', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': 'gua_a1b2c3d4_your-api-key-here'
    },
    body: JSON.stringify({
      phone: '+11234567890',
      status: 'fulfilled'
    })
  });

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

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

  response = requests.post(
      'https://api.guayaba.ai/contacts/update',
      headers={
          'Content-Type': 'application/json',
          'X-API-Key': 'gua_a1b2c3d4_your-api-key-here'
      },
      json={
          'phone': '+11234567890',
          'status': 'fulfilled'
      }
  )

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

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "success": true,
    "message": "Contact updated successfully",
    "contact": {
      "id": "contact-uuid-here",
      "phoneNumber": "+11234567890",
      "name": "John Doe",
      "campaignId": "550e8400-e29b-41d4-a716-446655440000",
      "status": "fulfilled",
      "fulfilledAt": "2026-04-22T15:30:00.000Z",
      "updatedAt": "2026-04-22T15:30:00.000Z"
    }
  }
  ```

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

  ```json 401 Unauthorized theme={null}
  {
    "error": "Unauthorized",
    "message": "Invalid or missing API key"
  }
  ```

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

  ```json 429 Too Many Requests theme={null}
  {
    "error": "Rate limit exceeded",
    "message": "Too many requests"
  }
  ```
</ResponseExample>