# PATCH /contacts/:id

**Resource:** [Contacts](./contacts.md)  
**Scopes:** `contacts:write`  
**Write operation:** yes

Update an existing contact. Only include fields you want to change. Every successful PATCH emits a field-level audit row to crm_field_change_log (viewable at /data/crm-logs with the crm_audit:read scope).

## Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `id` | path | uuid | yes | Contact ID |
| `first_name` | body | string | no | First name. Trimmed on save. |
| `last_name` | body | string | no | Last name. Send "" or null to clear a previously set surname -- empty/whitespace values are stored as NULL. |
| `email` | body | string | no | Email |
| `phone` | body | string | no | Mobile number in E.164 format. Landlines will be rejected -- use the landline field. |
| `landline` | body | string | no | Landline/fixed-line number in E.164 format. Set to null to clear. |
| `date_of_birth` | body | string | no | Date of birth in YYYY-MM-DD format. Set to null to clear. |
| `notes` | body | string | no | Notes |
| `metadata` | body | object | no | Custom field values as { field_id: value } pairs. Replaces entire metadata object -- read first with GET /contacts/:id and merge locally. Reserved key: "quick_links" stores per-contact Quick Link URLs as { <type-uuid>: <url> }. UUID-shaped keys at metadata root are rejected (400). |
| `email_unsubscribed` | body | boolean | no | Set true to mark contact as opted out of email. Set false to re-subscribe. This flag is also updated automatically on hard bounce, spam complaint, or unsubscribe link click. |
| `sms_unsubscribed` | body | boolean | no | Set true to mark contact as opted out of SMS. Set false to re-subscribe. This flag is also updated automatically when the contact texts STOP (opt out) or START (opt in). |

## Request example

```bash
curl -X PATCH \
  "https://api.trustpager.com/functions/v1/api/v1/contacts/a1b2c3d4-..." \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "sms_unsubscribed": false }'
```

## Response example

```json
{
  "data": {
    "id": "a1b2c3d4-...",
    "first_name": "John",
    "last_name": "Smith",
    "email": "john@example.com",
    "phone": "+61412345678",
    "email_unsubscribed": false,
    "sms_unsubscribed": false,
    "updated_at": "2026-04-27T12:00:00Z"
  },
  "meta": { "credits_remaining": 9498 }
}
```

---
Base URL: `https://api.trustpager.com/functions/v1/api/v1` — Auth: `Authorization: Bearer YOUR_API_KEY`