Action Builder API -- Getting Started

The Action Builder API is currently in Version 1.

September 17, 2024

• Added the option to remove_tags on person and connection helpers.
• Added the option to view and set more email, phone, and address statuses such as bad and do_not_contact in the status field for addresses and action_builder:confirmed for emails and phones.
• Added the address_type field to postal_addresses, which can be either physical or mailing.

February 1, 2023

• Added a "action_builder:pronouns" field to people, representing that entity's preferred pronouns.

October 25, 2023

• Added a "action_builder:create_tag": true option to the person signup helper and connections helper, which allows you to create new tags if they don't exist while added the tag to a person.

February 2, 2023

• Standardized the field name name at the tags endpoint, person signup helper (when adding tags), and connection helper (when adding tags). action_builder:name will still be accepted on POST tags, person signup helper, and connections helper.

January 4, 2023

• Added the action_builder:latest_assessment and action_builder:latest_assessment_created_date to people.

September 22, 2022

• Added the ability to post tags.
• Added the ability to delete taggings.

September 12, 2022

• Added the ability to delete people from a campaign.
• Added the ability to delete tags from a campaign.

August 31, 2022

• Phone numbers, email addresses, and street addresses now have a source field.

The Action Builder API is served in HAL+JSON format. It generally conforms to the Open Supporter Data Interface (OSDI) specification version 1.2.0, which can be found here.

HAL provides links to make navigation between endpoints and resources easy. In addition, the API is curied, linking directly to documentation within API calls.

The Content-Type: application/json header is generally required when making requests to the API.

We rate limit the API to a maximum of 4 calls per second.

API users are encouraged to queue their API calls and retry failures with exponential backoff, to ensure smooth API operation.

Back To Top ↑

The API Entry Point is the top-level entry point for Action Builder's API. It provides links to the campaigns resource.

An API key is required to access most of the API. Each organization on Action Builder has a separate API key allowing you to access that organization's data.

To retrieve your organization's API key, navigate to the API and Integrations page from the Admin Menu. From there, you can generate a new API key, copy your existing API key, or revoke your API key.

Note: Keep your API key secret. Anyone with your API key will be able to access any data in your account. Therefore, the API is not suitable for JavaScript implementations.

API keys must be sent as a header in this format:

					
OSDI-API-Token: your_api_key_here
			

Back To Top ↑

Once you have your API key, you can try the API using our browser here. Make sure to enter your API key to acces your data.

The OSDI-client library is a javascript/node based library for interacting easily with an OSDI-compliant API like ours.

Because the Action Builder API conforms to the OSDI standard, which is itself a JSON+HAL API, any of the many libraries available in various languages to work with HAL APIs can be used. A great list to get started with us here.

Back To Top ↑

We have a few suggestions to ensure speed and efficiency when using the API:

• Avoid big collections where possible, as they are sometimes slow and will often require lots of calls via paging.
• Make use of oData modified_date queries to only retrieve new records from collections since your last run through the API.
• Because calls slow down the farther down in pages you go (ex: page 10 will be much faster to retrieve than page 10,000), prefer to retrieve records from the API more often rather than less often to limit the number of pages you'll need to go through. For example, run your code to pull newly modified records every hour rather than every day.

Back To Top ↑

Almost everything in the Action Builder API is a resource. An individual person is a resource, as is a tagging, as is a connection.

People resources have an array of identifiers -- one and only one generated by Action Builder when that resource is created, as well as any custom identifiers you have passed in when you create resources using POST or modify them using PUT. The Action Builder identifier is deduplicated globally, across organizations and API keys. Custom identifiers are not deduplicated. You should only use custom identifiers if you need to match back to your system. Identifiers cannot be removed once they are created, but you can have more than one identifier.

Action Builder ships the following custom identifiers, which are used as prefixes. The custom value must be made of alphanumeric characters, dashes, and underscores and comes after the colon:

• dwid:
• custom_id:
• custom_id_1:
• custom_id_2:
• custom_id_3:
• custom_id_4:
• voterbase_id:

For example, your custom identifier may look like custom_id:a1b2-c3d4-e5f6.

Administrators can add new custom identifiers in the user interface with a chosen unique prefix, or archive (and thus hide) once they no longer want to use. The list of valid identifier prefixes is currently not available on the API. Talk to your administrators about what is in use.

All resources also have created_date and modified_date fields, created by our system, and a hash of _links pointing to various URL endpoints that are related to that resource, including at least one pointing to itself (the self link).

Here is an example of a person resource with a native and foreign identifier, created_date and modified_date fields, and links to various related resources:

					 
{
 "origin_system": "Action Builder",
 "identifiers": [
   "action_builder:124698f6-3496-4141-a39d-d51a174cc907",
   "custom_id:1b2c3d"
 ],
 "created_date": "2021-06-10T13:58:59.260Z",
 "modified_date": "2021-12-22T15:33:45.856Z",
 "action_builder:entity_type": "Person",
 "given_name": "Lily",
 "family_name": "Morrison",
 "action_builder:nickname": "The Yellow Dart",
 "browser_url": "https://techworkersunited.actionbuilder.org/entity/view/164/profile?campaignId=11415",
 "preferred_language": "en",
 "postal_addresses": [
   {
     "action_builder:identifier": "action_builder:fca729b9-d855-4043-9d8a-888fa7af95b6",
     "address_lines": [
       "97 Sutherland Alley"
     ],
     "locality": "Wilmington",
     "region": "NC",
     "postal_code": "55110",
     "country": "US",
	 "address_type": "physical"
   }
 ],
 "email_addresses": [
   {
     "action_builder:identifier": "action_builder:b1e48fad-0a8e-4694-b6f1-9e2783e5a6c7",
     "address": "[email protected]",
     "address_type": "Home"
   }
 ],
 "_links": {
   "curies": [
     {
       "name": "osdi",
       "href": "https://actionbuilder.org/docs/v1/{rel}",
       "templated": true
     },
     {
       "name": "action_builder",
       "href": "https://actionbuilder.org/docs/v1/{rel}",
       "templated": true
     }
   ],
   "self": {
     "href": "https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/84a684a7-2f5a-4359-bdb4-898ce4fbc88f/people/124698f6-3496-4141-a39d-d51a174cc907"
   },
   "action_builder:campaign": {
     "href": "https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/84a684a7-2f5a-4359-bdb4-898ce4fbc88f"
   },
   "action_builder:entity_type": {
     "href": "https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/84a684a7-2f5a-4359-bdb4-898ce4fbc88f/entity_types/786888a8-868f-4694-a3ba-1caf0688d0c0"
   },
   "action_builder:connections": {
     "href": "https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/84a684a7-2f5a-4359-bdb4-898ce4fbc88f/people/124698f6-3496-4141-a39d-d51a174cc907/connections"
   },
   "osdi:taggings": {
     "href": "https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/84a684a7-2f5a-4359-bdb4-898ce4fbc88f/people/124698f6-3496-4141-a39d-d51a174cc907/taggings"
   }
 }
}
					
				

Back To Top ↑

An array of resources is called a collection. A URL endpoint may return a collection of resources. For example, visiting https://actionbuilder.org/api/rest/v1/campaigns/:id/people will return a collection of people corresponding to the specified campaign and associated with your api key.

Individual resources in a collection are both embedded in the array and linked to in the links section, allowing for easy browsing and navigation.

Here is an example of the campaigns collection:

				
{
  "per_page": 25,
  "page": 1,
  "total_pages": 458,
  "_embedded": {
    "action_builder:campaigns": [
      {
        "origin_system": "Action Builder",
        "identifiers": [
          "action_builder:12e0d956-3414-418f-87b4-ffcea28d71ce"
        ],
        "name": "DC Local Organizing",
        "created_date": "2021-09-28T15:15:58.393Z",
        "modified_date": "2021-09-28T15:15:58.393Z",
        "target_number": 5000,
        "total_number": 3578,
        "archived": false,
        "_links": {
          "self": {
            "href": "https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/12e0d956-3414-418f-87b4-ffcea28d71ce"
          },
          "action_builder:entity_types": {
            "href": "https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/12e0d956-3414-418f-87b4-ffcea28d71ce/entity_types"
          },
          "action_builder:connection_types": {
            "href": "https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/12e0d956-3414-418f-87b4-ffcea28d71ce/connection_types"
          },
          "osdi:tags": {
            "href": "https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/12e0d956-3414-418f-87b4-ffcea28d71ce/tags"
          },
          "osdi:people": {
            "href": "https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/12e0d956-3414-418f-87b4-ffcea28d71ce/people"
          }
        }
      },
      {
        "origin_system": "Action Builder",
        "identifiers": [
          "action_builder:5d5bca74-b62c-4c65-8e74-89fc9b69bd3a"
        ],
        "name": "MD Local Organizing",
        "created_date": "2021-09-09T18:26:08.277Z",
        "modified_date": "2021-09-09T18:26:08.277Z",
        "target_number": 200,
        "total_number": 93,
        "archived": false,
        "_links": {
          "self": {
            "href": "https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/5d5bca74-b62c-4c65-8e74-89fc9b69bd3a"
          },
          "action_builder:entity_types": {
            "href": "https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/5d5bca74-b62c-4c65-8e74-89fc9b69bd3a/entity_types"
          },
          "action_builder:connection_types": {
            "href": "https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/5d5bca74-b62c-4c65-8e74-89fc9b69bd3a/connection_types"
          },
          "osdi:tags": {
            "href": "https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/5d5bca74-b62c-4c65-8e74-89fc9b69bd3a/tags"
          },
          "osdi:people": {
            "href": "https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/5d5bca74-b62c-4c65-8e74-89fc9b69bd3a/people"
          }
        }
      },
      {
        "origin_system": "Action Builder",
        "identifiers": [
          "action_builder:8f5e83b8-ebf1-4c63-ad5a-aa5335d0d96e"
        ],
        "name": "VA Local Organizing",
        "created_date": "2021-09-09T18:25:30.486Z",
        "modified_date": "2021-09-09T18:25:30.486Z",
        "target_number": 1000,
        "total_number": 364,
        "archived": false,
        "_links": {
          "self": {
            "href": "https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/8f5e83b8-ebf1-4c63-ad5a-aa5335d0d96e"
          },
          "action_builder:entity_types": {
            "href": "https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/8f5e83b8-ebf1-4c63-ad5a-aa5335d0d96e/entity_types"
          },
          "action_builder:connection_types": {
            "href": "https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/8f5e83b8-ebf1-4c63-ad5a-aa5335d0d96e/connection_types"
          },
          "osdi:tags": {
            "href": "https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/8f5e83b8-ebf1-4c63-ad5a-aa5335d0d96e/tags"
          },
          "osdi:people": {
            "href": "https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/8f5e83b8-ebf1-4c63-ad5a-aa5335d0d96e/people"
          }
        }
      },
     //truncated for brevity
    ]
  "_links": {
     "self": {
        "href": "https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns"
      },
     "previous": {
        "href": "https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns?page=457&per_page=25"
      },
     "curies": [
        {
          "name": "osdi",
          "href": "https://actionbuilder.org/docs/v1/{rel}",
          "templated": true
        },
        {
          "name": "action_builder",
          "href": "https://actionbuilder.org/docs/v1/{rel}",
          "templated": true
        }
    ],
  "action_builder:campaigns": [
    {
      "href": "https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/d69744cd-1bfa-463b-b642-7a5e8ca19c5f"
    },
    {
      "href": "https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/f8efd437-5887-40cc-9ffb-5aa7f4cd0699"
    },
    {
      "href": "https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/9415a397-9197-49a2-98f0-b2cb2385cfac"
    },
    {
      "href": "https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/ef9b1418-0568-4d15-8881-d71eb3248414"
    },
    {
      "href": "https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/bd06a0d6-9bf0-4dc8-861d-5af5bc678a60"
    },
    {
      "href": "https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/4dd2adc4-bac4-4345-a30d-7e4faa362683"
    },
    {
      "href": "https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/dc7734ea-628f-43d1-b0ed-811a1e73b845"
    },
    {
      "href": "https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/6d688e9d-fd5d-443f-83df-484fc95734d9"
    },
    {
      "href": "https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/5649128c-fdf4-4154-93ff-2198d9272021"
    }
  ]
 }
}
				
			

Back To Top ↑

By default we will return 25 resources per page when querying a collection. You can adjust the number of items returned by using the ?per_page=number_of_items_per_page URL argument. Note: You can retrieve a maximum of 25 resources per page.

To move through pages, use the previous and next links in the link section, or use the ?page=page_number URL argument to jump to a specific page

Back To Top ↑

A curie section is included with each API response. Curies are templated links that allow you to quickly find documentation on resources.

Curies are related to resources labeled in the [curie name]:[URI fragment] format. For example, if a resource is labeled with the code osdi:person you would find the curie labeled "osdi" and then add people to the templated URL.

For example, here is a person resource:

				
{
 "origin_system": "Action Builder",
 "identifiers": [
   "action_builder:124698f6-3496-4141-a39d-d51a174cc907",
   "custom_id:1b2c3d"
 ],
 "created_date": "2021-06-10T13:58:59.260Z",
 "modified_date": "2021-12-22T15:33:45.856Z",
 "action_builder:entity_type": "Person",
 "given_name": "Lily",
 "family_name": "Morrison",
 "action_builder:nickname": "The Yellow Dart",
 "browser_url": "https://techworkersunited.actionbuilder.org/entity/view/164/profile?campaignId=11415",
 "preferred_language": "en",
 "postal_addresses": [
   {
     "action_builder:identifier": "action_builder:fca729b9-d855-4043-9d8a-888fa7af95b6",
     "address_lines": [
       "97 Sutherland Alley"
     ],
     "locality": "Wilmington",
     "region": "NC",
     "postal_code": "55110",
	 "address_type": "physical",
     "country": "US"
   }
 ],
 "email_addresses": [
   {
     "action_builder:identifier": "action_builder:b1e48fad-0a8e-4694-b6f1-9e2783e5a6c7",
     "address": "[email protected]",
     "address_type": "Home"
   }
 ],
 "_links": {
   "curies": [
     {
       "name": "osdi",
       "href": "https://actionbuilder.org/docs/v1/{rel}",
       "templated": true
     },
     {
       "name": "action_builder",
       "href": "https://actionbuilder.org/docs/v1/{rel}",
       "templated": true
     }
   ],
   "self": {
     "href": "https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/84a684a7-2f5a-4359-bdb4-898ce4fbc88f/people/124698f6-3496-4141-a39d-d51a174cc907"
   },
   "action_builder:campaign": {
     "href": "https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/84a684a7-2f5a-4359-bdb4-898ce4fbc88f"
   },
   "action_builder:entity_type": {
     "href": "https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/84a684a7-2f5a-4359-bdb4-898ce4fbc88f/entity_types/786888a8-868f-4694-a3ba-1caf0688d0c0"
   },
   "action_builder:connections": {
     "href": "https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/84a684a7-2f5a-4359-bdb4-898ce4fbc88f/people/124698f6-3496-4141-a39d-d51a174cc907/connections"
   },
   "osdi:taggings": {
     "href": "https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/84a684a7-2f5a-4359-bdb4-898ce4fbc88f/people/124698f6-3496-4141-a39d-d51a174cc907/taggings"
   }
 }
}
				
			

To look up documentation on, say, the osdi:taggings link, you would find the curie named "osdi" and add taggings on to the end of the specified link to create https://actionbuilder.org/docs/v1/taggings, which is the link to documentation about this resource.

Curies also serve as namespaces. For example, things labeled osdi:[resource] correspond to the OSDI specification. Things labeled action_builder:[resource] are namespaced resources that appear in the Action Builder API but are not part of the OSDI specification.

Back To Top ↑

Each page of documentation about a specific resource contains charts showing all of the field names for that resource, their type, whether they are required, and a description about what they represent.

When describing elements of a JSON hash, dot notation will be used. For example, take this hash:

	
{
  "object" : {
    "name" : "this object has a name",
    "value" : "this object has a value"
  }
}
						

The "object" hash will appear as a named type in the main chart describing each field. It will be linked to a smaller chart below showing the fields within that hash.

Type may include definitions such as string or datetime. Field types can also be arrays, which are noted with the [] notation. If the array is an array of JSON hashes, then the array is named (ex: email_addresses[]) and linked to the chart below describing the fields in the hash. Otherwise, it will be notated as an array of a certain type, such as an array of strings, represented as strings[].

Finally, field types can be an embedded resource, which will be noted with a *, such as Person*, and linked to the documentation on that resource.

Back To Top ↑

Generally, the Action Builder API supports RESTful Create/Read/Update/Delete (CRUD) operations. However, only certain resources will respond to certain operations.

To create new resources, use POST. Generally, you post to endpoints of collections, such as https://actionbuilder.org/api/rest/v1/campaigns/[campaign_id]/people to create a new person.

When you need to associate a resource you are creating via POST to another existing resource, you would post a link to that other resource in a _links section of your POST message. However, some collections have special "helper" links that are labeled as such. These helpers are used for creating or updating two resources at the same time (such as a new person to be added to the list and a connection to an other entity). This is explained in more detail (with examples) in each helper's documentation.

To view a resource or a collection, use GET on its endpoint.

To edit or update resources, use PUT. Generally, you update on endpoints identifying individual resources, not endpoints associated with collections of resources. Only some fields may be update-able. For examples, see the documentation on individual resources.

PUT operations will attempt to upsert data. No data will be removed unless it is explicitly nulled using null as a value. Some fields cannot be removed.

POST and PUT operations should include the Content-Type set to application/json along with your API key, like so:

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

To delete resources, use DELETE. Generally, you delete on endpoints identifying individual resources, not endpoints associated with collections of resources. Only some resources are delete-able. For examples, see the documentation on individual resources.

Back To Top ↑

The Action Builder API supports basic filtering using a small subset of the OData query language.

The use cases we generally support have to do with finding individual resources by identifying characteristics, or finding collections of newly created or updated resources. This facilitates updating specific resources and syncing data between systems.

OData queries are url arguments and take the format ?filter=field_name operator 'value'.

The following operations are supported:

Operations

The following field names can be used for filtering on specific resources:

Resources and supported field names

Back To Top ↑