layout | title |
---|---|
default |
Canvassing Efforts |
This page defines the Canvassing Effort resource.
Canvassing Efforts represent specific canvassing/phone banking events planned for a specific time period. The resource contains information about start and end time, people to be canvassed or called, and a Script that is used for the effort. As people are contacted, Canvass resources are created representing the individual interaction between a canvasser and a person, as well as the data that resulted from that interaction.
{% include endpoints_and_url_structures.md %}
The link relation label for an Canvassing Effort resource is osdi:canvassing_effort
for a single Canvassing Effort resource or osdi:canvassing_efforts
for a collection of Canvassing Effort resources.
{% include fields_intro.md %}
{% include global_fields.md %}
Name | Type | Description |
---|---|---|
origin_system | string | A human readable identifier of the system where this Canvassing Effort was created. (ex: "OSDI System") |
name | string | The name of the Canvassing Effort. Intended for administrative display rather than a public title, though may be shown to a user. |
title | string | The title of the Canvassing Effort. Intended for public display rather than administrative purposes. |
description | string | A description of the Canvassing Effort, usually displayed publicly. May contain text and/or HTML. |
summary | string | A text-only single paragraph summarizing the Canvassing Effort. Shown on listing pages that have more than titles, but not enough room for full description. |
start_time | datetime | The start date and time for the Canvassing Effort. |
end_time | datetime | The end date and time for the Canvassing Effort. |
type | flexenum | The type of the Canvassing Effort. One of "in-person", "phone banking", or another value. |
total_canvasses | integer | A read-only computed property representing the current count of the total number of Canvasses on the Canvassing Effort. |
{% include links_intro.md %}
Name | Type | Description |
---|---|---|
self | Canvassing Effort* | A self-referential link to the canvassing effort. |
creator | Person* | A link to a single Person resource representing the creator of the Canvassing Effort. |
modified_by | Person* | A link to a Person resource representing the last editor of this Canvassing Effort. |
taggings | Taggings[]* | A link to the collection of Tagging resources for this canvassing effort. |
canvasses | Canvasses[]* | A link to a collection of Canvass resources representing the canvasses that occured on this Canvassing Effort. |
script | Script* | A link to the Script resource associated with the Canvassing Effort. |
{% include scenarios_intro.md %}
Canvassing Effort resources are sometimes presented as collections of canvassing efforts. For example, calling the canvassing efforts endpoint will return a collection of all the canvassing efforts stored in the system's database associated with your api key.
GET https://osdi-sample-system.org/api/v1/canvassing_efforts/
Header:
OSDI-API-Token:[your api key here]
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/canvassing_efforts?page=2"
},
"osdi:canvassing_efforts": [
{
"href": "https://osdi-sample-system.org/api/v1/canvassing_efforts/d91b4b2e-ae0e-4cd3-9ed7-d0ec501b0bc3"
},
{
"href": "https://osdi-sample-system.org/api/v1/canvassing_efforts/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/canvassing_efforts"
}
},
"_embedded":
{
"osdi:canvassing_efforts": [
{
"identifiers": [
"osdi_sample_system:a91b4b2e-ae0e-4cd3-9ed7-d0ec501b0bca",
"foreign_system:1"
],
"origin_system": "OSDI Sample System",
"created_date": "2014-03-20T21:04:31Z",
"modified_date": "2014-03-20T21:04:31Z",
"name": "Effort 1",
"title": "Team 1",
"description": "Effort 1 for Team 1",
"summary": "Effort 1 for Team 1",
"start_time": "2016-02-19T8:00:00Z",
"end_time": "2016-02-20T8:00:00Z",
"type": "in_person",
"total_canvasses": 100,
"_links": {
"self": {
"href": "https://osdi-sample-system.org/api/v1/canvassing_efforts/a91b4b2e-ae0e-4cd3-9ed7-d0ec501b0bca"
},
"osdi:creator": {
"href": "https://osdi-sample-system.org/api/v1/people/65345d7d-cd24-466a-a698-4a7686ef684f"
},
"osdi:modified_by": {
"href": "https://osdi-sample-system.org/api/v1/people/c945d6fe-929e-11e3-a2e9-12313d316c29"
},
"osdi:taggings": {
"href": "https://osdi-sample-system.org/api/v1/canvassing_efforts/a91b4b2e-ae0e-4cd3-9ed7-d0ec501b0bca/taggings"
},
"osdi:script": {
"href": "https://osdi-sample-system.org/api/v1/script/d91b4b2e-ae0e-4cd3-9ed7-d0ec501b0ba3"
},
"osdi:canvasses": {
"href": "https://osdi-sample-system.org/api/v1/canvassing_efforts/a91b4b2e-ae0e-4cd3-9ed7-d0ec501b0bca/canvasses"
}
}
},
{
"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",
"name": "Effort 2",
"title": "Team 1",
"description": "Effort 2 for Team 1",
"summary": "Effort 2 for Team 1",
"start_time": "2016-02-19T8:00:00Z",
"end_time": "2016-02-20T8:00:00Z",
"type": "phonebank",
"total_canvasses": 9264,
"_links": {
"self": {
"href": "https://osdi-sample-system.org/api/v1/canvassing_efforts/d91b4b2e-ae0e-4cd3-9ed7-d0ec501b0bc3"
},
"osdi:creator": {
"href": "https://osdi-sample-system.org/api/v1/people/65345d7d-cd24-466a-a698-4a7686ef684f"
},
"osdi:modified_by": {
"href": "https://osdi-sample-system.org/api/v1/people/c945d6fe-929e-11e3-a2e9-12313d316c29"
},
"osdi:script" : {
"href": "https://osdi-sample-system.org/api/v1/script/d91b4b2e-ae0e-4cd3-9ed7-d0ec501b0ba3"
},
"osdi:canvasses": {
"href": "https://osdi-sample-system.org/api/v1/canvassing_efforts/d91b4b2e-ae0e-4cd3-9ed7-d0ec501b0bc3/canvasses"
}
}
},
//truncated for brevity
]
}
}
Calling an individual Canvassing Effort resource will return the resource directly.
GET https://osdi-sample-system.org/api/v1/canvassing_efforts/d91b4b2e-ae0e-4cd3-9ed7-d0ec501b0baa
Header:
OSDI-API-Token:[your api key here]
200 OK
Content-Type: application/hal+json
Cache-Control: max-age=0, private, must-revalidate
{
"identifiers": [
"osdi_sample_system:a91b4b2e-ae0e-4cd3-9ed7-d0ec501b0bca",
"foreign_system:1"
],
"origin_system": "OSDI Sample System",
"created_date": "2014-03-20T21:04:31Z",
"modified_date": "2014-03-20T21:04:31Z",
"name": "Effort 2",
"title": "Team 1",
"description": "Effort 2 for Team 1",
"summary": "Effort 2 for Team 1",
"start_time": "2016-02-19T8:00:00Z",
"end_time": "2016-02-20T8:00:00Z",
"type": "in-person",
"total_canvasses": 100,
"_links": {
"self": {
"href": "https://osdi-sample-system.org/api/v1/canvassing_efforts/d91b4b2e-ae0e-4cd3-9ed7-d0ec501b0bc3"
},
"osdi:creator": {
"href": "https://osdi-sample-system.org/api/v1/people/65345d7d-cd24-466a-a698-4a7686ef684f"
},
"osdi:modified_by": {
"href": "https://osdi-sample-system.org/api/v1/people/c945d6fe-929e-11e3-a2e9-12313d316c29"
},
"osdi:script" : {
"href": "https://osdi-sample-system.org/api/v1/script/d91b4b2e-ae0e-4cd3-9ed7-d0ec501b0ba3"
},
"osdi:canvasses": {
"href": "https://osdi-sample-system.org/api/v1/canvassing_efforts/d91b4b2e-ae0e-4cd3-9ed7-d0ec501b0bc3/canvasses"
}
}
}
Posting to the effort collection endpoint will allow you to create a new Canvassing Effort. The response is the new Canvassing Effort 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.
POST https://osdi-sample-system.org/api/v1/canvassing_efforts/
Header:
OSDI-API-Token:[your api key here]
{
"identifiers": [
"foreign_system:1"
],
"origin_system": "OSDI Sample System",
"name": "Effort 2",
"title": "Team 1",
"description": "Effort 2 for Team 1",
"summary": "Effort 2 for Team 1",
"start_time": "2016-02-19T8:00:00Z",
"end_time": "2016-02-20T8:00:00Z",
"type": "in-person",
"_links": {
"osdi:script": {
"href": "https://osdi-sample-system.org/api/v1/script/d91b4b2e-ae0e-4cd3-9ed7-d0ec501b0ba3"
}
}
}
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",
"name": "Effort 2",
"title": "Team 1",
"description": "Effort 2 for Team 1",
"summary": "Effort 2 for Team 1",
"start_time": "2016-02-19T8:00:00Z",
"end_time": "2016-02-20T8:00:00Z",
"type": "in-person",
"total_canvasses": 0,
"_links": {
"self": {
"href": "https://osdi-sample-system.org/api/v1/canvassing_efforts/d91b4b2e-ae0e-4cd3-9ed7-d0ec501b0bc3"
},
"osdi:creator": {
"href": "https://osdi-sample-system.org/api/v1/people/65345d7d-cd24-466a-a698-4a7686ef684f"
},
"osdi:modified_by": {
"href": "https://osdi-sample-system.org/api/v1/people/c945d6fe-929e-11e3-a2e9-12313d316c29"
},
"osdi:script" : {
"href": "https://osdi-sample-system.org/api/v1/script/d91b4b2e-ae0e-4cd3-9ed7-d0ec501b0ba3"
},
"osdi:canvasses": {
"href": "https://osdi-sample-system.org/api/v1/canvassing_efforts/d91b4b2e-ae0e-4cd3-9ed7-d0ec501b0bc3/canvasses"
}
}
}
You can update an effort by calling a PUT operation on that effort'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.
{% include array_warning.md %}
PUT https://osdi-sample-system.org/api/v1/canvassing_efforts/d91b4b2e-ae0e-4cd3-9ed7-d0ec501b0baa
Header:
OSDI-API-Token:[your api key here]
{
"name": "Effort 2",
"title": "Canvassing Effort 2"
}
200 OK
Content-Type: application/hal+json
Cache-Control: max-age=0, private, must-revalidate
{
"identifiers": [
"osdi_sample_system:a91b4b2e-ae0e-4cd3-9ed7-d0ec501b0bca",
"foreign_system:1"
],
"origin_system": "OSDI Sample System",
"created_date": "2014-03-20T21:04:31Z",
"modified_date": "2014-03-20T21:04:31Z",
"name": "Effort 2",
"title": "Team 1",
"description": "Effort 2 for Team 1",
"summary": "Effort 2 for Team 1",
"start_time": "2016-02-19T8:00:00Z",
"end_time": "2016-02-20T8:00:00Z",
"type": "in-person",
"total_canvasses": 100,
"_links": {
"self": {
"href": "https://osdi-sample-system.org/api/v1/canvassing_efforts/d91b4b2e-ae0e-4cd3-9ed7-d0ec501b0bc3"
},
"osdi:creator": {
"href": "https://osdi-sample-system.org/api/v1/people/65345d7d-cd24-466a-a698-4a7686ef684f"
},
"osdi:modified_by": {
"href": "https://osdi-sample-system.org/api/v1/people/c945d6fe-929e-11e3-a2e9-12313d316c29"
},
"osdi:script" : {
"href": "https://osdi-sample-system.org/api/v1/script/d91b4b2e-ae0e-4cd3-9ed7-d0ec501b0ba3"
},
"osdi:canvasses": {
"href": "https://osdi-sample-system.org/api/v1/canvassing_efforts/d91b4b2e-ae0e-4cd3-9ed7-d0ec501b0bc3/canvasses"
}
}
}
You may delete an effort by calling the DELETE command on the Canvassing Effort's endpoint.
DELETE https://osdi-sample-system.org/api/v1/canvassing_efforts/d32fcdd6-7366-466d-a3b8-7e0d87c3cd8b
Header:
OSDI-API-Token:[your api key here]
200 OK
Content-Type: application/hal+json
Cache-Control: max-age=0, private, must-revalidate
{
"notice": "This canvassing effort was successfully deleted."
}