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 emailaddress@mydomain.com:my_api_key \
  -H "Host: example.org" \
  -H "Cookie: "
{
  "status": "Subscriber added",
  "subscriber": {
    "phone_number": "2141234567",
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com",
    "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

​
ID
integer
required

ID of the list

Body

application/json

Response

200 - application/json

Subscriber created successfully

The response is of type object.