NationBuilder is hiring

We're looking for software developers who want to change the world. Click here to learn more and apply.


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 VP of Community Adriel Hampton and the 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

Donation Synchronization, and Donation Search Endpoint

For my organization's use case, we need a synchronization of all donation records, in order to produce financial reports, and for other uses.  This requires high reliability of the synchronization process.

  1. Webhooks provide a synchronization potential with the downside that, like webhooks of other internet-based services, there is almost no feedback about webhook invocation failures.  This makes not meet the requirements of our use case.
  2. Querying the table of donation records as a replacement, or a verification procedure, of the webhook method would be workable.  However, since donations do not currently provide a search endpoint with an "updated_since" parameter, this creates the problem of having to download the whole donation table each time a synchronization is required.  This limitation makes the method virtually unusable for production employment in our use case.

Could you lift any of these limitations, or is there another way to solve this problem.  Again, we have the legal necessity of not missing any records, or misrepresenting any record fields.




1 reaction Share

ruby php

Add your reaction Share

Request for a webhook on petition signature

This would be radical.  Thanks!

Add your reaction Share

People Update server error

I'm trying to update a supporter record and running in to a 500 error.

I did a PUT request to
using the data:

This is the response:
HTTP/1.1 500 Internal Server Error
Date: Wed, 09 Apr 2014 14:38:59 GMT
Server: Apache/2.2.22 (Ubuntu)
X-UA-Compatible: IE=Edge,chrome=1
Cache-Control: no-cache
Nation-RateLimit-Limit: 15000
Nation-RateLimit-Remaining: 14978
Nation-RateLimit-Reset: 1397088000
X-Request-Id: 61ca028a58830a98d0c83ce60c18d079
X-Runtime: 0.532239
X-Rack-Cache: invalidate, pass
X-Powered-By: Phusion Passenger 4.0.23
Status: 500 Internal Server Error
Vary: Accept-Encoding
Content-Type: application/json
Via: 1.1
Connection: close
Transfer-Encoding: chunked
{"code":"server_error","message":"You have encountered a server error.","inner_error":{"name":"NoMethodError","message":"undefined method `strip' for nil:NilClass"}}


The same data POSTed to the create endpoint successfully created a supporter, and I'm using the same function to PUT tags.

Any ideas what could be causing this?

Add your reaction Share

People Create Endpoint and PHP.

Hello, I am trying to create an application with People Create Endpoint and the PHP API.
'Get Peoples' works perfect but when I try to add a new person in my Nation, the problems begin.
My token is valid, because I tested it with the new API Explorer tool.
My example with GET is:
$ token = ' MyToken ';
$ client -> setAccessToken ($ token );
$ response = $ client -> fetch ( $ baseApiUrl '/ api/v1/people /'. )
print_r ( $ response );

This shows all the Peoples in my nation.
And this is the example I'm using with POST:
$ token = ' MyToken ';
$ client -> setAccessToken ($ token );
/ *
$ data = array (
    'person ' = > array (
        'email' = > ' ' , " last_name " = > " Smith ", " first_name " = > "Bob"
) ;
$ data_string = json_encode ( $ data );
$ response = $ client -> fetch ( $ baseApiUrl '/ api/v1/people / ', $ data_string , "POST" . )
print_r ( $ response );
I'm not getting any response neither in the browser nor in the curl_request_info file.
What is wrong with my code?
I'm using Ryan Morgan's library ( ) .
I hope someone can help me or show me one example of how to do a POST Request for People correctly?
Thank you very much!
1 reaction Share

Set date when awarding social capital

I would like to be able to set the date when awarding social capital. More importantly I would like to do this through the API.

The reasoning for this is that if we manually award SC for somebody who volunteered to work a shift at one of our events, we would like the date that the SC was awarded to be the same date as the event. We actually have a backlog of SC that I was planning on importing using the API and just realized that I can't set the award date.


Add your reaction Share

Events API "guests_count" parameter clarification

Posted this on the Events API page ( but thought I should post here as well:

For the guests_count parameter, what is the API referencing? When you create an event, you have the option to do a simple RSVP and include +1s. However, if you have ticket sales, you purchase a number of tickets. Does guest_count reference +1s or number or tickets, or both? Ideally, it would great if it’s both!

Add your reaction Share

Test Token Example

You have great examples on how to navigate the minefield that is OAUTH, but now that you have test tokens, I'd like to see some simple example code on how to use the test token (python/php or even curl).


Official response from completed

curl https://[slug][my test token here] -X GET -H “Content-Type: application/json” -d ‘{"first_name":"Arion"}’ 

2 reactions Share

Searching people returns invalid json format error

I am searching people using this url:

with header "Content-Type: application/json" and with following request body:


but it gives me error that json format is invalid


Official response from completed

You can accomplish this search with a cURL command wrapping your JSON into the URL. See below for the command you can run in Terminal:

curl[my test token here] -X GET -H “Content-Type: application/json” -d ‘{"first_name":"abs"}’ 

3 reactions Share

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!

Official response from

Can you paste the code?

I have a few questions here

1) Why are you encrypting the access token?

2) When you say "save" you just as a session variable or are you saving to a DB?

3) How are you saving it to $_SESSION and do you have this issue with any other variables?  If so check your PHP version because $_SESSION and other register globals were deprecated in 5.3 and removed in 5.4  

I would guess you are doing something like (see below)


$_SESSION['token']=<access token here>;


If you are losing your the value on the next page perhaps you are not passing a session identifier and calling session_start which would cause a new session to start.

4 reactions Share

PUT to people API via PHP

When i do something link this in PHP:

$params = array(
    'person' => array(
      'email' => '','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?




Official response from

Alexander, I sent you an email with a proposed solution; let me know if that works for you.

thanks, Arion Hardison


3 reactions Share

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?

Official response from started

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.

2 reactions Share

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?

Official response from

Scott, thanks for your feedback. 1 and 2 sound like possible bugs - can you send us information on which nation you were working on and cURL commands and response bodies for us to review to Our bug reporting tips are here

I'm also looking into the feasibility of your request for recurring donations to be handled differently.

3 reactions Share

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.

Official response from

Eric, JSONP is supported for our API endpoints with the exception of stuff like the /oauth/token endpoint. You should be able to use it with endpoints like /api/v1/people

You also want to wrap your calls in JSONP. So:


If you continue to run into trouble, you can email us a text file with http request and response samples, using something like, to

1 reaction Share

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.


Official response from

Eric, the nation slug for safestreets was previously schoolmeals - you'll be able to use the API with the original name. 

3 reactions Share

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?


5 reactions Share

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.

Official response from

Thank you for your question.

In this case, you want to include the payload in the POST body as JSON, not in the URI as a query parameter. Although it might seem like both styles are equivalent, URI query parameters are more restrictive.

1 reaction Share

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.



Official response from

Steve, parent/child page relationships are not presently represented in the API. We'll review adding those parameters. 

2 reactions Share

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?




Official response from

It may be that you don't have a page with the slug "blog" on your site. The Page Attachments API POST endpoint is looking for a slug, not a page type. If you need more help on this issue, please email Thank you!

2 reactions Share

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('','NB Webhook Data',$message_body);



Add your reaction Share

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?

Official response from

Sebastian, the authorization is handled on a per-nation basis, so you won't need donors to approve passing their information once you have an access token from the nation. Per the quickstart guide, you'll have a nation administrator authorize the app, you'll get a short-live code back, then exchange if for an access token. That token should be stored securely and can be used again and again to pass information back to the appropriate nation. It expires only if revoked - then you'd need to have your app authorized again by the nation.

1 reaction Share

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 ?

Official response from completed

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

3 reactions Share

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!!

Official response from
5 reactions Share

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

Official response from

Yes! We have a set of endpoints for managing Political Capital.

1 reaction Share

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 Share

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 Share

access tokens

Official response from

Access tokens are described in our API quickstart guide

1 reaction Share

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? 

Official response from

Brad, we're in the process of updating the webhooks and REST for consistency and to expand the availability of fields - work address will be supported in both. We'll email the full API community when this is released.

Update: Work addresses are now available in the People API.

2 reactions Share

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. 

Official response from

Great suggestion, Bruce. We do intent to expose more communications features in the API - however, we don't presently have a timeline for this and have quite a lot of new features planned before communications. You may want to look into SendGrid's API, which we use for our mail services - you could build an email app using their tools and log new people and contacts back into NationBuilder using our existing calls. 

1 reaction Share

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 Share

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.

Official response from

Mark, note that commas have specific functionality in the native tagging feature (splitting a comma-separate value into multiple tags) - however, other punctuation in tags can be handled through the API with standard HTML URL encoding. Here's a helpful resource for the encoding for different characters, including spaces and forward slashes:

3 reactions Share

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

5 reactions Share

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.

Add your reaction Share

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

7 reactions Share

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

Official response from

Priority and party fields are now available in the People API.

6 reactions Share

Ruby tips: Debugging, layout and documentation

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

Add your reaction Share

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.

4 reactions Share

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 Share

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": ""




      "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!
Official response from

Ted, we've just released a major expansion of the People API that includes the fundraising flag, goals, amounts raised and more. You can review the docs on Github here: NationBuilder People API on Github

1 reaction Share

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 Share

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 Share

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 Share Integrations

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

Official response from

Because NationBuilder's API is still being expanded, we have not committed the internal resources to setting up a Zapier integration.

If would like to set up your own NationBuilder Zaps, it's possible to do that. We have, however, chosen not to have an official presence there at this time.

10 reactions Share

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
Official response from completed

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!

3 reactions Share

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.  

Official response from completed

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.

14 reactions Share


Would love to see the API access lists

Official response from completed

You got it!

3 reactions Share

Like this page to spread the word