Skip to main content

Requirements for Certification as a NationBuilder App or Integration

To be certified as a NationBuilder App or Integration, certain requirements must be met in order to ensure seamless operation, optimal usability, and to maintain the integrity of the NationBuilder ecosystem.

General Requirements (for all integrations)

  • Documentation: Provide comprehensive, step-by-step online documentation maintained by the app owner. This documentation should allow a new mutual customer to connect, configure, and maintain the integration without any prior familiarity with either platform. Native NationBuilder functionality does not need to be re-explained, but any customizations required for the integration to work must be outlined here. See “Documentation requirements for integrations that require NationBuilder website modifications” below for more details.
  • Landing page: The NationBuilder partner should create and maintain a NationBuilder-specific landing page that we can point NationBuilder customers to. The page should speak specifically to the integration and can optionally include a sign-up/create-an-account action if desired. This is the URL that we will link to from the NationBuilder Apps & Integrations directory.
  • Independent of NationBuilder Control Panel: It should be understood that NationBuilder Integrations do not have the ability to appear in the NationBuilder control panel as widgets, tabs or any other form, nor do they have the ability to alter the look or functionality of the NationBuilder control panel. All integration-related configuration and user-activity is done outside of the NationBuilder control panel, except for the step during authentication in which users are brought to the control panel to authorize a new integration.

Technical Integration Requirements

  • OAuth Credentials: Ensure secure management of API credentials, with user authentication happening by means of OAuth 2.0 authorization code flow, as outlined here, instead of asking customers for API tokens.
  • Data Integrity: Ensure data pushed to NationBuilder matches field constraints and is appropriately mapped for usability.
  • Error Handling: Implement sufficient error handling mechanisms for API interactions. Logic to handle retries and rate-limit queuing are not required but are recommended in order to assure that all API requests sent to NationBuilder are processed.
  • Rate Limit: Adhere to a rate limit of 250 requests per 10-second interval, per Nation.
  • Headers: All API requests must have a User-Agent header included that denotes the Application sending the request.
  • Logging: Implement logging to investigate customer-reported failures or issues with the integration.
  • Integration UI: Include a dedicated UI for managing NationBuilder integration. This can be a single page on your website, but ideally it lives somewhere in the dashboard of your application.
  • API V2 Token Refresh: If the integration leverages API V2, you must implement a refresh flow for expired tokens, with a preference for refreshing existing tokens when possible instead of generating new ones each time.

Documentation requirements for integrations that require NationBuilder website modifications

  • Instructions for modifying the customer’s NationBuilder website should take into consideration the unique configuration of NationBuilder’s CMS. 
  • when possible, editing theme components should be possible to implement at scale by editing a theme file instead of a custom page template, the instructions should reflect that.
  • While the change most likely requires the customer to edit code on their website, the solution ideally requires them to do that once while setting up the integration and then allows for them to use the integration using no-code techniques, such as applying page tags. The Liquid programming language built into NationBuilder’s CMS should help with this.
  • Any iframe solutions should note that iframes cannot be added directly to a WYSIWYG editor in NationBuilder; <iframe> is not one of the accepted HTML elements in our WYSIWYG whitelist.
  • If the setup does require the customer to edit the code on their website, thorough documentation should be provided, and you can optionally provide a contact at NationBuilder (Brian Palmer | [email protected]) or your organization who can help the customer implement this.

 

Additional Support

  • The Business Development team is available for consultation on proposed data mapping and integration configurations. Please contact us at [email protected] for further support.

Requirements for Listing on nationbuilder.com/apps

To be featured on our website, please email the following information to NationBuilder Business Development at [email protected]:

  • Application Details: 
    • Application Name
    • Desired page slug (i.e. nationbuilder.com/my_integration_name)
    • High-resolution logo (plus 80x80 thumbnail), 
    • Primary contact information
    • URL of a NationBuilder-specific landing page or application homepage link
  • App Description: A concise description of the app’s benefits (up to 200 characters, bullet-point format preferred).
  • Pricing Information: Basic pricing details (range or minimum).
  • Tags for Identification: Select tags that best describe your app’s customer segment focus:
    •  "Data", "Field", "Crowd engagement", "Communication", "Mobile”, "Content management."
  • Markets served: Note any geographical or ideological limitations (e.g. “progressives only”, “US and Canada only”, “We’re open to serving all communities”.)
  • Visuals: Please also include Screenshots or gifs of the app or integration in action.