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.
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 |
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. |
Related Objects
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”) |
Links
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. |
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. |
Related Resources
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)
]
}
}
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"
}
}
}
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"
}
}
}
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"
}
}
}
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."
}