NationBuilder

Overview

The NationBuilder class allows you to interact with the NationBuilder API. Users of this Parsons integration can download a full list of people, update and upsert people.

Note

Authentication

In order to use this class you need your nation slug and access token. To get your access token login to your nation and navigate to Settings > Developer > API Token and create a new token. You can get more info in the NationBuilder API docs.

Quickstart

To instantiate the NationBuilder class, you can either store your NB_SLUG and NB_ACCESS_TOKEN keys as environment variables or pass them in as arguments:

from parsons import NationBuilder

# First approach: Use API key environment variables

# In bash, set your environment variables like so:
# export NB_SLUG='my-nation-slug'
# export NB_ACCESS_TOKEN='MY_ACCESS_TOKEN'
nb = NationBuilder()

# Second approach: Pass API keys as arguments
nb = NationBuilder(slug='my-nation-slug', access_token='MY_ACCESS_TOKEN')

You can then make a request to get all people and save its data to a Parsons table using the method, get_people():

# Create Parsons table with people data from API
parsons_table = nb.get_people()

# Save people as CSV
parsons_table.to_csv('people.csv')

The above example shows how to create a Parsons table with all people registered in your NationBuilder nation.

API

class parsons.NationBuilder(slug: str | None = None, access_token: str | None = None)[source]

Instantiate the NationBuilder class

Args:
slug: str

The Nation Builder slug Not required if NB_SLUG env variable set. The slug is the nation slug of the nation from which your application is requesting approval to retrieve data via the NationBuilder API. For example, your application’s user could provide this slug via a text field in your application.

access_token: str

The Nation Builder access_token Not required if NB_ACCESS_TOKEN env variable set.

get_people() → Table[source]
Returns:

A Table of all people stored in Nation Builder.

update_person(person_id: str, person: Dict[str, Any]) → Dict[str, Any][source]

This method updates a person with the provided id to have the provided data. It returns a full representation of the updated person.

Args:
person_id: str

Nation Builder person id.

data: dict

Nation builder person object. For example {“email”: “user@example.com”, “tags”: [“foo”, “bar”]} Docs: https://nationbuilder.com/people_api

Returns:

A person object with the updated data.

upsert_person(person: Dict[str, Any]) → Tuple[bool, Dict[str, Any] | None][source]

Updates a matched person or creates a new one if the person doesn’t exist.

This method attempts to match the input person resource to a person already in the nation. If a match is found, the matched person is updated. If a match is not found, a new person is created. Matches are found by including one of the following IDs in the request:

  • civicrm_id

  • county_file_id

  • dw_id

  • external_id

  • email

  • facebook_username

  • ngp_id

  • salesforce_id

  • twitter_login

  • van_id

Args:
data: dict

Nation builder person object. For example {“email”: “user@example.com”, “tags”: [“foo”, “bar”]} Docs: https://nationbuilder.com/people_api

Returns:

A tuple of created and person object with the updated data. If the request fails the method will return a tuple of False and None.