Phone2Action API


Author: Johnny Reading
Contact: jreading@phone2action.com
Current API Version: 2.2.0
Documentation Version 2.2.2
Created: 2013-05-03
Modified: 2019-07-23

Authentication

Important All requests to all endpoints on the Phone2Action API must be authenticated using HTTP Basic Auth and your app ID and key.
Use those identifers as shown to the right in every request you make to the API.
All requests must also be made over HTTPS. You will receive a 403 error if you attempt to make a request via HTTP.

  1. $ curl https://api.phone2action.com/2.0/advocates
  2. -u APP_ID:APP_KEY

Create an advocate

This endpoint will create a contact under your Phone2Action account and (optionally) assign it to one or more campaigns. While certain fields aren't required, they are recommended. Enabling them will improve delivery to the webforms of targeted legislators.

Argument Description
campaigns array containing numeric campaign IDs (required)
One or more campaigns to which to add this contact
prefix string (recommended)
The contact's prefix (Mr., Mrs., Ms., Dr., etc)
firstname string (recommended)
The contact's first name
lastname string (recommended)
The contact's last name
email string (recommended -- one of email or phone IS required.)
The contact's email address (checked for format validity)
phone positive integer, 10 digits (U.S. only) (recommended -- one of email or phone IS required.)
The contact's phone number
address1 string (recommended)
The first line of the contact's street address (house number and street)
for example: 1800 Baltimore Avenue
zip5 positive integer, 5 digits (recommended)
The contact's five-digit ZIP code
message string (recommended)
(legislator email campaigns only) The advocate's message to their legislator(s).
guests positive integer, 5 digits (optional)
(RSVP campaigns only) The total number of guests attending, including the person registering.
guestNames array of strings, max 100 characters each (optional)
For all additional guests (beyond the person registering), the names of each.
smsOptin positive integer, 1 or 0 (optional)
You must include a valid phone number (phone) and campaign ID (campaigns[]) in the request.
Opts this contact in to receive future text messages.

smsOptinConfirmed positive integer, 1 or 0 (optional)
You must include the sms opt in parameter (smsOptin) in the request. If set to 1, a SMS opt in confirmation text will not be sent and the phone will be considered opted in to all future text messaging.

Not available for all accounts. Please contact your Phone2Action customer success manager in order to obtain access.
emailOptin positive integer, 1 or 0 (optional)
You must include a valid email address (email) and campaign ID (campaigns[]) in the request.
Opts this contact in to receive future email messages.
smsOptout positive integer, 1 or 0 (optional)
You must include a valid phone number (phone) and campaign ID (campaigns[]) in the request.
Opts this advocate out from future text messages.

Once an advocate has been opted out from text messaging, they cannot be opted back in.
emailOptout positive integer, 1 or 0 (optional)
You must include a valid email address (email) and campaign ID (campaigns[]) in the request.
Opts this advocate out from future email messages. An advocate can be opted back in to email messaging by using the emailOptin parameter set to 1 in an update request (see below).
p2asource string (optional)
The source tag of the advocate, which indicates the source of the advocate and how they joined the campaign. You can view the source of an advocate in the advocate's profile.
utm_source string (optional)
The UTM source tag of the advocate.
utm_medium string (optional)
The UTM medium tag of the advocate, used to identify the specific content medium that acquired the advocate.
utm_campaign string (optional)
The UTM campaign tag of the acquired advocate, used to track a campaign at a higher level.
utm_term string (optional)
The UTM term tag of the acquired advocate, used to track a keyword campaign's performance.
utm_content string (optional)
The UTM content tag of the acquired advocate, typically used to identify what specifically was clicked to acquire the advocate's information, such as a banner ad or a text link.

Definition

POST https://api.phone2action.com/2.0/advocates

Example Request

$  curl https://api.phone2action.com/2.0/advocates \
   -u APP_ID:APP_KEY \
   -d "campaigns[]=998" \
   -d "campaigns[]=999" \
   -d "firstname=Patrick" \
   -d "lastname=Smith" \
   -d "email=patrick@phone2action.com" \
   -d "phone=8165551234
                              
                              " \
   -d "address1=1800 Baltimore Avenue" \
   -d "zip5=64108" \
   -d "smsOptin=1" \
   -d "emailOptin=1" \
   -X POST

Example Response

{
  "success":1,
  "error":null,
  "type":"create",	
  "advocateid":19302020
}

Update an advocate

In order to update an existing advocate in your account, you must include the advocateid parameter in the request.

All other fields are otherwise optional. However, if you want the advocate to be subscribed via smsOptin and include that as a parameter, then you must include a phone number (phone) and campaign ID (campaigns[]). If you want the advocate to be subscribed via emailOptin, then you must include an email address (email) and campaign ID (campaigns[]).

Specifying other available fields that alredy exist for the advocate (for instance, specifying firstname in the update request when the advocate already has firstname defined) will overwrite the old information with the new information.

Argument Description
advocateid positive integer (required)
The Phone2Action id of an existing advocate. However, if you want the advocate to be subscribed via smsOptin, then you must include a phone number (phone) and campaign ID (campaigns[]). If you want the advocate to be subscribed via emailOptin, then you must include an email address (email) and campaign ID (campaigns[]).
campaigns array containing numeric campaign IDs (only required if smsOptin or emailOptin is included, otherwise optional)
One or more campaigns to which to add this contact
prefix string (optional)
The contact's prefix (Mr., Mrs., Ms., Dr., etc)
firstname string (optional)
The contact's first name
lastname string (optional)
The contact's last name
email string (optional, but is required if emailOptin is included.)
The contact's email address (checked for format validity)
phone positive integer, 10 digits (U.S. only) (optional, but is required if smsOptin is included.)
The contact's phone number
address1 string (optional)
The first line of the contact's street address (house number and street)
for example: 1800 Baltimore Avenue
zip5 positive integer, 5 digits (optional)
The contact's five-digit ZIP code
message string (optional)
(legislator email campaigns only) The advocate's message to their legislator(s).
guests positive integer, 5 digits (optional)
(RSVP campaigns only) The total number of guests attending, including the person registering.
guestNames array of strings, max 100 characters each (optional)
For all additional guests (beyond the person registering), the names of each.
smsOptin positive integer, 1 or 0 (optional)
You must include a valid phone number (phone) and campaign ID (campaigns[]) in the request.
Opts this contact in to receive future text messages.
smsOptinConfirmed positive integer, 1 or 0 (optional)
You must include the sms opt in parameter (smsOptin) and a valid phone number (phone) in the request. If set to 1, a SMS opt in confirmation text will not be sent and the phone will be considered opted in to all future text messaging.

Not available for all accounts. Please contact your Phone2Action customer success manager in order to obtain access.
emailOptin positive integer, 1 or 0 (optional)
You must include a valid email address (email) and campaign ID (campaigns[]) in the request.
Opts this contact in to receive future email messages.
smsOptout positive integer, 1 or 0 (optional)
You must include a valid phone number (phone) and campaign ID (campaigns[]) in the request.
Opts this advocate out from future text messages.

Once an advocate has been opted out from text messaging, they cannot be opted back in.
emailOptout positive integer, 1 or 0 (optional)
You must include a valid email address (email) and campaign ID (campaigns[]) in the request.
Opts this advocate out from future email messages. An advocate can be opted back in to email messaging by using the emailOptin parameter set to 1 in an update request.
p2asource string (optional)
You must include a valid campaign ID (campaigns[]) in the request.
The source tag of the advocate, which indicates the source of the advocate and how they joined the campaign. You can view the source of an advocate in the advocate's profile.
utm_source string (optional)
You must include a valid campaign ID (campaigns[]) in the request.
The UTM source tag of the advocate.
utm_medium string (optional)
You must include a valid campaign ID (campaigns[]) in the request.
The UTM medium tag of the advocate, used to identify the specific content medium that acquired the advocate.
utm_campaign string (optional)
You must include a valid campaign ID (campaigns[]) in the request.
The UTM campaign tag of the acquired advocate, used to track a campaign at a higher level.
utm_term string (optional)
You must include a valid campaign ID (campaigns[]) in the request.
The UTM term tag of the acquired advocate, used to track a keyword campaign's performance.
utm_content string (optional)
You must include a valid campaign ID (campaigns[]) in the request.
The UTM content tag of the acquired advocate, typically used to identify what specifically was clicked to acquire the advocate's information, such as a banner ad or a text link.

Definition

POST https://api.phone2action.com/2.0/advocates

Example Request

$  curl https://api.phone2action.com/2.0/advocates \
   -u APP_ID:APP_KEY \
   -d "advocateid=998876" \
   -d "campaigns[]=999" \
   -d "firstname=Patrick" \
   -d "lastname=Smith" \
   -d "email=patrick@phone2action.com" \
   -d "phone=8165551234
                              
                              " \
   -d "address1=1800 Baltimore Avenue" \
   -d "zip5=64108" \
   -d "smsOptin=1" \
   -d "emailOptin=1" \
   -X POST

Example Response

{
  "success":1,
  "error":null,
  "type":"update",
  "advocateid":"998876"
}

Post Twitter Card

This endpoint will accept data from a Twitter Lead Generation Card and add it to your Phone2Action account.

Argument Description
card string (required)
Card ID — passed automatically by Twitter
email string (required)
The user's email address — passed automatically by Twitter
name string (required)
The user's full name — passed automatically by Twitter
screen_name string (optional)
The user's Twitter screen name — passed automatically by Twitter
campaignid integer (required)
The campaign ID to associate with this user (advocate)
app_id string (required)
Your App ID, assigned by Phone2Action. This is the only endpoint on this API to NOT use HTTP Basic Authentication, since Twitter's Lead Generation Card Builder does not currently support it. Instead, send it as a POST parameter and it will be accepted there instead.
api_key string (required)
Your API Key, assigned by Phone2Action. This is the only endpoint on this API to NOT use HTTP Basic Authentication, since Twitter's Lead Generation Card Builder does not currently support it. Instead, send it as a POST parameter and it will be accepted there instead.

Definition

POST https://api.phone2action.com/2.0/twitterCard

Example Request

$  curl https://api.phone2action.com/2.0/twitterCard \
   -d "app_id=12345xyz" \
   -d "api_key=98760cba" \
   -d "campaignid=998" \
   -d "card=1o416" \
   -d "name=Patrick Stoddart" \
   -d "email=patrick@phone2action.com" \
   -d "token=857779ff1a1b9fd2ae686a3afb33cd44" \
   -d "tw_userid=635491364"
   -X POST

Example Response

{
  "success":1,
  "id":"19302020",
  "timestamp":1371582165
                              
                              
}

List advocates

This endpoint will list advocates associated with your Phone2Action account.

Request Arguments — all optional

Argument Description
page integer optional, default = 1
page number to return. Each page is limited to 100 advocate records.
updatedSince unix timestamp
Fetch all advocates updated in Phone2Action after this date/time.

Example: If I want to retrieve all advocates updated after 11/18/2017 @ 11:05am, I would pass in: 1511003151
state string, 2 characters US postal abbreviation for a state or territory
e.g., "CA" "NY" or "DC"
campaignid integer
ID of a campaign - fetch only advocates belonging to that campaign
email string
Fetch only advocates who have this email address on their record
phone string
Fetch only advocates who have this phone number on their record. Phone number can be in any format.
excludeGdpr positive integer, 1 or 0, default = 0
If set to 1, does not return advocate information that has been expunged due to a General Data Protection Regulation (GDPR) request.

Response

Property Description
id integer
advocate's ID number
prefix string
salutation, e.g., "Mr." "Ms." "Mrs."
firstname string
middlename string
lastname string
suffix string
e.g., "Jr." "Sr." "III."
notes string
notes from advocate's profile, left by an organizer
stage string
typically one of: "Lead", "Member", or "Super Advocate"
rating integer, 0 to 5
the advocate's star-rating
connections integer
the number of times this advocate has contacted their officials for any campaign
tags array of strings
any tag names assigned to this advocate
created_at date/time object including date, timezone_type, timezone
updated_at date/time object including date, timezone_type, timezone

Emails

(array of objects)
id integer
device ID number
address string
email address

Phones

(array of objects)
id integer
device ID number
number E.164-formatted string
phone number
subscribed boolean
true if subscribed to SMS, false if not

Address

(object)
street1 string
The first line of the advocate's street address. Includes house number, street, and direction if applicable.
street2 string
The second line of the advocate's street address. Includes apartment number if applicable.
city string
The city included in the advocate's address.
state string, 2 characters US postal abbreviation for a state or territory
e.g., "CA" "NY" or "DC"
zip5 integer, 5 digits
The 5 digit zip code included in the advocate's address.
zip4 integer, 4 digits
The 4 digit USPS zip code extension included in the advocate's address.
county string
The county in the advocate's address.
countryAbbr string
The country abbreviation in the advocate's address.
countryName string
The full country name in the advocate's address.
latitude string
The geographic latitude of the advocate's address.
longitude string
The geographic longitude of the advocate's address.

Districts

(object)
congressional integer
advocate's Congressional district
stateSenate integer
advocate's state senate district
stateHouse integer
advocate's state house district
cityCouncil integer

IDs

(array of objects)
product string
name of the product or source of the ID (e.g., "MailChimp" or "Import")
id string
advocate's external ID, from this product/source

Memberships

(array of objects)
id integer
ID of the membership
campaignid integer
ID of the campaign with which the membership is associated
name integer
name of the campaign with which the membership is associated
created_at date/time object including date, timezone_type, timezone
the date & time this advocate joined this campaign
source string
source of the membership, if applicable. e.g., "facebook" or "email blast"

Custom Fields

(array of objects)
fieldid integer
common ID of the field this data belongs to
name string
the field's name. If the campaign is accessed via a Phone2Action campaign page, this is also the prompt shown to the advocate.
value text
the value of the field, specific to this advocate
created_at date/time object including date, timezone_type, timezone
the date & time this data was recorded

Definition

GET https://api.phone2action.com/2.0/advocates

Example Request

$  curl https://api.phone2action.com/2.0/advocates?state=NY \
   -u APP_ID:APP_KEY

Example Response

{
  "success":true,
  "errorCode":null,
  "error":null,
  "advocates": [
  	{
  		"id":1,
  		"prefix":"Mr.",
  		"firstname":"James",
  		"middlename":"Robert",
  		"lastname":"Smith",
  		"suffix":null,
  		"emails":[
  			{
  				"id":123,
  				"address":"jsmith@me.com",
  				"subscribed":false
  			},
  			{
  				"id":124,
  				"address":"jsmith2@gmail.com",
  				"subscribed":true
  			}],
  		"phones":[
  			{
  				"id":194,
  				"number":"+13920195545
                              
                              ",
  				"subscribed":false
  			}],
  		"address":{
  			"street1":"123 Any St",
  			"street2":"Apt 102",
  			"city":"New York",
  			"state":"NY",
  			"zip5":10003,
  			"zip4":2492,
  			"county":"Kings",
			"countryAbbr":"US",
			"countryName":"United States",
  			"latitude":"-76.2021",
  			"longitude":"30.3810"
  		},
  		"districts":{
  			"congressional":4,
  			"stateSenate":3,
  			"stateHouse":39,
  			"cityCouncil":6
  		},
  		"notes":"Top advocate!",
  		"stage":"Member",
  		"rating":5,
  		"connections":13,
  		"fields":null,
  		"ids":[
  			{
  				"product":"MailChimp",
  				"id":"30193"
  			},
  			{
  				"product":"Import",
  				"id":"9503"
  			}],
  		"tags":[
  			"Volunteer",
  			"Business"
  			],
  		"created_at":{
			"date":"2014-01-05 23:59:43",
			"timezone_type":3,
		 	"timezone":"UTC"
		},
		"updated_at":{
			"date":"2014-01-05 23:59:43",
			"timezone_type":3,
		 	"timezone":"UTC"
		},
  		"memberships":[
  			{
  				"id":102,
  				"campaignid":430,
  				"name":"New York Advocacy",
				"created_at":{
					"date":"2014-01-05 23:59:43",
					"timezone_type":3,
					"timezone":"UTC"
				},
  				"source":"facebook"
  			}
  		],
  		"fields": [
			{
				"fieldid": 1524,
				"name": "School",
				"value": "Gonzaga High School",
				"created_at": {
					"date": "2014-03-15 12:50:11.000000",
					"timezone_type": 3,
					"timezone": "UTC"
				}
			}
		],
  	}]
}

Create a connection

This endpoint will initiate a connection with a legislator (or legislators) for a given advocate. You'll need to specify which type(s) of connection(s) to initiate, from the following:

Email: will send an email message to the officials assigned through the campaign, and will return a success message with the legislators' information and message sent.

Tweet: will return an "url" parameter containing a link to forward the user to approve a tweet containing all legislators' handles in one tweet. An "urls" array will also be included that contains links to tweet each individual legislator.

Call: will immediately intiate a call to the advocate's phone, and will return a success message with the legislators' information.

Webhooks coming soon
Argument Description
advocateid positive integer (required)
The Phone2Action identifier for the advocate with whom the connection will be initiated.
campaignid positive integer (required)
The campaign via which the advocate's message(s) will be sent.

The advocate must already have an existing membership for this campaign ID in order for the request to be successful. To view existing memberships for an advocate, please reference our List Advocates API endpoint.
type array indicating the type of communication
One or more of : "tweet", "email", or "call".
If including email, the advocate must have a valid email in their Phone2Action profile. If including call, the advocate must have a valid phone number in their Phone2Action profile.
Some communication types may not be available for certain accounts.
emailSubject string (optional, used for emails only and required if emailMessage is passed)
The subject line of the email to be sent. If nothing is passed for both this value and emailMessage, the campaign's default will be used. If emailMessage is passed, subject will be blank if this value is not included.
emailMessage string (optional, used for emails only)
The body of the email to be sent. If nothing is passed, the campaign's default will be used.
DO NOT include an introduction or signature (e.g., Dear Legislator, or Sincerely, John Doe. These will be added automatically.
tweetMessage string (optional, 280-character maximum, used for tweets only)
The body of the tweet to be sent. If nothing is passed, the campaign's default will be used.
Important: this overrides the entire contents of the tweet, including officials' Twitter handles. To include their usernames, add [@legislator], and leave up to 50 characters free from the tweet's contents (Twitter usernames can be up to 15 characters each, plus @ symbols and spaces).
p2asource string (optional)
The source tag of the advocate, which indicates the source of the advocate and how they joined the campaign. You can view the source of an advocate in the advocate's profile.
utm_source string (optional)
The UTM source tag of the advocate.
utm_medium string (optional)
The UTM medium tag of the advocate, used to identify the specific content medium that acquired the advocate.
utm_campaign string (optional)
The UTM campaign tag of the acquired advocate, used to track a campaign at a higher level.
utm_term string (optional)
The UTM term tag of the acquired advocate, used to track a keyword campaign's performance.
utm_content string (optional)
The UTM content tag of the acquired advocate, typically used to identify what specifically was clicked to acquire the advocate's information, such as a banner ad or a text link.

Definition

POST https://api.phone2action.com/2.0/connections

Example Request

$  curl https://api.phone2action.com/2.0/connections \
   -u APP_ID:APP_KEY \
   -d "advocateid=19302020" \
   -d "campaignid=123" \
   -d "type[]=tweet" \
   -d "type[]=call" \
   -d "tweetMessage=[@legislator] Please support this bill!" \
   -X POST

Example Response

{
  "success": 1,
  "error": null,
  "data": {
    "ids": [
      3097545,
      3097546
    ],
    "leg": {
      "3097545": {
        "id": 1,
        "level": "STATE",
        "chamber": "SENATE",
        "country": "US",
        "state": "MO",
        "district": "7",
        "title": "Minority Caucus Secretary",
        "name_full": "Jason Holsman",
        "name_first": "Jason",
        "name_last": "Holsman",
        "party": "D",
        "contact_mailing_addresses": null,
        "tweet_url": "http://api.phone2action.com/connection/twitter/2963"
      },
      "3097546": {
        "id": 2,
        "level": "LOCAL",
        "chamber": "OTHER",
        "country": "US",
        "state": "MO",
        "district": "KANSAS CITY",
        "title": "Mayor",
        "name_full": "Sylvester James",
        "name_first": "Sylvester",
        "name_last": "James",
        "party": null,
        "contact_mailing_addresses": null,
        "tweet_url": "http://api.phone2action.com/connection/twitter/2972"
      }
  },
  "url": "http://local.phone2action.com/connect/twitter/38/2",
    "urls": {
      "3097545": "http://api.phone2action.com/connection/twitter/2963",
      "3097546": "http://api.phone2action.com/connection/twitter/2972"
    }
  }
}

List campaigns

List all campaigns active for your customer account, including links and state specifications.

Argument Description
state string two-character alpha postal code for a state (optional)
Filters results by state
zip integer five-digit ZIP code (optional)
Filter results by ZIP code
includeGeneric true or false (optional, default = false)
When filtering by state or ZIP code, include unrestricted campaigns?
includePrivate true or false (optional)
If passed as true, will include private campaigns in results

Definition

GET https://api.phone2action.com/2.0/campaigns

Example Request

$  curl https://api.phone2action.com/2.0/campaigns?state=WA&includeGeneric=true \
   -u APP_ID:APP_KEY

Example Response

[
   {
      "id":1,
      "name":"Save the Whales",
      "display_name":"Save the Whales Now!",
      "subtitle":"Help us save the whales today!",
      "public":1,
      "topic":"Animals",
      "type":"CAMPAIGN",
      "link":"http:\/\/p2a.co\/whales",
      "restrict_allow":"{\"states\":[\"WA\"]}",
      "content":{
	"summary":"<p>Please support our cause.</p>",
      	"introduction":"<p>Welcome!</p>",
      	"call_to_action":"<p>Take action now!</p>",
      	"thank_you":"<p><strong>Thanks for taking action!</strong></p>",
	"background_image":"https://p2a-images.s3.amazonaws.com/qa/campaigns/1234/example.jpg"
       },
       "embed_code":"<div class=\"advocacy-actionwidget\" data-domain=\"p2a.co\" data-shorturl=\"nYRleQH\" data-responsive=\"true\" style=\"\"></div>\n<script>\n(function(d, s, id) {\nvar js, fjs = d.getElementsByTagName(s)[0];\nif (d.getElementById(id)) return;\njs = d.createElement(s); js.id = id;\njs.src = '//p2a.co/js/embed/widget/advocacywidget.min.js';\nfjs.parentNode.insertBefore(js, fjs);\n}(document, 'script', 'advocacy-actionwidget-code'));\n</script>\n",
       "updated_at":{
         "date":"2014-01-05 23:59:43",
         "timezone_type":3,
         "timezone":"UTC"
       }
   }
]