Table of Contents
Getting Started
In this section we will get you up and running querying your NationBuilder v2 API. You’ll learn how to authenticate your calls, send queries, and issue commands with data. This documentation assumes you have some familiarity with using web APIs, but even if not we will do our best to guide you through using NationBuilder APIs so you can go on to integrate your own tools and build some amazing things for your Nation!
While we will provide links for further reading our aim is for you to be able to get started on interacting with our APIs just by following the information on this page.
NationBuilder v2 Web APIs At A High Level
The API Design
NationBuilder’s web APIs are written in the JSON:APIGraphiti web API style. While you don’t need to fully understand that specification to use our APIs, what it means is that our APIs aim to be consistent and predictable while also being flexible for many use cases. Your calls to our API will travel over HTTP in a Request-Response process returning “resources”.
This means that you will see our APIs organized by resource, with common actions you can perform against each. It also means the HTTP action you use matters as much as the URL that you are calling. But don’t worry! It all follows a consistent pattern often noted with the CRUD acronym.
Create a resource using the POST action
e.g.
POST /api/v2/voters
Read a resources attributes using the GET action
e.g.
GET /api/v2/voters/{id}
Update a resources attributes using the PATCH action
e.g.
PATCH /api/v2/voters/{id}
Delete a resource using the DELETE action
e.g.
DELETE /api/v2/voters/{id}
You may have noticed in the first action for create we don’t define any data for creating the resource. That is because it is sent in the body of the request, not the HTTP action or the URL, but we’ll get to that later.
Security
NationBuilder takes great effort to make sure your data is safe. As such we follow the best current practices to make sure when you use APIs to interact with your Nation that it is you doing so. Similar to how you have to log into your Nation with a username and password when using the Control Panel you also need to provide the NationBuilder API assurances that you are who you say you are before the API calls will work. The next section will outline how to do so.In the next section I will go into how to do so.
Authentication
Access Tokens
API Access Tokens are used to prove that you have the proper authorization to access the database and authenticate which user you are doing so on behalf of. A proper API request must have the access token included, either as a URL parameter with access_token=xxx appended to the URL or by adding the access_token attribute and value as a header or in the body of the request.
📌 Note: The API uses JavaScript Object Notation (JSON). If you receive a 406 response code, it means that you need to include both the Content-Type and Accept headers of your request with the value of both of them set to Application/json.
Access Tokens are scoped to the user that generated them in regards to the permissions of access to the database. Users whose permission sets permit them to see only a limited segment of a nation’s people database will only be able to read and update those records using the API. If a Control Panel User (CPU) is unable to access the API at all, please make sure that the permission set that they have been assigned in Nation Settings has API enabled.
If you are just testing out your application or exploring the API, you can generate a test API token from the Developer tab of the nation settings. This will work as a fully operational API token with the caveat that it will expire in 24 hours and cannot be refreshed. For this reason, these tokens are for testing and development purposes only and should not be used for real-world production-level use cases. Instead, for those use-cases, you should generate the tokens via the OAuth 2.0 authorization code flow, which requires you to first register an application to obtain the necessary client credentials.
For more information on generating API tokens, see: https://support.nationbuilder.com/en/articles/9559128-generating-api-tokens
Registering An Application
Registering an application provides you with a set of client credentials – An OAuth Client ID, an OAuth Client Secret, and a Callback URL (the last of which is defined by the user when registering the application). These credentials alone do not provide access to the database, but they allow an authorized user to exchange a valid login attempt for a working API token. These API tokens expire after 24 hours and must be refreshed using a refresh flow in order to keep working after that. As such, the result of a successful OAuth authorization flow journey is that a response containing a working access token and the refresh token that will allow it to be refreshed will be sent to the application’s pre-defined callback URL along with the slug of the nation that it is for.
Registering an application is necessary for any sustained usage of the API, regardless of whether you are building an application that will be logged in and used by a single user, many users, many different nations, or even just via a machine-to-machine programmatic process. If you would like your app to be available to be installed on another nation, you have the ability to share it with another nation by entering the nation slug in the Application settings. Alternatively, if you would like your application to be available to the larger NationBuilder customer-base (or even a large segment of it), you can click the “make app public” checkbox and reach out to [email protected] to have the app approved and listed in our NationBuilder Apps & Integrations Directory.
For detailed instructions on the Oauth 2.0 authorization code flow, see this article:
If you have a non-expiring legacy API token, it will need to be upgraded to an expiring token in order to work with the v2 API. To learn more about migrating legacy API tokens to currently-supported API tokens, see this article: https://support.nationbuilder.com/en/articles/9869235-access-token-migration-guide
Calling Your First API Endpoint
Once you have a valid API v2 token, you are ready to start making API requests. Listed below are two very basic examples of API requests for creating (POST) and retrieving (GET) a signup object from a nation.
Create A Signup
Adds a person to the database
POST https://slug.nationbuilder.com/api/v2/signups&access_token=XXX
{
"data": {
"type": "signups",
"attributes": {
"born_at": "1990-08-06",
"email": "[email protected]",
"email_opt_in": true,
"employer": "NationBuilder",
"external_id": "12345",
"first_name": "Lucy",
"is_volunteer": true,
"last_name": "Butler",
"mobile_number": "1234567890",
"mobile_opt_in": true,
"middle_name": "Octavia",
"note": "Good talk",
"occupation": "Software engineer",
"party": "P",
"phone_number": "1234567890",
"recruiter_id": "1",
"sex": "F",
"signup_type": 1
}
}
}
The response will have a status of 201, indicating a new record was created, and will look like this:
{
"data": {
"id": "4389",
"type": "signups",
"attributes": {
"born_at": "1990-08-06",
"city_district": null,
"civicrm_id": null,
"county_district": null,
"county_file_id": null,
"datatrust_id": null,
"do_not_call": false,
"do_not_contact": false,
"dw_id": null,
"email": "[email protected]",
"email_opt_in": true,
"employer": "NationBuilder",
"external_id": "12345",
"federal_district": null,
"fire_district": null,
"first_name": "Lucy",
"is_volunteer": true,
"judicial_district": null,
"labour_region": null,
"last_name": "Butler",
"mobile_number": "1234567890",
"mobile_opt_in": true,
"middle_name": "Octavia",
"ngp_id": null,
"note": "Good talk",
"occupation": "Software engineer",
"party": "P",
"pf_strat_id": null,
"phone_number": "1234567890",
"precinct_id": null,
"recruiter_id": "1",
"rnc_id": null,
"rnc_regid": null,
"salesforce_id": null,
"school_district": null,
"school_sub_district": null,
"sex": "F",
"signup_type": 1,
"state_file_id": null,
"state_lower_district": null,
"state_upper_district": null,
"support_level": null,
"supranational_district": null,
"van_id": null,
"village_district": null,
"ward": null,
"work_phone_number": null,
"active_customer_expires_at": null,
"active_customer_started_at": null,
"author_id": null,
"auto_import_id": null,
"availability": null,
"banned_at": null,
"capital_amount_in_cents": 0,
"church": null,
"city_sub_district": null,
"closed_invoices_amount_in_cents": 0,
"closed_invoices_count": null,
"contact_status": null,
"could_vote_status": null,
"demo": null,
"donations_amount_in_cents": 0,
"donations_amount_this_cycle_in_cents": 0,
"donations_count": 0,
"donations_count_this_cycle": 0,
"donations_pledged_amount_in_cents": 0,
"donations_raised_amount_in_cents": 0,
"donations_raised_amount_this_cycle_in_cents": 0,
"donations_raised_count": 0,
"donations_raised_count_this_cycle": 0,
"donations_to_raise_amount_in_cents": 0,
"email1": "[email protected]",
"email1_is_bad": false,
"email1_is_bouncing": false,
"email2": null,
"email2_is_bad": false,
"email2_is_bouncing": false,
"email3": null,
"email3_is_bad": false,
"email3_is_bouncing": false,
"email4": null,
"email4_is_bad": false,
"email4_is_bouncing": false,
"ethnicity": null,
"fax_number": null,
"federal_donotcall": false,
"first_donated_at": null,
"first_fundraised_at": null,
"first_invoice_at": null,
"first_prospect_at": null,
"first_recruited_at": null,
"first_supporter_at": "2024-09-20T12:32:55-07:00",
"first_volunteer_at": "2024-09-20T12:32:55-07:00",
"full_name": "Lucy Butler",
"import_id": null,
"inferred_party": null,
"inferred_support_level": null,
"invoice_payments_amount_in_cents": 0,
"invoice_payments_referred_amount_in_cents": 0,
"invoices_amount_in_cents": 0,
"invoices_count": null,
"is_cpu": false,
"is_deceased": false,
"is_donor": false,
"is_fundraiser": false,
"is_ignore_donation_limits": false,
"is_leaderboardable": true,
"is_mobile_bad": false,
"is_possible_duplicate": false,
"is_profile_private": false,
"is_profile_searchable": true,
"is_prospect": false,
"is_supporter": true,
"is_survey_question_private": false,
"language": null,
"last_call_id": null,
"last_contacted_at": null,
"last_contacted_by_id": null,
"last_donated_at": null,
"last_fundraised_at": null,
"last_invoice_at": null,
"last_rule_violation_at": null,
"legal_name": null,
"locale": null,
"marital_status": null,
"mobile_number_normalized": "(123) 456-7890",
"note_updated_at": "2024-09-20T12:32:55-07:00",
"outstanding_invoices_amount_in_cents": 0,
"outstanding_invoices_count": null,
"overdue_invoices_count": 0,
"parent_id": null,
"party_member": false,
"phone_number_normalized": "(123) 456-7890",
"phone_time": null,
"prefix": null,
"previous_party": null,
"primary_email_id": 1,
"priority_level": null,
"priority_level_changed_at": null,
"profile_content": null,
"profile_content_html": null,
"profile_headline": null,
"received_capital_amount_in_cents": 0,
"registered_at": null,
"religion": null,
"rule_violations_count": 0,
"spent_capital_amount_in_cents": 0,
"submitted_address": null,
"suffix": null,
"support_level_changed_at": null,
"support_probability_score": null,
"township": null,
"turnout_probability_score": null,
"unsubscribed_at": null,
"username": null,
"warnings_count": 0,
"custom_values": {
"favorite_color": null,
"chapter": null,
},
"updated_at": "2024-09-20T12:32:55-07:00",
"created_at": "2024-09-20T12:32:55-07:00"
},
"relationships": {
"author": {
"links": {
"related": null
}
},
"last_contacted_by": {
"links": {
"related": null
}
},
"page": {
"links": {
"related": null
}
},
"parent": {
"links": {
"related": null
}
},
"precinct": {
"links": {
"related": null
}
},
"recruiter": {
"links": {
"related": "/api/v2/signups/1"
}
},
"signup_profile": {
"links": {
"related": "/api/v2/signup_profiles?filter[signup_id]=4389"
}
},
"voter": {
"links": {
"related": "/api/v2/voters?filter[signup_id]=4389"
}
},
"signup_tags": {
"meta": {
"included": false
}
},
"memberships": {
"links": {
"related": "/api/v2/memberships?filter[signup_id]=4389"
}
},
"path_journeys": {
"links": {
"related": "/api/v2/path_journeys?filter[signup_id]=4389"
}
},
"taggings": {
"links": {
"related": "/api/v2/signup_taggings?filter[signup_id]=4389"
}
},
"petition_signatures": {
"links": {
"related": "/api/v2/petition_signatures?filter[signup_id]=4389"
}
},
"signup_nations": {
"links": {
"related": "/api/v2/signup_nations?filter[signup_id]=4389"
}
}
}
},
"links": {
"self": "/api/v2/signups?data[attributes][born_at]=1990-08-06&data[attributes][email][email protected]&data[attributes][email_opt_in]=true&data[attributes][employer]=NationBuilder&data[attributes][external_id]=12345&data[attributes][first_name]=Lucy&data[attributes][is_volunteer]=true&data[attributes][last_name]=Butler&data[attributes][middle_name]=Octavia&data[attributes][mobile_number]=1234567890&data[attributes][mobile_opt_in]=true&data[attributes][note]=Good talk&data[attributes][occupation]=Software engineer&data[attributes][party]=P&data[attributes][phone_number]=1234567890&data[attributes][recruiter_id]=1&data[attributes][sex]=F&data[attributes][signup_type]=1&data[type]=signups&page[number]=1&page[size]=20",
"next": "/api/v2/signups?data[attributes][born_at]=1990-08-06&data[attributes][email][email protected]&data[attributes][email_opt_in]=true&data[attributes][employer]=NationBuilder&data[attributes][external_id]=12345&data[attributes][first_name]=Lucy&data[attributes][is_volunteer]=true&data[attributes][last_name]=Butler&data[attributes][middle_name]=Octavia&data[attributes][mobile_number]=1234567890&data[attributes][mobile_opt_in]=true&data[attributes][note]=Good talk&data[attributes][occupation]=Software engineer&data[attributes][party]=P&data[attributes][phone_number]=1234567890&data[attributes][recruiter_id]=1&data[attributes][sex]=F&data[attributes][signup_type]=1&data[type]=signups&page[number]=2&page[size]=20"
},
"meta": {}
}
Read A Signup
Gets a person from the database using their NationBuilder ID
GET https://slug.nationbuilder.com/api/v2/signups/1
The response here will look just like the response listed above, including the entire JSON representation of the person requested, but the response status will be 200, indicating a successful response.