People
The people endpoint accesses entity resources in a campaign. All entities of any type are accessible at the people endpoint. Entities enable you to organize and track the people & groups most important to your organization, in the way that makes the most sense for your organizers. People represent different entities who have been added to the database via the API, uploads, or other means. Every campaign starts with a people entity, and you can add more to represent other groups such as nonprofit organization, union local, or workplace.
Entities of every type are available at the people endpoint. You can use filtering to search by entity type and some other field names.
Resources at the people endpoint can have custom identifiers. You can use the custom identifiers in addition to the built-in action_builder identifier to match to an external system. The identifiers must be prefixed with one of the following and the custom value must be made of alphanumeric characters, dashes, and underscores:
dwid:custom_id:custom_id_1:custom_id_2:custom_id_3:custom_id_4:voterbase_id:
For example, your custom identifeir may look like custom_id:a1b2-c3d4-e5f6. More on identifiers here.
- Endpoints and URL Structures
- Field Names and Descriptions
- Links
- Related Resources
- Scenario: Retrieving a Collection of People Resources (GET)
- Scenario: Retrieving an Individual Person Resource (GET)
- Scenario: Creating a New Person Resource (POST)
- Scenario: Modifying an Individual Person Resource (PUT)
- Scenario: Deleting an Individual Person Resource (DELETE)
Endpoints and URL Structures
https://[your-sub-domain].actionbuilder.org/api/rest/v1/campaigns/[campaign_id]/people
People resources live exclusively at the above endpoint. The endpoint returns a collection of all the people associated with your API key and specified campaign.
URL Structures:
https://[your-sub-domain].actionbuilder.org/api/rest/v1/campaigns/[campaign_id]/people/[person_id]
To address a specific person, use the resource type name like:
https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/84a684a7-2f5a-4359-bdb4-898ce4fbc88f/people/60df91c0-edf5-4eea-b5d7-ec6f699e7e8f
Field Names and Descriptions
People Fields
| Field Name | Type | Required on POST | Description |
|---|---|---|---|
| origin_system | string | A human readable string identifying where this person originated. | |
| identifiers | strings[] | An array of the read-only Action Builder Identifier and any foreign identifiers in the format [system name]:[id]. Any custom foreign identifier you add must only have alphanumeric characters and dashes or underscores. 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_builder:entity_type | string | The entity type of this resource. Default is the primary entity type, usually people. | |
| given_name | string | Yes, or name | The person's first name. This field is will only appear if it is enabled by that entity type. |
| family_name | string | The person's last name. This field will only appear if it is enabled by that entity type. | |
| additional_name | string | An additional name not included in family or given. Usually a middle name. This field will only appear if it is enabled for that entity type. | |
| action_builder:nickname | string | The person's preferred name. This field will only appear if it is enabled by that entity type. | |
| name | string | Yes, or given_name | The person's name. This field is will only appear if it is enabled by that entity type. |
| action_builder:pronouns | string | The person's preferred pronouns. This field will only appear if it is enabled for that entity type. | |
| browser_url | string | A URL string pointing to the person or entity's administrative page in the UI. | |
| action_builder:latest_assessment | integer | The most recent assessment level of this entity. Assessment level must already exist in Action Builder. Will not appear if blank. | |
| action_builder:latest_assessment_created_date | datetime | The date and time the latest assessment was created. Action Builder only. System generated, not editable. | |
| preferred_language | string | The two digit language code for the language this person prefers. This field will only appear if it is enabled by that entity type. | |
| postal_addresses | postal_addresses[] | An array of postal address object hashes associated with the person. This field will only appear if it is enabled by that entity type. | |
| phone_numbers | phone_numbers[] | An array of phone number object hashes associated with the person. This field will only appear if it is enabled by that entity type. | |
| email_addresses | email_addresses[] | An array of email address object hashes associated with the person. This field will only appear if it is enabled by that entity type. | |
| birthdate | birthdate | An object representing the birthdate of the person. This field will only appear if it is enabled by that entity type. |
Postal Addresses Fields
| Field Name | Type | Required on POST | Description |
|---|---|---|---|
| action_builder:identifier | string | The read-only identifier for this postal address in the format [system name]:[id]. See the general concepts document for more information about identifiers. |
|
| postal_addresses.address_lines | string[] | An array of strings representing the person’s street address. There can be a maximum two items in the array, equating to two address lines. | |
| postal_addresses.locality | string | A city or other local administrative area. | |
| postal_addresses.region | string | The state or region represented by the two digit abbreviation. Only supports US and Canada. | |
| postal_addresses.postal_code | string | The region specific postal code, such as a zip code. | |
| postal_addresses.country | string | The country code according to ISO 3166-1 Alpha-2. Only supports US or CA. |
|
| postal_addresses.status | string | A value representing the status of the address. "Verified" if confirmed or null. | |
| postal_addresses.source | string | The origin of this postal address. System generated, not editable. |
Phone Numbers Fields
| Field Name | Type | Required on POST | Description |
|---|---|---|---|
| action_builder:identifier | string | The read-only identifier for this phone number in the format [system name]:[id]. See the general concepts document for more information about identifiers. |
|
| phone_numbers.number | string | The phone number of the person. Must including country code and must be numeric characters only. | |
| phone_numbers.extention | string | An optional associated extension for the number. | |
| phone_numbers.number_type | enum | The type of phone number. One of "Home", "Work" or "Mobile". Default is "Mobile". | |
| phone_numbers.status | enum | Indicates whether this phone number is subscribed to receive messages in the system. "Subscribed" or null. | |
| phone_numbers.action_builder:confirmed | string | A value representing the status of the phone number. "Verified" if confirmed or null. | |
| phone_numbers.source | string | The origin of this phone number. System generated, not editable. |
Email Address Fields
| Field Name | Type | Required on POST | Description |
|---|---|---|---|
| action_builder:identifier | string | The read-only identifier for this email address in the format [system name]:[id]. See the general concepts document for more information about identifiers. |
|
| email_addresses.address | string | The email address for the person. | |
| email_addresses.address_type | flexnum | The type of email address. One of “home” or “work”, default is "home". | |
| email_addresses.status | enum | Indicates whether this email address is subscribed to receive emails in the system, either on one or more email lists. "subscribed" or null. | |
| email_addresses.action_builder:confirmed | string | A value representing the status of the email address. "Verified" if confirmed or null. | |
| email_addresses.source | string | The origin of this email address. System generated, not editable. |
Birthdate Fields
| Field Name | Type | Required on POST | Description |
|---|---|---|---|
| birthdate.month | integer | An integer representing the month of the birth date of the person. | |
| birthdate.day | integer | An integer representing the day of the birth date of the person. | |
| birthdate.year | integer | An integer representing the 4 digit year of the birth date of the person. | |
| birthdate.age | integer | An integer representing the age of the person. |
Back To Top ↑
Links
| Link Name | Description |
|---|---|
| self | A link to this individual person resource. |
| action_builder:campaign | A link to the campaign this person type is in. Click here for campaigns documentation. |
| action_builder:entity_types | A link to the entity types forming this connection. Click here for entity types documentation. |
| action_builder:connections | An array of strings representing connections that involve this person or entity. Click here for connections documentation. |
| osdi:taggings | An array of strings representing tags on the person or entity's record. Click here for taggings documentation. |
Back To Top ↑
Related Resources
Scenario: Retrieving a collection of people resources (GET)
People resources are sometimes presented as collections of people. For example, calling the people endpoint will return a collection of all the people associated with that API key and specified campaign.
Request
GET https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/84a684a7-2f5a-4359-bdb4-898ce4fbc88f/people
Header:
OSDI-API-Token: your_api_key_here
Response
{
"per_page": 25,
"page": 1,
"total_pages": 1,
"_embedded": {
"osdi:people": [
{
"origin_system": "Action Builder",
"identifiers": [
"action_builder:60df91c0-edf5-4eea-b5d7-ec6f699e7e8f",
"custom_id_2:1111"
],
"created_date": "2021-12-06T18:40:18.829Z",
"modified_date": "2022-12-16T15:20:39.770Z",
"action_builder:entity_type": "person",
"given_name": "Lily",
"family_name": "Morrison",
"additional_name": "Lillian",
"action_builder:nickname": "The Yellow Dart",
"action_builder:pronouns": "she/her",
"browser_url": "https://techworkersunited.actionbuilder.org/entity/view/483/profile?campaignId=11415",
"action_builder:latest_assessment": 4,
"action_builder:latest_assessment_created_date": "2022-12-16T15:20:39.770Z",
"preferred_language": "en",
"postal_addresses": [
{
"action_builder:identifier": "action_builder:8eb308d6-9b2a-45a4-ba4d-14dca9a1d020",
"locality": "Wilmington",
"region": "NC",
"postal_code": "55110",
"country": "US",
"status": "verified"
}
],
"phone_numbers": [
{
"action_builder:identifier": "action_builder:e5a50ab4-38a7-4501-8103-154caf46a690",
"number": "15555555555",
"number_type": "Mobile"
}
],
"email_addresses": [
{
"action_builder:identifier": "action_builder:8c92c4a8-a185-4a52-825a-3f15d63d3352",
"address": "[email protected]",
"address_type": "home"
}
],
"_links": {
"self": {
"href": "https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/84a684a7-2f5a-4359-bdb4-898ce4fbc88f/people/60df91c0-edf5-4eea-b5d7-ec6f699e7e8f"
},
"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/60df91c0-edf5-4eea-b5d7-ec6f699e7e8f/connections"
},
"osdi:taggings": {
"href": "https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/84a684a7-2f5a-4359-bdb4-898ce4fbc88f/people/60df91c0-edf5-4eea-b5d7-ec6f699e7e8f/taggings"
}
}
},
{
"origin_system": "Action Builder",
"identifiers": [
"action_builder:124698f6-3496-4141-a39d-d51a174cc907",
"custom_id_2:1111"
],
"created_date": "2021-06-10T13:58:59.260Z",
"modified_date": "2021-06-10T13:58:59.260Z",
"action_builder:entity_type": "person",
"given_name": "Micah",
"family_name": "Roberts",
"action_builder:nickname": "The Red Sparrow",
"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"
}
],
"email_addresses": [
{
"action_builder:identifier": "action_builder:b1e48fad-0a8e-4694-b6f1-9e2783e5a6c7",
"address": "[email protected]",
"address_type": "home"
}
],
"_links": {
"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"
}
}
},
// truncated for brevity
]
},
"_links": {
"self": {
"href": "https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/84a684a7-2f5a-4359-bdb4-898ce4fbc88f/people"
},
"curies": [
{
"name": "osdi",
"href": "https://actionbuilder.org/docs/v1/{rel}",
"templated": true
},
{
"name": "action_builder",
"href": "https://actionbuilder.org/docs/v1/{rel}",
"templated": true
}
],
"osdi:people": [
{
"href": "https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/84a684a7-2f5a-4359-bdb4-898ce4fbc88f/people/cac7a9c4-c791-4609-9aff-4bae9c032de7"
},
{
"href": "https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/84a684a7-2f5a-4359-bdb4-898ce4fbc88f/people/42d941bd-03e4-486f-99be-b4b49bc0cdb7"
},
{
"href": "https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/84a684a7-2f5a-4359-bdb4-898ce4fbc88f/people/a58866ed-a9a1-493e-a24c-e807e4f890b8"
},
{
"href": "https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/84a684a7-2f5a-4359-bdb4-898ce4fbc88f/people/839db4d7-c86d-4329-a92d-e625134fbb3e"
},
{
"href": "https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/84a684a7-2f5a-4359-bdb4-898ce4fbc88f/people/60df91c0-edf5-4eea-b5d7-ec6f699e7e8f"
},
{
"href": "https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/84a684a7-2f5a-4359-bdb4-898ce4fbc88f/people/124698f6-3496-4141-a39d-d51a174cc907"
},
{
"href": "https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/84a684a7-2f5a-4359-bdb4-898ce4fbc88f/people/dc1cc1f7-2fe4-4057-bb9b-1fc4bc04250d"
},
{
"href": "https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/84a684a7-2f5a-4359-bdb4-898ce4fbc88f/people/e1277477-f9e8-478e-b8f9-6ea78e3f1f0e"
},
{
"href": "https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/84a684a7-2f5a-4359-bdb4-898ce4fbc88f/people/23d8daf6-e39a-45b2-ac99-1a2fdedb9188"
}
]
}
}
Back To Top ↑
Scenario: Retrieving an individual person resource (GET)
Calling an individual person resource will return the person directly, along with all associated fields and appropriate links to additional information about the person.
Request
GET https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/84a684a7-2f5a-4359-bdb4-898ce4fbc88f/people/60df91c0-edf5-4eea-b5d7-ec6f699e7e8f
Header:
OSDI-API-Token: your_api_key_here
Response
200 OK
Content-Type: application/hal+json
Cache-Control: max-age=0, private, must-revalidate
{
"origin_system": "Action Builder",
"identifiers": [
"action_builder:60df91c0-edf5-4eea-b5d7-ec6f699e7e8f",
"custom_id_2:1111"
],
"created_date": "2021-12-06T18:40:18.829Z",
"modified_date": "2022-12-16T15:20:39.770Z",
"action_builder:entity_type": "person",
"given_name": "Lily",
"family_name": "Morrison",
"additional_name": "Lillian",
"action_builder:nickname": "The Yellow Dart",
"browser_url": "https://techworkersunited.actionbuilder.org/entity/view/483/profile?campaignId=11415",
"action_builder:latest_assessment": 3
"action_builder:latest_assessment_created_date": "2022-12-16T15:20:39.770Z",
"preferred_language": "en",
"postal_addresses": [
{
"action_builder:identifier": "action_builder:8eb308d6-9b2a-45a4-ba4d-14dca9a1d020",
"locality": "Wilmington",
"region": "NC",
"postal_code": "55110",
"country": "US",
"status": "verified"
}
],
"phone_numbers": [
{
"action_builder:identifier": "action_builder:e5a50ab4-38a7-4501-8103-154caf46a690",
"number": "15555555555",
"number_type": "Mobile"
}
],
"email_addresses": [
{
"action_builder:identifier": "action_builder:8c92c4a8-a185-4a52-825a-3f15d63d3352",
"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/60df91c0-edf5-4eea-b5d7-ec6f699e7e8f"
},
"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/60df91c0-edf5-4eea-b5d7-ec6f699e7e8f/connections"
},
"osdi:taggings": {
"href": "https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/84a684a7-2f5a-4359-bdb4-898ce4fbc88f/people/60df91c0-edf5-4eea-b5d7-ec6f699e7e8f/taggings"
}
}
}
Back To Top ↑
Scenario: Creating a New Person (POST)
The people collection does not allow POST -- posting a new person directly to the people endpoint is not allowed.
People can be created using the person signup helper, documented here.
Back To Top ↑
Scenario: Modifying an Existing Person (PUT)
You can modify an existing person by using PUT at its individual endpoint.
You can modify an existing person's postal address, phone number, or email address by using PUT at the person's endpoint and either using the field's identifier or matching by the address, number, or any of the postal address fields. Postal addresses, phone numbers, and email addresses each have their own action_builder:identifier field which can be used to modify that field.
When updating a person's postal address, phone number, or email address you must include the action_builder:identifier in your request or match by address, number, or any of the postal address fields. Otherwise, new fields will be created instead of updating the existing fields.
You can remove a person's assessment by making action_builder:latest_assessment equal to null.
This example modifies the person's preferred name, assessment, and postal address. Note the use of the identifier in postal_addresses to identify which postal address to update.
Request
PUT https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/84a684a7-2f5a-4359-bdb4-898ce4fbc88f/people/60df91c0-edf5-4eea-b5d7-ec6f699e7e8f
Header:
OSDI-API-Token: your_api_key_here
{
"nickname": "Johnny",
"action_builder:latest_assessment": 1,
"postal_addresses": [
{
"address_lines": "1900 L St NW"
"locality": "Washington",
"region": "DC",
"postal_code": "20036",
"country": "US",
"identifier": "action_builder:e5a50ab4-38a7-4501-8103-154caf46a690"
}
]
}
Response
200 OK
Content-Type: application/hal+json
Cache-Control: max-age=0, private, must-revalidate
{
"identifiers": [
"action_builder:60df91c0-edf5-4eea-b5d7-ec6f699e7e8f"
],
"created_date": "2021-03-25T17:09:57Z",
"modified_date": "2022-12-16T15:20:39.770Z",
"family_name": "Smith",
"given_name": "John",
"nickname": "Johnny",
"action_builder:latest_assessment": 1,
"action_builder:latest_assessment_created_date": "2022-12-16T15:20:39.770Z",
"email_addresses": [
{
"address": "[email protected]",
"address_type": "home",
"identifier": "action_builder:e5a50ab4-38a7-4501-8103-154caf46a690"
}
],
"phone_numbers": [
{
"number": "12021234444",
"number_type": "mobile",
"identifier": "action_builder:f5a50ab4-38a7-4501-8103-154caf46a690"
}
],
"postal_addresses": [
{
"address_lines": "1900 L St NW"
"locality": "Washington",
"region": "DC",
"postal_code": "20036",
"country": "US",
"identifier": "action_builder:e5a50ab4-38a7-4501-8103-154caf46a690"
}
],
"_links": {
"self": {
"href": "https://actionbuilder.org/api/v1/campaigns/d32fcdd6-7366-466d-a3b8-7e0d87c3cd8c/people/60df91c0-edf5-4eea-b5d7-ec6f699e7e8f"
},
"action_builder:campaign": {
"href": "https://actionbuilder.org/api/v1/campaigns/d32fcdd6-7366-466d-a3b8-7e0d87c3cd8c"
},
"action_builder:entity_type": {
"href": "https://actionbuilder.org/api/v1/campaigns/d32fcdd6-7366-466d-a3b8-7e0d87c3cd8c/entity_types/d32fcdd6-7366-466d-a3b8-7e0d87c3cd8d"
},
"osdi:taggings": {
"href": "https://actionbuilder.org/api/v1/campaigns/d32fcdd6-7366-466d-a3b8-7e0d87c3cd8c/people/60df91c0-edf5-4eea-b5d7-ec6f699e7e8f/taggings"
},
"action_builder:connections": {
"href": "https://actionbuilder.org/api/v1/campaigns/d32fcdd6-7366-466d-a3b8-7e0d87c3cd8c/people/60df91c0-edf5-4eea-b5d7-ec6f699e7e8f/connections/5c9aa84d-31ad-4a3b-ad2e-552a0545c608"
},
"curies": [
{
"name": "osdi",
"href": "https://actionbuilder.org/docs/v1/{rel}",
"templated": true
},
{
"name": "action_builder",
"href": "https://actionbuilder.org/docs/v1/{rel}",
"templated": true
}
]
}
}
Back To Top ↑
Scenario: DELETE
Deleting a person will remove them from the campaign. This is equivalent to removing an entity from a campaign on the UI.
Request
DELETE https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/84a684a7-2f5a-4359-bdb4-898ce4fbc88f/people/327d68b0-02ed-40b4-a5f7-e35cb46a69de
Header:
OSDI-API-Token: your_api_key_here
Response
200 OK
Content-Type: application/hal+json
Cache-Control: max-age=0, private, must-revalidate
{
"message": "Entity has been removed from the campaign"
}
Back To Top ↑