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

# Update Subscriber

> Update a subscriber's details or fully unsubscribe them

Update a subscriber's first name, last name, status, tags, or custom attributes.
When you set `status` to `unsubscribed`, Sequenzy runs the full unsubscribe workflow:
it unsubscribes the contact from all lists and cancels their active sequence enrollments.
You can also update by external ID with `PATCH /api/v1/subscribers/external?externalId={externalId}`.

## Path Parameters

<ParamField path="email" type="string" required>
  Subscriber email (URL encoded)
</ParamField>

## Query Parameters

<ParamField query="externalId" type="string">
  External ID to use with `/subscribers/external`. Use this route for IDs that
  contain `/`.
</ParamField>

## Request Body

<ParamField body="firstName" type="string">
  First name
</ParamField>

<ParamField body="email" type="string">
  New delivery email address. This is most useful on the external ID route.
</ParamField>

<ParamField body="externalId" type="string">
  New customer-owned external ID. The update fails with `409` if another
  subscriber owns it.
</ParamField>

<ParamField body="lastName" type="string">
  Last name
</ParamField>

<ParamField body="phone" type="string">
  Phone number in E.164 format (`+15551234567`) or US national format. Stored
  normalized to E.164. An invalid phone returns `400 VALIDATION_ERROR`.
  Setting a phone does NOT subscribe the contact to SMS - use `smsConsent` for
  that.
</ParamField>

<ParamField body="smsConsent" type="boolean">
  SMS marketing consent. `true` sets the subscriber's SMS status to
  `subscribed` with consent source `api` - only send `true` when you have
  express written consent. `false` sets it to `unsubscribed`. Omitted leaves
  SMS status unchanged. Consent is never inferred from phone presence. See
  [SMS & MMS](/concepts/sms) for the full consent model.
</ParamField>

<ParamField body="status" type="string">
  Status: `active`, `unsubscribed`, or `bounced`. Setting `active` resubscribes
  the contact. Setting `unsubscribed` performs a full global unsubscribe.
</ParamField>

<ParamField body="tags" type="string[]">
  Replace all tags with this array
</ParamField>

<ParamField body="customAttributes" type="object">
  Custom attributes to update. By default this replaces the existing public
  custom-attribute map.
</ParamField>

<ParamField body="customAttributesStrategy" type="string" default="replace">
  How to apply `customAttributes`: `replace` replaces the existing public
  custom-attribute map, while `merge` overwrites only the provided keys and
  retains unspecified existing keys.
</ParamField>

```bash theme={null}
curl -X PATCH "https://api.sequenzy.com/api/v1/subscribers/user%40sequenzy.com" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Jane",
    "status": "active",
    "phone": "+15551234567",
    "smsConsent": true,
    "tags": ["customer", "vip"]
  }'
```

```bash theme={null}
curl -X PATCH "https://api.sequenzy.com/api/v1/subscribers/external?externalId=user_123" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "new-user@example.com",
    "lastName": "Updated",
    "customAttributesStrategy": "merge",
    "customAttributes": {
      "plan": "pro"
    }
  }'
```

With `customAttributesStrategy: "merge"`, a subscriber whose existing
`customAttributes` are
`{"arr":["1","2"],"letter":"X","val":true,"other":"abc"}` and whose PATCH
payload is
`{"customAttributesStrategy":"merge","customAttributes":{"arr":["3"],"letter":"Z","number":3}}`
ends with `{"arr":["3"],"letter":"Z","number":3,"val":true,"other":"abc"}`.

## Responses

<ResponseExample>
  ```json 200 theme={null}
  {
    "success": true,
    "subscriber": {
      "id": "sub_abc123",
      "email": "user@sequenzy.com",
      "externalId": "user_123",
      "firstName": "Jane",
      "lastName": "Doe",
      "phone": "+15551234567",
      "smsStatus": "subscribed",
      "status": "active",
      "tags": ["customer", "vip"],
      "customAttributes": { "plan": "pro" },
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-16T14:20:00Z"
    }
  }
  ```

  ```json 400 theme={null}
  {
    "success": false,
    "error": "externalId is required"
  }
  ```

  ```json 400 Invalid phone theme={null}
  {
    "success": false,
    "error": {
      "code": "VALIDATION_ERROR",
      "message": "Invalid phone number. Provide a valid phone in E.164 format, e.g. +15551234567, or US national format."
    }
  }
  ```

  ```json 422 theme={null}
  {
    "type": "validation",
    "on": "body",
    "property": "/status",
    "message": "Expected union value"
  }
  ```

  ```json 404 theme={null}
  {
    "success": false,
    "error": "Subscriber not found"
  }
  ```

  ```json 401 theme={null}
  {
    "success": false,
    "error": "Unauthorized"
  }
  ```

  ```json 409 theme={null}
  {
    "success": false,
    "error": "Subscriber identity conflict: target email belongs to a different subscriber."
  }
  ```

  ```json 500 theme={null}
  {
    "success": false,
    "error": "Internal server error"
  }
  ```
</ResponseExample>