Guidelines

Guidelines

Overview

Thank you for your interest in our Innovation Platform! We are excited to work with you.

In order to ensure a smooth experience for you, as well as for our mutual clients, please review these guidelines. They will provide you with a helpful overview to developing code that uses our API, and planning to release that code to clients. If you have any questions, please feel free to contact us.

We recommend the following process for developing your code, to ensure a successful experience for you and for clients:

  1. Request your sandbox API key. Once you've determined that you need an API key to implement a feature, please send us a request for an API key on our sandbox database. Please provide a clear description of your intended functionality, and feel free to include URLs or other references if the provided text area is insufficient.
  2. Development and discovery. Plan out your integration and implement the relevant code. In particular, if you are uncertain as to how you should map data from your system into ours, or vice versa, please get in touch; we are happy to help you iron out these questions.
  3. Determine billing impacts, and identify technical requirements.
    • As your new code comes together, you should have a good idea how your integration will impact usage of our system. Please consider whether your integration may impact client billing, or whether you will need an enterprise pricing package. See the Billing and usage section for more details.
    • You should also have an understanding of the technical requirements of your integration. Determine which API routes your code uses, as well as any other assumptions that your code needs to make about our system - e.g., whether a specific contact type is needed when posting canvass results. See the Technical requirements section for more details.
    • Finally, please provide us with the details we need to effectively communicate with our mutual clients, including: a good synopsis of the functionality you've developed; the date you anticipate on-boarding your first production clients; and any other details that may be relevant. Please give us at least a week's notice, so that we may prepare our systems to properly configure your production keys.
  4. Soft launch. We recommend identifying a small handful of beta clients who will be the first users of the new integration. This beta period helps ensure that any last-minute wrinkles are addressed efficiently. Please note that these clients will need to request a production key via the Support Request system in our user interface, as outlined below in the "Key generation and hand-off" section.
  5. Celebrate! Once you are confident that the beta period is a success, it's time to make the integration widely available, and to publicize it.

Once your app is launched, your clients will need API keys in our system, and there may be questions or issues that arise in production. Please see the sections Key generation and hand-off and Questions and bug reports to prepare for these scenarios. Finally, please be aware that your integration may be working with sensitive data; in order to protect privacy and to ensure the security of client data, please ensure good data security practices; see the Data management section for more details.

Billing and usage

  • Our standard API usage pricing is 1,000 free calls per day, with a fee of $0.01 per additional call. We bill at the end of the month and may provide a breakdown of their API usage by key.
  • Bulk API pricing is available if you or our mutual client expects to regularly exceed the daily limit. If you are interested in a plan, please contact us.
  • We monitor API usage to prevent abuse and excessive strain on system resources. Please exercise good judgment in the development of your code, and reach out to us if you have any questions about efficient use of our APIs. Should usage appear to significantly exceed the daily limit on a regular basis, we may contact you to investigate and resolve the matter.

Technical requirements

  • Before going live, please let us know the API routes which your integration requires, e.g. POST /people/findOrCreate, GET /events, etc. This list of routes will help us ensure that your production keys have access to the necessary permissions in our systems.
  • Please use the development process to identify the resources which your app needs in order to function properly, and let us know what they are so that we can make sure these resources are available to your production keys. Examples of resources required include:
    • Contact types
    • Result codes
    • External identifiers
    • Export job types
  • Please provide us with a one paragraph description of your application, so that we can communicate effectively about it with database administrators – if they have any questions before approving production keys, for example. Feel free to include URLs, demo videos, etc.
  • If you plan to add new functionality to your integration after it has gone into production, please develop that new functionality using your sandbox key, and follow the processes above as they relate to your new functionality.

Key generation and hand-off

  • Clients should request keys tied to their database via the Support request system in the NGP VAN user interface, and should specify the app for which they are requesting access.
  • We will generate the key and hand it off to a contact you have designated for receiving our API keys.
  • Keys will be made available via one-time links that expire after a fixed time period, along with a four-digit key reference. You should store the key reference so that it can be used to communicate about the key in the future.
  • You should never transmit or publish the API key, the HTTP Basic Authorization header which uses that key, or any other derivation of the API key, in plain text. Specifically that means that API keys should not appear on any web pages or public Github repositories, and should not be transmitted by email. Should we discover that an API key or any of these components have been published or transmitted, we will revoke and reissue the key as soon as possible. Multiple occurrences will be considered a violation of our Terms of Service and may result in revocation of all keys associated with your app.
  • If you need to communicate with us about an API key, please use the key reference we send you when the key is generated.

Questions and bugs

  • You may contact us via email, or via the support request form, if you have questions about our APIs, or problems using them.
  • To resolve problems as quickly as possible, you should include the key reference of the key used to make a request; the URL and body of the request; the response received; and any other details which may be applicable. Please do not transmit HTTP Basic Authorization headers via email, since the API key can be readily decoded from those headers.
  • Integration questions and error reporting should come from your staff - not clients. Because clients are generally not aware of the API calls your code is making, they will not be able to provide us with sufficient information to answer questions that arise. For security purposes, we do not accept requests for production data via the developer portal.

Data management

  • Data retrieved from our system may contain sensitive personal information, or may be the property of our clients.
  • Note that certain data sets, like voter file data and scores, are not necessarily the property of a given campaign or client directly, but are being provided by a separate organization. In those cases, it may be necessary to get signoff from those other entities in order to gain access.
  • You should follow good data security practices when handling this data. Do not place data in publicly-available places, and take care to properly delete data if you no longer need it.
  • Should a breach occur, please notify us immediately.