Signatures 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. Documentation for this resource for Version 2 of our API is available here.

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.

Sections:

Endpoints and URL structures

Endpoints:

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

https://actionnetwork.org/api/v1/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/v1/petitions/[petition_id]/signatures/[signature_id]

https://actionnetwork.org/api/v1/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/v1/petitions/d91b4b2e-ae0e-4cd3-9ed7-d0ec501b0bc3/signatures/167ce1d2-70b7-423e-b480-914981cbeaff

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 signature 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.
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 hash A hash of referrer data such as source code and referrer code. Action Network-only.
action_network:referrer_data.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.
action_network:referrer_data.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.
action_network:referrer_data.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.
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 ↑

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/v1/petitions/9f837109-710d-442f-8a99-857a21f36d25/signatures

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": 100,
  "per_page": 25,
  "page": 1,
  "total_records": 2500,
  "_links": {
    "self": {
      "href": "https://actionnetwork.org/api/v1/petitions/9f837109-710d-442f-8a99-857a21f36d25/signatures"
    },
    "record_signatures_helper": {
      "href": "https://actionnetwork.org/api/v1/petitions/9f837109-710d-442f-8a99-857a21f36d25/signatures"
    },
    "osdi:signatures": [
      {
        "href": "https://actionnetwork.org/api/v1/petitions/9f837109-710d-442f-8a99-857a21f36d25/signatures/d6bdf50e-c3a4-4981-a948-3d8c086066d7"
      },
      {
        "href": "https://actionnetwork.org/api/v1/petitions/9f837109-710d-442f-8a99-857a21f36d25/signatures/71497ab2-b3e7-4896-af46-126ac7287dab"
      },
      //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:signatures": [
      {
        "identifiers": [
          "action_network:d6bdf50e-c3a4-4981-a948-3d8c086066d7"
        ],
        "originating_system": "Action Network",
        "created_at": "2014-03-26T18:04:00Z",
        "modified_at": "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/v1/petitions/9f837109-710d-442f-8a99-857a21f36d25/signatures/d6bdf50e-c3a4-4981-a948-3d8c086066d7"
          },
          "osdi:petition": {
            "href": "https://actionnetwork.org/api/v1/petitions/9f837109-710d-442f-8a99-857a21f36d25"
          },
          "osdi:person": {
            "href": "https://actionnetwork.org/api/v1/people/699da712-929f-11e3-a2e9-12313d316c29"
          }
        }
      },
      {
        "identifiers": [
          "action_network:71497ab2-b3e7-4896-af46-126ac7287dab"
        ],
        "originating_system": "FreePetitionSite.com",
        "created_at": "2014-03-26T16:07:10Z",
        "modified_at": "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/v1/petitions/9f837109-710d-442f-8a99-857a21f36d25/signatures/71497ab2-b3e7-4896-af46-126ac7287dab"
          },
          "osdi:petition": {
            "href": "https://actionnetwork.org/api/v1/petitions/9f837109-710d-442f-8a99-857a21f36d25"
          },
          "osdi:person": {
            "href": "https://actionnetwork.org/api/v1/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/v1/petitions/9f837109-710d-442f-8a99-857a21f36d25/signatures/d6bdf50e-c3a4-4981-a948-3d8c086066d7

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:d6bdf50e-c3a4-4981-a948-3d8c086066d7"
  ],
  "originating_system": "Action Network",
  "created_at": "2014-03-26T18:04:00Z",
  "modified_at": "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/v1/petitions/9f837109-710d-442f-8a99-857a21f36d25/signatures/d6bdf50e-c3a4-4981-a948-3d8c086066d7"
    },
    "osdi:petition": {
      "href": "https://actionnetwork.org/api/v1/petitions/9f837109-710d-442f-8a99-857a21f36d25"
    },
    "osdi:person": {
      "href": "https://actionnetwork.org/api/v1/people/699da712-929f-11e3-a2e9-12313d316c29"
    },
    "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 signature (POST)

You can post a new signature to a petition with that petition's signatures 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_signatures_helper endpoint, to both create a new person and register that they signed the petition at the same time.

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.

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

Request

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

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

{
  "identifiers": [
    "free_petitions:1"
  ],
  "comments" : "Stop doing the thing",
  "originating_system" : "FreePetitions.com",
  "_links" : {
    "osdi:person" : { "href" : "https://actionnetwork.org/api/v1/people/c945d6fe-929e-11e3-a2e9-12313d316c29" }
  }
}

Response

						
200 OK

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


{
  "identifiers": [
    "free_petitions:1",
    "action_network:aa5afb7c-a483-4e94-8dd6-8faab70c6b4c"
  ],
  "originating_system": "FreePetitions.com",
  "created_at": "2014-03-26T18:11:03Z",
  "modified_at": "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/v1/people/c945d6fe-929e-11e3-a2e9-12313d316c29"
    },
    "self": {
      "href": "https://actionnetwork.org/api/v1/petitions/9f837109-710d-442f-8a99-857a21f36d25/signatures/aa5afb7c-a483-4e94-8dd6-8faab70c6b4c"
    },
    "osdi:petition": {
      "href": "https://actionnetwork.org/api/v1/petitions/9f837109-710d-442f-8a99-857a21f36d25"
    },
    "curies": [
      {
        "name": "osdi",
        "href": "https://actionnetwork.org/docs/v1/{rel}",
        "templated": true
      },
      {
        "name": "action_network",
        "href": "https://actionnetwork.org/docs/v1/{rel}",
        "templated": true
      }
    ]
  }
}

And here is an example of posting a signature with person data inlined to the special record_signatures_helper link on the signatures collection:

Request

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

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

{
  "identifiers": [
    "free_petitions:2"
  ],
  "comments" : "Stop doing the thing",
  "originating_system" : "FreePetitions.com",
  "person" : {
    "family_name" : "Smith",
    "given_name" : "John",
    "postal_addresses" : [ { "postal_code" : "20009" }],
    "email_addresses" : [ { "address" : "jsmith@mail.com" }]
  }
}

Response

						
200 OK

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


{
  "identifiers": [
    "free_petitions:2",
    "action_network:c7630707-34f2-48ee-a6c2-46214b94663a"
  ],
  "originating_system": "FreePetitions.com",
  "created_at": "2014-03-26T18:14:04Z",
  "modified_at": "2014-03-26T18:14:04Z",
  "comments": "Stop doing the thing",
  "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/v1/petitions/9f837109-710d-442f-8a99-857a21f36d25/signatures/c7630707-34f2-48ee-a6c2-46214b94663a"
    },
    "osdi:petition": {
      "href": "https://actionnetwork.org/api/v1/petitions/9f837109-710d-442f-8a99-857a21f36d25"
    },
    "osdi:person": {
      "href": "https://actionnetwork.org/api/v1/people/17be9a36-bb9a-4f68-94a8-40523b9dab27"
    },
    "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, a new person was created and their signature added to the petition at the same time. We deduplicate new people added this way by email address, so if the email posted corresponded with a person already in the system, we would update their record instead of creating a new person. The required fields for person remain the same -- email address and postal code -- and any posts missing that information will fail.

Note: The record_signatures_helper link is currently the same as the signatures collection, but that may not always be the case. Check the link to know exactly where to post.

And of course you can post a signature with more fields (such as address lines for your inline person data) if you'd like, but they are not required.

Back To Top ↑

Scenario: Modifying a signature (PUT)

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

Request

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

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

{	
  "identifiers": [
    "free_petitions:5"
  ],
  "comments": "Some new comments"
}

Response

						
200 OK

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


{
  "identifiers": [
    "free_petitions:3",
    "action_network:08837882-ccdc-4d3b-a047-d0badb990876",
    "free_petitions:5"
  ],
  "originating_system": "FreePetitions.com",
  "created_at": "2014-03-26T18:16:43Z",
  "modified_at": "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/v1/petitions/9f837109-710d-442f-8a99-857a21f36d25/signatures/08837882-ccdc-4d3b-a047-d0badb990876"
    },
    "osdi:petition": {
      "href": "https://actionnetwork.org/api/v1/petitions/9f837109-710d-442f-8a99-857a21f36d25"
    },
    "osdi:person": {
      "href": "https://actionnetwork.org/api/v1/people/17be9a36-bb9a-4f68-94a8-40523b9dab27"
    },
    "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 signature and 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 ↑