API Developers Forum

We're thrilled to see all the great development going on with the NationBuilder API, and want to open this forum up for public feedback, helps and hints, questions and more. This resource is curated by the NationBuilder API Team - our goal is developers helping developers, so we definitely want to hear from you. You can also use the tags to rank posts. Thanks!

Sort by

How to add a tag to user?

I have already used PUT people/:id/taggings api for that. But it is giving me response Bad Request Your browser sent a request that this server could not understand. [code] => 411 [content_type] => text/html )

Add your reaction Share

Release API Documentation as Open API Spec (formerly Swagger 2.0)

It seems like the Open API standard is becoming widely adopted (https://www.openapis.org). It would be helpful if the Nationbuilder API was made available in this format to help expedite development. I tried running the I/O Docs version through a converter, but appears to not be standard itself (or missing some elements).

Thanks!

Add your reaction Share

Option to control triggering webhook from API

It would be a nice feature to have a control on triggering webhook while updating a record using API . Something like "notifiy_webhook" : "true" .

4 reactions Share

Anedot integration does not push through records with invalid email addresses

It has been reported that the Anedot integration does not send donation information with invalid emails through to NationBuilder. If a donor mis-types their email address (such as .con or .ney), the information will not be sent through and there is no indication of which transactions were not synced with NationBuilder. This makes NationBuilder donation records inaccurate.

Official response from submitted

Thank you Lauren - I moved this over to our API forum for that team to take a look at!

1 reaction Share

Add feature to list all people on a step through API

We have received reports that users may find it helpful to list all people on a specific step within a specific path using our API. Currently, we offer the ability to index paths and search people, but not the ability to search people on a specific path or step.

Official response from submitted

Thanks Alex! I'm going to scoot this over to our API forum for that team to take a look at! 

1 reaction Share

Could I get a look at a pull request for your Ruby library?

This adds some better granularity to errors, so clients can respond dynamically to canonical HTTP status codes.

https://github.com/nationbuilder/nationbuilder-rb/pull/39

Add your reaction Share

users add tags

Add your reaction Share

Duplicate records being returned when hitting the lists API

It seems that the data that we get when we pull through the API is different than the data that you get when you just download a CSV file from a nation. The result is that the lists we pull from your API had about 20% duplicates. 

Official response from completed

This is likely the outcome of using the export context type 'voter ballot'. The context type 'people' will return a single record per .csv file generated by the export API.

Voter ballot exports will have multiple rows with the same record because each row can contain a different election in which that record/person voted.

1 reaction Share

Exports via API do not include "updated_at" field

The "updated_at" field is not included in exports initiated via the Export List endpoint;  "created_at" is included. Could "updated_at" be added please?

Official response from considering

This is something we will consider but does not have a timeline at the moment.

2 reactions Share

How to check if user has control panel access via API?

Hi all,

is it possible to check if the user has control panel access via the API? Perhaps also with their access level? Maybe using the /api/v1/people/me endpoint? Thanks!

Official response from considering

Craig,

It's currently not possible to know who has control panel access through the API. Permission sets aren't a resource the People API returns in the response body.

2 reactions Share

Can't generate OAuth tokens

According to the API Authentication Quick Start Guide, I should be able to generate an Oauth client ID/secret for my nation via Settings > Apps > New App. However, I only see options for "Install new app" and "Installed apps". The former shows a list of 3rd-party apps, but no option to create a new one. Am I looking in the wrong place?

Official response from completed

As Theodis pointed out, this information is wrong. It is actually under Settings > Developer > Register app. The documentation has been updated and thank you for bringing it to our attention.

2 reactions Share

Provide a way to list surveys through the API that do not require them to be on a Page.

Hi folks,

I want to use the surveys to let canvassers add extra details while they are contacting people using an app I am designing. Right now I am getting a list of surveys by hitting /api/v1/sites/:site_slug/pages/surveys

However, this only includes surveys that have a corresponding page made for them, so the user must first make a survey and *then* add it to a page on a site. Not the easiest!

Is it possible to just provide an endpoint that lists all surveys without requiring them to be on a page first?

Thanks!

Official response from considering

This is something we will consider but does not have a timeline at the moment.

2 reactions Share

Allowing alll fields on /contacts to be searchable

To the system I am working with, a Contact is unique across ALL of the following fields: type_id, method, author_id, person_id, status, note, created_at. However right now, the GET /contacts endpoint only allows us to search on person_id and author_id. In order for us to find an existing contact, we do the GET with those two params, and then iterate over the results looking for matches on all the other params. Is it possible for NationBuilder to accept those params as search terms and only return results that match all of those parameters?

This would allow us to process each connection much faster, and less processing on both NationBuilder and our ends. Since the endpoint is paginated, sometimes it takes multiple calls in order to find the Contact we are looking for.

Official response from considering

This is something we will consider but does not have a timeline at the moment.

1 reaction Share

People Search Endpoint - Updated since

What format is the "date" used in searches on the updated_since field in the people search endpont?

What is the granularity of the comparison, is it just a comparison of the date or is it really a combarison with the updated_at field of the record, which appears to have a resolution of 1s?

An example of using this api call might be useful.

Official response from submitted

The format can be either:

yyyy-mm-ddThour:minute:second-GMT timezone   (Ex: 2017-02-01T04:24:21-08:00)

or

mm/dd/yyyyThour:minute:second-GMT timezone   (Ex: 02/01/2017T04:24:21-08:00)

An example request using curl would look like this:

curl GET —header “content-type: application/json” 'https://{slug}.nationbuilder.com/api/v1/people/search?limit=1&updated_since=02/01/2017T04:24:21-08:00&access_token={token}'
1 reaction Share

Basic Pages API: Internal Styles

The content you can install in a page is inserted in the body of the page. It would be helpful if it was also possible to insert content into the head of the page, perhaps via an optional 'head' payload, in addition to the 'content' payload.

My use case is that I want to insert CSS as internal styles i.e. <style> ... </style> which can only be inserted in the head of the page. Note I need functionality that can't be deployed using inline styles (i.e. using the HTML style attribute).

Official response from considering

This is something we will consider but does not have a timeline at the moment.

1 reaction Share

Return a better error message when an API call is made to a nation, endpoint that does not exist

When making an API call to an invalid endpoint the response returns the HTML from a 404 page. A response body describing the issue (endpoint does not exist, nation does not exist) along with a 404 status would be preferred for debugging issues.

Example:


[17] pry(main)> NationBuilder::Client.new("foo", "bar").call(:donations, :index)
NationBuilder::ClientError: <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">

<head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8" />
<title>404 Error: The page you were looking for doesn't exist</title>
<style type="text/css">
body {
background: url(http://nationbuilder.s3.amazonaws.com/assets/404-grass.jpg) repeat top left;
color: #fff;
font-family: Lucida Grande, Lucida Sans Unicode, Garuda, sans-serif;
margin: 15px 0;
font-size: 1em;
}
#wrapper {
padding: 15px 0 0 45px;
}
#headline {
font-size: 2em;
font-weight: bold;
text-shadow: -1px -1px #333;
color: yellow;
}
#description {
font-size: 1.3em;
line-height: 1.8em;
color: #fff;
text-shadow: -1px -1px #333;
}
#footer {
clear: both;
font-size: 0.8em;
}
a:link, a:active, a:visited {
color: #ec7c31;
text-decoration: none;
}
a:hover {
text-decoration: none;
background-color: #fee34c;
color: #000;
}
#road {
margin-top: 15px;
}
</style>
</head>

<body>
<!-- This file lives in public/404.html -->

<div id="road">

<div id="wrapper">
<div id="headline">We couldn't find the page you were looking for.</div>
<div id="description">You may have mistyped the address or the page may have moved.</div>
</div>
<div id="road"><img src="http://nationbuilder.s3.amazonaws.com/assets/404-road.png" width="952" height="404"></div>
</div>

</body>
</html>
from [...]/gems/nationbuilder-rb-1.5.0/lib/nationbuilder/client.rb:129:in `parse_response_body'
Official response from considering

This is something we will consider but does not have a timeline at the moment.

1 reaction Share

Feature Request: get and add People relationships

It would be great to see the ability via the API to get any existing relationships a person has and add new ones, as you can do via the GUI.

Official response from considering

This is something we will consider but does not have a timeline at the moment.

5 reactions Share

Is there any way to ajax submit a form in NationBuilder?

Official response from considering

This is not possible with our current page infrastructure.

7 reactions Share

How to get people that appear on "Contacted By" page on the data entry sheet of a list?

Hi all, do you know how can I use the API to get the same list of people that appear under "Contacted By" on the data entry sheet?

I'm working on a data entry app and would like to have similar functionality to be able to choose who contacted a person. Thanks!

Official response from completed

You can do this using the contact API/index endpoint and passing in the author_id parameter. A request using cURL would like something like this:

curl 'https://{slug}.nationbuilder.com/api/v1/contacts?author_id={id}&access_token={token}'

11 reactions Share

Index of donations for a specific donor

Right now the Donations Index endpoints returns all donations in a nation. It would be great if the API allowed the donor ID to be specified and then only return donations that have been made by that person.

Official response from considering

This is something we will consider but does not have a timeline at the moment.

1 reaction Share

Basic Pages API: Restricting access to pages

In the GUI I can restrict access to a page, for example pages can be restricted to control panel users. However, I can't see any way of doing that via the Basic Pages API. Am I missing something?

The background is that I am writing an app that will periodically sync a Nation with an external database. I thought a good way to provide feedback on the operation of the app would be to populate a basic page on the Nation with status information. I would prefer that the page was only accessable by control panel users. Any other ideas?

- Andrew

Official response from completed

Setting 'who can view this page' is not an attribute with the basic page/create endpoint. 

1 reaction Share

Link donation to a membership through API

Whenever we assign a membership to a person through API, it always shows "Dues amount" as "Free" under "Memberships" tab ("Edit" > "Memberships") on the person's profile. Is there a way to link a donation to the membership or just show an amount instead of "Free"?

Official response from considering

This issue has been confirmed but does not have a set timeline on when it will be fixed. Please follow this cards if you would like to receive email updates about the status of this issue.

1 reaction Share

Can you assign point person through the API?

Official response from completed
1 reaction Share

Please add Petitions and Petition Signatures to the NationBuilder API

This would be very powerful for a bunch of existing integrations as well as new ones. For example, it would enable a service like CallHub to support members signing petitions via SMS. It would enable email your MP tools to track against petition pages directly within NationBuilder. It would also enable tools to report on a nation's core activities and track successes across a great range of actions.

Ideally, it would allow developers of external tools to work with NationBuilder's petitions as well as petition signatures, in the same way that we can already work with events and RSVPs (that event resource provides the best analogy).

I would say the key components would be:

  1. Index endpoint (to return all petitions per site)
  2. Create endpoint (create a new petition)
  3. Show/update/delete endpoints (these are less important to us, but useful all the same :)
  4. Petition signature Count endpoint (return the number of people who have signed a given petition)
  5. Petition signature Index endpoint (return the NationBuilder IDs, first names and emails of everyone who has signed a given petition)
  6. Petition signature Create endpoint (add a new signatory to a given petition)

Thanks for considering!

Official response from considering

Thanks CodeNation! I'll move this over to the API forum for that team to take a look at! There isn't a timeline on this at the moment but definitely a good suggestion. 

24 reactions Share

Get notes on person's profile via the API

With the current People API you can add a note to a person's profile which is great! However, it would be fantastic if you could also get those notes too via the API.

Official response from considering

This is something we will consider but does not have a timeline at the moment.

12 reactions Share

Suggestion: Address fields as parameters on the people/search endpoint.

At the moment, you can GET people/search with geographical filters City and State. It would be nice to able to also filter (for instance) on Address 1, or Street Number, Name, and Type, or ZIP. (ie. we would like to see more geographical / primary address filters exposed through the API.)

Official response from considering

This is something we will consider but does not have a timeline at the moment.

7 reactions Share

Imports via API and webhooks

The create import endpoint does not offer the option to "Bypass webhooks" that is available when you perform a manual import.

  1. Do imports initiated by via this endpoint the relevant webhooks (ie Person Created and Person Changed)?
  2. Whatever the response to (1) it would be useful to control this behaviour from the API as it is via the manual interface.

 

Official response from incomplete

Andrew,

The ability to bypass webhooks is not available through the import API. Can you please clarify your question, reproduced below:

  1. Do imports initiated by via this endpoint the relevant webhooks (ie Person Created and Person Changed)?
1 reaction Share

Looking for the "right" way to hook into the form submission API

Hi folks, we'd like to add some JS actions—adding content to fields—to an NationBuilder form on submit before the form validation/send is triggered. However binding on the form submit handler triggers after the NationBuilder actions and the data is not captured.

Is there an elegant/sanctioned way to hook into the event dispatcher? Essentially I need a callback before the form submits though NationBuilder XHR channels. Someone has a gist of how to do this, but the timing of this isn't correct (form still submits).

Add your reaction Share

Unable to use Import or People API with non-ascii characters (ie. á or ë with accents)

Hello. We're unable to import an CSV via the Import API, or update users via the People api when they have a name with a non-ascii character.

For example, if we post this JSON to the People API: 

{
"person": {
"email": "bob@example.com",
"last_name": "José",
"first_name": "Böb",
"sex": "M",
"signup_type": 0,
"employer": "Dexter Labs",
"party": "P",
"registered_address": {
"state": "TX",
"country_code": "US"
}
}
}

we receive a 400 Bad Request response. Can you please advise?

Official response from completed

When sending your request please set the content type in the header to Charset=UTF-8. For example, this is what the full header would look like:

--header "Content-Type: application/json; Charset=UTF-8"

2 reactions Share

Creating a new donation through the API doesn't carry with it the fundraiser info

We are using the donation API and are sending 'recruiter_name_or_email' through our integration to log who the fundraiser of a specific donation is. This data doesn't seem to be entering our nation even though the 'recruiter_name_or_email' field is a writable field.

Official response from considering

This issue has been confirmed but does not have a set timeline on when it will be fixed. Please follow this cards if you would like to receive email updates about the status of this issue.

1 reaction Share

Extend Oauth 2 implementation to include Resource owner credentials grant

For cron jobs or similar we need Nationbuilder to extend it's Oauth2 model to include Resource owner credentials grant

2 reactions Share

Imports via API incorrectly allocating records as prospects

I have imported a number of records via the API, which all have an email address and email_opt_in='Y', but the
records are being imported as PROSPECTS. Whereas http://nationbuilder.com/how_support_status_is_determined says:

"Records imported with:

  * support level = 1
  * support level = 2
  * email address and email opt-in = Y
  * mobile number and mobile opt-in = Y

will always be supporters."

Official response from considering

This issue has been confirmed but does not have a set timeline on when it will be fixed. Please follow this cards if you would like to receive email updates about the status of this issue.

2 reactions Share

When is it safe to delete list after invoking add tag endpoint?

I want to add/delete a bunch of tags from a bunch of people. This involves multiple sequences along the lines

  • Create temporary list
  • Add people to list
  • Add tags to people in list / remove tags from people in list
  • Delete list

The documentation for the add tag endpoint says:

Use this endpoint to apply a tag to the people contained in a list. Note: this endpoint returns a HTTP 204 status code, but the tag is not applied immediately. For larger lists, this operation takes many minutes.

The remove tags endpoint is similar. So when is it safe to delete the list?

Official response from duplicate
2 reactions Share

When is it safe to delete list after invoking add tag endpoint?

I want to add/delete a bunch of tags from a bunch of people. This involves multiple sequences along the lines

  • Create temporary list
  • Add people to list
  • Add tags to people in list / remove tags from people in list
  • Delete list

The documentation for the add tag endpoint says:

Use this endpoint to apply a tag to the people contained in a list. Note: this endpoint returns a HTTP 204 status code, but the tag is not applied immediately. For larger lists, this operation takes many minutes.

The remove tags endpoint is similar. So when is it safe to delete the list?

Official response from completed

Andrew,

Once your done with adding/removing tags from those people you can delete the list. Deleting the list does not delete the people on that list (http://apiexplorer.nationbuilder.com/nationbuilder#Lists) when you hit the /api/v1/lists/:list ID endpoint.

2 reactions Share

Updates and imports not involving emails failing due to email validation errors

I've just come across some unexpected behaviour.

When using the people update API to update a precinct_code, e.g. with the payload:

{'person': {'precinct_name': 'Burton Bradstock'}}

I received a "400 Bad Request" with the response

{"code":"validation_failed","message":"Validation Failed.","validation_errors":["email 'clive@xxxxx.co.ukinvalid' should look like an email address"]}

The same thing happened with imports that didn't involve email addresses failing because of email validation errors.

 

Official response from submitted

Because of the need to replicate this issue and the need for sensitive data to do so, I'm reaching out via email.

1 reaction Share

Trying to do shared Authentication but coming up blank

I have a need to integrate my Nation with an external system also hosted by us (on the same domain as our nation). The external system has user records and its own authentication. The external ids of these records are also present in our Nation.

What I really want is that when a user signs in to the external system they also sign in to our nation - i.e. I want a shared signon, but I cannot see any practical way of doing so.

Is there any avenue I can follow towards making this happen at all?

Official response from completed

David,

SSO might be the best solution here. It is an option available to enterprise customers. Please contact your community strategist to discuss implementation. 

1 reaction Share

Survey API not correct

http://nationbuilder.com/surveys_api

Copying and pasting example code to create a survey generates a warning message. Adding an extra status - associated with the survey as opposed to the question it then works.

 

http://nationbuilder.com/surveys_api

Official response from completed

Luke,

Thanks for the feedback. There was a missing 'status' for the survey page in the example code. It should work now.

2 reactions Share

API bulk tag removal

I'm having problems with the bulk tag removal API. For example, using the API explorer for my nation I send the following:

DELETE | Bulk Tag Removal|

/people/:id/taggings with id = 123 and body:

{ "tagging": { "tag": ["hello"] } }

I get response code: 400 { "code":"missing_parameters","message":"Missing Parameters.","parameters":["tagging"]}

In contrast, the API for adding tags works as expected. This has exactly the same syntax except the request is a PUT not a DELETE.

Official response from completed

This bug has been fixed.

6 reactions Share

API Reporting or Permission Levels

In order to ensure the security/privacy of our supporter information we'd like to see a daily report on how third party apps have used the API and/or the ability to restrict apps to read or write. 

There is nothing stopping an app that pushes information to our nation also downloading our entire database without us being aware. Supporters trust us with their personal information so we'd like to ensure we keep it safe.

1 reaction Share

When POSTing to donation API I keep getting a 'slug can't be blank' error

We are trying to hit the following API

token.post('/api/v1/donations', headers: {"Content-Type"=>"application/json", "Accept"=>"application/json"}, body: {:donation=>{:donor_id=>1234, :amount_in_cents=>1000, :payment_type_name=>"Other", :tracking_code_slug=>"", :succeeded_at=>Wed, 07 Sep 2016 23:18:32 EDT -04:00}})

Official response from completed

The tracking_code_slug can't be blank. It needs the tracking code value as a string, a 'null' or just not including the resource in the request. 

1 reaction Share

People/search endpoint only returns exact matches

When I hit the search endpoint for a name, for example, I have to use the exact name to return a result. For example, if I search for first_name=brad it won't return results for 'Bradley'. 

In addition, searching for names of organizations doesn't return results at all.

Official response from considering

This issue has been confirmed but does not have a set timeline on when it will be fixed. Please follow this cards if you would like to receive email updates about the status of this issue.

6 reactions Share

Webhooks are not firing

Webhooks don't seem to be firing for person created and changed webhooks. Possibly other events that trigger webhooks are also effected.

Official response from completed

This issue has been resolved. 

1 reaction Share

API and GUI validation inconsistencies

There appears to be inconsistencies between what is required/validated via the GUI, and what is required/validated via the API.

For example, via the GUI you can create and edit an event that has no location. However, trying to edit one of these events via the API will produce a validation error, as location is required.

This results in needing to add code such as this to all my event editing script:

contact = event["contact"]
contact["name"] = "Default Contact Name" if contact["name"].nil? || contact["name"].empty?
contact["email"] = "default@contact.com" if contact["email"].nil? || contact["email"].empty?
if !event["venue"].nil? && !event["venue"]["address"].nil?


address = event["venue"]["address"]
  address["city"] = "Unknown" if address["city"].nil? || address["city"].empty?
end

Official response from completed

Effy,

I attempted to replicate this issue in my sandbox and didn't encounter the error you described. To test I created an event using the UI without including a location. I then hit the PUT endpoint to update the event with new page tags and contact info and returned a 200 response code.  

1 reaction Share

Sites index returns null for domain

api/v1/sites returns 'null' for domains for all sites, regardless of if the site has a domain set.

Official response from considering

This is a confirmed bug but does not have a set timeline on when it will be fixed. Please follow this cards if you would like to receive email updates about the status of this issue.

1 reaction Share

No search functionality over developers' forum?!

new to NB, but trying to make something work on my 'nation' and this is one way i typically learn a new code base.  wazzup?

Add your reaction Share

Custom Fields list API method needed.

I think a new method is needed to list a nations custom fields and their types. For instance by only being able to view a custom field on a person I am unable to tell the difference between a text and a multiple choice field.

Also I am unable to infer the possible options for a multiple choice field if there is no person with that option. 

Official response from considering

This is something we will consider but does not have a timeline at the moment.

2 reactions Share

Attempts to delete people from a list through the API results in errors

There is some issue with “Delete People Endpoint” in “List API”( http://nationbuilder.com/lists_api ). It always returns 400 error with the message that says:

{"code":"missing_parameters","message":"Missing Parameters.","parameters":["people_ids"]} 

Official response from considering

This is something we are considering but we do not have a set timeline yet.

1 reaction Share

C# API PersonResponse conflict

I'm calling the Person Create endpoint, and receiving back a good response with json reflecting the new user.  But Newtonsoft.Json is returning an error when attempting to deserialize the Json to a NationBuilderAPI.V1.PersonResponse<NationBuilderAPI.V1.Person>.  Has there been an update to the Person Create endpoint that's not reflected in the C# API?  I'm using version NationbuilderAPI version 1.3 from Nuget.

Official response from completed

That is not a NationBuilder library. It is a third party offering that we don't support.

1 reaction Share

Create directory pages via the API

It would be great if this were possible! 

Official response from considering

This is something that we are considering. Please follow this page to get email updates regarding a directory page/create endpoint.

1 reaction Share

Including Paths in the API

Hi, 

It would be a huge help if paths and steps were included in the API.  Then we could automate much more of the importing and tracking that we do.  The feature has been out for a while and it seems intuitive that the feature would be included in the API.  Thanks so much!

Jenny Landon

Represent.Us

Official response from completed

Jenny,

We now have a paths API with the ability to index paths and steps. Please see the documentation.

9 reactions Share

Like this page to spread the word