Subscribers


Subscribers are the people who have subscribed to your group lists. With the API, you can create them (opt in), remove them (opt out), and retrieve them. The following actions can be performed on this resource...

Retrieve All Subscribers

Retrieves all subscribers associated with all groups in your account. By default, you will get the first 20 subscribers, but you can modify this with the limit and offset values in the query string. The max limit for a single request is 10,000.

GET https://api.textcarrier.com/v1/subscribers?limit=30&offset=10

Example response:


      {
           "meta":{
              "limit":20,
              "offset":0,
              "total":1
           },
           "links":{
              "self":"https://api.textcarrier.com/v1/subscribers/"
           },
           "subscribers":[
              {
                 "id":999354382,
                 "number":"+15554443443",
                 "firstName":"Ryan",
                 "lastName":"Smith",
                 "city":null,
                 "state":null,
                 "zipCode":null,
                 "country":null,
                 "birthDate":null,
                 "group":24223543,
                 "subscribedDate":"2017-02-20 13:22:29",
                 "email":""
              }
           ]
        }
        

Retrieve a Specific Subscriber

Retrieves a specific subscriber with the id equal to {id}.

GET https://api.textcarrier.com/v1/subscribers/{id}

Example response:


      {
            "links": {
                "self": "https://api.textcarrier.com/v1/subscribers/999354382"
            },
            "subscriber": {
                "id":999354382,
                 "number":"+15554443443",
                 "firstName":"Ryan",
                 "lastName":"Smith",
                 "city":null,
                 "state":null,
                 "zipCode":null,
                 "country":null,
                 "birthDate":null,
                 "group":24223543,
                 "subscribedDate":"2017-02-20 13:22:29",
                 "email":""
            }
        
        }
        

Opt a Subscriber In

Opts a new subscriber into a specific group list. Using this action, the subscriber will receive no confirmation that they were subscribed. If you would like to send an auto reply to the subscriber when opting them in, see "opting a subscriber in and sending an auto reply" below. Only subscribers who have given explicitly permission to be sent text messages may be opted in. TextCarrier holds a zero tolerance policy for sending unsolicited text messages.

POST https://api.textcarrier.com/v1/subscribers/

Arguments

Parameter Description
action (mandatory) The action for this specific request type is OPTIN. This must be included or the request will fail.
group (mandatory) The ID of the group to which to add the subscriber.
number (mandatory) The US phone number of the subscriber. Must be at least 10 digits. It will be normalized to digits-only, preceded by a +.
firstName The first name of the subscriber.
lastName The last name of the subscriber.
email The email address of the subscriber.
birthDate The birthdate of the subscriber formatted as: YYYY-MM-DD HH:MM:SS.
city The city of the subscriber.
state The state of the subscriber. If no state is provided, one will be derived from the area code automatically.
zipCode The zipcode of the subscriber.
country The country of the subscriber.

Example response:


      {
           "meta":{
              "success":1
           },
           "links":{
              "self":"https://api.textcarrier.com/v1/subscribers/999354382"
           },
           "subscriber":{
              "id":999354382,
                 "number":"+15554443443",
                 "firstName":"Ryan",
                 "lastName":"Smith",
                 "city":null,
                 "state":null,
                 "zipCode":null,
                 "country":null,
                 "birthDate":null,
                 "group":24223543,
                 "subscribedDate":"2017-02-20 13:22:29",
                 "email":""
           }
        }
        

Opt a Subscriber In and Send an Auto Reply

Opts a new subscriber into a specific group list. Using this action, the subscriber will receive the "auto reply" text message for the particular keyword they are being opted into. Only subscribers who have given explicitly permission to be sent text messages may be opted in. TextCarrier holds a zero tolerance policy for sending unsolicited text messages.

POST https://api.textcarrier.com/v1/subscribers/

Arguments

Parameter Description
action (mandatory) The action for this specific request type is OPTINWITHAUTOREPLY. This must be included or the request will fail.
group (mandatory) The ID of the group to which to add the subscriber.
number (mandatory) The US phone number of the subscriber. Must be at least 10 digits. It will be normalized to digits-only, preceded by a +.
firstName The first name of the subscriber.
lastName The last name of the subscriber.
email The email address of the subscriber.
birthDate The birthdate of the subscriber formatted as: YYYY-MM-DD HH:MM:SS.
city The city of the subscriber.
state The state of the subscriber. If no state is provided, one will be derived from the area code automatically.
zipCode The zipcode of the subscriber.
country The country of the subscriber.

Example response:


      {
           "meta":{
              "success":1
           },
           "links":{
              "self":"https://api.textcarrier.com/v1/subscribers/999354382"
           },
           "subscriber":{
              "id":999354382,
                 "number":"+15554443443",
                 "firstName":"Ryan",
                 "lastName":"Smith",
                 "city":null,
                 "state":null,
                 "zipCode":null,
                 "country":null,
                 "birthDate":null,
                 "group":24223543,
                 "subscribedDate":"2017-02-20 13:22:29",
                 "email":""
           }
        }
        

Edit a Subscriber

Edit an existing subscriber.

POST https://api.textcarrier.com/v1/subscribers/

Arguments

Parameter Description
action (mandatory) The action for this specific request type is EDIT. This must be included or the request will fail.
id (mandatory) The ID of the subscriber you are attempting to edit.
number The US phone number of the subscriber. Must be at least 10 digits. It will be normalized to digits-only, preceded by a +.
firstName The first name of the subscriber.
lastName The last name of the subscriber.
email The email address of the subscriber.
birthDate The birthdate of the subscriber formatted as: YYYY-MM-DD HH:MM:SS.
city The city of the subscriber.
state The state of the subscriber. If no state is provided, one will be derived from the area code automatically.
zipCode The zipcode of the subscriber.
country The country of the subscriber.

Example response:


      {
           "meta":{
              "success":1
           },
           "links":{
              "self":"https://api.textcarrier.com/v1/subscribers/999354382"
           },
           "subscriber":{
              "id":999354382,
                 "number":"+15554443443",
                 "firstName":"Ryan",
                 "lastName":"Smith",
                 "city":null,
                 "state":null,
                 "zipCode":null,
                 "country":null,
                 "birthDate":null,
                 "group":24223543,
                 "subscribedDate":"2017-02-20 13:22:29",
                 "email":""
           }
        }
        

Opt a Subscriber Out

Opts an existing subscriber with the id equal to {id} out of a specific group list. Using this action, the opt out will be recorded in such a way that they will never be able to be re-opted in via any method but texting in to join. The subscriber will receive no confirmation that they were opted out.

POST https://api.textcarrier.com/v1/subscribers/{id}

Arguments

Parameter Description
action (mandatory) The action for this specific request type is OPTOUT. This must be included or the request will fail.

Example response:


        {
        
            "meta": {
                "success": true
            }
        
        }
        

Delete a Subscriber

Deletes an existing subscriber with the id equal to {id} out of a specific group list. Using this action, the subscriber is simply removed from the list and can be re-opted in via the API at a later time. The subscriber will receive no confirmation that they were removed.

POST https://api.textcarrier.com/v1/subscribers/{id}

Arguments

Parameter Description
action (mandatory) The action for this specific request type is DELETE. This must be included or the request will fail.

Example response:


        {
        
            "meta": {
                "success": true
            }
        
        }