> ## Documentation Index
> Fetch the complete documentation index at: https://platform.tatango.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Adding a Subscriber
> This endpoint adds a subscriber to a list.
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
```http theme={null}
POST https://app.tatango.com/api/v2/lists/{ID}/subscribers
```
## OpenAPI
````yaml POST /api/v2/lists/{ID}/subscribers
openapi: 3.1.0
info:
title: Tatango Legacy v2 API
description: Tatango legacy v2 API endpoints for existing integrations.
version: 2.0.0
servers:
- url: https://app.tatango.com
security:
- basicAuth: []
paths:
/api/v2/lists/{ID}/subscribers:
post:
tags:
- Subscribers
summary: Adding a Subscriber
description: This endpoint adds a subscriber to a list.
parameters:
- name: ID
in: path
description: ID of the list
required: true
schema:
type: integer
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AddSubscriberRequest'
example:
subscriber:
phone_number: '2141234567'
first_name: John
last_name: Doe
email: john.doe@example.com
birthdate: '19900101'
zip_code: '75201'
gender: Male
bypass_opt_in_process: true
bypass_opt_in_response: false
tags: vip,customer
custom_field_key: custom_value
responses:
'200':
description: Subscriber created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/AddSubscriberResponse'
example:
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
x-codeSamples:
- lang: cURL
label: cURL
source: >-
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: "
- lang: Ruby
label: Ruby
source: >-
require 'net/http'
require 'uri'
uri =
URI.parse('https://app.tatango.com/api/v2/lists/ID/subscribers')
http = Net::HTTP.new(uri.host, uri.port)
request = Net::HTTP::Post.new(uri.request_url)
request.basic_auth("emailaddress@mydomain.com", "my_api_key")
request.body =
{"subscriber":{"phone_number":"2141234567","first_name":"John","last_name":"Doe"}}.to_json
response = http.request(request)
- lang: JavaScript
label: JavaScript
source: >-
var request = new XMLHttpRequest();
request.open('POST',
'https://app.tatango.com/api/v2/lists/ID/subscribers', false);
request.setRequestHeader('Content-Type', 'application/json');
request.setRequestHeader('Authorization', 'Basic ' +
btoa('emailaddress@mydomain.com:my_api_key'));
var data = JSON.stringify({ subscriber: { phone_number:
'2141234567', first_name: 'John', last_name: 'Doe' } });
request.send(data);
components:
schemas:
AddSubscriberRequest:
type: object
properties:
subscriber:
type: object
properties:
phone_number:
type: string
description: The wireless phone number of the subscriber
example: '2141234567'
first_name:
type: string
description: First name - char(50)
example: John
last_name:
type: string
description: Last name - char(50)
example: Doe
email:
type: string
description: Email - char(50)
example: john.doe@example.com
birthdate:
type: string
description: Birthdate - int(8)
example: '19900101'
zip_code:
type: string
description: ZIP code - char(6)
example: '75201'
gender:
type: string
description: Gender - char('Male' or 'Female')
enum:
- Male
- Female
example: Male
bypass_opt_in_process:
type: boolean
description: When true, adds phone number without double opt-in
example: true
bypass_opt_in_response:
type: boolean
description: When true, suppresses confirmation message
example: false
tags:
type: string
description: List of tags, comma separated
example: vip,customer
custom_field_key:
type: string
description: Custom data value
example: custom_value
required:
- phone_number
required:
- subscriber
AddSubscriberResponse:
type: object
properties:
status:
type: string
example: Subscriber added
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:
$ref: '#/components/schemas/Subscriber'
required:
- status
- subscriber
Subscriber:
type: object
properties:
phone_number:
type: string
description: The wireless phone number of the subscriber
example: '2141234567'
first_name:
type: string
description: First name of the subscriber
example: John
last_name:
type: string
description: Last name of the subscriber
example: Doe
email:
type: string
description: Email address of the subscriber
example: john.doe@example.com
birthdate:
type: string
description: Birthdate of the subscriber
example: '19900101'
zip_code:
type: string
description: ZIP code of the subscriber
example: '75201'
gender:
type: string
description: Gender of the subscriber
example: Male
cleaned_at:
type: string
format: date-time
description: Date/time of automatic unsubscription (if applicable)
nullable: true
subscribed_at:
type: string
format: date-time
description: Date subscriber first subscribed to this list
example: '2025-06-18T15:36:07Z'
opted_out_at:
type: string
format: date-time
description: Date subscriber last unsubscribed from this list
nullable: true
opt_in_method:
type: string
description: Original opt-in method used
example: api
keyword_name:
type: string
description: Keyword used for opt-in (if applicable)
nullable: true
carrier:
type: integer
description: Wireless carrier ID
example: 383
carrier_name:
type: string
description: Wireless carrier name
example: Verizon Wireless
global_carrier_id:
type: string
description: Global wireless carrier ID
example: '12345'
global_carrier_name:
type: string
description: Global wireless carrier name
example: Verizon
tags:
type: array
items:
type: string
description: List of tags associated with the subscriber
example:
- vip
- customer
total_messages_received:
type: integer
description: >-
The total amount of mass messages this specific subscriber has
received over their lifetime from this specific list
example: 15
required:
- phone_number
- subscribed_at
- opt_in_method
securitySchemes:
basicAuth:
type: http
scheme: basic
description: >-
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.
````