Unique ID Lists Version 2

This document describes the unique ID lists collection and unique ID list resource as implemented by the Action Network.

Unique ID lists correspond to ID Targets on the user interface, and are a custom list of people (activists) unique IDs created by the group associated with your API key.

Unique ID Lists have names identifying them, a count of the number of people unique IDs they contain, and other metadata such as when they were created.

Unique ID lists are useful for targeting a certain subset of people (activists) already associated with your group. For example, you might have taken your group's list, matched it to some data outside of Action Network, and decided to target an email to a certain subset of activists based on that outside data. If you can create a list of unique activist IDs (available on the SQL mirror, the API, or exported via reports) as the result of that targeting process, you can load that into our system as a unique ID list, and use it to target emails, mobile messages, or reports going forward. This is much quicker, especially at scale, than uploading a list of activists and adding a tag or something similar.

Note: Unique ID lists cannot add new people to your group or otherwise modify people data. They are only a list of already existing people (activist) IDs to be used for targeting.

Sections:

Endpoints and URL structures

Endpoints:

https://actionnetwork.org/api/v2/unique_id_lists

Unique ID list resources live exclusively at the above endpoint. The endpoint returns a collection of all the unique ID lists associated with your API key.

URL Structures:

https://actionnetwork.org/api/v2/unique_id_lists/[id]

To address a specific unique ID list, use the identifier without the action_network: prefix to construct a URL, like https://actionnetwork.org/api/v2/unique_id_lists/d91b4b2e-ae0e-4cd3-9ed7-d0ec501b0bc3

Back To Top ↑

Field names and descriptions

Unique ID list 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.
origin_system string A human readable string identifying where this unique ID list originated. May be used in the user interface for this purpose. Always Action Network. Not editable.
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.
name string Yes The internal name of the unique ID list. Shown to administrators in the interface under ID Targets.
count integer A system generated count of the number of unique IDs in the unique ID list. Not editable.
operation string An operation to be performed on PUT. One of append (which appends the passed unique_ids array to the unique ID list) or replace (which replaces the targets in the unique ID list with what was passed in the unique_ids array). Required on PUT. Will return errors if used on any other operation.
unique_ids strings[] Yes An array of people (activist) unique IDs to include in the unique ID list. People unique IDs can be obtained from the API, the SQL mirror, or exported from the interface via reports. While required on POST and PUT, this field is not shown on GET.
Back To Top ↑

Links

Link Name Description
self A link to this individual unique ID list resource.
Back To Top ↑

Related resources

Back To Top ↑

Scenario: Retrieving a collection of unique ID list resources (GET)

Unique ID list resources are sometimes presented as collections of unique ID lists. For example, calling the unique ID lists endpoint will return a collection of all the unique ID lists associated with your API key.

Request

						
GET https://actionnetwork.org/api/v2/unique_id_lists/

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": 10,
  "per_page": 25,
  "page": 1,
  "total_records": 250,
  "_links": {
    "next": {
      "href": "https://actionnetwork.org/api/v2/unique_id_lists?page=2"
    },
    "self": {
      "href": "https://actionnetwork.org/api/v2/unique_id_lists"
    },
    "action_network:unique_id_lists": [
      {
        "href": "https://actionnetwork.org/api/v2/unique_id_lists/65345d7d-cd24-466a-a698-4a7686ef684f"
      },
      {
        "href": "https://actionnetwork.org/api/v2/unique_id_lists/adb951cb-51f9-420e-b7e6-de953195ec86"
      },
      //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:unique_id_lists": [
      {
        "origin_system": "Action Network",
        "identifiers": [
          "action_network:65345d7d-cd24-466a-a698-4a7686ef684f",
          "my_system:1"
        ],
        "created_date": "2023-03-25T14:40:07Z",
        "modified_date": "2023-03-25T14:47:44Z",
        "name": "Volunteers",
        "count": 25,
        "_links": {
          "self": {
            "href": "https://actionnetwork.org/api/v2/unique_id_lists/65345d7d-cd24-466a-a698-4a7686ef684f"
          }
        }
      },
      {
        "origin_system": "Action Network",
        "identifiers": [
          "action_network:adb951cb-51f9-420e-b7e6-de953195ec86"
        ],
        "created_date": "2023-03-21T23:39:53Z",
        "modified_date": "2023-03-25T15:26:45Z",
        "name": "High dollar donors",
        "count": 6,
        "_links": {
          "self": {
            "href": "https://actionnetwork.org/api/v2/unique_id_lists/adb951cb-51f9-420e-b7e6-de953195ec86"
          }
        }
      },
      //truncated for brevity
    ]
  }
}
Back To Top ↑

Scenario: Retrieving an individual unique ID list resource (GET)

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

Request

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

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:adb951cb-51f9-420e-b7e6-de953195ec86"
  ],
  "created_date": "2023-03-21T23:39:53Z",
  "modified_date": "2023-03-25T15:26:45Z",
  "name": "High dollar donors",
  "count": 6,
  "_links": {
    "self": {
      "href": "https://actionnetwork.org/api/v2/unique_id_lists/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
      }
    ]
  }
}
Back To Top ↑

Scenario: Creating a new unique ID list (POST)

You can post a new unique ID list to the unique ID lists endpoint and a unique ID list resource will be created in our system.

A unique_ids array with at least one member must be included. The array can be as long as you'd like, though arrays of millions of members can take some time to process and return a response, typically on the order of a few minutes. The unique_ids array is not returned as a response to the POST, though the rest of the resource's JSON representation is.

Unique ID lists created in this way will show up in the list of ID targets in the user interface, which can then be used to target emails, mobile messages, or reports.

Request

						
POST https://actionnetwork.org/api/v2/unique_id_lists

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

{	
  "name": "Volunteers",
  "unique_ids": [
    "d8fff9ec-78a4-4c3d-a724-d4bb751abfbb",
    "adb951cb-51f9-420e-b7e6-de953195ec86"
  ]
}

Response

						
200 OK

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


{
  "origin_system": "Action Network",
  "identifiers": [
    "action_network:d8fff9ec-78a4-4c3d-a724-d4bb751abfbb"
  ],
  "created_date": "2023-03-26T21:52:07Z",
  "modified_date": "2023-03-26T21:52:07Z",
  "name": "Volunteers",
  "count": 2,
  "_links": {
    "self": {
      "href": "https://actionnetwork.org/api/v2/unique_id_lists/d8fff9ec-78a4-4c3d-a724-d4bb751abfbb"
    },
    "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 unique ID list (PUT)

You can modify an existing unique ID list by using PUT on its individual endpoint.

An operation field must be passed in your request, as well as a unique_ids array with at least one member. The array can be as long as you'd like, though arrays of millions of members can take some time to process and return a response, typically on the order of a few minutes. The unique_ids array is not returned as a response to the POST, though the rest of the resource's JSON representation is. You may also modify the name of the uniqud ID list if you wish.

An operation field with a value of append will append the array of unique_ids you passed to the existing unique ID list. This allows you to build up a unique ID list from multiple requests. An operation field with a value of replace will delete the existing targets and replace it with the unique_ids you passed. This allows you to replace a unique ID list in place, so users do not have to target a different item in the administrative interface.

Note: You cannot make concurrent API calls to append to the same unique ID list. Doing so will result in errors and each concurrent API call potentially overwriting others.

Request

						
PUT https://actionnetwork.org/api/v2/unique_id_lists/d8fff9ec-78a4-4c3d-a724-d4bb751abfbb

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

{	
  "operation": "append",
  "name": "Updated Volunteers",
  "unique_ids": [
    "d8fff9ec-78a4-4c3d-a724-d4bb751abfbb",
    "adb951cb-51f9-420e-b7e6-de953195ec86"
  ]
}

Response

						
200 OK

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


{
  "origin_system": "Action Network",
  "identifiers": [
    "action_network:d8fff9ec-78a4-4c3d-a724-d4bb751abfbb"
  ],
  "created_date": "2023-03-26T21:52:07Z",
  "modified_date": "2023-03-26T21:52:07Z",
  "name": "Updated Volunteers",
  "count": 4,
  "_links": {
    "self": {
      "href": "https://actionnetwork.org/api/v2/unique_id_lists/d8fff9ec-78a4-4c3d-a724-d4bb751abfbb"
    },
    "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: Deleting a unique ID list (DELETE)

You can delete a unique ID list to remove it from the system.

Request

						
DELETE https://actionnetwork.org/api/v2/unique_id_lists/71f8feef-61c8-4e6b-9745-ec1d7752f298/

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

Response

						
200 OK

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


{
  "notice": "This unique id list was successfully deleted."
}
Back To Top ↑