Responses Version 2

This document describes the OSDI responses collection and response resource as implemented by the Action Network.

Responses represent the action an activist took when they filled out a specific survey.

Responses are linked to the person resource corresponding to the activist who filled out the survey.

Sections:

Endpoints and URL structures

Endpoints:

https://actionnetwork.org/api/v2/surveys/[survey_id]/responses

https://actionnetwork.org/api/v2/people/[person_id]/responses

Response resources live at endpoints relating to the person who filled out the survey and the survey they signed. The endpoints return a collection of all responses associated with either that person or that survey.

URL Structures:

https://actionnetwork.org/api/v2/surveys/[survey_id]/responses/[response_id]

https://actionnetwork.org/api/v2/people/[person_id]/responses/[response_id]

To address a specific response, use the identifier without the action_network: prefix to construct a URL, like https://actionnetwork.org/api/v2/surveys/d91b4b2e-ae0e-4cd3-9ed7-d0ec501b0bc3/responses/167ce1d2-70b7-423e-b480-914981cbeaff

Back To Top ↑

Field names and descriptions

Response fields:
Field Name Type Required on POST Description
identifiers strings[] An array of identifiers in the format [system name]:[id]. Must be globally unique. See the general concepts document for more information about identifiers.
created_date datetime The date and time the resource was created. System generated, not editable.
modified_date datetime The date and time the resource was last modified. System generated, not editable.
action_network:person_id string The native Action Network identifier associated with the person who filled out this survey. Action Network-only feature. System generated, not editable.
action_network:survey_id string The native Action Network identifier associated with the survey this response was left on. Action Network-only feature. System generated, not editable.
action_network:referrer_data Referrer Data A hash of referrer data such as source code and referrer code. Action Network-only.
Referrer Data fields:
Field Name Type Required on POST Description
source string The source code of this response. 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 response. 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 response. Equivalent to someone taking action after clicking a link on the listed website. Corresponds to the websites chart in this action's manage page. Action Network-only.
email_referrer string The ID of the email that brought someone to the link to take action. Action Networks adds the ?email_referrer=[your email referrer] URL parameter on the links sent through the emailer. Pass that value back in your API calls here to mark this action as having taken place because of a response to that email.
mobile_message_referrer string The ID of the mobile message that brought someone to the link to take action. Action Networks adds the ?mobile_message_referrer=[your mobile referrer] URL parameter on the links sent through mobile messages. Pass that value back in your API calls here to mark this action as having taken place because of a response to that message.
Back To Top ↑

Links

Link Name Description
self A link to this individual response resource.
osdi:person A link to the person who made this response. Click here for people documentation.
action_network:survey A link to the survey this response was left on. Note: If this response was created via a referral code, this link may not be accessible because your API key does not give you permission to access the survey itself. Click here for survey documentation.
Back To Top ↑

Related resources

Back To Top ↑

Scenario: Retrieving a collection of response resources (GET)

Response resources are sometimes presented as collections of responses. For example, calling the responses endpoint on a specific survey will return a collection of all the responses associated with that survey.

Request

						
GET https://actionnetwork.org/api/v2/surveys/9f837109-710d-442f-8a99-857a21f36d25/responses

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": 100,
  "per_page": 25,
  "page": 1,
  "total_records": 2500,
  "_links": {
    "self": {
      "href": "https://actionnetwork.org/api/v2/surveys/9f837109-710d-442f-8a99-857a21f36d25/responses"
    },
    "action_network:responses": [
      {
        "href": "https://actionnetwork.org/api/v2/surveys/9f837109-710d-442f-8a99-857a21f36d25/responses/d6bdf50e-c3a4-4981-a948-3d8c086066d7"
      },
      {
        "href": "https://actionnetwork.org/api/v2/surveys/9f837109-710d-442f-8a99-857a21f36d25/responses/71497ab2-b3e7-4896-af46-126ac7287dab"
      },
      //truncated for brevity
    ],
    "curies": [
      {
        "name": "osdi",
        "href": "https://actionnetwork.org/docs/v2/{rel}",
        "templated": true
      },
      {
        "name": "action_network",
        "href": "https://actionnetwork.org/docs/v2/{rel}",
        "templated": true
      }
    ]
  },
  "_embedded": {
    "action_network:responses": [
      {
        "identifiers": [
          "action_network:d6bdf50e-c3a4-4981-a948-3d8c086066d7"
        ],
        "created_date": "2014-03-26T18:04:00Z",
        "modified_date": "2014-03-26T18:04:00Z",
        "action_network:person_id": "699da712-929f-11e3-a2e9-12313d316c29",
        "action_network:survey_id": "9f837109-710d-442f-8a99-857a21f36d25",
        "_links": {
          "self": {
            "href": "https://actionnetwork.org/api/v2/surveys/9f837109-710d-442f-8a99-857a21f36d25/responses/d6bdf50e-c3a4-4981-a948-3d8c086066d7"
          },
          "action_network:survey": {
            "href": "https://actionnetwork.org/api/v2/surveys/9f837109-710d-442f-8a99-857a21f36d25"
          },
          "osdi:person": {
            "href": "https://actionnetwork.org/api/v2/people/699da712-929f-11e3-a2e9-12313d316c29"
          }
        }
      },
      {
        "identifiers": [
          "action_network:71497ab2-b3e7-4896-af46-126ac7287dab"
        ],
        "created_date": "2014-03-26T16:07:10Z",
        "modified_date": "2014-03-26T16:07:10Z",
        "action_network:person_id": "c945d6fe-929e-11e3-a2e9-12313d316c29",
        "action_network:survey_id": "9f837109-710d-442f-8a99-857a21f36d25",
        "_links": {
          "self": {
            "href": "https://actionnetwork.org/api/v2/surveys/9f837109-710d-442f-8a99-857a21f36d25/responses/71497ab2-b3e7-4896-af46-126ac7287dab"
          },
          "action_network:survey": {
            "href": "https://actionnetwork.org/api/v2/surveys/9f837109-710d-442f-8a99-857a21f36d25"
          },
          "osdi:person": {
            "href": "https://actionnetwork.org/api/v2/surveys/c945d6fe-929e-11e3-a2e9-12313d316c29"
          }
        }
      },
      //truncated for brevity
    ]
  }
}
Back To Top ↑

Scenario: Retrieving an individual response resource (GET)

Calling an individual response resource will return the resource directly, along with all associated fields and appropriate links to additional information about the response.

Request

						
GET https://actionnetwork.org/api/v2/surveys/9f837109-710d-442f-8a99-857a21f36d25/responses/d6bdf50e-c3a4-4981-a948-3d8c086066d7

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": [
    "action_network:d6bdf50e-c3a4-4981-a948-3d8c086066d7"
  ],
  "created_date": "2014-03-26T18:04:00Z",
  "modified_date": "2014-03-26T18:04:00Z",
  "action_network:person_id": "699da712-929f-11e3-a2e9-12313d316c29",
  "action_network:survey_id": "9f837109-710d-442f-8a99-857a21f36d25",
  "_links": {
    "self": {
      "href": "https://actionnetwork.org/api/v2/surveys/9f837109-710d-442f-8a99-857a21f36d25/responses/d6bdf50e-c3a4-4981-a948-3d8c086066d7"
    },
    "action_network:survey": {
      "href": "https://actionnetwork.org/api/v2/surveys/9f837109-710d-442f-8a99-857a21f36d25"
    },
    "osdi:person": {
      "href": "https://actionnetwork.org/api/v2/people/699da712-929f-11e3-a2e9-12313d316c29"
    },
    "curies": [
      {
        "name": "osdi",
        "href": "https://actionnetwork.org/docs/v2/{rel}",
        "templated": true
      },
      {
        "name": "action_network",
        "href": "https://actionnetwork.org/docs/v2/{rel}",
        "templated": true
      }
    ]
  }
}
Back To Top ↑

Scenario: Creating a new response (POST)

You can POST a new response to a survey with that survey's response endpoint and a response resource will be created in our system.

When you post a response, you can either link to an existing person to register that this person took this survey, or you can post information about a new person inline to the special record_response_helper endpoint, to both create a new person and register that they took the survey at the same time. You can learn more about the record response helper here.

Either way, posting will also subscribe the person to the lists associated with the survey. For example, if the survey lists an individual account as a creator and a group as a sponsor, the person will be subscribed to both lists when the response is created. Currently multiple sponsors are not supported.

Background processing is available on this operation via the background_request=true URL argument. You can learn more about background processing here.

Note: POSTing responses will not send autoresponses.

Here is an example of posting a response linking to an existing person:

Request

						
POST https://actionnetwork.org/api/v2/surveys/9f837109-710d-442f-8a99-857a21f36d25/responses/

Header:
Content-Type: application/json
OSDI-API-Token: your_api_key_here


{
  "_links" : {
    "osdi:person" : { "href" : "https://actionnetwork.org/api/v2/people/c945d6fe-929e-11e3-a2e9-12313d316c29" }
  }
}

Response

						
200 OK

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


{
  "identifiers": [
    "action_network:aa5afb7c-a483-4e94-8dd6-8faab70c6b4c"
  ],
  "created_date": "2014-03-26T18:11:03Z",
  "modified_date": "2014-03-26T18:11:23Z",
  "action_network:person_id": "c945d6fe-929e-11e3-a2e9-12313d316c29",
  "action_network:survey_id": "9f837109-710d-442f-8a99-857a21f36d25",
  "_links": {
    "osdi:person": {
      "href": "https://actionnetwork.org/api/v2/people/c945d6fe-929e-11e3-a2e9-12313d316c29"
    },
    "self": {
      "href": "https://actionnetwork.org/api/v2/surveys/9f837109-710d-442f-8a99-857a21f36d25/responses/aa5afb7c-a483-4e94-8dd6-8faab70c6b4c"
    },
    "action_network:survey": {
      "href": "https://actionnetwork.org/api/v2/surveys/9f837109-710d-442f-8a99-857a21f36d25"
    },
    "curies": [
      {
        "name": "osdi",
        "href": "https://actionnetwork.org/docs/v2/{rel}",
        "templated": true
      },
      {
        "name": "action_network",
        "href": "https://actionnetwork.org/docs/v2/{rel}",
        "templated": true
      }
    ]
  }
}
Back To Top ↑

Scenario: Modifying a response (PUT)

You can modify an existing response by using PUT on its individual endpoint.

Background processing is available on this operation via the background_request=true URL argument. You can learn more about background processing here.

Request

						
PUT https://actionnetwork.org/api/v2/surveys/9f837109-710d-442f-8a99-857a21f36d25/responses/08837882-ccdc-4d3b-a047-d0badb990876

Header:
Content-Type: application/json
OSDI-API-Token: your_api_key_here


{
  "identifiers": [
    "other-system:230125s"
  ]
}

Response

						
200 OK

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


{
  "identifiers": [
    "action_network:08837882-ccdc-4d3b-a047-d0badb990876",
	"other-system:230125s"
  ],
  "created_date": "2014-03-26T18:16:43Z",
  "modified_date": "2014-03-26T18:20:33Z",
  "comments": "Some new comments",
  "action_network:person_id": "17be9a36-bb9a-4f68-94a8-40523b9dab27",
  "action_network:survey_id": "9f837109-710d-442f-8a99-857a21f36d25",
  "_links": {
    "self": {
      "href": "https://actionnetwork.org/api/v2/surveys/9f837109-710d-442f-8a99-857a21f36d25/responses/08837882-ccdc-4d3b-a047-d0badb990876"
    },
    "action_network:survey": {
      "href": "https://actionnetwork.org/api/v2/surveys/9f837109-710d-442f-8a99-857a21f36d25"
    },
    "osdi:person": {
      "href": "https://actionnetwork.org/api/v2/people/17be9a36-bb9a-4f68-94a8-40523b9dab27"
    },
    "curies": [
      {
        "name": "osdi",
        "href": "https://actionnetwork.org/docs/v2/{rel}",
        "templated": true
      },
      {
        "name": "action_network",
        "href": "https://actionnetwork.org/docs/v2/{rel}",
        "templated": true
      }
    ]
  }
}

The above example added a new identifier to the response. Identifiers are deduplicated globally, across groups and API keys, so ensure any you set are globally unique.

Editing of certain fields via PUT is not allowed, and is noted in the field names table above. For example, you can't change the person who is associated with this response. Invalid entries will be ignored.

Back To Top ↑

Scenario: Deleting a response (DELETE)

Deleting responses is not allowed via the API. DELETE requests will return an error.

Back To Top ↑