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

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!


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. 

Official response from

36 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

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

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

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

25 reactions

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

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.


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

12 reactions

When will API and web hooks be updated to reflect the new paths?

What is the status on webhooks/api access to paths?

11 reactions

New "upgrade" killing off the Developers?

According to , it looks like the Developer API is only going to be available on plans starting at a thousand dollars a month now?  This effectively kills off the developer market entirely.

Was this intended?  The Developer API was one of the main reasons I came to NationBuilder, and I keep my community hosted here.  It's also been a huge reason for me to promote NationBuilder as an option amongst other non-profits, but the new pricing effectively destroys the potential of usage by most non-profits... 

Is there any form of the API being left in the lower tiered plans?





It is true that nations on the Leader and Organization package will not have access to the API. Nations on any package can still install apps and hire a certified developer from our developer directory to build an integration with other systems using our API. The only restriction for nations on the Leader and Organization package is for them accessing the API to build a custom integration using non-certified developers.

Becoming a certified developer or publishing an app in our app directory will allow you to work with any customer regardless of the pricing package they are on. To become a certified developer please fill out this form and we'll be in touch shortly. To publish an app to our app directory please contact me directly at [email protected].

Official response from

18 reactions

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

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

Using the API from "pure" Javascript

I'd like to call into the API from within some JavaScript code, purely running in the browser.

How can you authenticate safely if you want to use the API purely on a client side application?  Many APIs allow you to restrict a token to a single or set of referrers (so they only work on sites under certain domains).  Is there a similar mechanism within NationBuilder's API?


14 reactions

Including Paths in the API


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




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

Official response from

11 reactions

Survey API endpoints

Is the survey aspect of the API live?  When I try to update survey questions I get this response back: 

"message":"Record not found"

I am using this json to pass it through:

"survey_response": {
"survey_id": 1,
"person_id": 2,
"question_responses": [{
"question_id": 2,
"response": 1
}, {
"question_id": 1,
"response": "yes"
}, {
"question_id": 3,
"response": "cool"

10 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

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.


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

Official response from

13 reactions

Using API in PHP for email sign up form; how to activate/verify email address?

I've got a script working nicely where a user visiting a WordPress site can fill out their name and email address, check the opt-in box, and sign up to a list on NationBuilder. But I can't seem to find any information on how to have NationBuilder send a verification email or double opt-in message to the new user to confirm that the email is valid and they do really truly want to be on this list. How would we go about this using the API?

4 reactions

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


This is not possible with our current page infrastructure.

Official response from

9 reactions

POST/PUT endpoints do not work.

I'm using the NB api via PHP. The GET/DELETE methods both work but no matter what I try I can not edit or add a new people resource using the client->fetch() function.

The error code is always a 400 no matter how I format the parameters. Please help and don't give me a canned response to the API helper because I've spent 3.5 hours already trying various things in the documentation which is thin to say the least.

11 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

Recording Pledge Data via the API

I'm working for a non-profit that is running a pledge drive, and has pledge form on its website.  Is there any way we can move pledge data into NationBuilder via the API?  I don't see pledges referenced anywhere in the documentation.

6 reactions

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.


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

Official response from

6 reactions

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


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

Official response from

7 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

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

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

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' = > ' [email protected] ' , " 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!
7 reactions

People Credentials

Hello I'm wondering if there is a way to use the people credentials from a nation into my application. 
I mean, is it possible that people from my nation logs in my app with their nationbuilder credentials (user and password)? 
I saw an app called oneclickpolitics which ensures that "NationBuilder customers can very Quickly and Securely login using their NationBuilder accounts." 
How can I do that? Am I missing some functionality from the nationbuilder API? As far as I know, the people endpoint returns no credentials. 
I would really appreciate any suggestions or help.
Thank you!
6 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

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

When Installing Field Edge app it disappears from my Control Panel

When I install Field Edge it doesn't appear in Installed Apps or in the app listing. This makes me concerned it's not installed. 

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

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


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

4 reactions

Webhooks do not immediately trigger when adding a tag

When adding a tag to someone in your database, the 'person changed' webhook will not fire until you save that profile or a different profile in the database. This makes syncing tags with an external database a challenge.

4 reactions

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.




2 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

Does access_token expire? oauth/token response includes "expires_in" attribute

In some tests I noticed that responses from /oauth/token have the attribute "expires_in". This attribute isn't included in the quick start guide example response, and a colleague found an article about access_tokens no longer expiring. Anyone have more information about this topic?


D B - What Alex is referring to in his previous comment is that tokens no longer expire until they are manually revoked through the nation's control panel.

Official response from

9 reactions

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

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

Search by any parameter

I’m working with my nation’s donation data, and I’d like to be able to search by more than just succeeded since, created since, failed since, and donor id. 

Is there any reason why I can’t pass tracking_code_id as a search parameter, or any of the other fields? Right now, my flow looks like this: 

Pull the entire list of donations that might match (say, by succeeded since date, or just pull them all)
Parse through and check the value/run my own search algorithm on the entire results I just pulled 
Do my processing 

Since I’m sometimes interested in searching all of our donations, that means each time I do this, I’m pulling down almost all of our donations, even if only 5-10 of them will match a criteria, like a tracking_code_id – it’s much slower than it needs to be, I think. 

Have I missed something? Is there a better way to use the search endpoint? What’s in the way of giving us access to this?



At this point we have only exposed the succeeded_at, created_since, failed_since, and donor_id search params for the donation search endpoint. There is not a way to run a targeted query via the API for just tracking codes.

We will consider adding a tracking_code_slug param in the future and will update this card and notify you when that is complete.

Official response from

5 reactions

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?

1 reaction

Issue with PUT'ing to people via API with PHP



We're using the NB people API with PHP and the adoy/oauth2 library. Recently, whenever our site makes a PUT to /api/v1/people/push, we seem to be receiving a code 400 error with no message attached. 




$payload = array(
'person' => array(
'first_name' => $first_name,
'last_name' => $last_name,
'email' => $email,
'note' => 'Sign up from web form at ' . DB::now(),
'email_opt_in' => true


$api_url = $baseApiUrl . '/api/v1/people/push';

$response = $client->fetch($api_url, $payload, 'PUT', array('Content-type' => 'application/json', 'Accept' => 'application/json'));

The response comes through like this:


    [result] => 

    [code] => 400

    [content_type] => text/plain; charset=utf-8



Can anyone point me in the direction of what isn't right here?




5 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

People Search Api not showing results



I am new to using the nation builder api. I have added multiple contacts to my account and trying to search on them using various fields. But I am unable to get the results.

The following person exists in my contacts and i can get it when I use first_name and last_name in the search parameters, but If i use city or state i am unable to get results.

primary_address: {

address1: "address"
address2: "3"
address3: null
city: "Fort Lauderdale"
state: "FL"
country_code: "US"
zip: "33311"
but if i use
i get no results
results: [0]
next: null
prev: null



Hi Ella,

There was an issue with people#search where instead of searching the primary address, the home address of people was searched instead (people in NationBuilder can have up to 7 different addresses, more on that here - including how to set primary address for a person). This explains why you weren't seeing results through the API as your nation didn't have any home addresses that matched what you were searching for.

A fix was pushed out today, and searching city or state through people#search should now return results that match based on the primary addresses of folks in your nation.



Official response from

5 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

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

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



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

Official response from

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

Webhooks: Support for Events


I'm suggesting support for webhooks for changes (creation, update, deletion) to events administered within NationBuilder.

My use case is I'm building a web app to index political events around the country. If groups, who are NationBuilder customers, could connect to it and submit new events and updates, that would have a huge impact on adoption, which would in turn impact event attendance for those customers, and subsequent volunteering, contributions and other engagement from the supporters. I can imagine other third party sites might be interested in this functionality too.

I'm a developer myself, so I'm happy to submit a pull request or sample code if that would be useful, but I'd be curious to hear NationBuilder's thoughts on adding this feature.

Thank you!


2 reactions

Liquid error: Internal error