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://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
  • List All Profiles
  • List Incoming Messages
  • Send SMS Message
  • Send Broadcast to Campaign Subscribers
  • Donation Summary
  • Count mConnect Calls



    •  

    List Campaigns
    URL: https://acme.mcommons.com/api/campaigns
    Protocol: HTTP GET
    Parameters: None
    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
    Sample Response: <response success=”true”><subscribers num=”1″> <subscriber source=”web”>123-456-7890</subscriber> <subscribers></response>

    List Group Members
    URL: https://acme.mcommons.com/api/group_members
    Protocol: HTTP GET
    Parameters: group_id
    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>

    List All Profiles
    URL: https://acme.mcommons.com/api/profiles
    Protocol: HTTP GET
    Parameters: limit (Limits the number of returned profiles. Defaults to 100)
    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">
  <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>
      <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>
      <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: 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>
    </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>
    </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

    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_id
    start_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