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!
Search people by precinct?
Is it possible to search for people by precinct? I'd like to use the API to find all people in a given precinct, so that I can build a strikethrough system for election day.
Thanks
1 reaction
Get the Name and Abbreviation of Capital for a Nation
Is it possible to get the custom name and abbreviation that someone has assigned to the (political/social) capital feature?
For example, if someone has changed "Political Capital" to "My Community Points" ("MCP"), we want to use that as the label when displaying capital_amount_in_cents. Displaying "Political Capital" generically could confuse people in many cases.
completed
There are not currently resources for the name or abbreviation assigned to a nation's political capital.
That said, this sounds like a very useful feature and I recommend that you request that it be added through our product suggestion page!
1 reaction
How to add a tag to user?
I have already used PUT people/:id/taggings api for that. But it is giving me response Bad Request Your browser sent a request that this server could not understand. [code] => 411 [content_type] => text/html )
completed
Hi there,
Try setting the Content-Type to application/json. I used the following curl command and received a 200 HTTP response:
curl -v -X PUT --header "Content-Type: application/json" "https://{slug}.nationbuilder.com/api/v1/people/{person_id}/taggings?access_token={token}" -d '{"tagging":{"tag":"{tag}"}}'
1 reaction
Anedot integration does not push through records with invalid email addresses
It has been reported that the Anedot integration does not send donation information with invalid emails through to NationBuilder. If a donor mis-types their email address (such as .con or .ney), the information will not be sent through and there is no indication of which transactions were not synced with NationBuilder. This makes NationBuilder donation records inaccurate.
submitted
Thank you Lauren - I moved this over to our API forum for that team to take a look at!
1 reaction
Add feature to list all people on a step through API
We have received reports that users may find it helpful to list all people on a specific step within a specific path using our API. Currently, we offer the ability to index paths and search people, but not the ability to search people on a specific path or step.
submitted
Thanks Alex! I'm going to scoot this over to our API forum for that team to take a look at!
3 reactions
Duplicate records being returned when hitting the lists API
It seems that the data that we get when we pull through the API is different than the data that you get when you just download a CSV file from a nation. The result is that the lists we pull from your API had about 20% duplicates.
completed
This is likely the outcome of using the export context type 'voter ballot'. The context type 'people' will return a single record per .csv file generated by the export API.
Voter ballot exports will have multiple rows with the same record because each row can contain a different election in which that record/person voted.
1 reaction
Exports via API do not include "updated_at" field
The "updated_at" field is not included in exports initiated via the Export List endpoint; "created_at" is included. Could "updated_at" be added please?
considering
This is something we will consider but does not have a timeline at the moment.
2 reactions
How to check if user has control panel access via API?
Hi all,
is it possible to check if the user has control panel access via the API? Perhaps also with their access level? Maybe using the /api/v1/people/me endpoint? Thanks!
considering
Craig,
It's currently not possible to know who has control panel access through the API. Permission sets aren't a resource the People API returns in the response body.
3 reactions
Can't generate OAuth tokens
According to the API Authentication Quick Start Guide, I should be able to generate an Oauth client ID/secret for my nation via Settings > Apps > New App. However, I only see options for "Install new app" and "Installed apps". The former shows a list of 3rd-party apps, but no option to create a new one. Am I looking in the wrong place?
completed
As Theodis pointed out, this information is wrong. It is actually under Settings > Developer > Register app. The documentation has been updated and thank you for bringing it to our attention.
2 reactions
Provide a way to list surveys through the API that do not require them to be on a Page.
Hi folks,
I want to use the surveys to let canvassers add extra details while they are contacting people using an app I am designing. Right now I am getting a list of surveys by hitting /api/v1/sites/:site_slug/pages/surveys
However, this only includes surveys that have a corresponding page made for them, so the user must first make a survey and *then* add it to a page on a site. Not the easiest!
Is it possible to just provide an endpoint that lists all surveys without requiring them to be on a page first?
Thanks!
considering
This is something we will consider but does not have a timeline at the moment.
2 reactions
People Search Endpoint - Updated since
What format is the "date" used in searches on the updated_since field in the people search endpont?
What is the granularity of the comparison, is it just a comparison of the date or is it really a combarison with the updated_at field of the record, which appears to have a resolution of 1s?
An example of using this api call might be useful.
submitted
The format can be either:
yyyy-mm-ddThour:minute:second-GMT timezone (Ex: 2017-02-01T04:24:21-08:00)
or
mm/dd/yyyyThour:minute:second-GMT timezone (Ex: 02/01/2017T04:24:21-08:00)
An example request using curl would look like this:
curl GET —header “content-type: application/json” 'https://{slug}.nationbuilder.com/api/v1/people/search?limit=1&updated_since=02/01/2017T04:24:21-08:00&access_token={token}'1 reaction
Basic Pages API: Internal Styles
The content you can install in a page is inserted in the body of the page. It would be helpful if it was also possible to insert content into the head of the page, perhaps via an optional 'head' payload, in addition to the 'content' payload.
My use case is that I want to insert CSS as internal styles i.e. <style> ... </style> which can only be inserted in the head of the page. Note I need functionality that can't be deployed using inline styles (i.e. using the HTML style attribute).
considering
This is something we will consider but does not have a timeline at the moment.
1 reaction
Return a better error message when an API call is made to a nation, endpoint that does not exist
When making an API call to an invalid endpoint the response returns the HTML from a 404 page. A response body describing the issue (endpoint does not exist, nation does not exist) along with a 404 status would be preferred for debugging issues.
Example:
[17] pry(main)> NationBuilder::Client.new("foo", "bar").call(:donations, :index)
NationBuilder::ClientError: <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8" />
<title>404 Error: The page you were looking for doesn't exist</title>
<style type="text/css">
body {
background: url(http://nationbuilder.s3.amazonaws.com/assets/404-grass.jpg) repeat top left;
color: #fff;
font-family: Lucida Grande, Lucida Sans Unicode, Garuda, sans-serif;
margin: 15px 0;
font-size: 1em;
}
#wrapper {
padding: 15px 0 0 45px;
}
#headline {
font-size: 2em;
font-weight: bold;
text-shadow: -1px -1px #333;
color: yellow;
}
#description {
font-size: 1.3em;
line-height: 1.8em;
color: #fff;
text-shadow: -1px -1px #333;
}
#footer {
clear: both;
font-size: 0.8em;
}
a:link, a:active, a:visited {
color: #ec7c31;
text-decoration: none;
}
a:hover {
text-decoration: none;
background-color: #fee34c;
color: #000;
}
#road {
margin-top: 15px;
}
</style>
</head>
<body>
<!-- This file lives in public/404.html -->
<div id="road">
<div id="wrapper">
<div id="headline">We couldn't find the page you were looking for.</div>
<div id="description">You may have mistyped the address or the page may have moved.</div>
</div>
<div id="road"><img src="http://nationbuilder.s3.amazonaws.com/assets/404-road.png" width="952" height="404"></div>
</div>
</body>
</html>
from [...]/gems/nationbuilder-rb-1.5.0/lib/nationbuilder/client.rb:129:in `parse_response_body'
considering
This is something we will consider but does not have a timeline at the moment.
1 reaction
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.
6 reactions
Is there any way to ajax submit a form in NationBuilder?
considering
This is not possible with our current page infrastructure.
9 reactions
How to get people that appear on "Contacted By" page on the data entry sheet of a list?
Hi all, do you know how can I use the API to get the same list of people that appear under "Contacted By" on the data entry sheet?
I'm working on a data entry app and would like to have similar functionality to be able to choose who contacted a person. Thanks!
completed
You can do this using the contact API/index endpoint and passing in the author_id parameter. A request using cURL would like something like this:
curl 'https://{slug}.nationbuilder.com/api/v1/contacts?author_id={id}&access_token={token}'
11 reactions
Index of donations for a specific donor
Right now the Donations Index endpoints returns all donations in a nation. It would be great if the API allowed the donor ID to be specified and then only return donations that have been made by that person.
considering
This is something we will consider but does not have a timeline at the moment.
1 reaction
Basic Pages API: Restricting access to pages
In the GUI I can restrict access to a page, for example pages can be restricted to control panel users. However, I can't see any way of doing that via the Basic Pages API. Am I missing something?
The background is that I am writing an app that will periodically sync a Nation with an external database. I thought a good way to provide feedback on the operation of the app would be to populate a basic page on the Nation with status information. I would prefer that the page was only accessable by control panel users. Any other ideas?
- Andrew
completed
Setting 'who can view this page' is not an attribute with the basic page/create endpoint.
1 reaction
Link donation to a membership through API
Whenever we assign a membership to a person through API, it always shows "Dues amount" as "Free" under "Memberships" tab ("Edit" > "Memberships") on the person's profile. Is there a way to link a donation to the membership or just show an amount instead of "Free"?
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.
1 reaction
Can you assign point person through the API?
Is there a way to assign point people through the API? All our lists are populated and kept up-to-date programmatically so we'd need to fit point-person assignments in this flow.
completed
You can absolutely do this via the people/push endpoint.
The resource you'll want to use is "parent_id" with the value set to the NationBuilder ID of the point person you want to assign.
1 reaction
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.
36 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.
considering
This is something we will consider but does not have a timeline at the moment.
13 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.)
considering
This is something we will consider but does not have a timeline at the moment.
7 reactions
Imports via API and webhooks
The create import endpoint does not offer the option to "Bypass webhooks" that is available when you perform a manual import.
- Do imports initiated by via this endpoint the relevant webhooks (ie Person Created and Person Changed)?
- Whatever the response to (1) it would be useful to control this behaviour from the API as it is via the manual interface.
incomplete
Andrew,
The ability to bypass webhooks is not available through the import API. Can you please clarify your question, reproduced below:
- Do imports initiated by via this endpoint the relevant webhooks (ie Person Created and Person Changed)?
1 reaction
Looking for the "right" way to hook into the form submission API
Hi folks, we'd like to add some JS actions—adding content to fields—to an NationBuilder form on submit before the form validation/send is triggered. However binding on the form submit handler triggers after the NationBuilder actions and the data is not captured.
Is there an elegant/sanctioned way to hook into the event dispatcher? Essentially I need a callback before the form submits though NationBuilder XHR channels. Someone has a gist of how to do this, but the timing of this isn't correct (form still submits).
1 reaction
Unable to use Import or People API with non-ascii characters (ie. á or ë with accents)
Hello. We're unable to import an CSV via the Import API, or update users via the People api when they have a name with a non-ascii character.
For example, if we post this JSON to the People API:
{
"person": {
"email": "[email protected]",
"last_name": "José",
"first_name": "Böb",
"sex": "M",
"signup_type": 0,
"employer": "Dexter Labs",
"party": "P",
"registered_address": {
"state": "TX",
"country_code": "US"
}
}
}
we receive a 400 Bad Request response. Can you please advise?
completed
When sending your request please set the content type in the header to Charset=UTF-8. For example, this is what the full header would look like:
--header "Content-Type: application/json; Charset=UTF-8"
2 reactions
Creating a new donation through the API doesn't carry with it the fundraiser info
We are using the donation API and are sending 'recruiter_name_or_email' through our integration to log who the fundraiser of a specific donation is. This data doesn't seem to be entering our nation even though the 'recruiter_name_or_email' field is a writable field.
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.
1 reaction
Extend Oauth 2 implementation to include Resource owner credentials grant
For cron jobs or similar we need Nationbuilder to extend it's Oauth2 model to include Resource owner credentials grant
2 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 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.
4 reactions
When is it safe to delete list after invoking add tag endpoint?
I want to add/delete a bunch of tags from a bunch of people. This involves multiple sequences along the lines
- Create temporary list
- Add people to list
- Add tags to people in list / remove tags from people in list
- Delete list
The documentation for the add tag endpoint says:
Use this endpoint to apply a tag to the people contained in a list. Note: this endpoint returns a HTTP 204 status code, but the tag is not applied immediately. For larger lists, this operation takes many minutes.
The remove tags endpoint is similar. So when is it safe to delete the list?
duplicate
2 reactions
When is it safe to delete list after invoking add tag endpoint?
I want to add/delete a bunch of tags from a bunch of people. This involves multiple sequences along the lines
- Create temporary list
- Add people to list
- Add tags to people in list / remove tags from people in list
- Delete list
The documentation for the add tag endpoint says:
Use this endpoint to apply a tag to the people contained in a list. Note: this endpoint returns a HTTP 204 status code, but the tag is not applied immediately. For larger lists, this operation takes many minutes.
The remove tags endpoint is similar. So when is it safe to delete the list?
completed
Andrew,
Once your done with adding/removing tags from those people you can delete the list. Deleting the list does not delete the people on that list (http://apiexplorer.nationbuilder.com/nationbuilder#Lists) when you hit the /api/v1/lists/:list ID endpoint.
2 reactions
Updates and imports not involving emails failing due to email validation errors
I've just come across some unexpected behaviour.
When using the people update API to update a precinct_code, e.g. with the payload:
{'person': {'precinct_name': 'Burton Bradstock'}}
I received a "400 Bad Request" with the response
{"code":"validation_failed","message":"Validation Failed.","validation_errors":["email '[email protected]' should look like an email address"]}
The same thing happened with imports that didn't involve email addresses failing because of email validation errors.
submitted
Because of the need to replicate this issue and the need for sensitive data to do so, I'm reaching out via email.
1 reaction
Trying to do shared Authentication but coming up blank
I have a need to integrate my Nation with an external system also hosted by us (on the same domain as our nation). The external system has user records and its own authentication. The external ids of these records are also present in our Nation.
What I really want is that when a user signs in to the external system they also sign in to our nation - i.e. I want a shared signon, but I cannot see any practical way of doing so.
Is there any avenue I can follow towards making this happen at all?
completed
David,
SSO might be the best solution here. It is an option available to enterprise customers. Please contact your community strategist to discuss implementation.
1 reaction
Survey API not correct
http://nationbuilder.com/surveys_api
Copying and pasting example code to create a survey generates a warning message. Adding an extra status - associated with the survey as opposed to the question it then works.
http://nationbuilder.com/surveys_api
completed
Luke,
Thanks for the feedback. There was a missing 'status' for the survey page in the example code. It should work now.
2 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.
completed
This bug has been fixed.
6 reactions
API Reporting or Permission Levels
In order to ensure the security/privacy of our supporter information we'd like to see a daily report on how third party apps have used the API and/or the ability to restrict apps to read or write.
There is nothing stopping an app that pushes information to our nation also downloading our entire database without us being aware. Supporters trust us with their personal information so we'd like to ensure we keep it safe.
1 reaction
When POSTing to donation API I keep getting a 'slug can't be blank' error
We are trying to hit the following API
token.post('/api/v1/donations', headers: {"Content-Type"=>"application/json", "Accept"=>"application/json"}, body: {:donation=>{:donor_id=>1234, :amount_in_cents=>1000, :payment_type_name=>"Other", :tracking_code_slug=>"", :succeeded_at=>Wed, 07 Sep 2016 23:18:32 EDT -04:00}})
completed
The tracking_code_slug can't be blank. It needs the tracking code value as a string, a 'null' or just not including the resource in the request.
1 reaction
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.
12 reactions
Webhooks are not firing
Webhooks don't seem to be firing for person created and changed webhooks. Possibly other events that trigger webhooks are also effected.
completed
This issue has been resolved.
1 reaction
API and GUI validation inconsistencies
There appears to be inconsistencies between what is required/validated via the GUI, and what is required/validated via the API.
For example, via the GUI you can create and edit an event that has no location. However, trying to edit one of these events via the API will produce a validation error, as location is required.
This results in needing to add code such as this to all my event editing script:
contact = event["contact"]
contact["name"] = "Default Contact Name" if contact["name"].nil? || contact["name"].empty?
contact["email"] = "[email protected]" if contact["email"].nil? || contact["email"].empty?if !event["venue"].nil? && !event["venue"]["address"].nil?
address = event["venue"]["address"]
address["city"] = "Unknown" if address["city"].nil? || address["city"].empty?
end
completed
Effy,
I attempted to replicate this issue in my sandbox and didn't encounter the error you described. To test I created an event using the UI without including a location. I then hit the PUT endpoint to update the event with new page tags and contact info and returned a 200 response code.
1 reaction
Sites index returns null for domain
api/v1/sites returns 'null' for domains for all sites, regardless of if the site has a domain set.
completed
4/28/17
This issue has been fixed.
This is a confirmed bug 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.
2 reactions
No search functionality over developers' forum?!
new to NB, but trying to make something work on my 'nation' and this is one way i typically learn a new code base. wazzup?
Add your reaction
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.
2 reactions
Attempts to delete people from a list through the API results in errors
There is some issue with “Delete People Endpoint” in “List API”( http://nationbuilder.com/lists_api ). It always returns 400 error with the message that says:
{"code":"missing_parameters","message":"Missing Parameters.","parameters":["people_ids"]}
considering
This is something we are considering but we do not have a set timeline yet.
1 reaction
C# API PersonResponse conflict
I'm calling the Person Create endpoint, and receiving back a good response with json reflecting the new user. But Newtonsoft.Json is returning an error when attempting to deserialize the Json to a NationBuilderAPI.V1.PersonResponse<NationBuilderAPI.V1.Person>. Has there been an update to the Person Create endpoint that's not reflected in the C# API? I'm using version NationbuilderAPI version 1.3 from Nuget.
completed
That is not a NationBuilder library. It is a third party offering that we don't support.
1 reaction
Create directory pages via the API
It would be great if this were possible!
considering
This is something that we are considering. Please follow this page to get email updates regarding a directory page/create endpoint.
1 reaction
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.
11 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.
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.
3 reactions
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!
2 reactions
Permissions on API
I would like to be able to do more with the API than just searches, such as creating and updating people. Currently this is possible with the test token, but not an OAuth token.
A global permission level for the API would be enough, along with a flag on users to specify if they can OAuth and use the API's extended permissions. That way I could grant fine-grained permissions to the API, then give just a few users access to the API through OAuth. I would really like to stop using the test token because that's terrible security long-term.
completed
Grigory,
You can limit access to staffers by toggling their permission set. If you navigate through the control panel to Settings > Permission sets > select the permission set you want to limit authentication for > and scroll to the bottom you will see the option under API. Toggle this to 'no' and then assign that permission set to staffers you want to limit app authentication for.
1 reaction