Mobile Commons API

The Mobile Commons API allows clients to interact with their campaigns and send messages programmatically.

Security

Authorization for the API is done using HTTP Basic Auth. You should use your Mobile Commons login email and password and you should access the API using your account’s subdomain (e.g. http://secure.mcommons.com). Please consult your HTTP library’s documentation for details on how to specify basic auth credentials.

Function Reference

List Campaigns
URL: https://secure.mcommons.com/api/campaigns
Protocol: HTTP GET
Parameters: include_opt_in_paths (set to 1 to include all opt-in path details. default is 0)
Sample Response: <response success=\”true\”> <campaigns><campaign id=\”3\” active=\”true\”> <name>All Users</name></campaign></campaigns>

List Groups
URL: https://secure.mcommons.com/api/groups
Protocol: HTTP GET
Parameters: None
Sample Response: <response success=\”true\”><groups><group id=\”3\” type=\”UploadedGroup\”> <name>Chocolate Lovers</name></group></groups>

List Campaign Subscribers
URL: https://secure.mcommons.com/api/campaign_subscribers
Protocol: HTTP GET
Parameters: campaign_id (Required)

opt_in_path_id (scope results to a particular opt-in path)

include_subscriber_count (add an element with the current subscriber count. possibly slow.)

limit (Limits the number of returned subscribers. Maximum of 1000)

page (Specifies which page, of the total number of pages of results, to return)
Sample Response: <response success=”true”><subscriptions num=”1″ page=”1″><sub><id>123</id><phone_number>1234567890</phone_number><activated_at>2011-11-01 15:30:59 UTC</activated_at><opted_out_at>2011-11-02 15:30:59 UTC</opted_out_at></sub></subscriptions></response>

List Group Members
URL: https://secure.mcommons.com/api/group_members
Protocol: HTTP GET
Parameters: group_id

limit (Limits the number of returned profiles. Maximum of 1000)

page (Specifies which page, of the total number of pages of results, to return)

from (Limits the returned profiles to ones updated after or on this date time. ISO-8601 format)

to (Limits the returned profiles to ones updated before or on this date time. ISO-8601 format)
Sample Response: <response success=”true”><group id=”3″ type=”UploadedGroup” name=”Chocolate Lovers”><profile id=”4054″><first_name>Mickey</first_name> <last_name>Mouse</last_name> <phone_number>555-123-1234</phone_number> <email>mickey@mouse.org</email> <address>
<street1>123 Mouse Way</street1> <street2>Apartment M</street2> <city>Orlando</city><state>FL</state> <postal_code>12345</postal_code> <country>USA</country> </address> </profile></group></response>

Create Group
URL: https://secure.mcommons.com/api/create_group
Protocol: HTTP GET
Parameters: name
Sample Response: <response success=”true”><group id=”3″ type=”UploadedGroup” name=”Chocolate Lovers”></group></response>

Add Group Member
URL: https://secure.mcommons.com/api/add_group_member
Protocol: HTTP GET
Parameters: group_idphone_number
Sample Response: <response success=”true”><group id=”3″ type=”UploadedGroup” name=”Chocolate Lovers”></group></response>

Remove Group Member
URL: https://secure.mcommons.com/api/remove_group_member
Protocol: HTTP GET
Parameters: group_idphone_number
Sample Response: <response success=”true”><group id=”3″ type=”UploadedGroup” name=”Chocolate Lovers”></group></response>

Profile Summary
URL: https://secure.mcommons.com/api/profile
Protocol: HTTP GET
Parameters: phone_number (Required)
company (Default is the firm)
include_messages (default false. Set to true to include associated text messages)
include_donations (default false. Set to true to include associated mobile giving donations, if any)
Sample Response: 
<?xml version="1.0" encoding="UTF-8"?>
<response success="true">
    <profile id="1">
      <first_name>John</first_name>
      <last_name>Doe</last_name>
      <phone_number>2025551234</phone_number>
      <email></email>
      <status>Active Subscriber</status>
      <source type="Keyword" name="JOIN"/>
      <address>
        <street1>1 Main St</street1>
        <street2></street2>
        <city>New York</city>
        <state>NY</state>
        <postal_code></postal_code>
        <country>US</country>
      </address>
      <location>
        <latitude>1.00000</latitude>
        <longitude>-1.00000</longitude>
      </location>
      <custom_columns>
        <custom_column name="favourite_ice_cream">Chocolate</custom_column>
        <custom_column name="remote_crm_id">999</custom_column>
      </custom_columns>
      <subscriptions>
        <subscription status="Active" campaign_id="1"/>
      </subscriptions>
      <integrations>
       <integration type="Salesforce" synchronized_at="2011-11-11T18:48:14Z" constituent_id="1"/>
      </integrations>
      <messages>
        <message message_type="opt_in" id="12345" status="Matched keyword JOIN">
          <body>JOIN</body>
          <when>2011-11-11 17:56:12 UTC</when>
          <campaign id="12345" active="true">
            <name>Main Subscriber List</name>
          </campaign>
        </message>
      </messages>
      <clicks>
        <click id="12345">
          <created_at>2011-11-11 19:21:54 UTC</created_at>
          <url>http://www.mobilecommons.com</url>
          <remote_addr>123.123.123.123</remote_addr>
          <http_referer>321.321.321.321</http_referer>
          <user_agent>Mozilla/5.0 (iPhone; U; CPU iPhone OS 4_2_6)</user_agent>
        </click>
      </clicks>
      <donations>
        <donation id="2975251" status="accepted">
          <amount>5</amount>
          <when>2012-08-13T13:48:10Z</when>
          <description>Texted 'GIVE' to 12345</description>
          <campaign id="123" active="true">
            <name>Donation Testing</name>
          </campaign>
        </donation>
      </donations>
    </profile>
</response>

Profile Update
URL: https://secure.mcommons.com/api/profile_update
Protocol: HTTP POST
Parameters: phone_number (Required)

phone

email

postal_code

first_name

last_name

street1

street2

city

state

country

Custom Column (Any custom column name)
Sample Response: The profile for this phone number will be created or updated. We’ll return a summary of the profile record (the same as the Profile Summary call).

<?xml version="1.0" encoding="UTF-8"?>
<response success="true">
    <profile id="1">
      <first_name>John</first_name>
      <last_name>Doe</last_name>
      <phone_number>2025551234</phone_number>
      <email></email>
      <status>Active Subscriber</status>
      <source type="Keyword" name="JOIN"/>
      <address>
        <street1>1 Main St</street1>
        <street2></street2>
        <city>New York</city>
        <state>NY</state>
        <postal_code></postal_code>
        <country>US</country>
      </address>
      <location>
        <latitude>1.00000</latitude>
        <longitude>-1.00000</longitude>
      </location>
      <custom_columns>
        <custom_column name="favourite_ice_cream">Chocolate</custom_column>
        <custom_column name="remote_crm_id">999</custom_column>
      </custom_columns>
      <subscriptions>
        <subscription status="Active" campaign_id="1"/>
      </subscriptions>
    </profile>
</response>

List All Profiles
URL: https://secure.mcommons.com/api/profiles
Protocol: HTTP GET
Parameters: limit (Limits the number of returned profiles. Maximum of 1000)
page (Specifies which page, of the total number of pages of results, to return)
from (Limits the returned profiles to ones updated afteror on this date time. ISO-8601 format)
to (Limits the returned profiles to ones updated before or on this date time. ISO-8601 format)
Sample Response: 
<?xml version="1.0" encoding="UTF-8"?>
<response success="true" num="2100" page="1" >
  <profiles>
    <profile id="1">
      <first_name>John</first_name>
      <last_name>Doe</last_name>
      <phone_number>2025551234</phone_number>
      <email></email>
      <status>Active Subscriber</status>
      <source type="Keyword" name="JOIN"/>
      <address>
        <street1>1 Main St</street1>
        <street2></street2>
        <city>New York</city>
        <state>NY</state>
        <postal_code></postal_code>
        <country>US</country>
      </address>
      <location>
        <latitude>1.00000</latitude>
        <longitude>-1.00000</longitude>
      </location>
      <custom_columns>
        <custom_column name="favourite_ice_cream">Chocolate</custom_column>
        <custom_column name="remote_crm_id">999</custom_column>
      </custom_columns>
      <subscriptions>
        <subscription status="Active" campaign_id="1"/>
      </subscriptions>
    </profile>
  </profiles>
</response>

List Incoming Messages
URL: https://secure.mcommons.com/api/messages
Protocol: HTTP GET
Parameters: include_profile (Set to true to include extra profile information for each message)

limit (Limits the number of returned messages. Defaults to 20. Can not be more than 100.)

page (Specifies which page, of the total number of pages of results, to return. The current page number and the total number of pages is set in the response xml)

query (Limits messages to ones that match this query term in their body)

campaign_id (Limits messages to this campaign)

start_time (Limits the messages to ones after this date time. ISO-8601 format. Assumes your user’s local timezone unless otherwise specified)

end_time (Limits the messages to ones before or on this date time. ISO-8601 format. Assumes your user’s local timezone unless otherwise specified)

Results can be filtered by adding one or more of the following parameters with the value 1 or 0 to show or hide them respectively:
opt_in, opt_out, help_request, reply, info_response, unknown, call_in_response, mdata_query, donation
Sample Response: 
<?xml version="1.0" encoding="UTF-8"?>
<response success="true">
  <messages limit="20" page_count="23" page="1">
    <message id="1000001" approved="false" type="mdata_query">
      <phone_number>2025551234</phone_number>
      <body>Starbucks</body>
      <received_at>2009-08-11 18:38:29 UTC</received_at>
      <campaign id="123" active="true">Main Subscriber List</campaign>
    </message>
    <message id="1000002" approved="false" type="opt_in">
      <phone_number>2025554567</phone_number>
      <body>Aardvark</body>
      <received_at>2009-08-10 19:35:03 UTC</received_at>
      <campaign id="123" active="true">Main Subscriber List</campaign>
	<profile id="1">
	  <first_name>John</first_name>
	  <last_name>Doe</last_name>
	  <phone_number>2025551234</phone_number>
	  <email></email>
	  <status>Active Subscriber</status>
	  <address>
	    <street1>1 Main St</street1>
	    <street2></street2>
	    <city>New York</city>
	    <state>NY</state>
	    <postal_code></postal_code>
	    <country>US</country>
	  </address>
	  <location>
	    <latitude>1.00000</latitude>
	    <longitude>-1.00000</longitude>
	  </location>
	</profile>
     </message>
  </messages>
</response>

List Outgoing Messages
URL: https://secure.mcommons.com/api/sent_messages
Protocol: HTTP GET
Parameters: limit (Limits the number of returned messages. Defaults to 20. Can not be more than 100.)

page (Specifies which page, of the total number of pages of results, to return. The current page number and the total number of pages is set in the response xml)

campaign_id (Limits messages to this campaign)start_time (Limits the messages to ones after this date time. ISO-8601 format. Assumes your user’s local timezone unless otherwise specified)

end_time (Limits the messages to ones before or on this date time. ISO-8601 format. Assumes your user’s local timezone unless otherwise specified)
Sample Response: 
<?xml version="1.0" encoding="UTF-8"?>
<response success="true">
  <messages limit="20" page_count="23" page="1">
    <message id="1000001" type="help_response" status="sent">
      <phone_number>2025551234</phone_number>
      <body>Message and data rates may apply</body>
      <sent_at>2009-08-11 18:38:29 UTC</sent_at>
      <campaign id="123" active="true">Main Subscriber List</campaign>
    </message>
  </messages>
</response>

Send SMS Message
URL: https://secure.mcommons.com/api/send_message
Protocol: HTTP POST
Parameters: campaign_id
body (160 characters or fewer)
phone_number
Sample Response: <response success=”true”></response>

Send Broadcast to Campaign Subscribers
URL: https://secure.mcommons.com/api/schedule_broadcast
Protocol: HTTP POST
Parameters: campaign_id
body (Fewer than 160 characters)
time (Optional, in ISO-8601 format, e.g. 2008-12-31T12:34:56)
Sample Response: <response success=”true”><broadcast id=”456″></response>
Notes: Broadcasts are considered immediate unless you add the “time=” parameter

List Calls
URL: https://secure.mcommons.com/api/calls
Protocol: HTTP GET
Parameters: mconnect_id (The id of the mConnect Required)

include_profile (Set to true to include extra profile information for each message)

limit (Limits the number of returned calls. Maximum of 1000. Default of 1000)

page (Specifies which page, of the total number of pages of results, to return)

from (Limits the returned calls to ones that ended after or on this date time. ISO-8601 format)

to (Limits the returned calls to ones that ended before or on this date time. ISO-8601 format)
Sample Response: 
<response success="true">
  <calls num="1000" page="2">
    <call id="11765581">
      <start_time>2011-07-08 05:11:03 UTC</start_time>
      <end_time>2011-07-08 05:11:24 UTC</end_time>
      <duration>20</duration>
      <call_status>no answer</call_status>
      <connection_source>web</connection_source>
      <email>user@yahoo.com</email>
      <profile_status>Active Subscriber</profile_status>
      <profile_status_at_call_time>Active Subscriber</profile_status_at_call_time>
      <handset_number>2125550001</handset_number>
      <carrier_name>Sprint (Sprint PCS)</carrier_name>
      <voip_number>8005550002</voip_number>
      <destination_number>2022243121</destination_number>
      <transcription/>
      <voicemail_duration/>
      <voicemail/>
      <mconnect id="10"></mconnect>
      <profile id="100">
        <email>user@yahoo.com</email>
        <first_name>Joe</first_name>
        <last_name>User</last_name>
        <address>
          <street1/>
          <street2/>
          <city/>
          <state>NY</state>
          <postal_code>10001</postal_code>
          <country/>
        </address>
      </profile>
      <legislator>
        <first_name>John</first_name>
        <last_name>Senator</last_name>
        <party>democrat</party>
        <district>Junior Seat</district>
        <state>NY</state>
      </legislator>
    </call>
  </calls>
</response>

Count the number of mConnect Calls
URL: https://secure.mcommons.com/api/call_count
Protocol: HTTP GET
Parameters: mconnect_id
Sample Response: <response success=”true”><call_count>255</call_count></response>

Donation Summary
URL: https://secure.mcommons.com/api/donation_summary
Protocol: HTTP GET
Parameters: fundraising_idstart_time (Optional, only include donations made after this time. ISO-8601 format)end_time (Optional, only include donations made before this time. ISO-8601 format)
Sample Response: <response success=”true”><donation_summary name=”fundraising campaign” start_time=”2010-01-01 12:00:00″ end_time=”2010-01-02 12:00:00″ ><accepted count=”10″ amount=”100″ /><pending count=”2″ amount=”20″ /></donation_summary></response>

List Web Clicks
URL: https://secure.mcommons.com/api/clicks
Protocol: HTTP GET
Parameters: url_id OR url (The id of the URL or the actual shortened URL itself with URL encoding Required)page (Specifies which page, of the total number of pages of results, to return)

from (Limits the results to ones that ended after or on this date time. ISO-8601 format)

to (Limits the results to ones that ended before or on this date time. ISO-8601 format)
Sample Response: 
<response success="true">
  <clicks num="1" page="1">
    <click id="123">
      <created_at>2012-04-10 21:35:29 UTC</created_at>
      <url>http://www.example.com/</url>
      <remote_addr>127.0.0.1</remote_addr>
      <http_referer>127.0.0.1</http_referer>
      <user_agent>
Mozilla/4.0 (compatible; MSIE 7.0)
</user_agent>
    </click>
  </clicks>
</response>

Errors & Troubleshooting

All API responses are returned as XML inside a <response> tag. The response tag will always have a success= attribute indicating success or failure.
If success=”false”, the child element will be an error tag with an error ID and human-readable message. For example:
<response success="false"><errror id="3" message="Missing message body"></response>

Error Codes

ID Code Message
0 Unknown error
1 Invalid campaign id
2 Invalid broadcast time
3 Invalid message body
4 Invalid company id
5 Invalid phone number
6 Invalid group id
7 Invalid start time
8 Invalid end time
9 Invalid mData id
10 Invalid mData key
11 This phone is not subscribed to this campaign
12 Invalid fundraising id
13 Invalid message template
14 Phone is not textable
15 Invalid mConnect ID
16 Invalid query parameters
17 Too many messages
18 Invalid name
19 Invalid opt-in path
20 Invalid URL