Questions Version 1

Note: This documentation describes Version 1 of our API, which is now depreciated. It will continue to work, but it will not reveive any updates or bug fixes. We recommend you use Version 2 instead. In Version 2, questions (and question answers) have been removed, and are replaced by custom field hash objects on person resources. Documentation for people for Version 2 of our API is available here.

This document describes the OSDI questions collection and question resource as implemented by the Action Network.

Questions are created by the organizer or group associated with your API key and represent a question that activists are asked to answer. Questions map to the names of the Action Network's custom form field system, so named HTML inputs on forms will show up in the API as questions, and custom column headings on uploads will show up as questions as well. Questions will only appear in the interface once they have at least one question answer associated with them.

Questions have names and other fields, and when activists answer them question answer resources are created representing the answer an activist made to that question.

Note: Questions are deduplicated on name, so posting a question with the same name as another will merge the two resources.

Sections:

Endpoints and URL structures

Endpoints:

https://actionnetwork.org/api/v1/questions

Question resources live exclusively at the above endpoint. The endpoint returns a collection of all the questions associated with your API key.

URL Structures:

https://actionnetwork.org/api/v1/questions/[id]

To address a specific question, use the identifier without the action_network: prefix to construct a URL, like https://actionnetwork.org/api/v1/questions/d91b4b2e-ae0e-4cd3-9ed7-d0ec501b0bc3

Back To Top ↑

Field names and descriptions

Field Name Type Required on POST Description
identifiers array[] An array of identifiers in the format [system name]:[id]. See the general concepts document for more information about identifiers.
originating_system string Yes A human readable string identifying where this question originated. May be used in the user interface for this purpose.
created_at datetime The date and time the resource was created. System generated, not editable.
modified_at datetime The date and time the resource was last modified. System generated, not editable.
name string Yes The question's name.
question_type enum The format of the question. One of ["Paragraph" "MultiChoice"]. System generated, always Paragraph, not editable.
Back To Top ↑

Links

Link Name Description
self A link to this individual question resource.
osdi:question_answers A link to a collection of all question answer resources associated with this question. Click here for question answers documentation.
Back To Top ↑

Scenario: Retrieving a collection of petition resources (GET)

Petition resources are sometimes presented as collections of petitions. For example, calling the petitions endpoint will return a collection of all the petitions associated with your API key.

Request

						
GET https://actionnetwork.org/api/v1/questions

Header:
api-key:[your api key here]

Response

						
200 OK

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


{
  "total_pages": 20,
  "per_page": 25,
  "page": 1,
  "total_records": 490,
  "_links": {
    "next": {
      "href": "https://actionnetwork.org/api/v1/questions?page=2"
    },
    "self": {
      "href": "https://actionnetwork.org/api/v1/questions"
    },
    "osdi:questions": [
      {
        "href": "https://actionnetwork.org/api/v1/questions/6ca859fc-4801-4aad-8d4b-c793826ba4c3"
      },
      {
        "href": "https://actionnetwork.org/api/v1/questions/16a5adba-e356-4476-a9f4-3ce0ebd41b6c"
      },
      //truncated for brevity
    ],
    "curies": [
      {
        "name": "osdi",
        "href": "https://actionnetwork.org/docs/v1/{rel}",
        "templated": true
      },
      {
        "name": "action_network",
        "href": "https://actionnetwork.org/docs/v1/{rel}",
        "templated": true
      }
    ]
  },
  "_embedded": {
    "osdi:questions": [
      {
        "identifiers": [
          "action_network:6ca859fc-4801-4aad-8d4b-c793826ba4c3"
        ],
        "originating_system": "Action Network",
        "name": "Your story",
        "question_type": "Paragraph",
        "created_at": "2014-03-27T14:24:22Z",
        "modified_at": "2014-03-27T14:24:22Z",
        "_links": {
          "self": {
            "href": "https://actionnetwork.org/api/v1/questions/6ca859fc-4801-4aad-8d4b-c793826ba4c3"
          },
          "osdi:question_answers": {
            "href": "https://actionnetwork.org/api/v1/questions/6ca859fc-4801-4aad-8d4b-c793826ba4c3/question_answers"
          }
        }
      },
      {
        "identifiers": [
          "action_network:16a5adba-e356-4476-a9f4-3ce0ebd41b6c"
        ],
        "originating_system": "Action Network",
        "name": "I am a parent",
        "question_type": "Paragraph",
        "created_at": "2014-03-27T14:24:22Z",
        "modified_at": "2014-03-27T14:24:22Z",
        "_links": {
          "self": {
            "href": "https://actionnetwork.org/api/v1/questions/16a5adba-e356-4476-a9f4-3ce0ebd41b6c"
          },
          "osdi:question_answers": {
            "href": "https://actionnetwork.org/api/v1/questions/16a5adba-e356-4476-a9f4-3ce0ebd41b6c/question_answers"
          }
        }
      },
      //truncated for brevity
    ]
  }
}
Back To Top ↑

Scenario: Retrieving an individual question resource (GET)

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

Request

						
GET https://actionnetwork.org/api/v1/questions/6ca859fc-4801-4aad-8d4b-c793826ba4c3

Header:
api-key:[your api key here]

Response

						
200 OK

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


{
  "identifiers": [
    "action_network:6ca859fc-4801-4aad-8d4b-c793826ba4c3"
  ],
  "originating_system": "Action Network",
  "name": "Your story",
  "question_type": "Paragraph",
  "created_at": "2014-03-27T14:24:22Z",
  "modified_at": "2014-03-27T14:24:22Z",
  "_links": {
    "self": {
      "href": "https://actionnetwork.org/api/v1/questions/6ca859fc-4801-4aad-8d4b-c793826ba4c3"
    },
    "osdi:question_answers": {
      "href": "https://actionnetwork.org/api/v1/questions/6ca859fc-4801-4aad-8d4b-c793826ba4c3/question_answers"
    },
    "curies": [
      {
        "name": "osdi",
        "href": "https://actionnetwork.org/docs/v1/{rel}",
        "templated": true
      },
      {
        "name": "action_network",
        "href": "https://actionnetwork.org/docs/v1/{rel}",
        "templated": true
      }
    ]
  }
}
Back To Top ↑

Scenario: Creating a new question (POST)

You can post a new question to the questions endpoint and a question resource will be created in our system.

Request

						
POST https://actionnetwork.org/api/v1/questions

Header:
Content-Type: application/json
api-key:[your api key here]
						

{	
  "identifiers": [
    "free_questions:1"
  ],
  "name": "What is your favorite color and why?",
  "originating_system": "FreeQuestions.com"
}

Response

						
200 OK

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


{
  "originating_system": "FreeQuestions.com",
  "identifiers": [
    "free_questions:1",
    "action_network:22723cb7-03fa-4187-954b-1debba177e69"
  ],
  "name": "What is your favorite color and why?",
  "question_type": "Paragraph",
  "created_at": "2014-03-27T18:56:18Z",
  "modified_at": "2014-03-27T18:56:18Z",
  "_links": {
    "self": {
      "href": "https://actionnetwork.org/api/v1/questions/22723cb7-03fa-4187-954b-1debba177e69"
    },
    "osdi:question_answers": {
      "href": "https://actionnetwork.org/api/v1/questions/22723cb7-03fa-4187-954b-1debba177e69/question_answers"
    },
    "curies": [
      {
        "name": "osdi",
        "href": "https://actionnetwork.org/docs/v1/{rel}",
        "templated": true
      },
      {
        "name": "action_network",
        "href": "https://actionnetwork.org/docs/v1/{rel}",
        "templated": true
      }
    ]
  }
}

In the above example, you can see how the foreign identifier being posted is merged into the identifiers array. We will intelligently search and deduplicate based on foreign and native identifiers. So if you post a question with an identifier that matches one already assigned to a question resource, your POST request will update that resource with new information instead of creating a duplicate.

And as a reminder, questions are deduplicated on name, so if you post a new question with the same name as an existing one, we will merge your new data with the existing question instead of creating a new resource.

Back To Top ↑

Scenario: Modifying a question (PUT)

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

Request

						
PUT https://actionnetwork.org/api/v1/questions/22723cb7-03fa-4187-954b-1debba177e69

Header:
Content-Type: application/json
api-key:[your api key here]
						

{	
  "identifiers": [
    "free_questions:2"
  ]
}

Response

						
200 OK

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


{
  "originating_system": "FreeQuestions.com",
  "identifiers": [
    "free_questions:1",
    "action_network:22723cb7-03fa-4187-954b-1debba177e69",
    "free_questions:2"
  ],
  "name": "What is your favorite color and why?",
  "question_type": "Paragraph",
  "created_at": "2014-03-27T18:56:18Z",
  "modified_at": "2014-03-27T18:57:22Z",
  "_links": {
    "self": {
      "href": "https://actionnetwork.org/api/v1/questions/22723cb7-03fa-4187-954b-1debba177e69"
    },
    "osdi:question_answers": {
      "href": "https://actionnetwork.org/api/v1/questions/22723cb7-03fa-4187-954b-1debba177e69/question_answers"
    },
    "curies": [
      {
        "name": "osdi",
        "href": "https://actionnetwork.org/docs/v1/{rel}",
        "templated": true
      },
      {
        "name": "action_network",
        "href": "https://actionnetwork.org/docs/v1/{rel}",
        "templated": true
      }
    ]
  }
}

The above example added a new identifier to the question.

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 question type -- that is a system generated property. Invalid entries will be ignored.

Back To Top ↑

Scenario: Deleting a question (DELETE)

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

Back To Top ↑