Submissions Version 2

This document describes the OSDI submissions collection and submission resource as implemented by the Action Network.

Submissions represent the action an activist took when they submitted a specific form.

Submissions are linked to the person resource corresponding to the activist who submitted the form.

Note: Submissions are deduplicated based on person, so a specific person can only submit to a given form once. And POSTing submissions will not send autoresponses.

Sections:

Endpoints and URL structures

Endpoints:

https://actionnetwork.org/api/v2/forms/[form_id]/submissions

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

Submission resources live at endpoints relating to the person who submitted the form and the form they signed. The endpoints return a collection of all submissions associated with either that person or that form.

URL Structures:

https://actionnetwork.org/api/v2/forms/[form_id]/submissions/[submission_id]

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

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

Back To Top ↑

Field names and descriptions

Submission 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 submitted on this form. Action Network-only feature. System generated, not editable.
action_network:form_id string The native Action Network identifier associated with the form this submission 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 submission. 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 submission. 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 submission. 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 submission resource.
osdi:person A link to the person who made this submission. Click here for people documentation.
osdi:form A link to the form this submission was left on. Note: If this submission was created via a referral code, this link may not be accessible because your API key does not give you permission to access the form itself. Click here for form documentation.
Back To Top ↑

Related resources

Back To Top ↑

Scenario: Retrieving a collection of submission resources (GET)

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

Request

						
GET https://actionnetwork.org/api/v2/forms/adb951cb-51f9-420e-b7e6-de953195ec86/submissions

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": 1,
  "per_page": 25,
  "page": 1,
  "total_records": 4,
  "_links": {
    "self": {
      "href": "https://actionnetwork.org/api/v2/forms/adb951cb-51f9-420e-b7e6-de953195ec86/submissions"
    },
    "osdi:submissions": [
      {
        "href": "https://actionnetwork.org/api/v2/forms/adb951cb-51f9-420e-b7e6-de953195ec86/submissions/c851b31b-291e-4503-b8ea-e51a740e6e56"
      },
      {
        "href": "https://actionnetwork.org/api/v2/forms/adb951cb-51f9-420e-b7e6-de953195ec86/submissions/32dc6359-76fd-4e97-aef7-f053a4fcc550"
      },
      //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": {
    "osdi:submissions": [
      {
        "identifiers": [
          "action_network:c851b31b-291e-4503-b8ea-e51a740e6e56"
        ],
        "created_date": "2014-03-25T15:26:45Z",
        "modified_date": "2014-03-25T15:26:46Z",
        "action:person_id": "d3e27e15-e5b5-4707-be96-8bc359462133",
        "action_network:form_id": "adb951cb-51f9-420e-b7e6-de953195ec86",
        "_links": {
          "self": {
            "href": "https://actionnetwork.org/api/v2/forms/adb951cb-51f9-420e-b7e6-de953195ec86/submissions/c851b31b-291e-4503-b8ea-e51a740e6e56"
          },
          "osdi:form": {
            "href": "https://actionnetwork.org/api/v2/forms/adb951cb-51f9-420e-b7e6-de953195ec86"
          },
          "osdi:person": {
            "href": "https://actionnetwork.org/api/v2/people/d3e27e15-e5b5-4707-be96-8bc359462133"
          }
        }
      },
      {
        "identifiers": [
          "action_network:4bf4254a-9411-4028-8cb7-a7d3ade5edea",
          "free_forms:1"
        ],
        "created_date": "2014-03-24T17:00:42Z",
        "modified_date": "2014-03-24T17:00:42Z",
        "action:person_id": "c945d6fe-929e-11e3-a2e9-12313d316c29",
        "action_network:form_id": "adb951cb-51f9-420e-b7e6-de953195ec86",
        "_links": {
          "self": {
            "href": "https://actionnetwork.org/api/v2/forms/adb951cb-51f9-420e-b7e6-de953195ec86/submissions/4bf4254a-9411-4028-8cb7-a7d3ade5edea"
          },
          "osdi:form": {
            "href": "https://actionnetwork.org/api/v2/forms/adb951cb-51f9-420e-b7e6-de953195ec86"
          },
          "osdi:person": {
            "href": "https://actionnetwork.org/api/v2/people/c945d6fe-929e-11e3-a2e9-12313d316c29"
          }
        }
      },
      //truncated for brevity
    ]
  }
}
Back To Top ↑

Scenario: Retrieving an individual submission resource (GET)

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

Request

						
GET https://actionnetwork.org/api/v2/forms/adb951cb-51f9-420e-b7e6-de953195ec86/submissions/c851b31b-291e-4503-b8ea-e51a740e6e56

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:c851b31b-291e-4503-b8ea-e51a740e6e56"
  ],
  "created_date": "2014-03-25T15:26:45Z",
  "modified_date": "2014-03-25T15:26:46Z",
  "action:person_id": "d3e27e15-e5b5-4707-be96-8bc359462133",
  "action_network:form_id": "adb951cb-51f9-420e-b7e6-de953195ec86",
  "_links": {
    "self": {
      "href": "https://actionnetwork.org/api/v2/forms/adb951cb-51f9-420e-b7e6-de953195ec86/submissions/c851b31b-291e-4503-b8ea-e51a740e6e56"
    },
    "osdi:form": {
      "href": "https://actionnetwork.org/api/v2/forms/adb951cb-51f9-420e-b7e6-de953195ec86"
    },
    "osdi:person": {
      "href": "https://actionnetwork.org/api/v2/people/d3e27e15-e5b5-4707-be96-8bc359462133"
    },
    "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 submission (POST)

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

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

Either way, submission are deduplicated by person, so a person can only submit a form once. Posting a new submission by a person who previously submitted the form will replace the old submission resource with the new one. Posting will also subscribe the person to the lists associated with the form. For example, if the form lists an individual account as a creator and a group as a sponsor, the person will be subscribed to both lists when the submission 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 signatures will not send autoresponses.

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

Request

						
POST https://actionnetwork.org/api/v2/forms/adb951cb-51f9-420e-b7e6-de953195ec86/submissions/

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:42d8e92f-f88a-4bd1-bc67-3c91474295c1"
  ],
  "created_date": "2014-03-27T14:04:28Z",
  "modified_date": "2014-03-27T14:04:28Z",
  "action:person_id": "c945d6fe-929e-11e3-a2e9-12313d316c29",
  "action_network:form_id": "adb951cb-51f9-420e-b7e6-de953195ec86",
  "_links": {
    "osdi:person": {
      "href": "https://actionnetwork.org/api/v2/people/c945d6fe-929e-11e3-a2e9-12313d316c29"
    },
    "self": {
      "href": "https://actionnetwork.org/api/v2/forms/adb951cb-51f9-420e-b7e6-de953195ec86/submissions/42d8e92f-f88a-4bd1-bc67-3c91474295c1"
    },
    "osdi:form": {
      "href": "https://actionnetwork.org/api/v2/forms/adb951cb-51f9-420e-b7e6-de953195ec86"
    },
    "curies": [
      {
        "name": "osdi",
        "href": "https://actionnetwork.org/docs/v2/{rel}",
        "templated": true
      },
      {
        "name": "action_network",
        "href": "https://actionnetwork.org/docs/v2/{rel}",
        "templated": true
      }
    ]
  }
}

And of course you can POST a submission with more fields (such as referrer data) if you'd like, but they are not required.

Back To Top ↑

Scenario: Modifying a submission (PUT)

You can modify an existing submission 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/forms/adb951cb-51f9-420e-b7e6-de953195ec86/submissions/c449e8cd-0a81-42d1-91f7-47cacf33dbe4

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:c449e8cd-0a81-42d1-91f7-47cacf33dbe4",
    "other-system:230125s"
  ],
  "created_date": "2014-03-27T14:05:44Z",
  "modified_date": "2014-03-27T14:07:36Z",
  "action:person_id": "17be9a36-bb9a-4f68-94a8-40523b9dab27",
  "action_network:form_id": "adb951cb-51f9-420e-b7e6-de953195ec86",
  "action_network:referrer_data": {
    "source": "api"
  }
  "_links": {
    "self": {
      "href": "https://actionnetwork.org/api/v2/forms/adb951cb-51f9-420e-b7e6-de953195ec86/submissions/c449e8cd-0a81-42d1-91f7-47cacf33dbe4"
    },
    "osdi:form": {
      "href": "https://actionnetwork.org/api/v2/forms/adb951cb-51f9-420e-b7e6-de953195ec86"
    },
    "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 submission. 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 submission. Invalid entries will be ignored.

Back To Top ↑

Scenario: Deleting a submission (DELETE)

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

Back To Top ↑