Outreaches Version 2

This document describes the OSDI outreaches collection and outreach resource as implemented by the Action Network.

Outreaches represent the action an activist took when they took action on a specific advocacy campaign. They are equivalent to the letters activists write using the letter campaigns tool in our UI or the calls activists make or receive using the call campaigns tool.

Outreaches that correspond to letter campaigns have a subject and message corresponding to the content of the letter that was sent, as well as a targets array showing who the letter was sent to, as well as other fields. They are linked to the person resource corresponding to the activist who made the outreach.

Note: Outreaches are not deduplicated based on person, unlike other similar resources in the Action Network API, so a specific person can make an outreach more than once on a advocacy campaign page. In fact, we will display an outreach for each target an activist writes to on our UI, even if on our UI they were writing to, say, both of their Senators at the same time and sent the same message to each. 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:

Endpoints and URL structures

Endpoints:

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

https://actionnetwork.org/api/v2/people/[person_id]/outreaches

Outreach resources live at endpoints relating to the person who took action and the advocacy campaign they took action on. The endpoints return a collection of all outreaches associated with either that person or that advocacy campaign.

URL Structures:

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

https://actionnetwork.org/api/v2/people/[person_id]/outreaches/[outreach_id]

To address a specific outreach, use the identifier without the action_network: prefix to construct a URL, like https://actionnetwork.org/api/v2/advocacy_campaigns/d91b4b2e-ae0e-4cd3-9ed7-d0ec501b0bc3/outreaches/167ce1d2-70b7-423e-b480-914981cbeaff

Back To Top ↑

Field names and descriptions

Outreach fields:
Field Name Type Required on POST Description
identifiers strings[] An array of identifiers in the format [system name]:[id]. Must be globally unique. See the general concepts document for more information about identifiers.
created_date datetime The date and time the resource was created. System generated, not editable.
modified_date datetime The date and time the resource was last modified. System generated, not editable.
type string The type of outreach, specifying how the activist performed the outreach to targets. System generated, not editable, always 'email' or 'phone' depending on if this was a letter campaign or a call campaign.
subject string The subject of the letter that the activist wrote to the targets. For email type advocacy campaigns only.
message string The message that the activist wrote to the targets. For email type advocacy campaigns only.
duration string The length of the call to the targets. For phone type advocacy campaigns only.
targets Targets[] An array of hashes identifying the targets of the outreach. Must always be an array of one.
action_network:person_id string The native Action Network identifier associated with the person who made the outreach. Action Network-only feature. System generated, not editable.
action_network:advocacy_campaign_id string The native Action Network identifier associated with the advocacy campaign this outreach was created on. Action Network-only feature. System generated, not editable.
action_network:referrer_data Referrer Data A hash of referrer data such as source code and referrer code. Action Network-only.
Target fields:
Field Name Type Required on POST Description
title string The title of the target of this outreach. (ex: 'Senator')
given_name string The first or given name of the target. (ex: 'John')
family_name string The last or family name of the target. (ex: 'Smith')
ocdid string The Open Civic Data Division ID for this target's political geography, if applicable. Click here for more documentation. (ex: 'ocd-division/country:us/state:ny/cd:18', which corresponds to New York's 18th Congressional District)
Referrer Data fields:
Field Name Type Required on POST Description
source string The source code of this outreach. Equivalent to someone taking action with the url argument ?source=[your source]. Corresponds to the sources chart in this action's manage page. Action Network-only.
referrer string The referrer code of this outreach. Equivalent to someone taking action with the url argument ?referrer=[your referrer code]. Must be a valid Action Network referrer code. Read-only. Corresponds to the referrers chart in this action's manage page. Action Network-only.
website string The website referrer for this outreach. Equivalent to someone taking action after clicking a link on the listed website. Action Network-only.
email_referrer string The id of the email that brought someone to the link to take action. Action Networks adds the ?email_referrer=[your email referrer] URL parameter on the links sent through the emailer. Pass that value back in your API calls here to mark this action as having taken place because of a response to that email.
mobile_message_referrer string The id of the mobile message that brought someone to the link to take action. Action Networks adds the ?mobile_message_referrer=[your mobile referrer] URL parameter on the links sent through mobile messages. Pass that value back in your API calls here to mark this action as having taken place because of a response to that message.
Back To Top ↑

Links

Link Name Description
self A link to this individual outreach resource.
osdi:person A link to the person who made this outreach. Click here for people documentation.
osdi:advocacy_campaign A link to the advocacy campaign this outreach was created on. Note: If this outreach was created via a referral code, this link may not be accessible because your API key does not give you permission to access the advocacy campaign itself. Click here for advocacy campaign documentation.
Back To Top ↑

Related resources

Back To Top ↑

Scenario: Retrieving a collection of outreach resources (GET)

Outreach resources are sometimes presented as collections of outreaches. For example, calling the outreaches endpoint on a specific advocacy campaign will return a collection of all the outreaches associated with that advocacy campaign.

Request

						
GET https://actionnetwork.org/api/v2/advocacy_campaigns/049e9bda-cb79-420d-91ba-92e5a15ba62f/outreaches

Header:
OSDI-API-Token: your_api_key_here

Response

						
200 OK

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


{
  "total_pages": 1,
  "per_page": 25,
  "page": 1,
  "total_records": 6,
  "_links": {
    "self": {
      "href": "https://actionnetwork.org/api/v2/advocacy_campaigns/049e9bda-cb79-420d-91ba-92e5a15ba62f/outreaches"
    },
    "osdi:outreaches": [
      {
        "href": "https://actionnetwork.org/api/v2/advocacy_campaigns/049e9bda-cb79-420d-91ba-92e5a15ba62f/outreaches/f1119c4e-b8ca-44ff-bfa7-f78f7ca3ec16"
      },
      {
        "href": "https://actionnetwork.org/api/v2/advocacy_campaigns/049e9bda-cb79-420d-91ba-92e5a15ba62f/outreaches/d86538c1-e8f7-46e1-8320-552da81bd48d"
      },
      //truncated for brevity
    ],
    "curies": [
      {
        "name": "osdi",
        "href": "https://actionnetwork.org/docs/v2/{rel}",
        "templated": true
      },
      {
        "name": "action_network",
        "href": "https://actionnetwork.org/docs/v2/{rel}",
        "templated": true
      }
    ]
  },
  "_embedded": {
    "osdi:outreaches": [
      {
        "identifiers": [
          "action_network:f1119c4e-b8ca-44ff-bfa7-f78f7ca3ec16"
        ],
        "created_date": "2014-03-27T17:42:21Z",
        "modified_date": "2014-03-27T17:42:24Z",
        "type": "email",
        "subject": "Please vote no!",
        "message": "Please vote no on bill 12345.",
        "targets": [
          {
            "title": "Representative",
            "given_name": "Jill",
            "family_name": "Black",
            "ocdid": "ocd-division/country:us/state:ny/cd:18"
          }
        ],
        "action_network:person_id": "c945d6fe-929e-11e3-a2e9-12313d316c29",
        "action_network:advocacy_campaign_id": "049e9bda-cb79-420d-91ba-92e5a15ba62f",
        "_links": {
          "self": {
            "href": "https://actionnetwork.org/api/v2/advocacy_campaigns/049e9bda-cb79-420d-91ba-92e5a15ba62f/outreaches/f1119c4e-b8ca-44ff-bfa7-f78f7ca3ec16"
          },
          "osdi:advocacy_campaign": {
            "href": "https://actionnetwork.org/api/v2/advocacy_campaigns/049e9bda-cb79-420d-91ba-92e5a15ba62f"
          },
          "osdi:person": {
            "href": "https://actionnetwork.org/api/v2/people/c945d6fe-929e-11e3-a2e9-12313d316c29"
          }
        }
      },
      {
        "identifiers": [
          "action_network:d86538c1-e8f7-46e1-8320-552da81bd48d"
        ],
        "created_date": "2014-03-27T17:40:56Z",
        "modified_date": "2014-03-27T17:41:11Z",
        "type": "email",
        "subject": "Don't do it!",
        "message": "Please vote no on this bill!",
        "targets": [
          {
            "title": "Representative",
            "given_name": "Liam",
            "family_name": "Hoover",
            "ocdid": "ocd-division/country:us/state:ca/sldl:110"
          }
        ],
        "action_network:person_id": "c945d6fe-929e-11e3-a2e9-12313d316c29",
        "action_network:advocacy_campaign_id": "049e9bda-cb79-420d-91ba-92e5a15ba62f",
        "_links": {
          "self": {
            "href": "https://actionnetwork.org/api/v2/advocacy_campaigns/049e9bda-cb79-420d-91ba-92e5a15ba62f/outreaches/d86538c1-e8f7-46e1-8320-552da81bd48d"
          },
          "osdi:advocacy_campaign": {
            "href": "https://actionnetwork.org/api/v2/advocacy_campaigns/049e9bda-cb79-420d-91ba-92e5a15ba62f"
          },
          "osdi:person": {
            "href": "https://actionnetwork.org/api/v2/people/c945d6fe-929e-11e3-a2e9-12313d316c29"
          }
        }
      },
      //truncated for brevity
    ]
  }
}
Back To Top ↑

Scenario: Retrieving an individual outreach resource (GET)

Calling an individual outreach resource will return the resource directly, along with all associated fields and appropriate links to additional information about the outreach.

Request

						
GET https://actionnetwork.org/api/v2/advocacy_campaigns/049e9bda-cb79-420d-91ba-92e5a15ba62f/outreaches/f1119c4e-b8ca-44ff-bfa7-f78f7ca3ec16

Header:
OSDI-API-Token: your_api_key_here

Response

						
200 OK

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


{
  "identifiers": [
    "action_network:f1119c4e-b8ca-44ff-bfa7-f78f7ca3ec16"
  ],
  "created_date": "2014-03-27T17:42:21Z",
  "modified_date": "2014-03-27T17:42:24Z",
  "type": "email",
  "subject": "Please vote no!",
  "message": "Please vote no on bill 12345.",
  "targets": [
    {
      "title": "Representative",
      "given_name": "Jill",
      "family_name": "Black",
      "ocdid": "ocd-division/country:us/state:ny/cd:18"
    }
  ],
  "action_network:person_id": "c945d6fe-929e-11e3-a2e9-12313d316c29",
  "action_network:advocacy_campaign_id": "049e9bda-cb79-420d-91ba-92e5a15ba62f",
  "_links": {
    "self": {
      "href": "https://actionnetwork.org/api/v2/fundraising_page/049e9bda-cb79-420d-91ba-92e5a15ba62f/outreaches/f1119c4e-b8ca-44ff-bfa7-f78f7ca3ec16"
    },
    "osdi:advocacy_campaign": {
      "href": "https://actionnetwork.org/api/v2/advocacy_campaigns/049e9bda-cb79-420d-91ba-92e5a15ba62f"
    },
    "osdi:person": {
      "href": "https://actionnetwork.org/api/v2/people/c945d6fe-929e-11e3-a2e9-12313d316c29"
    },
    "curies": [
      {
        "name": "osdi",
        "href": "https://actionnetwork.org/docs/v2/{rel}",
        "templated": true
      },
      {
        "name": "action_network",
        "href": "https://actionnetwork.org/docs/v2/{rel}",
        "templated": true
      }
    ]
  }
}
Back To Top ↑

Scenario: Creating a new outreach (POST)

You can post a new outreach to an advocacy campaign with that advocacy campaign's outreaches endpoint and an outreach resource will be created in our system.

Note: Unlike other action types, you may only post outreaches to advocacy campaigns 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 created using our user interface.

When you post an outreach, you can either link to an existing person to register that this person made an outreach on this advocacy campaign, or you can post information about a new person inline to the special record_outreach_helper endpoint, to both create a new person and register that they made an outreach on this advocacy campaign at the same time. You can learn more about the record outreach helper here.

Unlike other similar resources, outreaches are not deduplicated by person. A person may make an outreach on an advocacy campaign more than once. Posting a new outreach by a person who previously donated will create a new outreach resource.

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.

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

Here is an example of posting an outreach linking to an existing person:

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"
    }
  ],
  "_links" : {
    "osdi:person" : { "href" : "https://actionnetwork.org/api/v2/people/c945d6fe-929e-11e3-a2e9-12313d316c29" }
  }
}

Response

						
200 OK

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


{
  "identifiers": [
    "action_network:c2f42b7b-8d86-4afd-ba7e-d7b5b74abfc5"
  ],
  "created_date": "2014-03-27T17:53:55Z",
  "modified_date": "2014-03-27T17:57:02Z",
  "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": {
    "osdi:person": {
      "href": "https://actionnetwork.org/api/v2/people/c945d6fe-929e-11e3-a2e9-12313d316c29"
    },
    "self": {
      "href": "https://actionnetwork.org/api/v2/advocacy_campaigns/f77e736b-d295-4e68-96ec-a765090c6523/outreaches/c2f42b7b-8d86-4afd-ba7e-d7b5b74abfc5"
    },
    "osdi:advocacy_campaign": {
      "href": "https://actionnetwork.org/api/v2/advocacy_campaigns/f77e736b-d295-4e68-96ec-a765090c6523"
    },
    "curies": [
      {
        "name": "osdi",
        "href": "https://actionnetwork.org/docs/v2/{rel}",
        "templated": true
      },
      {
        "name": "action_network",
        "href": "https://actionnetwork.org/docs/v2/{rel}",
        "templated": true
      }
    ]
  }
}

And of course you can post an outreach with more fields (such as referrer data) if you'd like, but they are not required.

Back To Top ↑

Scenario: Modifying an outreach (PUT)

You can modify an existing outreach by using PUT on its individual endpoint. You cannot modify outreaches created by our system, only ones you create via the API.

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

Request

						
PUT https://actionnetwork.org/api/v2/advocacy_campaigns/f77e736b-d295-4e68-96ec-a765090c6524/outreaches/38ec0365-f996-42a0-b26a-dbed24cf927g

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


{
  "subject": "Please vote no!"
}

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-27T18:00:49Z",
  "type": "email",
  "subject": "Please vote no!"
  "targets": [
    {
      "given_name": "Joe",
      "family_name": "Schmoe"
    }
  ],
  "action_network:person_id": "17be9a36-bb9a-4f68-94a8-40523b9dab27",
  "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
      }
    ]
  }
}

The above example added a subject.

You can also modify outreaches of the phone type of advocacy campaigns.

Request

						
PUT https://actionnetwork.org/api/v2/advocacy_campaigns/f77e736b-d295-4e68-96ec-a765090c6523/outreaches/38ec0365-f996-42a0-b26a-dbed24cf927f

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


{
  "duration": "2"
}

Response

						
200 OK

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


{
  "identifiers": [
    "action_network:38ec0365-f996-42a0-b26a-dbed24cf927g"
  ],
  "created_date": "2014-03-27T17:58:45Z",
  "modified_date": "2014-03-27T18:00:49Z",
  "type": "phone",
  "duration": "2",
  "targets": [
    {
      "given_name": "Joe",
      "family_name": "Schmoe"
    }
  ],
  "action_network:person_id": "17be9a36-bb9a-4f68-94a8-40523b9dab27",
  "action_network:advocacy_campaign_id": "f77e736b-d295-4e68-96ec-a765090c6524",
  "_links": {
    "self": {
      "href": "https://actionnetwork.org/api/v2/advocacy_campaigns/f77e736b-d295-4e68-96ec-a765090c6524/outreaches/38ec0365-f996-42a0-b26a-dbed24cf927g"
    },
    "osdi:advocacy_campaign": {
      "href": "https://actionnetwork.org/api/v2/advocacy_campaigns/f77e736b-d295-4e68-96ec-a765090c6524"
    },
    "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
      }
    ]
  }
}

The above example added a call time duration.

Editing of certain fields via PUT is not allowed, and is noted in the field names table above. For example, you can't change the person who is associated with this outreach. Invalid entries will be ignored.

Back To Top ↑

Scenario: Deleting an outreach (DELETE)

Deleting outreaches is not allowed via the API. DELETE requests will return an error.

Back To Top ↑