We created a new viewing experience for our SMS API documentation. It's now all in one central location. Click here to check it out!

This method adds a recipient to a contact list. The custom fields are optional. Possible results from this method are:



ADDED - recipient was added succesfully.
DUPLCIATE / UPDATED - recipient already existed and the recipients data was updated.
OPTOUT - recipient existed on list and has unsubscribed at some point so cannot be added / updated.
DUPLICATE_DELETED - recipient already existed but has been deleted at some point.


Parameters


  • list_id - list identifier required in one of the two following formats:
    • integer - the list id as a numeric value, this can be found by requesting 'contact-lists.get' and using corresponding id values from the dataset
      OR
    • string - the list name EXACTLY as it is in the 'contact-lists.get' response.
  • mobile - string - recipients mobile number, required in one of the two following formats:
    • as a local number (you will need to pass a valid iso2 code in the mobileCountry parameter)
    • as an internationally formatted number (e.g. international code + mobile)
  • mobileCountry - string - iso2 code identifying the recipients country (e.g. AU) - only required when a local number is passed in the mobile field.
  • firstname - string - recipients firstname
  • lastname - string - recipients lastname
  • custom_1_value - string
  • custom_2_value - string
  • custom_3_value - string
  • custom_4_value - string
  • custom_5_value - string
  • custom_6_value - string
  • custom_7_value - string
  • custom_8_value - string
  • custom_9_value - string
  • custom_10_value - string


 




 




XML Request Example


<?xml version='1.0'?>

<request>

	<version>0.3</version>

	<key>API_KEY</key>

	<secret>API_SECRET</secret>

	<method>contact-lists.add-recipient</method>

	<params>

		<list_id>1076</list_id>

		<mobile>614xxxxxxxxx</mobile>

		<firstname>Test</firstname>

		<lastname>User</lastname>

		<mobile_dest_country />

	</params>

</request>







XML Response Example


<?xml version='1.0'?>

<xml>

	<method>contact-lists.add-recipient</method>

	<total>1</total>

	<time>2009-12-11 01:48:54 GMT</time>

	<timestamp>1260496134 GMT</timestamp>

	<data>

		<result>ADDED</result>

		<list_id>1076</list_id>

	</data>

</xml>







PHP Example


Download the PHP API Client


<?php



// change api key and secret to your own

$myAPIKey = "API_KEY";

$myAPISecret = "API_SECRET";



// include base class

require('APIclient.php');



// create new client object

$transmitsmsAPI = new transmitsmsAPI($myAPIKey, $myAPISecret);



// set parameters

$list_id = 1076;

$mobile = '614xxxxxxxxx';

$mobileCountry = 'AU';

$firstname = 'John';

$lastname = 'John';



// execute request

$methodResponse = $transmitsmsAPI->addContactListRecipient($list_id, $mobile, $mobileCountry, $firstname, $lastname);



// parse response into xml object

$xml = @simplexml_load_string($methodResponse);



echo ((string) $xml->data->result == 'ADDED') ? "Recipient added successfully" : "Recipient not added: " . (string) $xml->data->result;



?>






GET Example


Using a URL based request system you can request this method by using the below URL - be sure to url encode all your variables!


http://burst.transmitsms.com/api-wrapper/contact-lists.add-recipient?apikey=API_KEY&apisecret=API_SECRET&list_id=LIST_ID&mobile=MOBILE&firstname=FIRSTNAME&lastname=LASTNAME&mobile_dest_country=AU