Using OSDI

OSDI

The Open Supporter Data Interface specifies an API and data structures for interoperability among products in the progressive cause-based, campaign and non-profit marketplace. As a leading technology provider for Democratic and progressive organizations, NGP VAN is proud to play a leading part in this coalition. The NGP VAN OSDI service makes resources from the VAN available via this specification, thereby enabling consumers to reuse API-client code.

Common Models

Getting started

The endpoint for the NGP VAN OSDI service is https://osdi.ngpvan.com.

The service provides data in HAL+JSON format. HAL is a “discoverable” hypermedia format which allows clients to traverse a network of interrelated resources and operate on them in an agreed-upon manner. Links embedded in HAL resources also reference documentation on this site.

All requests to this service must:

  • Send requests using https
  • Use Content-type: application/hal+json

Authentication

To authenticate with the OSDI service, send the following header:

OSDI-API-Token: 56cd877b-bcea-4a96-aaed-7a4ea8711fee|1

The format for the API token is a VAN API key joined to a database mode with a pipe. Use 0 for VoterFile mode, and 1 for MyCampaign mode. In the example above, the VAN API key is 56cd877b-bcea-4a96-aaed-7a4ea8711fee and the service is being accessed in MyCampaign mode.

API Entry Point

The API Entry Point (AEP) is the “starting point” for the OSDI service; from here you can navigate to every other resource in the system, using links embedded in the response and agreed-upon OSDI conventions.

The AEP for the OSDI service is https://osdi.ngpvan.com/api/v1/.

People

Overview

An OSDI Person represents a person who you wish to interact with: a voter, a donor, or a supporter. In the NGP VAN OSDI service, people represent VAN People.

GET/people/{personId}

Retrieve a specific Person
Description

Use this endpoint to retrieve information about a specific Person available in the current context. If you are operating in VoterFile mode, the person returned will be a voter. If you are operating in MyCampaign mode, the person returned will be a donor, volunteer, or other supporter.

Request
GET https://osdi.ngpvan.com/api/v1/people/1111
Response

A standard Person object, if found.

{
    "identifiers": [
        "VAN:777888"
    ],
    "given_name": "Harriet",
    "family_name": "Tubman",
    "additional_name": "R",
    "_links": {
        "self": {
            "href": "https://osdi.ngpvan.com/api/v1/people/777888"
        },
        "osdi:record_canvass_helper": {
            "href": "https://osdi.ngpvan.com/api/v1/people/777888/record_canvass_helper"
        }
    },
    "postal_addresses": [
        {
            "primary": true,
            "address_lines": [
                "123 Freedom Road",
                "Apt. 2",
            ],
            "locality": "Baltimore",
            "region": "MD",
            "postal_code": "21218",
        },
    ],
    "email_addresses": [
        {
            "primary": true,
            "address": "htubman@fake.ngpvan.com"
        },
        {
            "primary": false,
            "address": "harriettubman@gmail.com"
        },
    ],
    "phone_numbers": [
        {
            "primary": true,
            "number": "2345678901",
            "extension": "5125",
        }
    ]
}

POST/people/person_signup_helper

Signup a person as a new supporter
Description

This endpoint makes OSDI Person Signup Helper functionality available, thereby allowing you to create new supporters in the VAN. The endpoint only creates new MyCampaign records, and is therefore only available in MyCampaign mode.

Request

The add_tags property should list the ID of tags that should be added to the created MyCampaign record.

POST https://osdi.ngpvan.com/api/v1/people/person_signup_helper
{
    "person": {
        "additional_name": "Louise",
        "email_addresses": [
            {
                "address": "rcarson@fake.ngpvan.com",
                "primary": true
            },
            {
                "address": "rachelcarson@gmail.com",
                "primary": false
            }
        ],
        "family_name": "Carson",
        "given_name": "Rachel",
        "phone_numbers": [
            {
                "extension": "123",
                "number": "2356789012",
                "primary": true
            }
        ],
        "postal_addresses": [
            {
                "address_lines": [
                    "123 Spring Rd.",
                    "Apt. 3",
                    "c/o Carson Foundation"
                ],
                "locality": "Silver Spring",
                "postal_code": "20902",
                "primary": true,
                "region": "MD"
            }
        ]
    },
    "add_tags": [
        123789,
        456123
    ]
}
Response
{
    "identifiers": [
        "VAN:888777"
    ],
    "given_name": "Rachel",
    "family_name": "Carson",
    "additional_name": "Louise",
    "_links": {
        "self": {
            "href": "https://osdi.ngpvan.com/api/v1/people/888777"
        },
        "osdi:record_canvass_helper": {
            "href": "https://osdi.ngpvan.com/api/v1/people/888777/record_canvass_helper"
        },
    },
    "postal_addresses": [
        {
            "address_lines": [
                "123 Spring Rd",
                "Apt. 3",
                "c/o Carson Foundation"
            ],
            "locality": "Silver Spring",
            "region": "MD",
            "postal_code": "20902",
        }
    ],
    "email_addresses": [
        {
            "primary": true,
            "address": "rcarson@fake.ngpvan.com"
        },
        {
            "primary": false,
            "address": "rachelcarson@fake.ngpvan.com"
        }
    ],
    "phone_numbers": [
        {
            "primary": true,
            "number": "2356789012",
            "extension": "123"
        }
    ]
}

POST/people/{personId}/record_canvass_helper

Record canvass helper
Description

This endpoint makes OSDI Record Signup Helper functionality available, thereby allowing you to record canvass data for people who exist in the VAN. The endpoint is available in both VoterFile and MyCampaign mode.

Request

The canvass object should include a contact_type property of phone or walk. The success property should be true if the contact was reached, or false if not. If the contact was not reached, the status_code must provide the VAN Result Code indicating the reason the contact was not reached. It is not necessary to provide the input_type property of the canvass object, because all requests from this endpoint will be marked with VAN’s API Input Type.

The add_tags property should list the ID of tags that should be added to the created MyCampaign record. The add_answers property should list the paths of questions and the ID of the response for each answer. Because all questions have type SingleChoice, the response property of add_answers should only have one element.

POST https://osdi.ngpvan.com/api/v1/people/999777555/record_canvass_helper
{
  "canvass": {
    "action_date": "2015-08-18T11:02:15Z",
    "contact_type": "phone",
    "success": true,
    "status_code": ""
  },
  "add_tags": [
    4321,
    5678
  ],
  "add_answers": [
    {
      "question": "https://osdi.ngpvan.com/api/v1/questions/200300",
      "responses": [ 333444 ]
    },
    {
      "question": "https://osdi.ngpvan.com/api/v1/questions/300400",
      "responses": [ 111222 ]
    }
  ]
}
Response

This endpoint responds with information about the recorded canvass.

{
    "action_date": "2015-08-18T11:02:15Z",
    "contact_type": "phone",
    "success": true,
    "status_code": "",
    "identifiers": [
        "VAN:999777555"
    ],
    "_links": {
        "osdi:target": {
            "href": "https://osdi.ngpvan.com/api/v1/people/999777555"
        }
    }
}

Tags

Overview

An OSDI Tag is a boolean field used to indicate that a person has some affiliation, interest, or property that you care about. In the NGP VAN OSDI service, tags represent VAN Activist Codes.

GET/tags

Retrieve available Tags
Description

Use this endpoint to retrieve all Tags that are available in the current context.

Request

This endpoint accepts OSDI pagination parameters and returns a standard paginated response.

By default, this endpoint returns 50 records per request. A maximum of 200 records per request is allowed via the per_page parameter.

GET https://osdi.ngpvan.com/api/v1/tags?per_page=75&page=2
Response

This endpoint responds with a standard paged response of Tags.

{
    "total_pages": 1,
    "per_page": 50,
    "page": 1,
    "total_records": 2,
    "_embedded": [
        {
            "origin_system": "VAN",
            "name": "Yard sign",
            "description": "Wants us to provide a yard sign",
            "identifiers": [
                "VAN:999"
            ],
            "_links": {
                "self": {
                    "href": "https://osdi.ngpvan.com/api/v1/tags/999"
                }
            }
        },
        {
            "origin_system": "VAN",
            "name": "Environmentalist",
            "description": "Is an environmentalist",
            "identifiers": [
                "VAN:1111"
            ],
            "_links": {
                "self": {
                    "href": "https://osdi.ngpvan.com/api/v1/tags/1111"
                }
            }
        }
    ]
}

GET/tags/{tagId}

Retrieve a specific Tag
Description

Use this endpoint to retrieve information about a specific Tag available in the current context.

Request
GET https://osdi.ngpvan.com/api/v1/tags/1111
Response

A standard Tag object, if found.

{
    "origin_system": "VAN",
    "name": "Environmentalist",
    "description": "Is an environmentalist",
    "identifiers": [
        "VAN:1111"
    ],
    "_links": {
        "self": {
            "href": "http://osdi.ngpvan.com/api/v1/tags/1111"
        }
    }
}

Questions

Overview

An OSDI Question is a field used to gather some data about a person, e.g. level of support for a candidate, most important issue, etc. In the NGP VAN OSDI service, questions represent VAN Survey Questions. All Questions in the NGP VAN OSDI service are of type SingleChoice. Within each Question, the response property provides available SurveyResponses.

GET/questions

Retrieve available Questions
Description

Use this endpoint to retrieve all Questions that are available in the current context.

Request

This endpoint accepts OSDI pagination parameters and returns a standard paginated response.

By default, this endpoint returns 50 records per request. A maximum of 200 records per request is allowed via the per_page parameter.

GET https://osdi.ngpvan.com/api/v1/questions?per_page=75&page=1
Response

This endpoint responds with a standard paged response of Questions.

{
    "total_pages": 1,
    "per_page": 50,
    "page": 1,
    "total_records": 3,
    "_embedded": [
        {
            "origin_system": "VAN",
            "name": "Abe",
            "description": "Do you support Abraham Lincoln?",
            "title": "Lincoln 1860",
            "summary": "Do you support Abraham Lincoln?",
            "question_type": "SingleChoice",
            "identifiers": [
                "VAN:199888"
            ],
            "_links": {
                "self": {
                    "href": "http://osdi.ngpvan.com/api/v1/questions/199888"
                }
            },
            "responses": [
                {
                    "key": 444555,
                    "name": "Y",
                    "title": "Yes"
                },
                {
                    "key": 444556,
                    "name": "M",
                    "title": "Maybe"
                },
                {
                    "key": 444557,
                    "name": "N",
                    "title": "No"
                }
            ]
        },
        {
            "origin_system": "VAN",
            "name": "Issue",
            "description": "Which issue do you care about most?",
            "title": "Most important issue",
            "summary": "Which issue do you care about most?",
            "question_type": "SingleChoice",
            "identifiers": [
                "VAN:199777"
            ],
            "_links": {
                "self": {
                    "href": "http://osdi.ngpvan.com/api/v1/questions/199777"
                }
            },
            "responses": [
                {
                    "key": 333555,
                    "name": "J",
                    "title": "Jobs"
                },
                {
                    "key": 333556,
                    "name": "E",
                    "title": "Education"
                },
                {
                    "key": 444557,
                    "name": "H",
                    "title": "Health care"
                }
            ]
        }
    ]
}

GET/questions/{questionId}

Retrieve a specific Question
Description

Use this endpoint to retrieve information about a specific Question available in the current context.

Request
GET https://osdi.ngpvan.com/api/v1/questions/111222
Response

A standard Question object, if found.

{
    "origin_system": "VAN",
    "name": "Abe",
    "description": "Do you support Abraham Lincoln?",
    "title": "Lincoln 1860",
    "summary": "Do you support Abraham Lincoln?",
    "question_type": "SingleChoice",
    "identifiers": [
        "VAN:111222"
    ],
    "_links": {
        "self": {
            "href": "http://osdi.ngpvan.com/api/v1/questions/111222"
        }
    },
    "responses": [
        {
            "key": 444555,
            "name": "Y",
            "title": "Yes"
        },
        {
            "key": 444556,
            "name": "M",
            "title": "Maybe"
        },
        {
            "key": 444557,
            "name": "N",
            "title": "No"
        }
    ]
}