Record Outreach Helper Version 2

This document describes the OSDI record outreach helper endpoint as implemented by the Action Network.

The record outreach helper allows you to create or update a person record and mark that person as having made an outreach on an advocacy campaign at the same time (as well as tag that person).

This saves API calls. POSTing a new outreach without the helper would mean you need a link to the person you want to associate the outreach with, which would entail either an oData search to look up the existing person or a POST using the person_signup_helper to add the person first. The record outreach helper allows you to post a person's data along with an outreach, and the helper will automatically create or deduplicate the person and then create an outreach for them on the specified advocacy campaign, all in one API call.

The record outreach helper takes the normal outreach format (described here) with an additional JSON hash with person data, and an optional array of tags to add to the person's record.

People are matched and deduplicated by phone number and email address, both of which can be attached to an activist record. People are required to have either an email address or a phone number. If a person is posted without an email address, a record with only phone number will be created and vice versa. If adding or changing a phone number results in more than one activist having the same number for your group, one of two things will happen. If both activists have email addresses, the phone number will be removed from the old activist and added to the new activist. If one of the activists is a mobile-only record, then the records will be merged. More on deduplicating here.

If the email or phone number posted corresponds with a person already in the system, we update their record instead of creating a new person. If the person is new to your email list, they will be subscribed to the email list associated with your API key. (In networks, subscribed statuses will travel up the network. Unsubscribed statuses will not).The only valid status is subscribed, no other status fields are valid at this endpoint.

People's mobile subscription status works differently than email subscription status. If they are new to your mobile list, by default they will be added as unsubscribed, unless you pass subscribed If they are an existing person already in your group, the person's mobile subscription status will not be changed, unless you pass subscribed in the mobile status field. (In networks, if this group does has the 'mobile status goes up the network' setting checked, a mobile subscribed status will travel up the network where an unsubscribed will not.) No other status fields are valid on this endpoint.

Items in the optional add_tags and remove_tags array are matched to existing tags associated with the list matching your API key by name. If a matching tag is found, that tag will be added or removed from the person's record. If not, the tag will be ignored. The operation to add tags will always run before the operation to remove tags.

Background processing is available on this operation via the background_request=true URL argument. You can learn more about background processing here.

Finally, you can POST to this helper without an API key. This is useful to enable a javascript implementation, say the use of a custom form that you create, without leaking your API key to browsers. If you use unauthenticated or blind POST without an API key, the response will be essentially no information, to avoid leaking any personal data over the API without an API key present. You will receive a success status code and an empty JSON response if successful, or an error status code and an error message if not. See the blind post tutorial for an example.

Note: Outreaches are not deduplicated based on person, so a specific person can make more than one outreach on an advocacy campaign. In fact, a new outreach is created for each target the person sends to using our user interface, even if they send the same letter to more than one target at once. And unlike other action types, you may only post outreaches to advocacy campaign pages that have been created via the API, and these will not send autoresponses or send messages to targets. You cannot add an outreach to an advocacy campaign page created using our user interface.

Sections:

• Endpoint
• Field names and descriptions
• Related resources
• Scenario: Creating a new outreach (POST)

Endpoint

Endpoint:

https://actionnetwork.org/api/v2/advocacy_campaigns/[advocacy_campaign_id]/outreaches

The record outreach helper lives at the endpoint relating to the collection of outreaches on a specific advocacy campaign.

Back To Top ↑

Field names and descriptions

Record Outreach Helper fields:

Target fields:

Referrer Data fields:

Back To Top ↑

Related resources

• Outreaches
• Advocacy Campaigns
• People

Back To Top ↑

Scenario: Creating a new outreach (POST)

If you post with an inline person hash instead of with a link to a person object as described here, we will create or update the matching person and associate them with a new outreach on the specified advocacy campaign, all in one API call.

An email address or phone number is the only required field, though others can be POSTed.

Outreaches are not deduplicated by person, so a person can make an outreach on an advocacy campaign more than once. In fact, a new outreach is created for each target the person sends to using our user interface, even if they send the same letter to more than one target at once.

Tags can also be added to a person's record when POSTing using the helper by including the optional tags array. Items in the array are matched to existing tags associated with the list matching your API key by name. If a matching tag is found, that tag will be added to the person's record. If not, the tag will be ignored.

Finally, you can POST to this helper without an API key. This is useful to enable a javascript implementation, say the use of a custom form that you create, without leaking your API key to browsers. See the blind post tutorial for an example.

Note: Unlike other action types, you may only post outreaches to advocacy campaign pages that have been created via the API, and these will not send autoresponses or send messages to targets. You cannot add an outreach to an advocacy campaign page created using our user interface.

Here is an example of posting an outreach with person data inlined to the special record_outreach_helper link on the outreaches collection, along with tags:

Request

						
POST https://actionnetwork.org/api/v2/advocacy_campaigns/f77e736b-d295-4e68-96ec-a765090c6523/outreaches

Header:
Content-Type: application/json
OSDI-API-Token: your_api_key_here


{
  "targets": [
    {
      "given_name": "Joe",
      "family_name": "Schmoe"
    }
  ],
  "person" : {
    "family_name" : "Smith",
    "given_name" : "John",
    "postal_addresses" : [ { "postal_code" : "20009" }],
    "email_addresses" : [ { "address" : "jsmith@mail.com" }],
    "phone_numbers": [ {"number": "2021234444" }]
  },
  "add_tags": [
    "advocate",
    "member"
  ],
  "remove_tags": [
    "inactive"
  ]
} 
					

Response

						
200 OK

Content-Type: application/hal+json
Cache-Control: max-age=0, private, must-revalidate


{
  "identifiers": [
    "action_network:38ec0365-f996-42a0-b26a-dbed24cf927f"
  ],
  "created_date": "2014-03-27T17:58:45Z",
  "modified_date": "2014-03-27T17:58:45Z",
  "type": "email",
  "targets": [
    {
      "given_name": "Joe",
      "family_name": "Schmoe"
    }
  ],
  "action_network:person_id": "c945d6fe-929e-11e3-a2e9-12313d316c29",
  "action_network:advocacy_campaign_id": "f77e736b-d295-4e68-96ec-a765090c6523",
  "_links": {
    "self": {
      "href": "https://actionnetwork.org/api/v2/advocacy_campaigns/f77e736b-d295-4e68-96ec-a765090c6523/outreaches/38ec0365-f996-42a0-b26a-dbed24cf927f"
    },
    "osdi:advocacy_campaign": {
      "href": "https://actionnetwork.org/api/v2/advocacy_campaigns/f77e736b-d295-4e68-96ec-a765090c6523"
    },
    "osdi:person": {
      "href": "https://actionnetwork.org/api/v2/people/17be9a36-bb9a-4f68-94a8-40523b9dab27"
    },
    "curies": [
      {
        "name": "osdi",
        "href": "https://actionnetwork.org/docs/v2/{rel}",
        "templated": true
      },
      {
        "name": "action_network",
        "href": "https://actionnetwork.org/docs/v2/{rel}",
        "templated": true
      }
    ]
  }
}
					

In the above example, a new person was created and their outreach added to the advocacy campaign at the same time. The tags 'advocate' and 'member' were added to that person's record as well. We deduplicate people added this way by email address and phone number, so if the email posted corresponded with a person already in the system, we would update their record instead of creating a new person. The required fields for person remain the same -- email address or phone number and postal code -- and any posts missing that information will fail.

If the person is new, they will be subscribed to the email list associated with your API key. If not, their subscription status (subscribed, unsubscribed, etc...) will not be changed unless you pass subscribed in the status field, as described in the people documentation. In that case, they will be subscribed to the email list, even if they were previously unsubscribed. No other status fields are valid on this endpoint.

New people are not automatically subscribed to the mobile list. They will not be subscribed to the mobile list unless you pass subscribed in the phone status field, as described in the people documentation.

Of course you can POST an outreach with more fields such as address lines for your inline person data or custom fields if you'd like, but they are not required. And you can omit your API key, in which case the response will a success status code and an empty JSON object if successful, or an error code and message if not.

Back To Top ↑