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 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:
- Index endpoint (to return all petitions per site)
- Create endpoint (create a new petition)
- Show/update/delete endpoints (these are less important to us, but useful all the same :)
- Petition signature Count endpoint (return the number of people who have signed a given petition)
- Petition signature Index endpoint (return the NationBuilder IDs, first names and emails of everyone who has signed a given petition)
- Petition signature Create endpoint (add a new signatory to a given petition)
Thanks for considering!
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.
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).
Theme API to Support Easy Theme Creation / Updates
[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?
Thanks
Mohamed Hisham
zapier.com Integrations
Do you support integration using Zapier.com? This would be very helpful as it supports hundreds of different integrations in one package. Thanks!
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.
completed
If you're experiencing a bug, please contact our support team at [email protected] and follow these steps for reporting your bug.
Thanks!
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.
considering
This issue has been confirmed but does not have a set timeline on when it will be fixed. Please follow this cards if you would like to receive email updates about the status of this issue.
When will API and web hooks be updated to reflect the new paths?
What is the status on webhooks/api access to paths?
New "upgrade" killing off the Developers?
According to http://nationbuilder.com/feature_comparison , 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?
-Reed
completed
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].
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.
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.
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?
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.
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
Including Paths in the API
Hi,
It would be a huge help if paths and steps were included in the API. Then we could automate much more of the importing and tracking that we do. The feature has been out for a while and it seems intuitive that the feature would be included in the API. Thanks so much!
Jenny Landon
Represent.Us
completed
Jenny,
We now have a paths API with the ability to index paths and steps. Please see the documentation.
Survey API endpoints
Is the survey aspect of the API live? When I try to update survey questions I get this response back:
{
"code":"not_found",
"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"
}]
}
}
Is there any way to ajax submit a form in NationBuilder?
considering
This is not possible with our current page infrastructure.
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.)
considering
This is something we will consider but does not have a timeline at the moment.
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.
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.
submitted
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.
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.
considering
This is something we will consider but does not have a timeline at the moment.
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.
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.
considering
This is something we will consider but does not have a timeline at the moment.
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?
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.
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.
submitted
We are investigating why FieldEdge doesn't show up under 'Installed Apps.' After testing the integration, it is clear that FieldEdge is syncing with the nation so functionality is not limited due to this issue.
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.
Thanks,
Steve
submitted
Steve, parent/child page relationships are not presently represented in the API. We'll review adding those parameters.
People Credentials
I mean, is it possible that people from my nation logs in my app with their nationbuilder credentials (user and password)?
People Create Endpoint and PHP.
Imports via API incorrectly allocating records as prospects
I have imported a number of records via the API, which all have an email address and email_opt_in='Y', but the
records are being imported as PROSPECTS. Whereas http://nationbuilder.com/how_support_status_is_determined says:
"Records imported with:
* support level = 1
* support level = 2
* email address and email opt-in = Y
* mobile number and mobile opt-in = Y
will always be supporters."
considering
This issue has been confirmed but does not have a set timeline on when it will be fixed. Please follow this cards if you would like to receive email updates about the status of this issue.
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).
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.
completed
This bug has been fixed.
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);
print_r($response);
i get the following response
Array
(
[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?
submitted
Alexander, I sent you an email with a proposed solution; let me know if that works for you.
thanks, Arion Hardison
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.
Thanks!
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.
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).
Thanks
Dennis
completed
curl https://[slug].nationbuilder.com/api/v1/people/search?access_token=[my test token here] -X GET -H “Content-Type: application/json” -d ‘{"first_name":"Arion"}’
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.
- 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.
- 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.
Thanks,
--
Pav
I get a 500 error when trying to add a page attachment to a blog
When I hit the following url:
https://mysitename.nationbuilder.com/api/v1/sites/mysitename/pages/blog/attachments?access_token=mytoken
with the data:
{"attachment":{"filename":"flower-tiny.jpg","content_type":"image/jpeg","content":"/9j/4AAQSkZJRgABAQEASABIAAD/4QBARXhpZgAATU0AKgAAAAgAAYdpAAQA\nAAABAAAAGgAAAAAAAqACAAQAAAABAAAADKADAAQAAAABAAAADAAAAAD/2wBD\nAAEBAQEBAQEBAQEBAQEBAgMCAgICAgMCAwIDBAMEBAQDBAQEBQYFBAUGBQQE\nBQcGBgYHBwcHBAUICAgHCAYHBwf/2wBDAQEBAQIBAgMCAgMHBQQFBwcHBwcH\nBwcHBwcHBwcHBwcHBwcHBwcHBwcHBwcHBwcHBwcHBwcHBwcHBwcHBwcHBwf/\nwAARCAAMAAwDASIAAhEBAxEB/8QAHwAAAQUBAQEBAQEAAAAAAAAAAAECAwQF\nBgcICQoL/8QAtRAAAgEDAwIEAwUFBAQAAAF9AQIDAAQRBRIhMUEGE1FhByJx\nFDKBkaEII0KxwRVS0fAkM2JyggkKFhcYGRolJicoKSo0NTY3ODk6Q0RFRkdI\nSUpTVFVWV1hZWmNkZWZnaGlqc3R1dnd4eXqDhIWGh4iJipKTlJWWl5iZmqKj\npKWmp6ipqrKztLW2t7i5usLDxMXGx8jJytLT1NXW19jZ2uHi4+Tl5ufo6erx\n8vP09fb3+Pn6/8QAHwEAAwEBAQEBAQEBAQAAAAAAAAECAwQFBgcICQoL/8QA\ntREAAgECBAQDBAcFBAQAAQJ3AAECAxEEBSExBhJBUQdhcRMiMoEIFEKRobHB\nCSMzUvAVYnLRChYkNOEl8RcYGRomJygpKjU2Nzg5OkNERUZHSElKU1RVVldY\nWVpjZGVmZ2hpanN0dXZ3eHl6goOEhYaHiImKkpOUlZaXmJmaoqOkpaanqKmq\nsrO0tba3uLm6wsPExcbHyMnK0tPU1dbX2Nna4uPk5ebn6Onq8vP09fb3+Pn6\n/9oADAMBAAIRAxEAPwD5/wD+CUf/AAS4/wCCd3xc/Ym+FHjPxj8L/G3xj+M/\nxomsLPVneyj1SXQJLuW4iF8EjdFtNNhGTJM25xhSc7QB/ON/wVV/Yag/Ys/b\nB8X/AAh8NadeaZ4TvbG31rSYGZ7oR2s7yxgLIwBdS0DkZ6ZK5O2vPf2SP+Cj\n37Uv7HnhrxV4Y+CnivSNM0/XIiu69sheSWYw5IgYsPLBbaxHIJRcjHB+VPjL\n8dPiv+0B8QNa+KHxd8a6x4y8ba8V+0Xlw+07V+7GqrhUUZOAAByT1JNeFjci\nxeT18HQyvHSlhGqlSsq8Yzqyqza5VCpHltSpWnGMbK8XC65ouT+yzzD08Vle\nAxNTESdSPNBQjTpwhbTmcmm5Tle1m0t5O+tj/9k=\n","updated_at":"2014-01-03T11:19:23-06:00"}}
I get a 500 error. Any way I can get this to work?
Thanks,
Steve
submitted
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 [email protected]. Thank you!
Set address used as primary address
Using the API, how can I update which address is currently used as the primary address? e.g. mailing, home, billing, ... It would also make sense if the person object included which address is currently set as the primary address. This is helpful to know which address to update.
submitted
It isn't possible to change which address is the primary address via the API. If it is not set manually in the control panel, the primary address is set automatically to the first present address in this hierarchy:
1. home
2. registered
3. billing
4. work
5. mailing
6. user-submitted
7. Twitter
If you wish a different address to be the primary for a group of records, you would need to run a batch update in the control panel.
PUT request
We're making a request to an offsite domain, and when I making a PUT request to the offsite server via $.ajax, it looks as if the authenticity token is being concatenated to the end of the stringified JSON object - this obviously causes problems when our offsite server attempts to parse the JSON object, it finds a "&authenticity_token=..." which is not valid JSON.
It looks as if the check of how the authenticity token should be appended (I snooped around a bit in the minified liquid files) is a bit naive. Yes, we're sending up JSON, but best practice (http://stackoverflow.com/a/12693986 <http://stackoverflow.com/a/12693986>) is to stringify with $.ajax first. The authenticity token attachment logic incorrectly interprets the stringified JSON to be a query string.
I have solved this for the most part by preventing this event handler from firing by including the 'global:false;' option in the AJAX request. Thanks!
submitted
Hi Luke,
You should be able to stringify your JSON data in an $.ajax request, though it sounds like you were able to resolve this on your own by setting the global parameter to false. If you're still running into issues, however, you can send your examples to [email protected] and we'd be happy to investigate further.
FWIW, another developer seemed to encounter a similar error and was able to resolve by removing the accepts parameter: JSON/jQuery formatting for People create?
How to get client id and api secret
How to get client id and api secret
completed
Steps 3 and 4 of our API Quickstart guide describe how to obtain a client ID and API access token:
Pagination on the API returns different results in production vs. testing environments
When I run this method locally, I get the pagination information up at the top (page, total_pages, per_page, total); the same result as in NB's API Explorer. When I run it in my production environment... Heroku, nada.
The interesting thing is that the "next" and "prev" hash show up both locally and in production. So, I also tried to use them as markers to loop, making API calls until the "next" hash returns nil, spelling the end of the pagination. Again, this works perfectly fine locally. However, in production this actually made it worse because it resulted in an infinite loop which crashed the app. It seems the API never actually returns next as "nil", but instead keeps returning a unique API URL to the "next" set: "/api/v1/survey_responses?__nonce=[omitted]&__token=[omitted]&page=1448&per_page=100&survey_id=47"
I'm trying to figure if it's NationBuilder's API, my app or Heroku that are causing this discrepancy. Am reaching out to Heroku as well and testing the app itself.
I wanted to see if anyone else has come across this and solved it?
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.
considering
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!
Tags Endpoint Doesn't Accept Forward Slashes
I'm trying to use the GET /tags/:tag/people endpoint, searching for a tag such as "Ajax/Bowmanville" and getting a 404 response. It works fine with a tag like "Ajax-Pickering" which doesn't have the front slash. I've tried replacing the front slashes with %2F, as suggested here http://nationbuilder.com/mdunbar50/issue_with_space_and_in_people_tags_search but it doesn't help. Any advice would help! Thanks
considering
We have confirmed this bug but do not have a timeline for when a fix for this issue will be implemented. But we've noted it and will post any updates here.
List
Would love to see the API access lists
completed
You got it! http://nationbuilder.com/lists_api
Custom Fields list API method needed.
I think a new method is needed to list a nations custom fields and their types. For instance by only being able to view a custom field on a person I am unable to tell the difference between a text and a multiple choice field.
Also I am unable to infer the possible options for a multiple choice field if there is no person with that option.
considering
This is something we will consider but does not have a timeline at the moment.
Is Theme Sync dead?
Used it quite a bit 2 years ago to great effect. Now it loops between choose site page and back to login page. Choosing a site seems to log me back out.
Still working for other people?
started
Jedd,
ThemeSync still works and I recommend uninstalling/reinstalling it to get past the hiccup you're experiencing. Also, we have started working on a different solution that utilizes a Dropbox integration.
I am facing issues with http and https to https//www.
I am facing issues with http and https to https//www. is not redirect. http is redirecting https//www. but https is not redirect. Can anyone suggest me how we resolve it
Issue with PUT'ing to people via API with PHP
Hi,
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.
Code:
$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?
Thanks,
Sam
Subscribe to list widget
I want to add a box to my site that allows users to sign up for a mailing list that we are now migrating to NationBuilder.
My site is Python/Django. I have this already set up with Mailchimp.
The Python Quickstart doc doesn't explain what the variables 'code' or 'REDIRECT_URI' are or how they should function in step 4.
This should be pretty basic functionality. Am I missing something? Is there a simpler way to implement this?
completed
Brett, for a single-nation use, just use an app test token - you can find that in your nation's control panel under Settings > Apps.
Webhooks: Support for Events
Hello,
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!
Jon
submitted
Jon,
Have you considered setting up your app so that customers can authenticate it against their nation and then you can use our events API to index events in any nation that authenticates on a rolling basis? It seems like that would be a work-around that would require as much, if not less, work on the part of the nation owner to setup.