Skip to main content

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!

Please check your e-mail for a link to activate your account.
Sort by

500 Error with PHP OAuth

I'm having an odd problem with the API. I wrote a script which was working fine in early August, but when I returned to using it I now get a 500 error when generating a token. If I make a new app, it will generate a token fine once but any repeated executions will return a 500. I haven't changed anything, and it was worked fine before. Help?

NB doesn't seem to have a good way to post code, but here's the blog post I wrote a few weeks ago with my code:

// OAuth 2 Library
require_once ROOT . '/OAuth2/Client.php';
require_once ROOT . '/OAuth2/GrantType/IGrantType.php';
require_once ROOT . '/OAuth2/GrantType/AuthorizationCode.php'; 

// Client ID and Secret from Nation Builder 
const CLIENT_ID = 'id';
const CLIENT_SECRET = 'secret';

// Constants we need to talk to Nation Builder
const REDIRECT_URI = "";
const TOKEN_ENDPOINT = "";

// Start a new OAuth2 Client 
$client = new OAuth2\Client(CLIENT_ID, CLIENT_SECRET); 

// Check if we have an authorize code, if not obtain one 
if (!isset($_GET['code'])) { 
     // Generate the URL we need to go to get the token 
     $auth_url = $client->getAuthenticationUrl(AUTHORIZATION_ENDPOINT, REDIRECT_URI); 

     // Redirect to that URL (which then sends us back to the REDIRECT_URI with a code, IE this page) 
     header('Location: ' . $auth_url); 

     // End this process 

// We have a code, so generate the parameters we need to get an access token 
$params = array('code' => $_GET['code'], 'redirect_uri' => REDIRECT_URI); 

// Obtain our access token 
$response = $client->getAccessToken(TOKEN_ENDPOINT, 'authorization_code', $params);
2 reactions

Accessing blog posts of deleted blog


When deleting a blog, the blog posts themselves are not deleted and can still be viewed on the site by their URL and found via search. How do we use the NationBuilder API to access blog posts of a deleted blog? All of the blog post methods require a blog ID.

not planned


Thanks for bringing this to our attention. After testing this it is clear that deleting the blog post is difficult after deleting the blog if you don't have the blog_id because the ability to index blog pages goes away when you delete the page. It is possible to delete the posts through the control panel. To do this, please go to your nation's control panel and select the Website tab and then toggle the drop down for 'page type' to 'blog post.' Once here you should see all blog posts including the posts that were subpages of the blog page you deleted and can choose to delete the posts here.

Official response from

4 reactions

Accessing blog posts of edited blog


When editing a blog, the blog posts themselves are not deleted and can still be viewed on the site by their URL and found via search.

Add your reaction

Accessing People on non-Directory Pages

I'm wondering if there is a way to configure a non-directory page (for example, a donations page) so that it has access to the People profiles through Liquid. Are all pages on a Nation's website configured so that they have access to the entire Nationbuilder database through Liquid, or do I need to make requests separately, through a separately implemented Javascript API if I want to access Nationbuilder people on a donation page?

not planned

Hey Lachlan, our site object has drops available for recent_supporters and random_supporters, but no drops that give full access to the people database. It's worth mentioning that the Directory pagetype only pulls from supporters, and is generally scoped to supporters with a specific tag. Unfortunately, there is no secure way to do this via the API as ours is meant for server-side code and there isn't a way to hide the access token client-side.

Official response from

3 reactions

access tokens

1 reaction

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.

3 reactions

Additional PHP resources and simple PHP example app

We've been seeing a lot of PHP development on our APIs, and we're hopeful that the developers using that language will continue to add shared resources. With that in mind, Jason Johnston from our team wrote up this "uber basic" client:

And Ryan Morgan from Veracity Media added body support for POST/PUTing to this OAuth 2.0 wrapper:

Note: These are resources provided on an as-is basis and are not supported by NationBuilder. We encourage developers to continue to add to them and to use GitHub's pull request and issue reporting features.

Add your reaction

Add user to the nation builder after registration on wordpress site

How can I add user to the nation builder after his registration on wordpress site



You can develop an API connection between your WordPress site and NationBuilder. Learn more from our quick start guide about this process. 

There is an existing application called Gravity Forms that some NationBuilder users use with their WordPress websites to establish a connection between the two platforms. You can also use a 3rd party NationBuilder integration such as 123FormBuilder. 


Official response from

1 reaction

Allow a read-only subset of the API to be called without authentication

We need to pull in data via AJAX to our NationBuilder site to populate it dynamically (we are hacking tags to link Events to Pages).  However, being client-side we can't implement OAuth but we don't need to POST any data.

Add your reaction

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.

1 reaction

API Access for Development

Our organization is using Nation Builder for their website and we would like to start developing a tool to manage our Blog, which will need to hook into the Blog API. I can easily code this, but need to get access to the API. What steps do I need to perform in order to gain access to the API? Thanks, Wil

Add your reaction

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"] = "[email protected]" 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?



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.  

Official response from

1 reaction

API Authentication STEP 3 ambiguity


3. Record the code that comes back

We will redirect him/her to your redirect_uri with a code parameter in its query string, so a request will come through like this:



There is a minor problem/inconvenience with that process. When client clicked on the authorization url and you redirected a request to the application callback with the code, there is no information who authorized that.

This is probably OK for entirely manual registration, however it would be really helpful to attach a client slag '{slug}' which I generated the Authorization request for:




2 reactions

API based credential checking?

hi all,

I'm designing an app which will have 2 parts;

  • a (server-side) token request service which has an access token to operate the NB API
  • a browser based app which will needs to use the NB API, so requires its own access token

I'd like to restrict the usage of the browser app to people with current credentials in my NB site, and potentially tagged in a certain way. Something like this;

  1. user posts credentials (userid, pwd-hash) to my token request service
  2. my service uses the NB API to check the user's credentials (userid, pwd-hash) 
  3. if good, the service requests a new access token for the user and returns it to the user's browser ... this is the reply to the request (1)
  4. user's browser app can now operate the API and do something useful.

Is there an API call to support (2) ??

Is this a reasonable pattern?


3 reactions

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.


This bug has been fixed.

Official response from

6 reactions

API: DELETE /lists/:list_id/listings/:person_id => 404 response for person in the list.


using this command (all variables in {} are substituted in):

curl -X DELETE --header "Content-Type: application/json" --header "Accept:application/json" https://{MY_SLUG}{THE_LIST}/listings/{MY_ID}?access_token=...

i get a 404 response even though the person is in list (previously checked using api explorer).


can you please fix this? 

5 reactions

API exerpt, thumbnail and featured content sliders


How can I add the excerpt, thumbnail and a featured content slider via the api?



1 reaction

API Explorer broken on donations and people search endpoints

As per my previous two posts concerning these matters, the people and search endpoints return a 400 when provided with unexpected URL parameters. The API Explorer provides them with one of these, __proto__. This should be removed so that the API Explorer actually works on these endpoints.


Thanks for noting this Jeremy. We have flagged it with our product and engineering team. There is no set timeline on when this change will go into effect but we will update this posting when it does.

Official response from

4 reactions

API Explorer not generating calls or any JSON

I just generated my first test token and have submitted it on the API Explorer along with my nation's slug. However none of the endpoints are generating any JSON feedback. In my browser Explorer, I see the following error in my console: SyntaxError: JSON.parse: unexpected character at line 1 column 1 of the JSON data. Can anyone help? Do I need to follow any additional steps to get the API Explorer working? I just want to set up a simple AJAX call within my nation's page template. This is my first time using the API. Any help is really appreciated! Thank you.


I tested the API explorer on our end using a known functional API token and I wasn't able to replicate the issue you have described.

Could you reach out to us with the nation where you generated the test token? I would be happy to test out the token you are using on your end to make sure that the tokens are valid.

Official response from

1 reaction

API for managing Political/Social Capital?

Is there a plan to open up the ability to add/remove political capital from the API... this would allow us to add PC for external events outside of the NB site... which would be very powerful... not something we need now, but I can see us using this in the future... thanks... 

1 reaction

API imports result call returns an empty failure_csv field.

When importing people using the import call from the API, although the Errors CSV file is available in the people import report, and that the correct number of failure is reported in the response, the field failure_csv is returned empty (null). Here's an example of responses: {"result":{"rows_updated":0,"rows_succeeded":0,"rows_failed":9,"failure_csv":null}} {"result":{"rows_updated":2360,"rows_succeeded":2612,"rows_failed":24,"failure_csv":null}} The response match exactly the report on the control panel, except for the file which is only available on from the control panel. The following params are used for the import call: 'type' => 'people', 'file' => [base 64 encoded csv file], 'is_overwritable' => 'true' Thanks for your help.


Unfortunately it isn't possible to access the error file via the API. I have corrected the error in our documentation that suggested this was possible.


Official response from

1 reaction

[API] Relationships between People to People/Organizations are not available

We are not able to add relationships either between people with each other or with an organization through the API provided by NationBuilder.

We are trying to add various types of users on NationBuilder, such as adding a student and a school. However, we want to assign that a particular student has the relation "Student At" his/her school. This assignment is not available as the current API version does not support the endpoint "Relationships".

Is there a solution to set these relationships?


Mohamed Hisham

21 reactions

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

App Integration Leading Practices?

I'll frame this question in a general way so it applies to other 3rd party app developers, not just me:

What level of API integration are NB customers asking for?

For example, if you build a third-party app that can help members of a nation interact with each other (i.e. group chat or something else), there are several ways I can imagine that you'd want to integrate it with NB, each with a different level of complexity:

  • No integration: Just listing an app in the app directory, essentially as an ad for the app-- probably not an option.
  • Minimal integration: Include the app in an iframe and have either no sign-in requirement or require that the members of the nation sign in a second time within the app's iframe as part of the app's authentication process.
  • Deep integration: Connect to the People API so that members of a nation can sign into your app from within a NB page for that nation.
  • Other options?

Are any of those options emerging as common or recommended?  

What are NB customer expectations around 3rd party app integration?  I don't expect they'd be too happy with requiring that the members of their nation sign in twice-- once to NB and once to the app.  That's what I found with one client I worked with.


2 reactions

A question about Sign Up pages.

Hi All,

We use the Victory theme.The sign up demands that the single line address is filled. We don't want that as we have custom fields to collect addresses. So how do I edit the page to not require the single line address box be filled? I expect it has some thing to do with the code below. By the way we will be getting rid of any way for the members to log in.

{% if page.signup.is_all_info_collected? == false %}
                  {% if request.sorta_logged_in? %}
                    {% submit_tag "Update info", class:"submit-button" %}
                  {% else %}
                  {% submit_tag "Signup", class:"submit-button" %}
                {% endif %}
              {% endif %}

            {% endform_for %}

Add your reaction

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

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

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


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

Official response from

1 reaction

Bad Request on /donations/search endpoint

Similar to my previous post, this endpoint is also needlessly strict. The API Explorer is also broken on this as a result. These endpoints need, at the very least, documentation explaining the inconsistent strictness, and the __proto__ URL parameter needs to be removed from the API Explorer. Moreover, this requirement to not include any unexpected URL parameters should be removed from the endpoints.

2 reactions

Bad Request on /people/search endpoint

If any unexpected parameters are sent to the /people/search endpoint, it fails with a 400 Bad Request, and doesn't explain further in the body text. This is a problem, especially considering the API Explorer adds an empty __proto__ URL param, which is rejected by the API with the message above. Really, the API should ignore any irrelevant URL parameters, rather than just mysteriously dying. If there's a technical limitation around these for some reason, the response text should at least be more verbose.


Overall, we don't have any specialized error reporting through the API. If the request is incorrect, you are properly sent back a 400 bad request (or other respective response). We could set up the API to provide errors depending on typos or if the request contains irrelevant URL parameters, but we haven't prioritized this sort of project. As an alternative to the API Explorer, you could use your own tools to send requests through our "REST API" in NationBuilder. For example, you can use "curl" to send requests through terminal on a Mac (or command prompt on Windows).

Official response from

3 reactions

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).


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

Official response from

1 reaction

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


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

Official response from

1 reaction

Batch updating and importing Blog Posts via API

I would think that many others would have had to migrate from Wordpress or Drupal to Nationbuilder by this point, but I can't seem to find many resources.

Seeing as there is no way to batch import posts I created a script to do so, and categorize them under their respective parent blog within Nationbuilder- attaching an 'external_id'.

So now, to update these same posts (content authors have made edits on old site during NB development) I have to first make a GET request to /sites/:site_slug/pages/blogs/:id/match to get the external id, then another UPDATE request to /sites/:site_slug/pages/blogs/:blog_id/posts/:blog_post_id .

Is there was an UPDATE or DELETE by 'external_id' method available or in the works? Many developers will be migrating to Nationbuilder and these functions alone will make the migration process easier- and open the doors to CSV batch editing for larger sites.


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

However we are paying close attention to the most popular suggestions so please share and encourage others to follow and comment!

Official response from

2 reactions

blog post images


Reading here:

Is it possible to show a blog posts attachments or feature silder (I can see those options aren't listed...)?

Is it possible to check if a page has a specific attachment?






Hi Matt,

Sure - via Liquid it's possible to see the attachments for any particular page using page_attachments (more information on that here). There are also some additional variables for featured content sliders, which are called a bit differently.

Using the API, this is possible through the page attachments endpoint where you could view a single (or all) attachments on a page, or upload your own. Featured content sliders, on the other hand, aren't currently accessible through our endpoints.

Hope this helps!


Official response from

2 reactions

Blog Posts by Author

Is it possible to get a list of blog posts created by a specific author via the API? If so, can you link me to the page with the info for this because I cannot seem to locate anything about it. Thanks, Wil


Unfortunately there is not a search endpoint for blog posts. As an alternative, you could Index all blog posts and then have your own app search specifically for the author_id field. 

Official response from

1 reaction

Bug tracker

I think NB needs a bug tracker. Is there one I'm missing. Currently, we report bugs via point people or by developer email addresses that we happen to have. This system does not work for a variety of reasons. 

I've reported many bugs via point people, and mostly they are misunderstood or ignored. I am sitting on about a dozen low or medium priority bugs that I'd happy report, but since I can only do so through point people I only report major, show-stopping bugs. And even then they usually don't get through to the engineers until I start squeaking. 

A professional bug tracker that the engineering team can directly access, without point people as gate keepers, is important. 


If you're experiencing a bug, please contact our support team at [email protected] and follow these steps for reporting your bug.


Official response from

16 reactions

Building a custom form with multiple tagging sections


I’m trying to build a custom form that will have multiple sections, that will tag people with their response. I can get the html displaying the way I want it to, and submit the form with the “text_fields”, but when it comes down to tagging people…. I’m lost!

code example,

     {% form_for signup %}   

     {% hidden_field_tag "page_id", %}     

{% error_messages_for signup %}

Can you verify your information?

  • {% text_field "name", class:"text", placeholder: "name" %}
  • {% text_field "email", class:"text", placeholder: "email" %}           
  • {% text_field "submitted_address", class:"text" %}

i am A...

Check one that applies


           Do Not Identify

What issues matter most to you

Check one that applies

        National Security    


         Securing the Border             

         Issue 4

         Issue 5

         Issue 6                               

how often would you like to receive updates?

Check one that applies




         {% submit_tag "Signup", class:"submit-button" %}

         {% endform_for %}

Any help of feedback would be AWESOME! Even a place to reference some samples.

Thanks !

2 reactions

Building Custom Applications

Hey all .... reasonably new to NB, but long time web native.

At first glance of custom NB development I can only see reference to API authentications.  
I can see here, a reference to PHP "Tools" Anatomy of a NationBuilder app ... which is cool, as most of our work is LAMP based.

I have clients with custom "apps" that we would look to be embedding into the workflows and profile/ACL access methods of NationBuilder ... which would require the applications to be run within the NB framework/site structure.  This is application around career profiling, strength/weakness profiling, career training, life direction, etc ... specifically about people who have lost direction, at risk, or needing direction/life planning after certain events in life.

I guess what we'd be looking to do is build something like a NB functional area, such as core "events/survey/petitions" type thing as a functional addon/app.  Is this something that can be plugged in, installed, maintained ... when it is not core?

Embedding custom apps and functionality into platforms like Drupal/Joomla/WP is easy enough ... but having trouble finding how/where we can do this type of thing in NB.  Hoping someone can point me in the right direction.

Thanks in advance,

Max Lynam :)

Add your reaction

calling /people/search with a custom field

Hi! I'm trying to call the people/search endpoint, searching on a custom field. As per the documentation it seems the url below would work for searching for us_citizen=true, but it returns a 500. Suggestions on what I'm doing wrong? Thanks! Heather

2 reactions

Cancelling the recurring donation

How to cancel a recurring donation? By looking at API documentation I've noticed that each donation has two fields: recurring_donation_id (which is not writable) and canceled_at.

1 reaction

Cannot obtain auth token

I cannot get past step 4 of the quickstart:

I've made sure that my client id, secret, redirect url and code are all accurate and up to date. 


curl -X POST --header "Content-Type: application/json" --header "Accept: application/json" --data '{"grant_type":"authorization_code", "client_id":"CLIENTID", "client_secret":"SECRET", "redirect_uri":"http://localhost:9000", "code":"CODE"}'

Note: things in capitals have been redacted


{"error":"invalid_grant","error_description":"The provided authorization grant is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client."}

Any thoughts as to what could be going on?

2 reactions

cannot update neither contact_method_id nor call_status_id


We are posting those fields as following, but when read back the call_status_id field does not exist or empty and contact_status_id shows  the old value.

"call_status_id": "4",

"contact_status_id": "3"

Add your reaction

Can't create a new contact; getting validation error

I'm trying to create a contact record but am getting a validation error:
HTTP POST (301.95ms) body   {"contact":{"sender_id":3,"status":"answered","method":"door_knock","type_id":2,"note":null}} Response status   Net::HTTPBadRequest (400)Response body   {"code":"validation_failed","message":"Validation Failed.","validation_errors":["recipient_id can't be blank"]}
recipient_id is listed as an optional attribute in the docs and it seems redundant since I'm passing the recipient in the url, but I'll play along:
HTTP POST (747.43ms) body   {"contact":{"sender_id":3,"recipient_id":12456,"status":"answered","method":"door_knock","type_id":2,"note":null}} Response status   Net::HTTPBadRequest (400)Response body   {"code":"validation_failed","message":"Validation Failed.","validation_errors":["recipient_id can't be blank"]}
I'm using code that used to work (and didn't need recipient ID). I've also tried this in the API explorer and get the same results.
Any advice?
1 reaction

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?


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.

Official response from

2 reactions

Can you assign point person through the API?


Official response from

1 reaction

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.


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

Official response from

1 reaction

Civicrm synchronisation

Has anyone already written code to synchronise People data between NationBuilder and a Civicrm site, using the two APIs?

We need to do that between our existing membership database and our NationBuilder site. I'd be interested to hear of any experiences from those who have already tried to do that.

11 reactions

client_credentials grant type

Hello, Looking at the Authentication process, could you implement the client_credentials grant type ? It would help authenticating from machine to machine without having to rely on a user account. It would allow those who don't like long lived tokens for their security risks to have an alternative. Many thanks

1 reaction

Comments API

Any chance we’ll see access to the Page Comments API in the near future? I’d love to be able to leverage Disqus comments without sacrificing the value of the native comment platform (i.e., creating new signup records and appending comment information to existing ones).

3 reactions

create a person returns 302


I am trying to create a new person via POST /api/v1/people and getting back 302 response without any other info.

This is the request  body:

{"person": { "first_name": "New", "last_name": "Person1", "phone": "1613111222", "email": "[email protected]" } }

Please help!

8 reactions

Create directory pages via the API

It would be great if this were possible! 


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

Official response from

1 reaction

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.


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.

Official response from

1 reaction