Outreach

This document defines the Outreach resource.

Outreaches are a type of action that a user may take by participating in an advocacy campaign. Outreaches have fields to describe them such as when the outreach was created, who the user contacted as the target of their advocacy, and the content of the message a user sent to that target, and typically are linked to the person who made the outreach.

Sections

Endpoints and URL structures

OSDI does not specify specific endpoints and link structures for compliant systems to use. Rather, because OSDI is a HAL+JSON API, endpoints and structures are defined in the links section of each returned resource, starting with the API Entry Point link.

HAL’s link structure lets an API consumer move through API levels, resources, and collections by parsing and following links. While most systems will not change the value of their links often and obey RESTful design principles, the value of each link when that resource is retrieved is the only canonical value, and it can change at any time.

The link relation label for a Outreach resource is osdi:outreach for a single Outreach resource or osdi:outreaches for a collection of Outreach resources.

Back to top…

Fields

The field names for this resource, with standard names, punctuation and capitalization, and values where appropriate.

Note: As with the entire OSDI specification, the specific fields a compliant system implements will vary between each system, as will the fields each system requires when creating or updating resources, which fields are writeable, and the operations you are allowed to perform on each resource.

Common Fields

A set of common fields that appear on all resources is included first, for reference.

Name Type Description
identifiers strings[] A unique string array of identifiers in the format [system name]:[id]. See the general concepts document for more information about identifiers.
created_date datetime A read-only property representing the date and time the resource was created on the local system.
modified_date datetime A read-only property representing the date and time the resource was last modified on the local system.

Control Headers

An “osdi:control” JSON object may contain common OSDI control headers which can be used on an OSDI POST, PUT, PATCH, Helper or other function calls to modify server behavior. Read More

Name Type Description
return_response boolean Defaults to true, if specified as false, the operation does not need to return the resource representation in the response

Back to top…

Outreach Fields

A list of fields specific to the Outreach resource.

Name Type Description
origin_system string A human readable identifier of the system where this outreach was created. (ex: “OSDI System”)
action_date string The date and time the outreach was made by the person.
type flexunum The type of outreach, specifying how the user performed the outreach to targets. One of “email”, “in-person”, “phone”, “postal mail”, or another type as needed.
duration integer The duration in seconds of the outreach, if applicable. (ex: duration will only be present on phone outreach types)
subject string The subject of the outreach, if applicable. (ex: subject will only be present on email outreach types)
message string The message of the outreach, if applicable. (ex: message will only be present on email or postal mail outreach types)
notes string Notes left by the person doing the outreach, if any. For example, any feedback they got from the person they called.
referrer_data Referrer Data* An object hash representing referrer and sourcing information about this outreach.
targets Target[] An array of target object hashes representing the targets of the outreach.

Back to top…

These JSON hashes included in the table above are broken out into their own tables for readability, rather than independent resources with their own endpoints.

Target

Name Type Description
target.title string The title or position of the target. (ex: “Senator” or “CEO”)
target.organization string The organization the target belongs to. (ex: “U.S. Senate” or “Acme Corporation”)
target.given_name string The first or given name of the target. (ex: “John”)
target.family_name string The last or family name of the target. (ex: “Smith”)
target.ocdid string The Open Civic Data Division ID for this target’s political geography, if applicable. See here for more documentation. (ex: “ocd-division/country:us/state:ny/cd:18”, which corresponds to New York’s 18th Congressional District)
postal_addresses Postal Addresses[] Postal address[es] of the target
email_addresses Email Addresses[] Email address[es] of the target
phone_numbers Phone Numbers[] Phone number[s] of the target

Postal Addresses

Name Type Description
postal_addresses.primary boolean Denotes if this is the primary address. A person can have only one primary address.
postal_addresses.address_type enum The type of address. One of “Home”, “Work”, or “Mailing”.
postal_addresses.venue string Optional venue name at the address, useful for names of buildings. (ex: Smith Hall)
postal_addresses.address_lines strings[] An array of strings representing the person’s street address.
postal_addresses.locality string A city or other local administrative area.
postal_addresses.region string State or subdivision codes according to ISO 3166-2 (Final 2 alpha digits).
postal_addresses.postal_code string The region specific postal code, such as a zip code.
postal_addresses.country string The country code according to ISO 3166-1 Alpha-2.
postal_addresses.language string Language in which the address is recorded – language code according to ISO 639.
postal_addresses.location object An object hash representing the geocoded location information for the address.
postal_addresses.location.latitude float A positive or negative float number representing the latitude of the address.
postal_addresses.location.longitude float A positive or negative float number representing the longitude of the address.
postal_addresses.location.accuracy enum A value representing the accuracy of the geocode. One of “Rooftop” or “Approximate”.
postal_addresses.status enum A value representing the status of the address. One of “Potential”, “Verified”, “Bad”, or “Past”.
postal_addresses.last_verified_date datetime A value representing the last verified date of the address.
occupation string The occupation of the person.

Email Addresses

Name Type Description
email_addresses.primary boolean Denotes if this is the primary address. A person can have only one primary address.
email_addresses.address string The email address for the person.
email_addresses.address_type flexenum The type of email address. One of “personal”, “work”, “other”, or another value.
email_addresses.status enum Indicates whether this email address is subscribed to receive emails in the system, either on one or more email lists. One of “subscribed”, “unsubscribed”, “bouncing”, “spam complaints”.

Phone Numbers

Name Type Description
phone_numbers.primary string Denotes if this is the primary phone number. A person can have only one primary number.
phone_numbers.number string The phone number of the person. Must including country code and must be numeric characters only.
phone_numbers.extension string An optional associated extension for the number.
phone_numbers.description string A freeform description of the phone number.
phone_numbers.number_type flexenum The type of phone number. One of “Home”, “Work”, “Mobile”, “Other”, “Daytime”, “Evening”, “Fax”, or another value.
phone_numbers.operator string The operator or carrier associated with the number. Example: “Verizon”
phone_numbers.country string The country code according to ISO 3166-1 Alpha-2.
phone_numbers.sms_capable boolean True if the number can accept SMS text messages.
phone_numbers.do_not_call boolean True if this number is registered on the US FCC Do Not Call Registry.

Referrer Data

Name Type Description
referrer_data.source string The source code that was used when this outreach was created. Typically used to track individual links, such as a post on social media or a link in a specific email. (ex: “facebook-101016-mainpage”)
referrer_data.referrer string The code or ID representing a person or group that referred this outreach. Typically used to track which person referred the person who made this outreach. (ex: “jane-doe”)
referrer_data.website string The top level domain of the website where the person clicked from to then subsequently make this outreach. (ex: “facebook.com”)
referrer_data.url string The specific URL where the person clicked from to then subsequently make this outreach. (ex: “https://facebook.com/posts/12345”)

Back to top…

The links associated with this resource, available in the links section of the resource. Links that are part of the OSDI spec are typically prefixed with the osdi: namespace to aid in curie matching and readability.

Note: As with the entire OSDI specification, the specific links a compliant system supplies will vary between each system. In addition, systems may choose to embed a linked resource directly in the response in addition to linking to it in the links section, using the standard _embedded syntax described in the general overview documentation.

Name Type Description
self Outreach* A self-referential link to the outreach.
person Person* A link to a single Person resource representing the person who made the outreach.
advocacy_campaign Advocacy Campaign* A link to an Advocacy Campaign resource representing the advocacy campaign on which this outreach was created.

Back to top…

Helpers

Helpers faciliate combined creation operations (POST) that are commonly performed by users. Each resource may have one or more associated helpers, which perform different operations and have separate syntax. Some initial OSDI implementations may only support helpers, rather than full RESTful access.

The helpers that operate on this resource are described in the table below. Click on the helper to view its documentation and syntax.

Name Description
record_outreach_helper Allows the creation of an outreach and a person at the same time.

Back to top…

Back to top…

Scenarios

The scenarios below show some common Create, Read, Update, Delete (CRUD) operations that can be performed on this resource, as well as any resource-specific behaviors worth highlighting. The following examples are for informational purposes. The authoritative resource definitions are above in the Fields tables and should be followed in the event of a conflict with the examples.

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 particular advocacy campaign will return a collection of all the outreaches made on that advocacy campaign.

Request

GET https://osdi-sample-system.org/api/v1/advocacy_campaigns/c945d6fe-929e-11e3-a2e9-12313d316c29/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": 10,
    "per_page": 25,
    "page": 1,
    "total_records": 250,
    "_links": {
        "next": {
            "href": "https://osdi-sample-system.org/api/v1/advocacy_campaigns/c945d6fe-929e-11e3-a2e9-12313d316c29/outreaches?page=2"
        },
        "osdi:outreaches": [
            {
                "href": "https://osdi-sample-system.org/api/v1/advocacy_campaigns/c945d6fe-929e-11e3-a2e9-12313d316c29/outreaches/d91b4b2e-ae0e-4cd3-9ed7-d0ec501b0bc3"
            },
            {
                "href": "https://osdi-sample-system.org/api/v1/advocacy_campaigns/c945d6fe-929e-11e3-a2e9-12313d316c29/outreaches/1efc3644-af25-4253-90b8-a0baf12dbd1e"
            },
            //(truncated for brevity)
        ],
        "curies": [
            {
                "name": "osdi",
                "href": "https://osdi-sample-system.org/docs/v1/{rel}",
                "templated": true
            }
        ],
        "self": {
            "href": "https://osdi-sample-system.org/api/v1/advocacy_campaigns/c945d6fe-929e-11e3-a2e9-12313d316c29/outreaches"
        }
    },
    "_embedded": {
        "osdi:outreaches": [
            {
                "identifiers": [
                    "osdi_sample_system:d91b4b2e-ae0e-4cd3-9ed7-d0ec501b0bc3",
                    "foreign_system:1"
                ],
                "origin_system": "OSDI Sample System",
                "created_date": "2014-03-20T21:04:31Z",
                "modified_date": "2014-03-20T21:04:31Z",
                "action_date": "2014-03-18T11:02:15Z",
                "type": "email",
                "subject": "Vote no!",
                "message": "Please vote no on HR 100.",
                "referrer_data": {
                    "source": "facebook-101016-mainpage",
                    "referrer": "jane-doe",
                    "website": "facebook.com",
                    "url": "https://facebook.com/posts/12345"
                },
                "targets": [
                    {
                        "title": "Senator",
                        "given_name": "John",
                        "family_name": "Smith",
                        "organization": "U.S. Senate",
                        "ocdid": "ocd-division/country:us/state:ny"
                    },
                    {
                        "title": "Senator",
                        "given_name": "Jennifer",
                        "family_name": "Larson",
                        "organization": "U.S. Senate",
                        "ocdid": "ocd-division/country:us/state:ny",
                        "postal_addresses": [
                            {
                                "primary": true,
                                "address_type": "Home",
                                "address_lines": [
                                    "1900 Pennsylvania Ave"
                                ],
                                "locality": "Washington",
                                "region": "DC",
                                "postal_code": "20009",
                                "country": "US",
                                "language": "en",
                                "location": {
                                    "latitude": 38.919,
                                    "longitude": -77.0379,
                                    "accuracy": "Rooftop"
                                },
                                "last_verified_date": "2014-03-20T21:04:31Z"
                            }
                        ],
                        "email_addresses": [
                            {
                                "primary": true,
                                "address": "johnsmith@mail.com",
                                "address_type": "Personal",
                            }
                        ],
                        "phone_numbers": [
                            {
                                "primary": true,
                                "number": "11234567890",
                                "extension": "432",
                                "description": "Worksite line",
                                "number_type": "Work",
                                "operator": "ATT",
                                "country": "US",
                                "sms_capable": false,
                                "do_not_call": true
                            }
                        ]
                    }
                ],
                "_links": {
                    "self": {
                        "href": "https://osdi-sample-system.org/api/v1/advocacy_campaigns/c945d6fe-929e-11e3-a2e9-12313d316c29/outreaches/d91b4b2e-ae0e-4cd3-9ed7-d0ec501b0bc3"
                    },
                    "osdi:advocacy_campaign": {
                        "href": "https://osdi-sample-system.org/api/v1/advocacy_campaigns/c945d6fe-929e-11e3-a2e9-12313d316c29"
                    },
                    "osdi:person": {
                        "href": "https://osdi-sample-system.org/api/v1/people/65345d7d-cd24-466a-a698-4a7686ef684f"
                    }
                }
            },
            {
                "identifiers": [
                    "osdi_sample_system:1efc3644-af25-4253-90b8-a0baf12dbd1e"
                ],
                "origin_system": "OSDI Sample System",
                "created_date": "2014-03-20T20:44:13Z",
                "modified_date": "2014-03-20T20:44:13Z",
                "action_date": "2014-03-12T01:45:34Z",
                "type": "email",
                "subject": "Don't do it!",
                "message": "Vote no tomorrow!",
                "referrer_data": {
                    "source": "email-101116-subjecttest1"
                },
                "targets": [
                    {
                        "title": "Senator",
                        "given_name": "Jane",
                        "family_name": "Doe",
                        "organization": "U.S. Senate",
                        "ocdid": "ocd-division/country:us/state:va"
                    }
                },
                "_links": {
                    "self": {
                        "href": "https://osdi-sample-system.org/api/v1/advocacy_campaigns/c945d6fe-929e-11e3-a2e9-12313d316c29/outreaches/1efc3644-af25-4253-90b8-a0baf12dbd1e"
                    },
                    "osdi:advocacy_campaign": {
                        "href": "https://osdi-sample-system.org/api/v1/advocacy_campaigns/c945d6fe-929e-11e3-a2e9-12313d316c29"
                    },
                    "osdi:person": {
                        "href": "https://osdi-sample-system.org/api/v1/people/adb951cb-51f9-420e-b7e6-de953195ec86"
                    }
                }
            },
            //(truncated for brevity)
        ]
    }
}

Back to top…

Scenario: 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://osdi-sample-system.org/api/v1/advocacy_campaigns/c945d6fe-929e-11e3-a2e9-12313d316c29/outreaches/d91b4b2e-ae0e-4cd3-9ed7-d0ec501b0bc3

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": [
        "osdi_sample_system:d91b4b2e-ae0e-4cd3-9ed7-d0ec501b0bc3",
        "foreign_system:1"
    ],
    "origin_system": "OSDI Sample System",
    "created_date": "2014-03-20T21:04:31Z",
    "modified_date": "2014-03-20T21:04:31Z",
    "action_date": "2014-03-18T11:02:15Z",
    "type": "email",
    "subject": "Vote no!",
    "message": "Please vote no on HR 100.",
    "referrer_data": {
        "source": "facebook-101016-mainpage",
        "referrer": "jane-doe",
        "website": "facebook.com",
        "url": "https://facebook.com/posts/12345"
    },
    "targets": [
        {
            "title": "Senator",
            "given_name": "John",
            "family_name": "Smith",
            "organization": "U.S. Senate",
            "ocdid": "ocd-division/country:us/state:ny"
        },
        {
            "title": "Senator",
            "given_name": "Jennifer",
            "family_name": "Larson",
            "organization": "U.S. Senate",
            "ocdid": "ocd-division/country:us/state:ny"
        }
    ],
    "_links": {
        "self": {
            "href": "https://osdi-sample-system.org/api/v1/advocacy_campaigns/c945d6fe-929e-11e3-a2e9-12313d316c29/outreaches/d91b4b2e-ae0e-4cd3-9ed7-d0ec501b0bc3"
        },
        "osdi:advocacy_campaign": {
            "href": "https://osdi-sample-system.org/api/v1/advocacy_campaigns/c945d6fe-929e-11e3-a2e9-12313d316c29"
        },
        "osdi:person": {
            "href": "https://osdi-sample-system.org/api/v1/people/65345d7d-cd24-466a-a698-4a7686ef684f"
        }
    }
}

Back to top…

Scenario: Creating a new outreach (POST)

Posting to the outreaches collection endpoint and including a link to an existing Person resource will allow you to create a new outreach associated with that advocacy campaign and person. The response is the new outreach that was created. While each implementing system will require different fields, any optional fields not included in a post operation should not be set at all by the receiving system, or should be set to default values.

For information on how to create a person along with an outreach, see the Record Outreach Helper documentation.

Request

POST https://osdi-sample-system.org/api/v1/advocacy_campaigns/c945d6fe-929e-11e3-a2e9-12313d316c29/outreaches/

Header:
OSDI-API-Token:[your api key here]

{
    "identifiers": [
        "foreign_system:1"
    ],
    "origin_system": "OpenSupporter",
    "action_date": "2014-03-18T11:02:15Z",
    "type": "phone",
    "duration": 120,
    "referrer_data": {
        "source": "api"
    },
    "targets": [
        {
            "title": "Senator",
            "given_name": "John",
            "family_name": "Smith",
            "organization": "U.S. Senate",
            "ocdid": "ocd-division/country:us/state:ny"
        },
        {
            "title": "Senator",
            "given_name": "Jennifer",
            "family_name": "Larson",
            "organization": "U.S. Senate",
            "ocdid": "ocd-division/country:us/state:ny"
        }
    ],
    "_links" : {
        "osdi:person" : { 
            "href" : "https://osdi-sample-system.org/api/v1/people/65345d7d-cd24-466a-a698-4a7686ef684f" 
        }
    }
}

Response

200 OK

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

{
    "identifiers": [
        "osdi_sample_system:d91b4b2e-ae0e-4cd3-9ed7-de9uemdse",
        "foreign_system:1"
    ],
    "created_date": "2014-03-20T21:04:31Z",
    "modified_date": "2014-03-20T21:04:31Z",
    "action_date": "2014-03-18T11:02:15Z",
    "type": "phone",
    "duration": 120,
    "referrer_data": {
        "source": "api"
    },
    "targets": [
        {
            "title": "Senator",
            "given_name": "John",
            "family_name": "Smith",
            "organization": "U.S. Senate",
            "ocdid": "ocd-division/country:us/state:ny"
        },
        {
            "title": "Senator",
            "given_name": "Jennifer",
            "family_name": "Larson",
            "organization": "U.S. Senate",
            "ocdid": "ocd-division/country:us/state:ny"
        }
    ],
    "_links": {
        "self": {
            "href": "https://osdi-sample-system.org/api/v1/advocacy_campaigns/c945d6fe-929e-11e3-a2e9-12313d316c29/outreaches/d91b4b2e-ae0e-4cd3-9ed7-de9uemdse"
        },
        "osdi:advocacy_campaign": {
            "href": "https://osdi-sample-system.org/api/v1/advocacy_campaigns/c945d6fe-929e-11e3-a2e9-12313d316c29"
        },
        "osdi:person": {
            "href": "https://osdi-sample-system.org/api/v1/people/65345d7d-cd24-466a-a698-4a7686ef684f"
        }
    }
}

Back to top…

Scenario: Modifying an outreach (PUT)

You can update an outreach by calling a PUT operation on that outreach’s endpoint. Your PUT should contain fields that you want to update. Missing fields will be ignored by the receiving system. Systems may also ignore PUT values, depending on whether fields you are trying to modify are read-only or not. You may set an attribute to nil by including the attribute using nil for value.

Note: Modifying members of an array separately is not supported. To change the contents of an array, first GET the current contents and then PUT back only those you wish to keep.

Request

PUT https://osdi-sample-system.org/api/v1/advocacy_campaigns/c945d6fe-929e-11e3-a2e9-12313d316c29/outreaches/d91b4b2e-ae0e-4cd3-9ed7-de9uemdse/

Header:
OSDI-API-Token:[your api key here]

{
    "action_date": "2014-03-17T11:02:15Z"
}

Response

200 OK

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

{
    "identifiers": [
        "osdi_sample_system:d91b4b2e-ae0e-4cd3-9ed7-de9uemdse",
        "foreign_system:1"
    ],
    "created_date": "2014-03-20T21:04:31Z",
    "modified_date": "2014-03-20T21:04:31Z",
    "action_date": "2014-03-17T11:02:15Z",
    "type": "phone",
    "duration": 120,
    "referrer_data": {
        "source": "facebook-101016-mainpage",
        "referrer": "jane-doe",
        "website": "facebook.com",
        "url": "https://facebook.com/posts/12345"
    },
    "targets": [
        {
            "title": "Senator",
            "given_name": "John",
            "family_name": "Smith",
            "organization": "U.S. Senate",
            "ocdid": "ocd-division/country:us/state:ny"
        },
        {
            "title": "Senator",
            "given_name": "Jennifer",
            "family_name": "Larson",
            "organization": "U.S. Senate",
            "ocdid": "ocd-division/country:us/state:ny"
        }
    ],
    "_links": {
        "self": {
            "href": "https://osdi-sample-system.org/api/v1/advocacy_campaigns/c945d6fe-929e-11e3-a2e9-12313d316c29/outreaches/d91b4b2e-ae0e-4cd3-9ed7-de9uemdse"
        },
        "osdi:advocacy_campaign": {
            "href": "https://osdi-sample-system.org/api/v1/advocacy_campaigns/c945d6fe-929e-11e3-a2e9-12313d316c29"
        },
        "osdi:person": {
            "href": "https://osdi-sample-system.org/api/v1/people/65345d7d-cd24-466a-a698-4a7686ef684f"
        }
    }
}

Back to top…

Scenario: Deleting an outreach (DELETE)

You may delete an outreach by calling the DELETE command on the outreach’s endpoint.

Request

DELETE https://osdi-sample-system.org/api/v1/advocacy_campaigns/c945d6fe-929e-11e3-a2e9-12313d316c29/outreaches/d91b4b2e-ae0e-4cd3-9ed7-de9uemdse

Header:
OSDI-API-Token:[your api key here]

Response

200 OK

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

{
    "notice": "This outreach was successfully deleted."
}

Back to top…