Outreach Payload

This document describes the Action Network webhook payload for outreaches.

Outreaches represent the action an activist took when they filled out and sent a letter to a target of a letter campaign or called a target of a call campaign (both called an advocacy campaign on the API), or outreaches POSTed to advocacy campaigns over the API.

The outreach format is closely related to the record outreach helper and outreach resources on the Action Network API. Please refer to that documentation for a fuller explanation of fields, format, and how they relate to other resources.

Outreaches are linked to the person resource corresponding to the activist who sent the letter, as well as the advocacy campaign that was used to send the letter.

Outreaches are often batched, with multiple hashes coming as part of the array that is POSTed to your server's URL when the webhook is fired. Each hash represents a letter sent to a particular target. For example, if you asked an activist to write to their members of Congress you can expect three outreaches in a batch, one representing a letter to their representative and two to their Senators.

Outreach payloads will also be sent if an activist only fills out step 1 of the letter campaign form (collecting their address) but for various reasons does not actually send a message to a target. For example, no targets could be found for their area (if they're writing from DC and the letter campaign is targeted to Senators, as DC does not have any Senators) or they just did not complete the letter form. Which fields in the payload will be sent during each of these circumstances is noted in the field tables below.

Sections:

Type

Outreach events are identified by their type, which is the JSON closure that surrounds the hash in the POSTed array.

The outreach type is osdi:outreach.

Back To Top ↑

Field names and descriptions

Outreach fields:
Field Name Type Description
identifiers strings[] An array of identifiers in the format [system name]:[id]. See the general concepts document for more information about identifiers.
created_date datetime The date and time the resource was created.
modified_date datetime The date and time the resource was last modified.
type string The type of outreach, specifying how the activist performed the outreach to targets. Can be 'email' to correspond with letter campaigns on the UI and 'phone' to correspond with call campaigns on the UI.
subject string The subject of the letter sent to the targets. Only present if the activist completed an outreach and actually sent a message. For email type advocacy campaigns only.
message string The message that the activist wrote to the targets. Only present if the activist completed an outreach and actually sent a message. 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. Only present if the activist found targets to write to.
action_network:referrer_data Referrer Data A hash of referrer data such as source code and referrer code. Action Network-only.
person Person* A hash representing person data to associate with this outreach. Contains only the fields entered by the activist when they created the attendance, not full fields on their record. See the people document for more information about people.
add_tags strings[] An array of strings representing tags that were added to the person's record during the outreach creation. Note: The person may have already had these tags applied to their record before taking action, and in a network these tags may not exist on parent groups. This array only represents what tags were attempted to be added to the person's record, not the actual result of those operations.
action_network:sponsor Sponsor A hash of sponsor data indicating the sponsor (if the group sponsored the action) or referrer (if the group used their referrer code to send activists to take action). Useful for determining where in a network the event originated. Action Network-only.
idempotency_key string A hash of webhook message id. Unique per webhook message, consistent across retries.
Target fields:
Field Name Type 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 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.
Sponsor fields:
Field Name Type Description
title string The name of the sponsoring or referring group.
browser_url string The URL to the group's public page.
Back To Top ↑

Links

Link Name Description
self A link to this individual outreach resource. Only present if the activist found targets to write to. Click here for outreach documentation.
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 left 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. Only present if the activist found targets to write to. Click here for advocacy campaign documentation.
Back To Top ↑

Related resources

Back To Top ↑

Example

If an activist takes action on a letter campaign and your webhook's trigger matches the event, an outreach webhook payload like the below will be fired off to your server's webhook URL. The below example does not show all possible fields. As noted in the webhooks documentation, only fields that were entered by the activist while taking action will be included in the payload.

Request

						
POST https://your-webhook-url.com

Header:
Content-Type: application/json


[
  {
    "osdi:outreach": {
      "created_date": "2018-11-07T19:49:26Z",
      "modified_date": "2018-11-07T19:49:26Z",
      "type": "email",
      "subject": "Please vote for this bill",
      "message": "Please vote for bill no 123",
      "targets": [
        {
          "title": "Representative",
          "given_name": "Jill",
          "family_name": "Black",
          "ocdid": "ocd-division/country:us/state:ny/cd:18"
        }
      ],
      "identifiers": [
        "action_network:32b6df18-014f-4e0c-b112-f1bacfc41a61"
      ],
      "person": {
        "created_date": "2018-11-07T17:56:40Z",
        "modified_date": "2018-11-07T19:46:40Z",
        "family_name": "Smith",
        "postal_addresses": [
          {
            "primary": true,
            "address_lines": [
              "1600 Pennsylvania Ave NW"
            ],
            "locality": "Washington",
            "postal_code": "20036",
            "region": "District of Columbia",
            "country": "US",
            "location": {
              "latitude": 41.2967,
              "longitude": -73.6698,
              "accuracy": "Approximate"
            }
          }
        ],  
        "email_addresses": [
          {
            "primary": true,
            "address": "jsmith@mail.com",
            "status": "subscribed"
          }
        ],
        "phone_numbers": [
          {
            "primary": true,
            "number": "12024444444",
            "number_type": "Mobile",
            "status": "subscribed"
          }
        ],
        "languages_spoken": [
          "en"
        ],
        "custom_fields": {
          "phone_number": "123.456.7890"
        }
      },
      "action_network:referrer_data": {
        "source": "facebook"
      },
      "add_tags": [
        "volunteer",
        "member"
      ],
      "_links": {
        "self": {
          "href": "https://actionnetwork.org/api/v2/advocacy_campaigns/48de2ac1-2398-41db-8d19-699e23bec035/outreaches/32b6df18-014f-4e0c-b112-f1bacfc41a61"
        },
        "osdi:advocacy_campaign": {
          "href": "https://actionnetwork.org/api/v2/advocacy_campaigns/48de2ac1-2398-41db-8d19-699e23bec035"
        },
        "osdi:person": {
          "href": "https://actionnetwork.org/api/v2/people/0df69aaf-3614-4315-b73a-088866b404e8"
        }
      }
    },
    "action_network:sponsor": {
      "title": "Progressive Action Now",
      "url": "https://actionnetwork.org/groups/progressive-action-now"
    },
    "idempotency_key": "1679091c5a880faf6fb5e6087eb1b2dcou"
  },
  {
    "osdi:outreach": {
      "created_date": "2018-11-07T19:49:26Z",
      "modified_date": "2018-11-07T19:49:26Z",
      "type": "email",
      "subject": "Please vote for this bill",
      "message": "Please vote for bill no 987",
      "targets": [
        {
          "title": "Senator",
          "given_name": "John",
          "family_name": "Doe",
          "ocdid": "ocd-division/country:us/state:ny"
        }
      ],
      "identifiers": [
        "action_network:32b6df18-014f-4e0c-b112-f1bacfc41a61"
      ],
      "person": {
        "created_date": "2018-11-07T17:56:40Z",
        "modified_date": "2018-11-07T19:46:40Z",
        "family_name": "Smith",
        "postal_addresses": [
          {
            "primary": true,
            "address_lines": [
              "1600 Pennsylvania Ave NW"
            ],
            "locality": "Washington",
            "postal_code": "20036",
            "region": "District of Columbia",
            "country": "US",
            "location": {
              "latitude": 41.2967,
              "longitude": -73.6698,
              "accuracy": "Approximate"
            }
          }
        ],  
        "email_addresses": [
          {
            "primary": true,
            "address": "jsmith@mail.com",
            "status": "subscribed"
          }
        ],
        "phone_numbers": [
          {
            "primary": true,
            "number": "12024444444",
            "number_type": "Mobile",
            "status": "subscribed"
          }
        ],
        "languages_spoken": [
          "en"
        ],
        "custom_fields": {
          "phone_number": "123.456.7890"
        }
      },
      "action_network:referrer_data": {
        "source": "facebook"
      },
      "add_tags": [
        "volunteer",
        "member"
      ],
      "_links": {
        "self": {
          "href": "https://actionnetwork.org/api/v2/advocacy_campaigns/48de2ac1-2398-41db-8d19-699e23bec035/outreaches/32b6df18-014f-4e0c-b112-f1bacfc41a61"
        },
        "osdi:advocacy_campaign": {
          "href": "https://actionnetwork.org/api/v2/advocacy_campaigns/48de2ac1-2398-41db-8d19-699e23bec035"
        },
        "osdi:person": {
          "href": "https://actionnetwork.org/api/v2/people/0df69aaf-3614-4315-b73a-088866b404e8"
        }
      }
    },
    "action_network:sponsor": {
      "title": "Progressive Action Now",
      "url": "https://actionnetwork.org/groups/progressive-action-now"
    }
  },
  {
    "osdi:outreach": {
      "created_date": "2020-11-07T19:49:26Z",
      "modified_date": "2020-11-07T19:49:26Z",
      "type": "phone",
      "duration": "4",
      "targets": [
        {
          "title": "Representative",
          "given_name": "Joe",
          "family_name": "Smith",
          "ocdid": "ocd-division/country:us/state:ca/cd:25"
        }
      ],
      "identifiers": [
        "action_network:32b6df18-014f-4e0c-b112-f1bacfc41a62"
      ],
      "person": {
        "created_date": "2020-11-07T17:56:40Z",
        "modified_date": "2020-11-07T19:46:40Z",
        "family_name": "Roberts",
        "postal_addresses": [
          {
            "primary": true,
            "address_lines": [
              "1600 Pennsylvania Ave NW"
            ],
            "locality": "Washington",
            "postal_code": "20036",
            "region": "District of Columbia",
            "country": "US",
            "location": {
              "latitude": 41.2967,
              "longitude": -73.6698,
              "accuracy": "Approximate"
            }
          }
        ],  
        "email_addresses": [
          {
            "primary": true,
            "address": "jroberts@mail.com",
            "status": "subscribed"
          }
        ],
        "phone_numbers": [
          {
            "primary": true,
            "number": "12024444445",
            "number_type": "Mobile",
            "status": "subscribed"
          }
        ],
        "languages_spoken": [
          "en"
        ],
      },
      "action_network:referrer_data": {
        "source": "facebook"
      },
      "add_tags": [
        "volunteer",
        "member"
      ],
      "_links": {
        "self": {
          "href": "https://actionnetwork.org/api/v2/advocacy_campaigns/48de2ac1-2398-41db-8d19-699e23bec034/outreaches/32b6df18-014f-4e0c-b112-f1bacfc41a62"
        },
        "osdi:advocacy_campaign": {
          "href": "https://actionnetwork.org/api/v2/advocacy_campaigns/48de2ac1-2398-41db-8d19-699e23bec034"
        },
        "osdi:person": {
          "href": "https://actionnetwork.org/api/v2/people/0df69aaf-3614-4315-b73a-088866b404e9"
        }
      }
    },
    "action_network:sponsor": {
      "title": "Progressive Action Now",
      "url": "https://actionnetwork.org/groups/progressive-action-now"
    },
    "idempotency_key": "1679091c5a880faf6fb5e6087eb1b2dcou2"
  }
]
Back To Top ↑