Create or update (upsert) a subscriber, send welcome, start a workflow

Creates or updates a subscriber and sends a welcome message if the subscriber is new to the channel. New subscribers are subscribed to the channel. If the subscriber already exists and is unsubscribed, a 405 Method Not Allowed will returned. You must honor the users request to not recieve further messages. See Compliance documentation.

This function transactionally updates the subscriber, their tags and properties, and then sends a welcome. This means that any failure implies that the changes were not persisted and no message was sent.

This end point allows the updating of email_address,external_user_id, tags, and properties. Tags and properties specified for existing subscribers are merged. To replace the values, use the reset flag.

The welcome message can be specified in the request or a welcome series configured on the channel can be sent. It is an error to specify both a welcome message and request that a series be sent. It is also an error to request a welcome series when no series has been configured on the channel. Welcome series tagging is applied when determining which welcome series to send, which matches the subscriber's tags to some welcome series. If there is no matching series, the default series is sent.

In addition to sending welcome series, the more recent workflow feature is also available through this API. By specifying the workflow to start and any necessary arguments, it is possible to start a workflow after updating the subscriber. Note that if the conditions for starting the workflow are not met, the workflow is not executed for the subscriber.

A note on HTTP status codes that upsert can return

  • 200 We performed the updates on an existing subscriber
  • 201 We created a new subscriber and applied the updates
  • 400 Some part of your request was not in an acceptable form ( eg - you supplied an email address, but it was not in valid form )
  • 405 The subscriber has unsubscribed, and thus can not be re-added to the system via this call ( See Compliance documentation. )
  • 412 the phone number is not able to receive messages ( could be a landline )

Note: If are planning to make > 1000 calls to this end point in a single session, it would be better to use our enterprise bulk upsert end point. Please request access via

Resource URL:


Resource information:

Response formatJSON
Requires authentication?Yes



The customer's phone number.


The customer's email address.


External ID for the customer.


Properties to set for the subscriber. An empty hash will clear the subscriber's properties.


An array of Tag SIDs to add to the subscriber. An empty array will clear the subscriber's tags.


A boolean indicating that the subscriber's properties and tags should be cleared before applying the specified tags and properties.


The welcome message text to send to the subscriber if they are new. This param is mutually exclusive with workflow_sid_to_start and send_welcome_series.


A boolean indicating that a welcome series configured on the channel should be sent if the subscriber is new. This param is mutually exclusive with workflow_sid_to_start and welcome_message_body.


The SID for an automation workflow to start. The workflow must be enabled. If you are wanting to use it as a "welcome" automation, you should consider setting the max_subscriber_executions to 1. This param is mutually exclusive with send_welcome_series and welcome_message_body.


A dictionary of arguments to pass to the workflow being started.


The subscriber status - subscribed, unsubscribed, or unconfirmed. To add a user without subscribing them, include a status of "unconfirmed". If this param is not included, new users are subscribed to the channel. Please note, you can not change an unsubscribed subscriber's status with this mechanism. We generally assume that once a subscriber has said STOP, it should be respected. If you believe you have the legal right to re-subscribe them, use the update end point.

Sample code:

curl \
  -X POST \
  -u '[SID]:[TOKEN]' \
  -H 'Content-Type: application/json' \
  -d '{
    "email_address": "",
    "external_user_id": "12357111317",
    "properties": {
      "firstName": "Joe",
      "lastName": "Smith"
    "tag_sids": ["p03Gjl8Uzn0RkZSpHXHnrw"],
    "send_welcome_series": true
  }' \

# Sample response
  "phone_number": "5009998080",
  "status": "subscribed",
  "subscribed_at": "2017-01-25T21:43:04.618Z",
  "unsubscribed_at": null,
  "created_at": "2017-01-25T21:43:04.620Z",
  "updated_at": "2017-01-25T21:43:04.620Z",
  "carrier": "AT&T Wireless",
  "carrier_updated_at": "2017-01-25T21:43:04.618Z",
  "added_to_inbox_at": null,
  "sid": "daBoeXvpfadRPgyYaaZJpw",
  "account_sid": "p03Gjl8Uzn0RkZSpHXHnrw",
  "channel_sid": "p03Gjl8Uzn0RkZSpHXHnrw",
  "transport_sid": "p03Gjl8Uzn0RkZSpHXHnrw"
Python coming soon.
Node coming soon.