Signatures Version 2

This document describes the OSDI signatures collection and signature resource as implemented by the Action Network.

Signatures represent the action an activist took when they signed a specific petition.

Signatures can have comments associated with them, and are linked to the person resource corresponding to the activist who signed the petition.

Note: Signatures are deduplicated based on person, so a specific person can only sign a given petition once. And POSTing signatures will not send autoresponses.

Sections:

Endpoints and URL structures

Endpoints:

https://actionnetwork.org/api/v2/petitions/[petition_id]/signatures

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

Signature resources live at endpoints relating to the person who signed the petition and the petition they signed. The endpoints return a collection of all signatures associated with either that person or that petition.

URL Structures:

https://actionnetwork.org/api/v2/petitions/[petition_id]/signatures/[signature_id]

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

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

Back To Top ↑

Field names and descriptions

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

Related resources

Back To Top ↑

Scenario: Retrieving a collection of signature resources (GET)

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

Request

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

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/petitions/9f837109-710d-442f-8a99-857a21f36d25/signatures"
    },
    "osdi:signatures": [
      {
        "href": "https://actionnetwork.org/api/v2/petitions/9f837109-710d-442f-8a99-857a21f36d25/signatures/d6bdf50e-c3a4-4981-a948-3d8c086066d7"
      },
      {
        "href": "https://actionnetwork.org/api/v2/petitions/9f837109-710d-442f-8a99-857a21f36d25/signatures/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": {
    "osdi:signatures": [
      {
        "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:petition_id": "9f837109-710d-442f-8a99-857a21f36d25",
        "_links": {
          "self": {
            "href": "https://actionnetwork.org/api/v2/petitions/9f837109-710d-442f-8a99-857a21f36d25/signatures/d6bdf50e-c3a4-4981-a948-3d8c086066d7"
          },
          "osdi:petition": {
            "href": "https://actionnetwork.org/api/v2/petitions/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",
        "comments": "Stop doing the thing",
        "action_network:person_id": "c945d6fe-929e-11e3-a2e9-12313d316c29",
        "action_network:petition_id": "9f837109-710d-442f-8a99-857a21f36d25",
        "_links": {
          "self": {
            "href": "https://actionnetwork.org/api/v2/petitions/9f837109-710d-442f-8a99-857a21f36d25/signatures/71497ab2-b3e7-4896-af46-126ac7287dab"
          },
          "osdi:petition": {
            "href": "https://actionnetwork.org/api/v2/petitions/9f837109-710d-442f-8a99-857a21f36d25"
          },
          "osdi:person": {
            "href": "https://actionnetwork.org/api/v2/people/c945d6fe-929e-11e3-a2e9-12313d316c29"
          }
        }
      },
      //truncated for brevity
    ]
  }
}
Back To Top ↑

Scenario: Retrieving an individual signature resource (GET)

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

Request

						
GET https://actionnetwork.org/api/v2/petitions/9f837109-710d-442f-8a99-857a21f36d25/signatures/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:petition_id": "9f837109-710d-442f-8a99-857a21f36d25",
  "_links": {
    "self": {
      "href": "https://actionnetwork.org/api/v2/petitions/9f837109-710d-442f-8a99-857a21f36d25/signatures/d6bdf50e-c3a4-4981-a948-3d8c086066d7"
    },
    "osdi:petition": {
      "href": "https://actionnetwork.org/api/v2/petitions/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 signature (POST)

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

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

Either way, signatures are deduplicated by person, so a person can only sign a petition once. Posting a new signature by a person who previously signed the petition will replace the old signature resource with the new one. Posting will also subscribe the person to the lists associated with the petition. For example, if the petition lists an individual account as a creator and a group as a sponsor, the person will be subscribed to both lists when the signature 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 signature linking to an existing person:

Request

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

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


{
  "comments" : "Stop doing the thing",
  "_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",
  "comments": "Stop doing the thing",
  "action_network:person_id": "c945d6fe-929e-11e3-a2e9-12313d316c29",
  "action_network:petition_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/petitions/9f837109-710d-442f-8a99-857a21f36d25/signatures/aa5afb7c-a483-4e94-8dd6-8faab70c6b4c"
    },
    "osdi:petition": {
      "href": "https://actionnetwork.org/api/v2/petitions/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 signature (PUT)

You can modify an existing signature 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/petitions/9f837109-710d-442f-8a99-857a21f36d25/signatures/08837882-ccdc-4d3b-a047-d0badb990876

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


{
  "comments": "Some new comments"
}

Response

						
200 OK

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


{
  "identifiers": [
    "action_network:08837882-ccdc-4d3b-a047-d0badb990876",
  ],
  "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:petition_id": "9f837109-710d-442f-8a99-857a21f36d25",
  "_links": {
    "self": {
      "href": "https://actionnetwork.org/api/v2/petitions/9f837109-710d-442f-8a99-857a21f36d25/signatures/08837882-ccdc-4d3b-a047-d0badb990876"
    },
    "osdi:petition": {
      "href": "https://actionnetwork.org/api/v2/petitions/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 changed the comments.

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 signature. Invalid entries will be ignored.

Back To Top ↑

Scenario: Deleting a signature (DELETE)

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

Back To Top ↑