developers

Automatically place incoming contact requests— like from a sign-up form—into your Shoutlet contact database.

This helps explain to your development team how to integrate your contact gathering forms with the Shoutlet contact API.

To begin, you need:

1. a Shoutlet account
2. a Shoutlet Client API key
3. shoutlet Group ID (optional)

If you don't have these last two items, contact your account representative.
(This will be automated in the future.)

The Basic Contact API allows for requests to be made via either GET or POST for the purpose of adding contacts to the Shoutlet contact database; for protection of your API key it is highly recommended that you use POST for any external-facing action.

As part of this request, you are REQUIRED to pass the following 2 items:

1. cid - your client ID number
2. capi - your client API key

You may also use the following optional items:

1. gid - a shoutlet Group ID, in which to place new contacts

Finally, pass along values for any of the fields listed below in Shoutlet Contact Fields. Once you have your name/value pairs setup, you need to pass them to:

http://client.shoutlet.com/shoutlet/api/contact_add

In response, Shoutlet will provide either 0 (an error has occurred) or a positive integer (the unique ID of the contact in the shoutlet database). At most minimal, the following get string would allow you to add a contact:

http://client.shoutlet.com/shoutlet/api/   »
		contact_add?cid=222&capi=a21e12345d7fedcdeaef8   »
		e3725eee1c2&cn_full_name=Jim%20McCarthy& »
		cn_email=jim@foo.com
			

line breaks are marked with   »

As your API key allows anyone to add contacts to your Shoutlet database, it is a good idea to make sure that only you and your development team can see the API key. In the near future, Shoutlet will be providing HTTPS support—which will allow for further securing of the key.

Following is a list of valid contact field names to be passed via the API:

name fields:

cn_first_name

first name

cn_middle_name

middle name

cn_last_name

last name

cn_full_name

full name (non-distinguished between first and last)

cn_salutation

salutation

important shoutlet contact fields:

cn_email

e-mail address (used by Shoutlet for e-mail shouts)

cn_cell_phone

mobile phone (used by Shoutlet for SMS shouts)

home information:

cn_home_phone

home phone

cn_home_address1

home address line 1

cn_home_address2

home address line 2

cn_home_address3

home address line 3

cn_home_address4

home address line 4

cn_home_address5

home address line 5

cn_home_country

home country

cn_home_state

home state

cn_home_city

home city

cn_home_zip_code

home ZIP code

work information:

cn_work_phone

work phone

cn_work_phone_ext

work phone extension

cn_occupation

occupation

cn_company_name

company name

cn_company_size

company size

cn_company_title

title at company

cn_company_dept

department

cn_company_address1

company address line 1

cn_company_address2

company address line 2

cn_company_address3

company address line 3

cn_company_address4

company address line 4

cn_company_address5

company address line 5

cn_company_country

company country

cn_company_state

company state

cn_company_city

company city

cn_company_zip_code

company ZIP code

cn_company_url

company URL

demographics:

cn_gender

sex

cn_marital_status

marital status

cn_children

children

cn_birthdate

birthdate (any format)

cn_age

age

cn_education

education

cn_school

school/college attended

cn_income_level

income

internet presence:

cn_homepage_url

homepage URL

cn_skype

Skype ID

cn_note

notes

Below is a sample PHP application which utilizes the Shoutlet API:

<?php
// The URL for the Shoutlet Contact API:
  $api_url = 'http://client.shoutlet.com/shoutlet/ »
api/contact_add';

// Your Client ID (provided by Shoutlet)
  $client_id  = 222;
  
// Your Client API Key (provided by Shoutlet)
  $client_api = 'a21e12345d7fedcdeaef8e3725eee1c2';
  
// An Optional Group ID for placing new contacts
// directly into a Shoutlet Group 
// (provided by Shoutlet)
  $group_id   = 276;
  $warning    = '';
  if (isset($_REQUEST['submit'])) {
  
// Validate the data against your needs:
  if (empty($_REQUEST['cn_first_name']))  »
  { $warning .= 'first name required<br />'; }

  if (empty($_REQUEST['cn_last_name']))  »
  { $warning .= 'last name required<br />'; }

  if (!preg_match('/^[^@\s]+@([-a-z0-9]+\.)+  »
  [a-z]{2,}$/i', $_REQUEST['cn_email'])) {  »
  $warning .= 'valid e-mail required<br />'; }

  if (!$warning) {
// Build a query string, the required 
// fields are: cid, capi. Optional fields 
// include gid and any of the Shoutlet 
// contact field IDs. This example uses 
// PHP CURL to make a post request with 
// these fields to Shoutlet
  $query = join('&', array("cid=$client_id",
   "capi=$client_api",
   "gid=$group_id",
   "cn_first_name={$_REQUEST['cn_first_name']}",
   "cn_last_name={$_REQUEST['cn_last_name']}",
   "cn_cell_phone={$_REQUEST['cn_cell_phone']}",
   "cn_email={$_REQUEST['cn_email']}"));
    $ch = curl_init($api_url);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $query);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

// On success Shoutlet will return the numerical 
// unique ID of your new Contact, or 0 on failure.
  $response = curl_exec($ch);
   curl_close($ch);
   if ($response > 0) {
    header('Location: http://www.shoutlet.com/');
    exit;
   }
   else { $warning = 'An error occurred »
    saving this contact.'; }
   }
}
?>

line breaks are marked with   »