Mobile Commons API
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://acme.mcommons.com). Please consult your HTTP library’s documentation for details on how to specify basic auth credentials.
Function Reference
- List Campaigns
- List Groups
- List Campaign Subscribers
- List Group Members
- Create Group
- Add Group Member
- Remove Group Member
- List All Profiles
- Profile Summary
- List Incoming Messages
- List Outgoing Messages
- Send SMS Message
- Send Broadcast to Campaign Subscribers
- List Calls
- Count mConnect Calls
- Donation Summary
| List Campaigns | |
|---|---|
| URL: | https://acme.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://acme.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://acme.mcommons.com/api/campaign_subscribers |
| Protocol: | HTTP GET |
| Parameters: | campaign_id (Required)opt_in_path_id (scope results to a particular opt-in path) |
| 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://acme.mcommons.com/api/group_members |
| Protocol: | HTTP GET |
| Parameters: | group_idlimit (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://acme.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://acme.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://acme.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://acme.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) |
| 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>
</profile>
</response>
|
| List All Profiles | |
|---|---|
| URL: | https://acme.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 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: |
<?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://acme.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: |
| 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://acme.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://acme.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://acme.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://acme.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://acme.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://acme.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> |
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 |