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)

sort (set to asc or desc to sort by campaign ID ascending or descending. default is ascending)

status (set to active or ended to filter results. default is empty and returns all campaigns)

campaign_id (provide a specific campaign ID to view single result, invalid campaign ID will return all campaigns)

Sample Response:

<?xml version="1.0" encoding="UTF-8"?>
<response success="true">
  <campaigns>
    <campaign id="303" active="false">
      <name>Campaign One</name>
      <description></description>
      <tags>
        <tag>Tag Name Here</tag>
      </tags>
      <opt_in_paths>
        <opt_in_path id="175057" active = "true">
        <name>My Opt-In Path</name>
        <tags>
          <tag>OIP ABC</tag>
        </tags>
      </opt_in_path>
    </campaign>
    <campaign id="304" active="false">
      <name>Huge Campaign</name>
      <description></description>
      <tags>
        <tag>Tag Name Here</tag>
      </tags>
    </campaign>
    <campaign id="305" active="true">
      <name>Another Campaign</name>
      <description>Campaign to end all campaigns</description>
      <tags>
        <tag>Tag Name Here</tag>
      </tags>
    </campaign>
  </campaigns>
</response>

Example

curl --user yourusername:yourpassword \
https://secure.mcommons.com/api/campaigns

List Keywords

URL:

https://secure.mcommons.com/api/keywords

Protocol:

HTTP GET

Parameters:

None

Sample Response:

<?xml version="1.0" encoding="UTF-8"?>

<response success="true">

  <keywords>

    <keyword id="101" active="false">

      <name>First</name>

      <opt_in_path_id>201</opt_in_path_id>

      <ended_at>2007-07-05 16:39:40 UTC</ended_at>

      <created_at>2007-05-30 23:16:38 UTC</created_at>

      <updated_at>2013-01-08 18:45:31 UTC</updated_at>

    </keyword>

    <keyword id="102" active="true">

      <name>Second</name>

      <opt_in_path_id>202</opt_in_path_id>

      <ended_at>2008-08-05 16:39:40 UTC</ended_at>

      <created_at>2008-08-30 23:16:38 UTC</created_at>

      <updated_at>2013-08-08 18:45:31 UTC</updated_at>

    </keyword>

  </keywords>

</response>

Example

curl --user yourusername:yourpassword \
https://secure.mcommons.com/api/keywords

List Groups

URL:

https://secure.mcommons.com/api/groups

Protocol:

HTTP GET

Parameters:

limit (Control the limit of groups per page -- Max is 1000 & Default is 1000).

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

Sample Response:

<?xml version="1.0" encoding="UTF-8"?>
<response success="true">
  <<groups page="2" limit="500" page_count="3">>
    <group id="14" type="FilteredGroup" status="active">
      <name>Group One</name>
     <hint>These counts have been updated in the past 30 minutes</hint>
      <size>2</size>
    </group>
    <group id="91" type="UploadedGroup" status="active">
      <name>Group Two</name>
      <size>1</size>
    </group>
    .
    .
    .
  </groups>
</response>

Example

curl --user yourusername:yourpassword \
https://secure.mcommons.com/api/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)

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

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

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

to (Limits the returned subscribers to ones subscribed to that campaign before or on this date time. ISO-8601 format)

Sample Response:

<?xml version="1.0" encoding="UTF-8"?>

<response success="true">

  <subscriptions num="1″ page="1″>

    <sub>

      <id>123</id>
      <profile_id>1234567</profile_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>

Example

curl --user yourusername:yourpassword \
https://secure.mcommons.com/api/campaign_subscribers?campaign_id=101

List Group Members

URL:

https://secure.mcommons.com/api/group_members

Protocol:

HTTP GET

Parameters:

group_id (Required)

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">

    <group name="MC Test" id="49xxxx" type="UploadedGroup">

        <profile id="347xxxxxx">

            <first_name>Joe</first_name>

            <last_name>user</last_name>

            <phone_number>12025551234</phone_number>

            <email>user@yahoo.com</email>

            <status>Active Subscriber</status>

            <created_at>2019-06-21 14:49:40 UTC</created_at>

            <updated_at>2019-06-25 19:33:38 UTC</updated_at>

            <opted_out_at/>

            <opted_out_source/>

            <source type="API" name="User1" email="user1@domain.com"/>

            <address>

                <street1/>

                <street2/>

                <city/>

                <state/>

                <postal_code/>

                <country>US</country>

            </address>

            <last_saved_location>

                <latitude>38.906639</latitude>

                <longitude>-77.016577</longitude>

                <precision>state</precision>

                <city/>

                <state>DC</state>

                <postal_code/>

                <country>US</country>

            </last_saved_location>

            <custom_columns>

                <custom_column name="Age"/>

                <custom_column name="Favorite Animal"/>

            </custom_columns>

       <subscriptions>

    <subscription campaign_id="162xxx" campaign_name="MC_test2" campaign_description="" opt_in_path_id="" status="Active" opt_in_source="User1" created_at="2019-06-21T14:49:40Z" activated_at="2019-06-22T20:24:36Z" opted_out_at="" opt_out_source=""/>

        </subscriptions>

            <clicks>

      </clicks>

        </profile>

    </group>

</response>

For those companies with advocacy features turned on your response will also include the following districts information:

<last_saved_districts>

            <congressional_district>DC-1</congressional_district>

            <state_upper_district>DC-</state_upper_district>

           <state_lower_district>DC-</state_lower_district>

           <split_district>No</split_district>

</last_saved_districts>

 Example

curl --user yourusername:yourpassword \
https://secure.mcommons.com/api/group_members?group_id=2

Create Group

URL:

https://secure.mcommons.com/api/create_group

Protocol:

HTTP GET

Parameters:

name

Sample Response:

<?xml version="1.0" encoding="UTF-8"?>

<response success="true">

  <group id="3″ type="UploadedGroup" name="Chocolate Lovers"></group>

</response>

Example

curl --user yourusername:yourpassword \
https://secure.mcommons.com/api/create_group?name=group1

Add Group Member

URL:

https://secure.mcommons.com/api/add_group_member

Protocol:

HTTP GET

Parameters:

group_id

phone_number (can be a single phone number OR a comma-separated list to add multiple numbers -- Up to 1000 phone number per single request)

Sample Response:

<?xml version="1.0" encoding="UTF-8"?>

<response success="true">

  <group id="3″ type="UploadedGroup" name="Chocolate Lovers"></group>

</response>

Example

curl --user yourusername:yourpassword \
https://secure.mcommons.com/api/add_group_member?\
group_id=2&phone_number=5554443322

Example (multiple numbers)

curl --user yourusername:yourpassword \
https://secure.mcommons.com/api/add_group_member?\
group_id=2&phone_number=5554443322,5553331234,5552224321

Remove Group Member

URL:

https://secure.mcommons.com/api/remove_group_member

Protocol:

HTTP GET

Parameters:

group_id (Required)

phone_number (Required, can be a single phone number or a comma separated list to remove multiple numbers -- Up to 1000 numbers)

Sample Response:

<?xml version="1.0" encoding="UTF-8"?>

<response success="true">

  <group id="3″ type="UploadedGroup" name="Chocolate Lovers"></group>

</response>

Example

curl --user yourusername:yourpassword \
https://secure.mcommons.com/api/remove_group_member?\
group_id=2&phone_number=5554443322

Example (multiple numbers)

curl --user yourusername:yourpassword \
https://secure.mcommons.com/api/remove_group_member?\
group_id=2&phone_number=5554443322,5553331234,5552224321

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="34xxxxxxx">

     <first_name>John</first_name>

     <last_name>Doe</last_name>

        <phone_number>12025551234</phone_number>

        <email/>

        <status>Profiles with no Subscriptions</status>

        <created_at>2019-06-21 14:49:40 UTC</created_at>

        <updated_at>2019-06-21 14:49:40 UTC</updated_at>

        <opted_out_at/>

        <opted_out_source/>

        <source type="API" name="User1" email="user1@domain.com"/>

        <address>

            <street1/>

            <street2/>

            <city/>

            <state/>

            <postal_code/>

            <country>US</country>

        </address>

        <last_saved_location>

            <latitude>38.906639</latitude>

            <longitude>-77.016577</longitude>

            <precision>state</precision>

            <city/>

            <state>DC</state>

            <postal_code/>

            <country>US</country>

        </last_saved_location>

           <custom_columns>

            <custom_column name="Age"/>

            <custom_column name="Favorite animal"/>

            <custom_column name="Yes/NO"/>

        </custom_columns>

        <integrations>

    </integrations>

        <clicks>

    </clicks>

    </profile>

</response>

For those companies with advocacy features turned on your response will also include the following districts information:

<last_saved_districts>

            <congressional_district>DC-1</congressional_district>

            <state_upper_district>DC-</state_upper_district>

           <state_lower_district>DC-</state_lower_district>

           <split_district>No</split_district>

</last_saved_districts>

Example

curl --user yourusername:yourpassword \
https://secure.mcommons.com/api/profile?phone_number=5554443322

Profile Update

URL:

https://secure.mcommons.com/api/profile_update

Protocol:

HTTP POST

Parameters:

phone_number (Required)

email

postal_code

first_name

last_name

street1

street2

city

state

country

Custom Column (Any custom column name)

opt_in_path_id: This will subscribe the user to this campaign and send the message flow in this opt-in path. The value should be your opt-in path key.

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="34xxxxxxx">

     <first_name>John</first_name>

     <last_name>Doe</last_name>

        <phone_number>12025551234</phone_number>

        <email/>

        <status>Active subscriber</status>

        <created_at>2019-06-21 14:49:40 UTC</created_at>

        <updated_at>2019-06-21 14:49:40 UTC</updated_at>

        <opted_out_at/>

        <opted_out_source/>

        <source type="API" name="User1" email="user1@domain.com"/>

        <address>

            <street1/>

            <street2/>

            <city/>

            <state/>

            <postal_code/>

            <country>US</country>

        </address>

        <last_saved_location>

            <latitude>38.906639</latitude>

            <longitude>-77.016577</longitude>

            <precision>state</precision>

            <city/>

            <state>DC</state>

            <postal_code/>

            <country>US</country>

        </last_saved_location>

        <custom_columns>

            <custom_column name="Age"/>

            <custom_column name="Favorite animal"/>

            <custom_column name="Yes/NO"/>

        </custom_columns>
       <subscriptions>
         <subscription campaign_id="162xxx" campaign_name="MC_test2" campaign_description="" opt_in_path_id="" status="Active" opt_in_source="User1" created_at="2019-06-21T14:49:40Z" activated_at="2019-06-22T20:24:36Z" opted_out_at="" opt_out_source=""/>
</subscriptions>

        <integrations>

    </integrations>

        <clicks>

    </clicks>

For those companies with advocacy features turned on your response will also include the following districts information:

<last_saved_districts>

            <congressional_district>DC-1</congressional_district>

            <state_upper_district>DC-</state_upper_district>

           <state_lower_district>DC-</state_lower_district>

           <split_district>No</split_district>

</last_saved_districts>

Example

curl --user yourusername:yourpassword \
--data "phone_number=5554443322&email=user@gmail.com" \
https://secure.mcommons.com/api/profile_update

Profile OptOut

URL:

https://secure.mcommons.com/api/profile_opt_out

Protocol:

HTTP POST

Parameters:

phone_number (Required)

campaign_id (Opt-out this campaign only. Default is all campaigns.)

subscription_id (Opt-out this subscription only. Default is all subscriptions.)

Sample Response:

<?xml version="1.0" encoding="UTF-8"?>

<response success="true">

    <profile id="3389xxxxx">

        <first_name></first_name>

        <last_name></last_name>

        <phone_number>2025551234</phone_number>

        <email></email>

        <status>Undeliverable</status>

        <created_at>2019-04-26 19:58:54 UTC</created_at>

        <updated_at>2019-06-25 21:43:09 UTC</updated_at>

        <opted_out_at>2019-06-25 21:43:09 UTC</opted_out_at>

        <opted_out_source>Opt-out from API</opted_out_source>

        <source type="Keyword" name="call me" id="763xxx" opt_in_path_id="25xxxx" message_id="12604xxxxx"/>

        <address>

            <street1>123 Test St</street1>

            <street2>#4315</street2>

            <city>City name</city>

            <state>TX</state>

            <postal_code>76104</postal_code>

            <country>US</country>

        </address>

        <last_saved_location>

            <latitude>32.735247</latitude>

            <longitude>-97.324103</longitude>

            <precision>range_interpolation</precision>

            <city>Fort Worth</city>

            <state>TX</state>

            <postal_code>76104</postal_code>

            <country>US</country>

        </last_saved_location>

        <custom_columns>

            <custom_column name="Age"/>

            <custom_column name="TEST"/>

        </custom_columns>

        <subscriptions>

            <subscription campaign_id="162xxx" campaign_name="MC_test2" campaign_description="" opt_in_path_id="25xxx" status="Opted-Out" opt_in_source="call me" created_at="2019-04-26T19:58:54Z" activated_at="2019-04-26T19:58:54Z" opted_out_at="2019-06-25T21:43:09Z" opt_out_source="Opt-out from API"/>

        </subscriptions>

        <integrations>

    </integrations>

        <clicks>

    </clicks>

    </profile>

</response>

For those companies with advocacy features turned on your response will also include the following districts information:

<last_saved_districts>

            <congressional_district>DC-1</congressional_district>

            <state_upper_district>DC-</state_upper_district>

           <state_lower_district>DC-</state_lower_district>

           <split_district>No</split_district>

</last_saved_districts>

Example

curl --user yourusername:yourpassword \
--data "phone_number=15553334411&campaign_id=2" \
https://secure.mcommons.com/api/profile_opt_out

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 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)

Note: If you don't specify the timezone in From & To parameters, we will default to UTC.

To specify the time zone you need to pass/append the correct UTC offset to the timestamp in the API call

"from" and "to" limits will pull in updates to: first name, last name, email, address fields, custom fields, any change to the subscription status (opted in Or opted out).

phone_number (Limits the returned profiles matching the provided phone numbers. Phone numbers should be specified with country code, but we’ll recognize most formats. You can either provide a comma separated list – &phone_number=19145550000,12025550000 or as an array – &phone_number[]=19145550000&phone_number[]=12025550000)

include_custom_columns (*Optional default 'true' - allows exclusion of custom columns associated with profiles, pass 'false' to limit)

include_subscriptions (*Optional default 'true' - allows exclusion of subscriptions for each profile, pass 'false' to limit)

include_clicks (*Optional default 'true' - allows exclusion of clicks)

include_members (*Optional default 'true' - allows exclusion of profile member records maintained for integrations)

Sample Response:

<?xml version="1.0" encoding="UTF-8"?>

<response success="true">

    <profiles num="1000" page="1">

        <profile id="347xxxxxx">

            <first_name>Joe</first_name>

            <last_name>user</last_name>

            <phone_number>12025551234</phone_number>

            <email>user@yahoo.com</email>

            <status>Profiles with no Subscriptions</status>

            <created_at>2019-06-21 14:49:40 UTC</created_at>

            <updated_at>2019-06-25 19:33:38 UTC</updated_at>

            <opted_out_at/>

            <opted_out_source/>

            <source type="API" name="User1" email="user1@domain.com"/>

            <address>

                <street1></street1>

                <street2></street2>

                <city></city>

                <state></state>

                <postal_code></postal_code>

                <country>US</country>

            </address>

            <last_saved_location>

                <latitude>38.906639</latitude>

                <longitude>-77.016577</longitude>

                <precision>state</precision>

                <city/>

                <state>DC</state>

                <postal_code/>

                <country>US</country>

            </last_saved_location>

             <custom_columns>

                <custom_column name="Age"/>

                <custom_column name="Favorite animal"/>  

            </custom_columns>

      <subscriptions>

    <subscription campaign_id="162xxx" campaign_name="MC_test2" campaign_description="" opt_in_path_id="" status="Active" opt_in_source="User1" created_at="2019-06-21T14:49:40Z" activated_at="2019-06-22T20:24:36Z" opted_out_at="" opt_out_source=""/>

          </subscriptions>

            <integrations>

      </integrations>

            <clicks>

      </clicks>

        </profile>

    </profiles>

</response>

For those companies with advocacy features turned on your response will also include the following districts information:

<last_saved_districts>

            <congressional_district>DC-1</congressional_district>

            <state_upper_district>DC-</state_upper_district>

           <state_lower_district>DC-</state_lower_district>

           <split_district>No</split_district>

</last_saved_districts>

Precision Types & Description

• Address: Latitude/Longitude Conversion.
• rooftop: We found the exact point with rooftop level accuracy
• Point: We found the exact point from address range interpolation where the range contained a single point
• Range_interpolation We found the exact point by performing address range interpolation
• Street_center: The result is a geocoded street centroid
• Place: The point is a city/town/place
• State: The point is a state

Example

curl --user yourusername:yourpassword \
https://secure.mcommons.com/api/profiles

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 per page. Defaults to 20. Can not be more than 1000.)
• 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)
• Note: 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, reactivation, call_in_response, mdata_query, donation. All message types in the Inbox are supported.

Sample Response:

<?xml version="1.0" encoding="UTF-8"?>

<response success="true">

    <messages page="1" limit="20" page_count="17">

        <message id="1297356299" type="opt_out" approved="false">

            <phone_number>1650xxxxxxx</phone_number>

            <carrier_name>Verizon Wireless</carrier_name>

            <profile>33468xxxx</profile>

            <body>stop</body>

            <message_template_id>37786436</message_template_id>

            <mms>false</mms>

            <multipart>false</multipart>

            <keyword/>

            <received_at>2019-06-27 20:45:08 UTC</received_at>

            <previous_id id="6797453174"/>

            <next_id id="6897747278"/>

            <campaign id="162617" active="true">

                <name>MC_test2</name>

            </campaign>

            <profile id="33468xxxx">

                <first_name>John</first_name>

                  <last_name>Doe</last_name>

                <phone_number>1650xxxxxxx</phone_number>

                <email/>

                <status>Undeliverable</status>

                <created_at>2019-03-14 17:24:13 UTC</created_at>

                <updated_at>2019-06-27 20:45:08 UTC</updated_at>

                <opted_out_at>2019-06-27 20:45:08 UTC</opted_out_at>

                <opted_out_source>Texted a STOP word</opted_out_source>

                <source type="Uploaded Group" name="MC Test" id="402704"/>

                <address>

                    <street1/>

                    <street2/>

                    <city/>

                    <state/>

                    <postal_code/>

                    <country>US</country>

                </address>

                <last_saved_location>

                    <latitude>37.573485</latitude>

                    <longitude>-122.32253</longitude>

                    <precision>place</precision>

                    <city>San Mateo</city>

                    <state>CA</state>

                    <postal_code>94401</postal_code>

                    <country>US</country>

                </last_saved_location>

                <custom_columns>

                    <custom_column name="Age"/>

                    <custom_column name="yes-No test"/>

                </custom_columns>

                <integrations>

        </integrations>

                <clicks>

        </clicks>

            </profile>

        </message>

     </messages>

 </response>

For those companies with advocacy features turned on your response will also include the following districts information:

     <last_saved_districts>

              <congressional_district>CA-14</congressional_district>

              <state_upper_district>CA-</state_upper_district>

              <state_lower_district>CA-</state_lower_district>

              <split_district>No</split_district>

     </last_saved_districts>

 Additional Information 

• The "previous_id": Is the ID of the MT (Mobile terminated/message sent to the user) that is being replied to.
• The "next_id": Is the ID of the response (MT) we send back as a reply to that incoming message.
• If there is no "previous_id", that incoming message was not a reply to previous MT.
• If there is no “next_id”, then Mobile Commons hasn't responded yet or didn't send a response because there wasn't one.

Example

curl --user yourusername:yourpassword \
https://secure.mcommons.com/api/messages

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. Cannot be more than 1000.
• 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 page="3" limit="20" page_count="79">     

      <message id="6483711098" type="info_request" status="sent">

            <phone_number>15102xxxxxx</phone_number>

            <profile>3347xxxxx</profile>

            <body>Please reply with your full address.</body>

            <sent_at>2019-04-04 19:03:15 UTC</sent_at>

            <message_template_id>37162415</message_template_id>

            <mms>false</mms>

            <multipart>false</multipart>

            <campaign id="162xxx" active="true">

                <name>MC_test2</name>

            </campaign>

            <previous_id id="12493xxxxx"/>

            <next_id id="12493xxxxx"/>

        </message>

    </messages>

</response>

 Additional Information

• The "previous_id": Is the ID of the MO (Mobile originated/message came in from the user) that is being replied to.
• The "next_id": is the ID of the response/Reply (MO) we receive back from the user to that outgoing message.
• If there are no "previous_id", that outgoing message was not a reply to an incoming message.
• If there is no “next_id”, depending on when the results are pulled, the end user hasn't replied yet or didn't send a response because it wasn't needed.

Example

curl --user yourusername:yourpassword \
https://secure.mcommons.com/api/sent_messages

Send SMS Message

URL:

https://secure.mcommons.com/api/send_message

Protocol:

HTTP POST

Parameters

campaign_id

body (160 characters or fewer. If passing body as a URL param, the value must be URL encoded)

phone_number (required)

attachment_id (optional, allows you to include an attachment already uploaded in your platform)

previous_id (optional, links to previous message)

Sample Response:

<?xml version="1.0" encoding="UTF-8"?>
<response success="true">
  <message id="1029384756" type="generic" status="queued">
    <phone_number>12025554259</phone_number>
    <profile>170357741</profile>
    <body>Welcome from an SMS!</body>
    <sent_at>2018-11-21 14:29:44 UTC</sent_at>
    <message_template_id/>
    <campaign id="123" active="true">
      <name>Welcome Campaign</name>
    </campaign>
    <tags>
    </tags>
  </message>
</response>

Example

curl --user yourusername:yourpassword \
--data "campaign_id=2&body=Welcome&phone_number=15554443322" \
https://secure.mcommons.com/api/send_message

Send MMS Message

URL:

https://secure.mcommons.com/api/send_mms

Protocol:

HTTP POST

Parameters:

campaign_id
body (1600 characters or fewer. If passing body as a URL param, the value must be URL encoded)

phone_number

attachment_id (*Optional id of attachment to be included with the message)

uploaded_attachment (*Optional multi-part supported image to be sent)

Sample Response:

<?xml version="1.0" encoding="UTF-8"?>
<response success="true">
  <message id="1029384786" type="generic" status="queued">
    <phone_number>12025554259</phone_number>
    <profile>170357741</profile>
    <body>Welcome from an MMS!</body>
    <sent_at>2018-11-21 14:39:44 UTC</sent_at>
    <message_template_id/>
    <campaign id="123" active="true">
      <name>Welcome Campaign</name>
    </campaign>
    <tags>
    </tags>
  </message>
</response>

Example

curl --user yourusername:yourpassword \
--data "campaign_id=2&body=Welcome&phone_number=15554443322" \
https://secure.mcommons.com/api/send_mms

curl --user yourusername:yourpassword \
--form "uploaded_attachment=@image-to-upload.jpg" \
--form "campaign_id=2" \
--form "body=Welcome MMS" \
--form "phone_number=15554443322" \
https://secure.mcommons.com/api/send_mms

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:

<?xml version="1.0" encoding="UTF-8"?>

<response success="true">

  <broadcast id="456">

</response>

Notes:

Broadcasts are considered immediate unless you add the “time=” parameter

Example

curl --user yourusername:yourpassword \
--data "campaign_id=2&body=Welcome&time=2016-12-31T12:34:56" \
https://secure.mcommons.com/api/schedule_broadcast

Reschedule a Broadcast

URL:

https://secure.mcommons.com/api/reschedule_broadcast

Protocol:

HTTP POST

Parameters:

broadcast_id

time (Optional, in ISO-8601 format, e.g. 2008-12-31T12:34:56)

Sample Response:

<?xml version="1.0" encoding="UTF-8"?>

<response success="true">

  <broadcast id="456">

</response>

Example

curl --user yourusername:yourpassword \
--data "broadcast_id=2&time=2016-12-31T12:34:56" \
https://secure.mcommons.com/api/reschedule_broadcast

Unschedule a Broadcast

URL:

https://secure.mcommons.com/api/unschedule_broadcast

Protocol:

HTTP POST

Parameters:

broadcast_id

Sample Response:

<?xml version="1.0" encoding="UTF-8"?>

<response success="true">

  <broadcast id="456">

</response>

Example

curl --user yourusername:yourpassword \
--data "broadcast_id=2&body=Welcome&time=2016-12-31T12:34:56" \
https://secure.mcommons.com/api/unschedule_broadcast

List Broadcasts

URL:

https://secure.mcommons.com/api/broadcasts

Protocol:

HTTP GET

Parameters:

• campaign_id (Optional): scope broadcasts to just a single campaign.
• status (optional): filter by the broadcast status (draft, scheduled, or generated)
• start_time (Date - ISO-8601 format): Limit the broadcasts to the ones with delivery date On and after the provided date.
• end_time (Date - ISO-8601 format): Limit the broadcasts to the ones with delivery date On and before the provided date. (The start_time and end_time for this endpoint are designed to be used together to limit the results to that interval. If one of them is used separately, we will pull the broadcasts sent on the provided date only).
• Page (number): Specify which page of the total number of pages to return. We show the total count of pages and the current page number in the XML response.
• Limit (number): Control the number of records to return per page. The default is 20 broadcasts per page, Max is 1000.

Sample Response:

<?xml version="1.0" encoding="UTF-8"?>

<response success="true">

    <broadcasts page="1" limit="100" page_count="1">

        <broadcast id="123456" status="generated">

            <name>TEST broadcast</name>

            <body>This is the broadcast body</body>

            <campaign id="1234" active="true">

                <name>Test Campaign</name>

            </campaign>

            <delivery_time>2019-11-17 12:29:40 UTC</delivery_time>

            <include_subscribers>false</include_subscribers>

            <throttled>false</throttled>

            <localtime>false</localtime>

            <automated>false</automated>

            <estimated_recipients_count>3</estimated_recipients_count>

            <replies_count>0</replies_count>

            <opt_outs_count>0</opt_outs_count>

            <included_groups>

                <group name="MC_TEST" id="54321" type="FilteredGroup">

                  </group>

            </included_groups>

            <excluded_groups>           

            </excluded_groups>

            <tags>

                <tag>tes@test.com</tag>

            </tags>

        </broadcast>

    </broadcasts>

</response>

Example

curl --user yourusername:yourpassword \
https://secure.mcommons.com/api/broadcasts?campaign_id=2

List Broadcast

URL:

https://secure.mcommons.com/api/broadcast

Protocol:

HTTP GET

Parameters:

broadcast_id (required)

Sample Response: 

<?xml version="1.0" encoding="UTF-8"?>
<response success="true">
  <broadcast id="1270085" status="generated">
   <name>Broadcast 05/19/2017 03:55PM Message Name</name>
   <body>
     Your message content here.
   </body>
   <campaign id="123456" active="true">
     <name>My Campaign</name>
   </campaign>
   <delivery_time>2017-05-19 19:59:16 UTC</delivery_time>
   <include_subscribers>false</include_subscribers>
   <throttled>false</throttled>
   <localtime>false</localtime>
   <automated>false</automated>
   <replies_count>231</replies_count>

   <opt_outs_count>12</opt_outs_count>

   <estimated_recipients_count>1</estimated_recipients_count>
   <included_groups>
     <group name="just a group name" id="123456" type="FilteredGroup"></group>
   </included_groups>
   <excluded_groups></excluded_groups>
   <tags></tags>
</broadcast>
</response>

Example

curl --user yourusername:yourpassword \
https://secure.mcommons.com/api/broadcast?broadcast_id=1234

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)

include_profile_id_only (optional, if not provided all profile details will be returned instead of just restricting it to profile id)

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:

<?xml version="1.0" encoding="UTF-8"?>
<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>

Example

curl --user yourusername:yourpassword \
https://secure.mcommons.com/api/calls

Count the number of mConnect Calls

URL:

https://secure.mcommons.com/api/call_count

Protocol:

HTTP GET

Parameters:

mconnect_id

Sample Response:

<?xml version="1.0" encoding="UTF-8"?>

<response success="true">

  <call_count>255</call_count>

</response>

Example

curl --user yourusername:yourpassword \
https://secure.mcommons.com/api/call_count

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:

<?xml version="1.0" encoding="UTF-8"?>

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

Example

curl --user yourusername:yourpassword \
https://secure.mcommons.com/api/donation_summary

List Web Clicks

URL:

https://secure.mcommons.com/api/clicks

Protocol:

HTTP GET

Parameters:

url_id OR url: required, the id of the URL or the actual shortened URL itself with URL encoding.

page: optional, specifies which page, of the total number of pages of results, to return.

From: optional, limits the results to ones that ended after or on this date time. ISO-8601 format)

To: optional, limits the results to ones that ended before or on this date time. ISO-8601 format)

include_profile: optional, adds phone number and profile details to response. Default is false for performance reasons.

total_link_clicks: optional, provides the total link clicks. Default is false.

Sample Response:

Sample response for total_link_clicks=true:

1<response success="true">

2  <clicks total_link_clicks="100" unique="15"> </clicks>

3</response>

Sample response for total_link_clicks=false which is the default:

<?xml version="1.0" encoding="UTF-8"?>

<response success="true">

  <clicks num="1" unique="1" page="1">

    <click id="123">

      <created_at>2012-04-10 21:35:29 UTC</created_at>

      <url>http://www.example.com/</url>

      <clicked_url>http://lil.ms/1</clicked_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>

      <profile_id>123456</profile_id>

    </click>

  </clicks>

</response>

Example

curl --user yourusername:yourpassword \
https://secure.mcommons.com/api/clicks

List mConnects

URL:

https://secure.mcommons.com/api/mconnects

Protocol:

HTTP GET

Parameters:

None

Sample Response:

<?xml version="1.0" encoding="UTF-8"?>
<response success="true">
  <mconnects>
    <mconnect id=“1234” active="false">
      <name>Call your State Senator</name>
      <destination_number/>
      <destination_description></destination_description>
      <tags>
        <tag>Tag Name Here</tag>
      </tags>
      <voip_number/>
      <call_type>autoroute</call_type>
      <autoroute>true</autoroute>
      <subscriber_followup></subscriber_followup>
      <nonsubscriber_followup></nonsubscriber_followup>
      <call_timeout>120</call_timeout>
      <failover_number></failover_number>
      <failover_text></failover_text>
      <voicemail>false</voicemail>
      <transcribe>false</transcribe>
      <shortcode>654321</shortcode>
    </mconnect>
    <mconnect id=“213” active="true">
      <name>Call Congress English</name>
      <destination_number/>
      <destination_description></destination_description>
      <voip_number/>
      <call_type>autoroute</call_type>
      <autoroute>true</autoroute>
      <subscriber_followup>Thank you for calling. If you'd like to join our list, please reply first_name</subscriber_followup>
      <nonsubscriber_followup></nonsubscriber_followup>
      <call_timeout>120</call_timeout>
      <failover_number></failover_number>
      <failover_text></failover_text>
      <voicemail>true</voicemail>
      <transcribe>false</transcribe>
      <shortcode>654321</shortcode>
      <crm_alert_id>54321</crm_alert_id>
    </mconnect>
  </mconnects>
</response>

Example

curl --user yourusername:yourpassword \
https://secure.mcommons.com/api/mconnects

List Tinyurls

URL:

https://secure.mcommons.com/api/tinyurls

Protocol:

HTTP GET

Parameters:

None

Sample Response:

<?xml version="1.0" encoding="UTF-8"?>
<response success="true">
  <tinyurls num="199">
    <tinyurl id="267510">
      <created_at>2015-09-16 15:23:42 UTC</created_at>
      <name>Test Link</name>
      <mode>redirect</mode>
      <url>http://www.q4kidz.org</url>
      <host>lil.ms</host>
      <description></description>
      <key>v6m</key>
    </tinyurl>
    <tinyurl id="269090">
      <created_at>2015-09-25 20:58:17 UTC</created_at>
      <name>http://lil.ms/vry</name>
      <mode>redirect</mode>
      <url>http://is.gd/m8edsm</url>
      <host>lil.ms</host>
      <description/>
      <key>vry</key>
    </tinyurl>
  </tinyurls>
</response>

Example

curl --user yourusername:yourpassword \
https://secure.mcommons.com/api/tinyurls

Add Tag

URL:

https://secure.mcommons.com/api/add_tag

Protocol:

HTTP GET

Parameters:

tag: name of tag (Required)

At least one parameter from the list below is required:

campaign_id: optional, may be a single or an array of campaign ids to be tagged
opt_in_path_id: optional, may be a single or an array of opt_in_path ids to be tagged
mconnect_id: optional, may be a single or an array of mconnect ids to be tagged
broadcast_id: optional, may be a single or an array of broadcast ids to be tagged

Sample Response:

<?xml version="1.0" encoding="UTF-8"?>
<response success="true">
  <tags id="9" name="tag5" count="3">
    <tag id="226" name="test campaign flow" type="Campaign"/>
    <tag id="3" name="test tagging" type="mConnect"/>
    <tag id="5" name="Broadcast 05/28/2017 02:57AM copy" type="Broadcast"/>
  </tags>
</response>

Example

curl --user yourusername:yourpassword \
https://secure.mcommons.com/api/add_tag

Remove Tag

URL:

https://secure.mcommons.com/api/remove_tag

Protocol:

HTTP GET

Parameters:

tag: name of tag (Required)

At least one parameter from the list below is required:

campaign_id: optional, may be a single or an array of campaign ids to be tagged
optin_path_id: optional, may be a single or an array of opt_in_path ids to be tagged
mconnect_id: optional, may be a single or an array of mconnect ids to be tagged
broadcast_id: optional, may be a single or an array of broadcast ids to be tagged

Sample Response:

<?xml version="1.0" encoding="UTF-8"?>
<response success="true">
  <tags id="9" name="tag5" count="3">
    <tag id="226" name="test campaign flow" type="Campaign"/>
    <tag id="3" name="test tagging" type="mConnect"/>
    <tag id="5" name="Broadcast 05/28/2017 02:57AM copy" type="Broadcast"/>
  </tags>
</response>

Example

curl --user yourusername:yourpassword \
https://secure.mcommons.com/api/remove_tag

List Tags

URL:

https://secure.mcommons.com/api/tags

Protocol:

HTTP GET

Parameters:

type: Filter by Object type taggable ( campaign, broadcast, opt_in_path, mconnect )

campaign_id: List all tags on a specific campaign

broadcast_id: List all tags on a specific broadcast

opt_in_path_id: List all tags on a specific opt in path

mconnect_id: List all tags on a specific mconnect

tag_id: List all things tagged with this specific tag ID

tag: Filter to objects tagged by the tag_name

Sample Response:

<?xml version="1.0" encoding="UTF-8"?>
<response success="true">
  <tags>
    <tag id="4" name="my tag">
      <taggable>
        <object id="223" type="Campaign"/>
      </taggable>
    </tag>
    <tag id="5" name="tag1">
      <taggable>
        <object id="3" type="mConnect"/>
        <object id="1" type="Broadcast"/>
      </taggable>
    </tag>
    <tag id="6" name="tag2">
      <taggable>
        <object id="223" type="Campaign"/>
        <object id="1" type="Broadcast"/>
        <object id="226" type="Campaign"/>
        <object id="22" type="OptInPath"/>
      </taggable>
    </tag>
  </tags>
</response>

Example

curl --user yourusername:yourpassword \
https://secure.mcommons.com/api/tags

Campaign Opted In

URL:

https://secure.mcommons.com/api/campaign_opted_in

Protocol:

HTTP GET

Parameters:

campaign_id (Required): Integer corresponding to the Mobile Commons Campaign the subscriber is being opted in to

phone_number (Required): The mobile device number of the subscriber being opted in

Sample Response:

<?xml version="1.0" encoding="UTF-8"?>

<response success="true">

    <result>true</result>

</response>

Example

curl --user yourusername:yourpassword \
https://secure.mcommons.com/api/campaign_opted_in?\
campaign_id=3234&phone_number=5554443322

Custom Column Value

URL:

https://secure.mcommons.com/api/custom_column_value

Protocol:

HTTP GET

Parameters:

phone_number (Required): The mobile device number of the subscriber wherein we want to pull the custom field from

key(Custom column name): The string (1+ characters) name of the custom field to pull the value of

Sample Response:

<?xml version="1.0" encoding="UTF-8"?>

<response success="true">

    <value>John</value>

</response>

Example

curl --user yourusername:yourpassword \
https://secure.mcommons.com/api/custom_column_value?\
phone_number=5554443322&key=first_name

Attachments

URL:

https://secure.mcommons.com/api/attachments

Protocol:

HTTP GET

Parameters:

None

Sample Response:

<?xml version="1.0" encoding="UTF-8"?>

<response success="true">

    <attachments>

        <attachment>

            <id>1</id>

            <name>diag</name>

            <thumbnail_link>http://secure.mcommons.com/attachments/143543/display?size=small</thumbnail_link>

        </attachment>

        <attachment>

            <id>10</id>

            <name>name</name>

            <thumbnail_link>http://secure.mcommons.com/attachments/167345/display?size=small</thumbnail_link>

        </attachment>

    </attachments>

</response>

Example

curl --user yourusername:yourpassword \
https://secure.mcommons.com/api/attachments

Upload Attachment

URL:

https://secure.mcommons.com/api/upload_attachment

Protocol:

HTTP POST

Parameters:

• name, used to set a friendly name of the uploaded attachment, defaults to filename if left empty (optional)
• uploaded_attachment, multipart/form-data encoded attachment file (required)

Sample Response:

<?xml version="1.0" encoding="UTF-8"?>

<response success="true">

        <attachment>

            <id>31</id>

            <name>Sunris</name>
 

<thumbnail_link>http://secure.mcommons.com/attachments/31/display?size=small</thumbnail_link>

        </attachment>    

</response>

Example

curl --user yourusername:yourpassword --form "uploaded_attachment=@morning_sunrise.jpg" --form "name=Sunrise" https://company.mcommons.com/api/upload_attachment

Edit Attachment

URL:

https://secure.mcommons.com/api/edit_attachment

Protocol:

HTTP GET

Parameters:

• attachment_id, ID of the attachment to be edited (required)
• name, a friendly name for the attachment (required

Sample Response:

<?xml version="1.0" encoding="UTF-8"?>

<response success="true">

    <attachment>

        <id>19</id>

        <name>First Dogger</name>

        <thumbnail_link>http://company.mcommons.com/attachments/19/display?size=small</thumbnail_link>

    </attachment>

</response>

Example

curl --user yourusername:yourpassword 'https://company.mcommons.com/api/edit_attachment?attachment_id=19&name=First%20Dogger'

Archive Attachment

URL:

https://secure.mcommons.com/api/archive_attachment

Protocol:

HTTP GET

Parameters:

• attachment_id, ID of the attachment to archive (required)

Sample Response:

<?xml version="1.0" encoding="UTF-8"?>

<response success="true">

Example

curl --user yourusername:yourpassword 'https://company.mcommons.com/api/archive_attachment?attachment_id=18'

Clear Conversation

URL:

https://secure.mcommons.com/api/clear_conversation

Protocol:

HTTP POST

Parameters:

campaign_id (Required): Integer corresponding to the Mobile Commons Campaign. If the subscriber is in a conversation (info request, mid-message list, etc..), this conversation will be cleared.

phone_number (Required): The mobile device number of the subscriber we want to clear the conversation for

Sample Response:

<?xml version="1.0" encoding="UTF-8"?>

<response success="true"/>

Example

curl --user yourusername:yourpassword \
--data "campaign_id=2&phone_number=15554443322" \
https://secure.mcommons.com/api/clear_conversation

mData Entries

URL:

https://secure.mcommons.com/api/mdata_entries

Protocol:

HTTP GET

Parameters:

mdata_id (Required) - ID of mData to retrieve entries for, input (Required) - content of ‘input’ column for an mData that requires a CSV upload or manual entry, non-Web Service mDatas. Requires input is an exact match, does not do fuzzy search.

Sample Response:

<?xml version="1.0" encoding="UTF-8"?>
<response success="true">
<mdata_entries>
   <mdata_entry>
     <id>24540398</id>
     <mdata_id>14333</mdata_id>
     <input>california</input>
     <output>The population of California is 36,457,549</output>
     <created_at>2017-03-27 17:43:11 UTC</created_at>
   </mdata_entry>
</mdata_entries>
</response>

Example

curl -- user yourusername:yourpassword \
https://secure.mcommons.com/api/mdata_entries?\
mdata_id=123456&input=brooklyn

Trigger mData

URL:

https://secure.mcommons.com/api/trigger_mdata

Protocol:

HTTP GET

Parameters:

mdata_id (Required) - ID of mData to trigger, phone_number (Required) - phone number of the recipient to receive MT, args (Required only if mData requires it) - body of simulated MO to trigger mData

Sample Response:

<?xml version="1.0" encoding="UTF-8"?>
<response success="true"/>

Example

curl -- user yourusername:yourpassword \
https://secure.mcommons.com/api/trigger_mdata?\
mdata_id=123456&phone_number=5554443322&args=ZOOM

Profile Update Attribute

URL:

https://secure.mcommons.com/api/profile_update_attribute

Protocol:

HTTP POST

Parameters:

phone_number: required, if phone doesn't exist we'll return an error, this will not create new phone/profile

attribute: required,  first_name, last_name, email, all address fields, constituent_id, custom fields; one at a time.

attribute_value: required, will validate when sending in against the format of the field (please see our article on custom fields and mail merge fields)

save_behavior: required,  must include either always_create or create_if_key_value_not_exists

• always_create: will set value whether or not anything exists in that field
• create_if_key_value_not_exists: will look for custom columns/attributes if it returns nill then it will update that value; will not create a new custom column

Sample Response:

<?xml version="1.0" encoding="UTF-8"?>

<response success="true">

    <profile id="3477xxxx">

        <first_name>Bassel</first_name>

        <last_name>user</last_name>

        <phone_number>12025551234</phone_number>

        <email>user@yahoo.com</email>

        <status>Active Subscriber</status>

        <created_at>2019-06-21 14:49:40 UTC</created_at>

        <updated_at>2019-06-25 22:38:50 UTC</updated_at>

        <opted_out_at/>

        <opted_out_source/>

        <source type="API" name="User1" email="user1@domain.com"/>

        <address>

            <street1></street1>

            <street2></street2>

            <city></city>

            <state></state>

            <postal_code></postal_code>

            <country>US</country>

        </address>

        <last_saved_location>

            <latitude>38.906639</latitude>

            <longitude>-77.016577</longitude>

            <precision>state</precision>

            <city/>

            <state>DC</state>

            <postal_code/>

            <country>US</country>

        </last_saved_location>

        <custom_columns>

            <custom_column name="Age"/>

            <custom_column name="contact_NYC"/>

            <custom_column name="Test"/>

        </custom_columns>

    <subscriptions>

      <subscription campaign_id="4015xx" campaign_name="test_campaign" campaign_description="test campaign" opt_in_path_id="" status="Opted-Out" opt_in_source="f12" created_at="2016-02-11T18:38:23Z" activated_at="2019-06-22T18:38:23Z" opted_out_at="" opt_out_source=""/>

    </subscriptions>

    <integrations>

        <integrations>

    </integrations>

        <clicks>

    </clicks>

    </profile>

</response>

For those companies with advocacy features turned on your response will also include the following districts information:

<last_saved_districts>

            <congressional_district>DC-1</congressional_district>

            <state_upper_district>DC-</state_upper_district>

           <state_lower_district>DC-</state_lower_district>

           <split_district>No</split_district>

</last_saved_districts>

Example

curl -- user yourusername:yourpassword \
https://secure.mcommons.com/api/profile_update_attribute?\
phone_number=2125552023&attribute=counter&attribute_value=1&\
save_behavior=always_create

List mData

URL:

https://secure.mcommons.com/api/mdatas

Protocol:

HTTP GET

Parameters:

None

Sample Response:

<?xml version="1.0" encoding="UTF-8"?>

<response success="true">

  <mdatas>

    <mdata>

      <id>1</id>

      <name>First mData</name>

      <type>database</type>

      <uuid>MD8C3CEDCF3B2A55F8170B8B31DE97639E</uuid>

    </mdata>

    <mdata>

      <id>11</id>

      <name>Web mData</name>

      <type>web_service</type>

      <uuid>MDAC9F4FB6754AF86B2108E07A4F5DE63E</uuid>

    </mdata>

  </mdatas>

</response>

Example

curl --user yourusername:yourpassword \
https://secure.mcommons.com/api/mdata

List mData Queries

URL:

https://secure.mcommons.com/api/mdata_queries

Protocol:

HTTP GET

Parameters:

mdata_id (required)

from (limits returned queries to ones created after or on this date. ISO‌-8601 format)

to (limits returned queries to ones created before or on this date. ISO‌-8601 format)

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

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

include_custom_columns (default true, if set to false no custom columns/values will be returned)

Sample Response:

<?xml version="1.0" encoding="UTF-8"?>

 <response success="true">

 <mdata name="mdata 5440" id="4667" type="database">

  <queries page="1" limit="100" page_count="1">

   <query>

    <created_at>2018-07-26 16:26:45 UTC</created_at>

    <keyword/>

    <input>zjgbs5 gdfetw</input>

    <output>There were no results for your search</output>

    <result>error_response</result>

    <error_log_body/>

    <query_location>

      <street1/>

      <city/>

      <state/>

      <postal_code/>

      <country/>

      <latitude/>

      <longitude/>

     </query_location>

     <profile>

      <status>Active Subscriber</status>

      <email>hhussein@uplandsoftware.com</email>

      <first_name>Hager</first_name>

      <last_name>kom</last_name>

      <source_type>Keyword</source_type>

      <source_name>poor</source_name>

      <phone>

       <phone_number>16505548381</phone_number>

       <carrier_name>Verizon Wireless</carrier_name>

      </phone>

      <address>

        <street1>218 Guernsey St</street1>

        <street2>Apt 1</street2>

        <city>brooklyn</city>

        <state>CA</state>

        <postal_code>11222</postal_code>

        <country>US</country>

        <latitude>40.728088</latitude>

        <longitude>-73.955134</longitude>

        <geocoded_city>Brooklyn</geocoded_city>

        <geocoded_state>NY</geocoded_state>

        <geocoded_postal_code>11222</geocoded_postal_code>

        <geocoded_country>US</geocoded_country>

       </address>

       <custom_columns>

        <custom_column name="age"> 77 </custom_column>

        <custom_column name="Anniversary Test"> </custom_column>

        <custom_column name="Birthday"> </custom_column>

        <custom_column name="Counter"> </custom_column>

        <custom_column name="custom_date"> </custom_column>

        <custom_column name="CustomColumn1"> j </custom_column>

        <custom_column name="earlier_or_later"> </custom_column>

        <custom_column name="favorite animal"> </custom_column>

        <custom_column name="Favorite Color"> zjgbs5 Brown </custom_column>

        <custom_column name="language"> English </custom_column>

        <custom_column name="Sent Birthday Inventation"> </custom_column>

        <custom_column name="time"> </custom_column>

        <custom_column name="yes_no"> </custom_column>

       </custom_columns>

      </profile>

     </query>

   </queries>

  </mdata>

 </response>

Example

curl --user yourusername:yourpassword \ https://secure.mcommons.com/api/mdata_queries?mdata_id=101

"clear_request"

User texted a CLEAR keyword

"call_in_response”

User texted a response that triggered an mConnect

"call_in"

User texted a response that triggered an mConnect after already doing so at least 1x other time

"deactivation"

User texted "stop all", this is a carrier required delineation

"direct_response”

User texted a reply to a 1-1, chat or agent-view message

"donation_confirmation"

User confirmed a donation

"donation_decline"

User declined a donation

"donation_response"

User replied to a mobile giving broadcast

"donation"

User texted a donation keyword

"duplicate_opt_in"

User texted an opt-in keyword or phrase multiple times

"ftaf_opt_in_confirmation"

User, beta, confirmed tell a friend opt-in

"ftaf_opt_in_declination"

User, beta, declined tell a friend opt-in

"ftaf_response"

User responded toa  taf prompt; ALPHA or referrer responses

"help_request"

User texted a HELP keyword

"info_response"

User texted a response to a broadcast request that was saving a response

"invalid_call_in_response"

User texted something other than the specific format we were looking for to trigger an mConnect

"invalid_donation_response"

User texted in a response to a donation request with something other than a confirmation or declination

"invalid_ftaf_response"

User, ALPHA,  responded to a TAF prompt with something other than phone numbers

"invalid_info_response"

User texted in something other than the specifically formatted type of response we were looking for

"invalid_mdata_query"

User texted in an mdata query in a format other than the one we were looking for

"invalid_question_response"

User texted in something other than the specifically formatted type of response we were looking for in a question prompt

"mdata_query"

User texted in a messages that queried an mData

"opt_in_confirmation"

User texted in a confirmation to a double opt-in

"opt_in_declination"

User texted in a decline word to a double opt-in

"opt_in"

User texted a keyword that allowed them to 

"opt_out"

User texted a STOP keyword

"question_response"

User texted a response that is being saved as a question response to an MT

"reactivation"

User texted in Oops to re-join

"reply"

User texted a reply to an MT

"simultaneous"

Two duplicate MOs arrived at the same time; we process the second (duplicate one) with this type

"unknown_help_request"

User texted a help keyword but we don't know what campaign they are texting into

"unknown_opt_out"

User texted a stop keyword but we don't know what campaign they are texting into

"unknown"

User texted a message but we can't determine the campaign it belongs to, or user texted a reactivation keyword multiple times

"unmatched"

User texted a message that the platform wasn’t looking for and the platform has unmatched messaging turned on

"regular_text"

Sent regular MT

"info_request"

Sent MT that is looking for an info reply

"call_in_request"

Sent MT that is looking for a reply to trigger a phone call

"mdata_request"

Sent MT that is looking for a reply to trigger an mData

"donation_request"

Sent MT that is looking for a reply to donat

"opt_in_request"

Sent MT that is looking for a reply to opt-in

"ftaf_request"

Sent MT that is looking for a TAF response

"ftaf_opt_in_request"

Sent MT that is looking for a TAF opt-in

"question"

Sent MT that is looking for a question type response

"direct_message"

Sent MT that is looking for a response to a 1-1, chat or agent view message

"opt_in_confirmation"

Sent MT requesting an opt-in comfirmation

"clear_response"

Sent MT confirming a clear request

"help_response"

Sent MT with help content

"opt_out_receipt"

Sent MT confirming an opt-out

"mdata_response"

Sent MT that is an mData response

"persistent_mdata_response"

Sent MT that is an mData response, sent as response to any request when a persistent mData is turned on

"t_and_c_message"

Sent MT that is a terms and conditions message

"donation_confirmation"

Sent MT after receipt of donation confirmation

"donation_approved"

Sent MT after receipt of donation approval

"donation_declined"

Sent MT when donation was declined

"donation_exceeded"

Sent MT when donation was exceeding amount

"donation_failure"

Sent MT when donation failed

"donation_unconfirmed"

Sent MT when donation was never confirmed

"duplicate_subscription_notification"

Sent MT in response to a user trying to opt in to the same keyword multiple times when the opt-in path has this message turned on

Initial

The message is generated but it's not yet pushed to the queue to be sent.

Queued

The message has been pushed to the queue and is being forwarded to the aggregator (Our gateway to the carrier)

Undeliverable

We can’t get this out because either the status changed to opted-out or something happened at the carrier level and was unable to deliver the message.

Failed Permanently

When we attempt to send the message and we receive an un-retriable error from the aggregator due to the phone/carrier status.

Sent

The message was delivered successfully to the phone.

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 Key

11

Phone is not opted-in 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

21

Invalid attachment

22

Invalid broadcast id

23

Invalid broadcast state change

24

Broadcast has not been sent. Can not retrieve recipients.

25

Message Template was mdata_request but campaign is not an mData

26

Invalid user id

27

API rate limit exceeded

28

Missing phone_number parameter

29

Invalid profile item save behavior

30

Invalid profile attributes

31

Invalid previous id

32

Invalid tag name

33

Invalid tag parameters

34

Invalid shortcode id

35

Invalid date range

36

Invalid scheduled_message_id

37

Message has already been sent