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

# Partially update contact CRM

> Partially update contact CRM attributes with automatic activity logging and transactional guarantees

Partially update CRM pipeline attributes on a contact record, including lifecycle stage transitions, lead scoring adjustments, owner reassignments, and AI handling delegation.

Whenever lifecycle stages, scores, or AI handling settings change, the system automatically appends an audit event to the contact's [activity timeline](/api-reference/contacts/get-activities) (such as `stage_changed`, `lead_score_changed`, `handoff_to_human`, or `handoff_to_ai`).

***

### Authentication

This endpoint requires Bearer token authentication.

```http theme={null}
Authorization: Bearer <token>
```

| Header | Type | Required | Description | Format |
| :- | :- | :- | :- | :- |
| `Authorization` | `string` | **Yes** | Scoped organization API key or Bearer JWT token | `Bearer <token>` |

***

### Input parameters

<ParamField path="contact_id" type="string" required>
  Unique UUID identifier of the contact. Example: `7b8f9e2a-4c1d-48ef-9123-bcde456789ab`.
</ParamField>

<ParamField header="Authorization" type="string" required>
  Bearer token for authentication. Format: `Bearer <token>`.
</ParamField>

<ParamField body="lifecycle_stage" type="string">
  Target CRM lifecycle stage: `new`, `engaged`, `qualified`, `customer`, or `lost`.
</ParamField>

<ParamField body="lead_score" type="integer">
  Numerical lead score between `0` and `100`.
</ParamField>

<ParamField body="owner_id" type="string">
  UUID of the assigned team member, or `null` to unassign.
</ParamField>

<ParamField body="ai_handling" type="boolean">
  Toggle between automated AI engine handling (`true`) or human agent takeover (`false`).
</ParamField>

<ParamField body="name" type="string">
  Updated full name of the contact.
</ParamField>

<ParamField body="tags" type="string[]">
  Updated array of classification tags.
</ParamField>

<ParamField body="notes" type="string">
  Updated internal notes.
</ParamField>

<ParamField body="custom_fields" type="object">
  Updated custom metadata attributes dictionary.
</ParamField>

***

### Response Fields

Returns the updated [ContactResponse](/api-reference/contacts/get-contact#response-fields) object:

<ResponseField name="id" type="string">Contact UUID.</ResponseField>
<ResponseField name="organization_id" type="string">Organization UUID.</ResponseField>
<ResponseField name="phone_number" type="string">Telephone number.</ResponseField>
<ResponseField name="name" type="string">Updated contact name.</ResponseField>
<ResponseField name="tags" type="string[]">Updated classification tags.</ResponseField>
<ResponseField name="notes" type="string">Updated notes text.</ResponseField>
<ResponseField name="custom_fields" type="object">Updated metadata object.</ResponseField>
<ResponseField name="lifecycle_stage" type="string">Updated lifecycle stage (`new`, `engaged`, `qualified`, `customer`, `lost`).</ResponseField>
<ResponseField name="lead_score" type="integer">Updated lead qualification score (0–100).</ResponseField>
<ResponseField name="owner_id" type="string">Assigned owner UUID or `null`.</ResponseField>
<ResponseField name="ai_handling" type="boolean">Current AI handling status.</ResponseField>
<ResponseField name="last_activity_at" type="string">Timestamp of the newly registered activity.</ResponseField>
<ResponseField name="source" type="string">Contact origin.</ResponseField>
<ResponseField name="created_at" type="string">Creation timestamp.</ResponseField>
<ResponseField name="updated_at" type="string">Modification timestamp.</ResponseField>

***

<RequestExample>
  ```bash cURL theme={null}
  curl -X PATCH "https://api.sayvy.ai/api/v1/contacts/7b8f9e2a-4c1d-48ef-9123-bcde456789ab" \
    -H "Authorization: Bearer <token>" \
    -H "Content-Type: application/json" \
    -d '{
      "lifecycle_stage": "qualified",
      "lead_score": 90,
      "ai_handling": false,
      "owner_id": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d"
    }'
  ```

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

  url = "https://api.sayvy.ai/api/v1/contacts/7b8f9e2a-4c1d-48ef-9123-bcde456789ab"

  payload = {
      "lifecycle_stage": "qualified",
      "lead_score": 90,
      "ai_handling": False,
      "owner_id": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d"
  }

  headers = {
      "Authorization": "Bearer <token>",
      "Content-Type": "application/json"
  }

  response = requests.patch(url, json=payload, headers=headers)
  print(response.status_code)
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://api.sayvy.ai/api/v1/contacts/7b8f9e2a-4c1d-48ef-9123-bcde456789ab", {
    method: "PATCH",
    headers: {
      "Authorization": "Bearer <token>",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      lifecycle_stage: "qualified",
      lead_score: 90,
      ai_handling: false,
      owner_id: "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d"
    })
  });

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

  ```java Java theme={null}
  import java.net.URI;
  import java.net.http.HttpClient;
  import java.net.http.HttpRequest;
  import java.net.http.HttpResponse;

  String jsonPayload = """
  {
    "lifecycle_stage": "qualified",
    "lead_score": 90,
    "ai_handling": false
  }
  """;

  HttpRequest request = HttpRequest.newBuilder()
      .uri(URI.create("https://api.sayvy.ai/api/v1/contacts/7b8f9e2a-4c1d-48ef-9123-bcde456789ab"))
      .header("Authorization", "Bearer <token>")
      .header("Content-Type", "application/json")
      .method("PATCH", HttpRequest.BodyPublishers.ofString(jsonPayload))
      .build();

  HttpResponse<String> response =
      HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
  System.out.println(response.body());
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "id": "7b8f9e2a-4c1d-48ef-9123-bcde456789ab",
    "organization_id": "00000000-0000-0000-0000-000000000001",
    "phone_number": "+14155550199",
    "name": "Jane Miller",
    "tags": [
      "vip"
    ],
    "notes": "Handoff to enterprise sales team",
    "custom_fields": {
      "company": "Acme Corp"
    },
    "lifecycle_stage": "qualified",
    "lead_score": 90,
    "owner_id": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
    "ai_handling": false,
    "last_activity_at": "2026-10-07T16:00:00Z",
    "source": "manual",
    "created_at": "2026-10-07T11:00:00Z",
    "updated_at": "2026-10-07T16:00:00Z"
  }
  ```

  ```json 404 Not Found theme={null}
  {
    "detail": "Contact not found"
  }
  ```

  ```json 401 Unauthorized theme={null}
  {
    "detail": "Unauthorized"
  }
  ```
</ResponseExample>

***

<div
  style={{
display: "flex",
alignItems: "center",
justifyContent: "space-between",
backgroundColor: "rgba(255, 255, 255, 0.03)",
border: "1px solid rgba(255, 255, 255, 0.08)",
borderRadius: "16px",
padding: "10px 18px",
marginTop: "40px",
gap: "16px",
flexWrap: "wrap"
}}
>
  <a
    href="/api-reference/contacts/update-contact"
    style={{
display: "inline-flex",
alignItems: "center",
gap: "6px",
color: "#94A3B8",
textDecoration: "none",
fontSize: "14px",
fontWeight: "500",
padding: "4px 8px"
}}
  >
    <span style={{ fontSize: "16px" }}>‹</span> Previous
  </a>

  <div
    style={{
display: "flex",
alignItems: "center",
gap: "16px",
backgroundColor: "rgba(255, 255, 255, 0.04)",
border: "1px solid rgba(255, 255, 255, 0.06)",
borderRadius: "12px",
padding: "8px 16px",
marginLeft: "auto"
}}
  >
    <div style={{ textAlign: "right" }}>
      <div style={{ fontSize: "13px", fontWeight: "700", color: "#F8FAFC" }}>Get contact activities</div>

      <div style={{ fontSize: "11px", color: "#94A3B8", maxWidth: "260px", overflow: "hidden", textOverflow: "ellipsis", whiteSpace: "nowrap" }}>
        GET /api/v1/contacts/\{contact\_id}/activities
      </div>
    </div>

    <div style={{ width: "1px", height: "24px", backgroundColor: "rgba(255, 255, 255, 0.1)" }} />

    <a
      href="/api-reference/contacts/get-activities"
      style={{
  display: "inline-flex",
  alignItems: "center",
  gap: "6px",
  color: "#94A3B8",
  textDecoration: "none",
  fontSize: "14px",
  fontWeight: "500"
}}
    >
      Next <span style={{ fontSize: "16px" }}>›</span>
    </a>
  </div>
</div>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.