Adding a Subscriber

cURL

curl "https://app.tatango.com/api/v2/lists/ID/subscribers" -d '{"subscriber":{"phone_number":"2141234567","first_name":"John","last_name":"Doe"}}' -X POST \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -u [email protected]:my_api_key \
  -H "Host: example.org" \
  -H "Cookie: "

{
  "status": "Subscriber added",
  "subscriber": {
    "phone_number": "2141234567",
    "first_name": "John",
    "last_name": "Doe",
    "email": "[email protected]",
    "birthdate": "19900101",
    "zip_code": "75201",
    "gender": "Male",
    "cleaned_at": null,
    "subscribed_at": "2025-06-18T15:36:07Z",
    "opted_out_at": null,
    "opt_in_method": "api",
    "keyword_name": null,
    "carrier": 383,
    "carrier_name": "Verizon Wireless",
    "global_carrier_id": "12345",
    "global_carrier_name": "Verizon",
    "tags": [
      "vip",
      "customer"
    ]
  }
}

POST

api

lists

{ID}

subscribers

cURL

curl "https://app.tatango.com/api/v2/lists/ID/subscribers" -d '{"subscriber":{"phone_number":"2141234567","first_name":"John","last_name":"Doe"}}' -X POST \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -u [email protected]:my_api_key \
  -H "Host: example.org" \
  -H "Cookie: "

{
  "status": "Subscriber added",
  "subscriber": {
    "phone_number": "2141234567",
    "first_name": "John",
    "last_name": "Doe",
    "email": "[email protected]",
    "birthdate": "19900101",
    "zip_code": "75201",
    "gender": "Male",
    "cleaned_at": null,
    "subscribed_at": "2025-06-18T15:36:07Z",
    "opted_out_at": null,
    "opt_in_method": "api",
    "keyword_name": null,
    "carrier": 383,
    "carrier_name": "Verizon Wireless",
    "global_carrier_id": "12345",
    "global_carrier_name": "Verizon",
    "tags": [
      "vip",
      "customer"
    ]
  }
}

The following parameters can be used to bypass the opt-in process:

bypass_opt_in_process - When true, adds phone number without double opt-in
bypass_opt_in_response - When true, suppresses confirmation message

FAQs

What happens when we use the add subscriber API to add a home phone number (i.e. non-cellular)?

You will receive the message “Bad phone number: landline or unreachable carrier” with the status code 422.

What happens when we use the add subscriber API to add a phone number that is currently unsubscribed from the list?

We will initiate the process of resubscribing the phone number to the list.

What happens when we use the add subscriber API to add a phone number that is already subscribed to the list?

A 200 OK is returned and no changes are made to the subscriber.

Can I request something other than a reply of YES to opt-in when opting into an API?

No. The reply is currently configured to YES.

Can I add a subscriber via API with custom data for that subscriber?

Yes. The optional parameters are listed for this API endpoint.

For subscriber fields like name, birthday, etc., are there any limitations on what we can use, like character limit, only certain characters, etc?

Yes. All optional parameters’ limitations are noted - see the JSON parameters above.

In what format should phone numbers be sent?

The phone number should be a continuous string of ten digits - with no dashes and no country code (e.g. “2065551111”).

If an account has multiple lists, and a phone number has opted-out, or been cleaned from one list, can we use the API to add them to a new list?

Yes - each list is a separate entity.

Request URL

POST https://app.tatango.com/api/v2/lists/{ID}/subscribers

Authorizations

Authorization

string

header

required

Tatango authenticates API requests by validating an API key passed via HTTP Basic Authentication. Use your login email as the username and your API key as the password.

Path Parameters

integer

required

ID of the list

Body

application/json

subscriber

object

required

Show child attributes

subscriber.phone_number

string

required

The wireless phone number of the subscriber

Example:

"2141234567"

subscriber.first_name

string

First name - char(50)

Example:

"John"

subscriber.last_name

string

Last name - char(50)

Example:

"Doe"

subscriber.email

string

Email - char(50)

Example:

"[email protected]"

subscriber.birthdate

string

Birthdate - int(8)

Example:

"19900101"

subscriber.zip_code

string

ZIP code - char(6)

Example:

"75201"

subscriber.gender

enum<string>

Gender - char('Male' or 'Female')

Available options:

Male,

Female

Example:

"Male"

subscriber.bypass_opt_in_process

boolean

When true, adds phone number without double opt-in

Example:

true

subscriber.bypass_opt_in_response

boolean

When true, suppresses confirmation message

Example:

false

subscriber.tags

string

List of tags, comma separated

Example:

"vip,customer"

subscriber.custom_field_key

string

Custom data value

Example:

"custom_value"

Response

200 - application/json

Subscriber created successfully

status

string

required

Examples:

"Subscriber added"

"Subscriber being added to campaign pending confirmation"

"Subscriber has been added - no opt-in message was sent due to list settings."

"Subscriber has already been sent opt-in message for this campaign."

"Subscriber is already subscribed to this campaign."

subscriber

object

required

Show child attributes

subscriber.phone_number

string

required

The wireless phone number of the subscriber

Example:

"2141234567"

subscriber.subscribed_at

string<date-time>

required

Date subscriber first subscribed to this list

Example:

"2025-06-18T15:36:07Z"

subscriber.opt_in_method

string

required

Original opt-in method used

Example:

"api"

subscriber.first_name

string

First name of the subscriber

Example:

"John"

subscriber.last_name

string

Last name of the subscriber

Example:

"Doe"

subscriber.email

string

Email address of the subscriber

Example:

"[email protected]"

subscriber.birthdate

string

Birthdate of the subscriber

Example:

"19900101"

subscriber.zip_code

string

ZIP code of the subscriber

Example:

"75201"

subscriber.gender

string

Gender of the subscriber

Example:

"Male"

subscriber.cleaned_at

string<date-time> | null

Date/time of automatic unsubscription (if applicable)

subscriber.opted_out_at

string<date-time> | null

Date subscriber last unsubscribed from this list

subscriber.keyword_name

string | null

Keyword used for opt-in (if applicable)

subscriber.carrier

integer

Wireless carrier ID

Example:

383

subscriber.carrier_name

string

Wireless carrier name

Example:

"Verizon Wireless"

subscriber.global_carrier_id

string

Global wireless carrier ID

Example:

"12345"

subscriber.global_carrier_name

string

Global wireless carrier name

Example:

"Verizon"

subscriber.tags

string[]

List of tags associated with the subscriber

Example:

["vip", "customer"]

subscriber.total_messages_received

integer

The total amount of mass messages this specific subscriber has received over their lifetime from this specific list

Example:

15

Updating a List Getting a Subscriber

⌘I

v2 API Reference

Accounts

Lists

Subscribers

Custom Fields

Tags

Messaging

Message Log (MOMT) Reports

Shortcodes

Transactional Messages

Webhooks

Adding a Subscriber

FAQs

Request URL

Authorizations

Path Parameters

Body

Response

v2 API Reference

Accounts

Lists

Subscribers

Custom Fields

Tags

Messaging

Message Log (MOMT) Reports

Shortcodes

Transactional Messages

Webhooks

​FAQs

​Request URL

Authorizations

Path Parameters

Body

Response

FAQs

Request URL