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

How to save access token in PHP?

I've tried saving the access token as a key/value pair in the $_SESSION variable, but if

a) I encrypt it and then save it, on the next page or request, it has changed or 

b) I don't encrypt it and save it as a string, it is deleted from $_SESSION on the next page.


What am I doing wrong here? I need to make multiple requests in sequence and have a feeling I shouldn't need to ask for a new access token with each one. Thanks!

4 reactions

PUT to people API via PHP

When i do something link this in PHP:

$params = array(
    'person' => array(
      'email' => '[email protected]','home_address' => array('country' => 'Germany', 'zip' => '66666' ))

$header = array('Authorization:' => $token,'Content-Type:' => 'application/json', 'Accept:' => 'application/json');
$response = $client->fetch($baseApiUrl . '/api/v1/people/push?access_token=myaccesstoken', $params, 'PUT',$header);

i get the following response

    [result] => Array
            [code] => missing_parameters
            [message] => Missing Parameters.
            [parameters] => Array
                    [0] => person

            [inner_error] => Array
                    [name] => Api::Error::MissingParameters
                    [message] => Missing parameters: person


    [code] => 400
    [content_type] => application/json


Whats wrong with the Parameters? Do i need to add something else to the Params?




13 reactions

Missing membership fields in People API

I want to synchronise our civicrm membership records with NationBuilder. But the People API does not have any fields for membership level, start or end dates. 

Any chance in including every possible People field in the People API?


David, thanks for your suggestion - and yes, we're working on a massive expansion to the People API fields that should address your needs. We'll shoot you an email when that goes live.

Official response from

3 reactions

Limitations with the write endpoint of the Donations API

The new write endpoint has a few limitations that make it difficult to implement a good external donations solution and track the donations back in Nation Builder:

1) It does not allow donations to be assigned to an existing supporter, but instead creates a new user for every donation. Ideally we'd be able to pass a signup id in the initial payload, which would then assign the donations.

2) We have not been able to write any donation types other than CASH (such as Credit Card), which means they are recorded as "FAILED" and do not show up in reporting.

3) There are no options to write recurring donations and have them show up in /admin/signups/{id}/donations/recurring. This means we cannot effectively build an external recurring donations system and track that back through Nation Builder.

1-2 are priorities for us to be able to effectively use the API for our apps, any idea when these options may be supported?

3 reactions

Fields that can be mapped to NationBuilder from 123contactform

I've been using the new 123contactform integration and it is fantastic! seems to be missing some standard fields that are available in the people/edit page on NB. 

From 123contactform you can map to home, meetup (what is this? it doesn't seem to exist on the NB side), billing, and mailing addresses, but there is no work address available.

Also, the primary address is there, but according to other posts I've seen, the primary designation is set to whatever address gets populated first.  When mapping from 123contactform to NB on the primary address fields, it doesn't populate because of that.

There is also no work phone available. 

Can you make work phone, work address, and website available in the integration?

1 reaction

How to use JSONP with the API?

I'm trying to call the people api through AJAX using jquery but the response doesnt seem to have a callback wrapper, which causes an error. here is some sample code:

function getPeople(){
data = {
"access_token" : token
url: peopleIndexUrl,
type: "GET",
cache: false,
data: data,
dataType: 'jsonp',
success: function(data,textStatus,jqXHR){
error: function(jqXHR,textStatus,errorThrown){


 The call does seem to go through fine. Perhaps I have to change the callback? Thanks.

1 reaction

error "nation_not_found"

I followed the PHP API Quickstart guide and was able to easily obtain an access token. However, when I am trying to use the API in any way I get the following error response:

Array ( [result] => Array ( [error] => nation_not_found [message] => The nation identified by this request was not found. ) [code] => 404 [content_type] => application/json )

My nation is, is there a setting I have to enable in order to use the API? Thanks.


3 reactions

Theme API to Support Easy Theme Creation / Updates

I know there is the Mac theme sync tool but for those not using Mac, NationBuilder theme development is a pain. Also for those of us using continuous deployment that wouldn't be of any help as most probably aren't using Mac for that.
We wrote a Shopify Desktop Theme Editor for any platform to handle this for Shopify users through Shopify's theme endpoint but were wondering if there would ever be a NationBuilder endpoint for this?
Any other NationBuilder devs who'd like this?


26 reactions

Page Attachments API question.

Trying to upload a file with thru the oauth library, and getting error that the request uri is too long. I used encoder such as and got a ridiculously long string.

content -  Base 64 encoded representation of the file, with standard RFC 4648

Am I doing something wrong? Does "representation of the file" means an encoded version of the file? or it means url to the file or some other kind of representations?

Any helps/hints are appreciated.

5 reactions

How does one create a sub page of a page through the API

There doesn't seem to be a way to either create pages as sub pages through the api or to attach existing pages to other pages as sub-pages.

Any help would be appreciated.



8 reactions

I get a 500 error when trying to add a page attachment to a blog

When I hit the following url:


with the data:




I get a 500 error. Any way I can get this to work?




2 reactions

PHP Webhook Listener

Make a php file on your server and create a webhook to point to it. When data is sent to the page, it will send you an email with the data. Make sure to change the email address before using.


$data = file_get_contents('php://input');
$json_data = json_decode($data);
$obj = $json_data->payload;
// Assemble the body of the email...
$message_body = <<<EOM
first name: $fname \n
last name: $lname \n
nationbuilder_id: $nid \n
mail('[email protected]','NB Webhook Data',$message_body);



1 reaction

Using OAuth2 access tokens with the People API


We are trying to use the with the Push endpoint to create new donors in the NationBuilder system from our external website. Basically when we process a new transaction we want to record the person in NationBuilder using the API. Obviously asking the donor to approve this action as part of the donation process is a pretty strange, so I'm a bit puzzled by the use of OAuth2 for this use case. 


I have been following the documentation here to do the development:

I've managed to get things working in PHP as per this guide:


It seems we need to manually approve the application to get access in order to capture an access token which we can then use to post information to NationBuilder. Am I taking the right approach here? Should I be storing the access token server side to use later down the track for all our API requests? What happens when the access token expires?

1 reaction

People API Should Expose "Bad Email Address" field

Like the title says, the boolean flag for the "bad email address" exposed in the HTML UI should be available in the Person record returned. Is there another way to acquire and set this value ?


Update: This field was added to the People API on March 25. Thanks for your suggestion!

Official response from

3 reactions

PUT Method on Blog Posts API Example

Hi, i am reading the "Create Endpoint" article in the API documentation guide. I can't make   the Post request work.
Could you provide a php code where i can see how to create the body for the request?

I'm using this code:

$fetch = $client->fetch($baseApiUrl . '/api/v1/sites/johndoe/pages/blogs/1/posts/', $parameters = array($json_body), 'POST', array(
"Content-Type" => "application/json",
"x-li-format" => "json"

I get this message: "invalid_json".


Thanks in advance!!

4 reactions

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

Is JSONP enabled in the API?

I'm attempting to using AngularJS to access the API using JSONP (eg ?callback=JSON_CALLBACK, via this ST question) and I'm getting a 404 when hitting the /oauth/token endpoint.

Is JSONP enabled? If so, what might I be doing wrong here?

Relevant code below:

$http.jsonp('', {
  method: 'POST',
  data: {
    client_id: 'CLIENT_ID',
    redirect_uri: 'http://localhost:9000',
    grant_type: 'authorization_code',
    client_secret: 'SECRET',
    code: 'CODE',
3 reactions

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

access tokens

1 reaction

Does the API allow access to the work address?

Many supporters have work addresses -- this is where the employer's address is stored when people give that info when making donations. 

However, it appears that the webhooks API only pushes out a supporters' primary address? This is not explicitly confirmed in the docs but I've done some testing and think this is the case. 

What's more confusing is whether or not this field is available via the REST api. The docs list every other address field. I'm wondering if this is a documentation omission, or if for some reason the work address isn't included? 


Hi Brad,

We've updated webhooks (v4) to include work addresss, and made some updates to the API as well to make the included fields read/writeable via the People endpoint

Official response from

5 reactions

email api?

Any thoughts on an email API that could help supporters recruit others? For example, I want to start a recruiting drive where each supporter recruits at least two others. I'd like to create an app that allows people to enter a few emails, use default/editable text, and send emails out right from the page on their behalf. 

5 reactions

Using webhooks with PHP

Autumn Welles with Richir Outreach posted up this helpful NationBuilder webhooks + PHP tutorial with example script earlier this year.

Add your reaction

Issue with Space and / in People Tags search

Was building app that to search for for people with specific tags using api call : GET , but it returns code t=404(NOT FOUND) if tag tagname string contains space or "/".   This was not expected as spaces and / characters do not seem create search problems in other Tag searches on Nationbuilder outide of the API.

3 reactions

Request Date Field in Contacts API

As noted else where in support, Contacts apparently default to date the contact was entered, and don't allow option to edit date to that on which contact actually occurred.  This, ought to be fixed generally, and the option to edit the date added to the Contacts API

8 reactions

Request an Activity Stream API

I would like an API to access the Activity Stream, as the Contacts API is only showing a portion of the communications relevant to a person.  My present objective is simply to access the same information as is shown in the People dashboard in read only format.

3 reactions

Request Followups API

Would like an API to access followups set for a person (or all persons) and assigned to a user (or any user).

22 reactions

People API could be improved easily with access to party and priority level fields

Would like to have the party and priority level fields added to the People API

6 reactions

Ruby tips: Debugging, layout and documentation

Our CTO, Dan Walmsley, spotted these helpful tips from globaldev:

Add your 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

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

Getting data on fundraisers' goals and amounts raised so far


We'd like to do analytics to track things like progress toward individual fundraisers' fundraising goals. To do this, we'd need to 1) determine whether a person is a fundraiser, 2) get their fundraising goal amount, and 3) add up all of the individual donations that that fundraiser has raised so far.
According to Adriel, there's a "is_fundraiser" field that will be surfaced, so it sounds like that takes care of the first requirement. Is there also a way to get a fundraiser's goal amount, if that's been set in the UI?
Also, in the Donations API documentation, it says we can get information about individual donations in this form:




      "id": 314,


      "amount": "$10.00",


      "succeeded_at": "2013-02-21T10:04:15-04:00",


      "corporate_contribution": false,


      "fec_type": "Contribution",


      "donor": {


        "id": 8472,


        "first_name": "Sarah",


        "last_name": "Kerrigan",


        "email": "[email protected]"




      "election": {


        "cycle": "2013",


        "period": "Primary"






Besides "donor" is there some field in the Donations API that gives information on the fundraiser who raised that individual donation, so that we can link fundraisers with all of the donations they've raised? Thanks!
1 reaction

NationBuilder Ruby gem from the team at ActionSprout

If you're looking for a Ruby gem to help out your development efforts, ActionSprout's got one up on GitHub here.

1 reaction

François Kooman's PHP OAuth client now includes support for NationBuilder

If you're building PHP apps on our API, this should come in handy. Please note that this is third-party code and is not supported by NationBuilder. PHP developers have also indicated that Lusitanian's library is helpful. For official resources, browse our docs.

1 reaction

Make tags available in the Blog Posts Index endpoint

Tags are supported when you GET an individual blog post, or POST/PUT a blog post, but not when you GET a blog's index.

Would be nice to be able to get lots of tags at once so they can be batch edited.

In short, it'd be great if the same fields for a GET on an individual post would be available for a GET of the blog's index.

1 reaction Integrations

Do you support integration using This would be very helpful as it supports hundreds of different integrations in one package. Thanks!

25 reactions

Expand the /nearby endpoint


This could be a really powerful tool for our canvassers. But.... when I tried to build off it, I ran into a couple roadblocks.

  1. A 1mi search radius is far too big for someone walking around door-to-door
  2. There wasn't any way to limit the search to only people with complete addresses on file


This was just a bug, you should be able to put a distance in a parameter, 1 mile was only meant to be a default.  Thanks for the feedback!

Official response from

3 reactions

Posting Financial Transactions

Would be great if the Donations API could be opened up to read/write or that the Invoicing function be added as a read/write API so that we're able to post different types of transactions info.  

For instance, an e-commerce solution could post customer sales back to the Nation either as a donation using a tracking code or by generating and closing an invoice.  


We've opened up write access to nearly all the donation fields. You can find the docs on our main page, and you can also view the NationBuilder Donations API on Github here.

Official response from

14 reactions


Would love to see the API access lists


You got it!

Official response from

3 reactions