> ## 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.

# Create Subscriber

> Create a new subscriber or update an existing one based on duplicate strategy

Create a new subscriber or handle existing ones based on the `duplicateStrategy` parameter.

## Request Body

<ParamField body="email" type="string">
  Subscriber delivery email address. Required when creating a new subscriber.
</ParamField>

<ParamField body="externalId" type="string">
  Your app/customer/user ID for this subscriber. It is unique within your
  workspace and is trimmed without lowercasing.
</ParamField>

<ParamField body="firstName" type="string">
  First name
</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" default="active">
  Status: `active`, `unsubscribed`, or `bounced`.
</ParamField>

<ParamField body="optInMode" type="string" default="default">
  Consent mode: `default` obeys your workspace double opt-in setting for new
  active subscribers, `confirmed` creates an active subscriber immediately when
  you have verified consent, and `double_opt_in` sends a confirmation email and
  keeps the contact unsubscribed until they confirm.
</ParamField>

<Note>
  Omitting `optInMode` follows the workspace double opt-in setting. Use
  `confirmed` only when your app already verified consent. When confirmation is
  required, Sequenzy applies requested lists and tags only after the subscriber
  clicks the confirmation link. `default` does not send confirmation email to an
  existing unsubscribed contact.
</Note>

<ParamField body="tags" type="string[]">
  Array of tag names to assign
</ParamField>

<ParamField body="lists" type="string[]">
  Array of list IDs to add the subscriber to. If omitted, the subscriber follows
  your workspace default lists setting. If set to an empty array `[]`, the
  subscriber will not be added to any lists.
</ParamField>

<ParamField body="customAttributes" type="object">
  Custom key-value attributes
</ParamField>

<ParamField body="enrollInSequences" type="boolean" default="true">
  Whether to enroll the subscriber in matching sequences. Defaults to `true`.
</ParamField>

<ParamField body="duplicateStrategy" type="string" default="skip">
  How to handle existing subscribers: - `skip` - Don't update existing
  subscribers (default) - `merge` - Only fill in missing fields, never overwrite
  existing values - `overwrite` - Replace all fields (but never reactivate
  unsubscribed users)
</ParamField>

```bash theme={null}
curl -X POST "https://api.sequenzy.com/api/v1/subscribers" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "externalId": "user_123",
    "firstName": "John",
    "lastName": "Doe",
    "phone": "+15551234567",
    "smsConsent": true,
    "tags": ["lead", "saas.monthly"],
    "lists": ["list_abc123"],
    "enrollInSequences": true,
    "duplicateStrategy": "skip"
  }'
```

## Responses

<ResponseExample>
  ```json 200 New subscriber theme={null}
  {
    "success": true,
    "subscriber": {
      "id": "sub_abc123",
      "email": "user@example.com",
      "externalId": "user_123",
      "firstName": "John",
      "lastName": "Doe",
      "phone": "+15551234567",
      "smsStatus": "subscribed",
      "status": "active",
      "tags": ["lead", "saas.monthly"],
      "createdAt": "2024-01-15T10:30:00Z",
      "created": true,
      "updated": false,
      "skipped": false
    }
  }
  ```

  ```json 200 Double opt-in queued theme={null}
  {
    "success": true,
    "subscriber": {
      "id": "sub_abc123",
      "email": "user@example.com",
      "externalId": "user_123",
      "firstName": "John",
      "lastName": "Doe",
      "status": "unsubscribed",
      "tags": [],
      "createdAt": "2024-01-15T10:30:00Z",
      "created": true,
      "updated": false,
      "skipped": false
    },
    "optIn": {
      "required": true,
      "emailQueued": true
    }
  }
  ```

  ```json 200 Existing subscriber (skipped) theme={null}
  {
    "success": true,
    "subscriber": {
      "id": "sub_abc123",
      "email": "user@example.com",
      "externalId": "user_123",
      "firstName": "John",
      "lastName": "Doe",
      "status": "active",
      "tags": ["existing-tag"],
      "createdAt": "2024-01-10T08:00:00Z",
      "created": false,
      "updated": false,
      "skipped": true
    }
  }
  ```

  ```json 200 Existing subscriber (merged) theme={null}
  {
    "success": true,
    "subscriber": {
      "id": "sub_abc123",
      "email": "user@example.com",
      "firstName": "John",
      "lastName": "Doe",
      "status": "active",
      "tags": ["existing-tag", "lead", "saas.monthly"],
      "createdAt": "2024-01-10T08:00:00Z",
      "created": false,
      "updated": true,
      "skipped": false
    }
  }
  ```

  ```json 400 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 401 theme={null}
  {
    "success": false,
    "error": "Unauthorized"
  }
  ```

  ```json 409 theme={null}
  {
    "success": false,
    "error": "Subscriber identity conflict: email and externalId point to different subscribers."
  }
  ```

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

<Card title="Double Opt-In" icon="mail" href="/concepts/double-opt-in">
  Learn how confirmation emails, pending subscribers, and signup tags work.
</Card>

<Card title="SMS & MMS" icon="message" href="/concepts/sms">
  Learn how SMS consent, quiet hours, and message credits work.
</Card>