TurboVote API (1.0.0)

Download OpenAPI specification:Download

Overview

The TurboVote API allows you to programmatically interact with the TurboVote system.

To learn more about any aspect of the TurboVote API, contact us or grab a time to meet.

Visit our API support page that has more information if you are looking to integrate with the TurboVote API, ask questions, or request support.

Authentication

The API uses API keys (bearer tokens) for authentication, and attached to these tokens are roles and other metadata which grant permissions on the API.

To obtain an API key, contact us.

Once you have an API key, include it in requests in the Authorization HTTP header along with the literal word Bearer:

Authorization: Bearer tva_1234567890abcdef

Content types

All requests and responses are currently represented as JSON. When sending JSON bodies to the API, you need to specify the Content-Type header as application/json. Other content types, if supported, will be documented separately.

Example:

curl -H 'Content-Type: application/json' \
  https://api.turbovote.org/v1/...

Generate a user export

Overview

Accepts a JSON body specifying parameters for a bulk user export. Once the request is made, the system will immediately begin to generate the export. This may take several seconds, and the server will wait to return a response until the export is complete. Once the export is complete, the returned redirect response to the request will contain a URL where the CSV of the requested export will be available. The URL will only be valid for a few minutes, and it is recommended that you fetch the export CSV immediately after receiving the response by following this link and downloading the CSV.

Data is currently refreshed approximately every hour, but this may change in the future.

Examples

Examples use curl due to its ubiquity and portability but you can of course use any utility or language you like!

Note the -L parameter in these examples which instructs cURL to follow redirects automatically, this allows you to automate the two requests (one to generate the export, the second to download the file) in a single command.

All parameters

An example request containing all parameters in order to request an export for a single 24-hour period:

curl https://api.turbovote.org/v1/user/export \
  -L \
  -d '{"hostnames": ["example.turbovote.org"], "start": "2024-02-01T00:00:00Z", "end": "2024-02-02T00:00:00Z"}' \
  -H 'Authorization: Bearer tva_1234567890abcdef' \
  -H 'Content-Type: application/json' \
  -o example-all-parameters-turbovote-export.csv

Filter by start date

This request will use the default end date of the most recent UTC midnight, and only includes a start date:

curl https://api.turbovote.org/v1/user/export \
  -L \
  -d '{"hostnames": ["example.turbovote.org"], "start": "2024-02-01T00:00:00-05:00"}' \
  -H 'Authorization: Bearer tva_1234567890abcdef' \
  -H 'Content-Type: application/json' \
  -o example-start-only-turbovote-export.csv

Multiple hostnames

You may have noticed that hostnames is an array; if your API key is authorized to access multiple hostnames you can supply any or all of these along with your request:

curl https://api.turbovote.org/v1/user/export \
  -L \
  -d '{"hostnames": ["example.turbovote.org", "valuedpartner.turbovote.org"]}' \
  -H 'Authorization: Bearer tva_1234567890abcdef' \
  -H 'Content-Type: application/json' \
  -o example-multiple-hostnames-turbovote-export.csv
Authorizations:
BearerAuth
Request Body schema: application/json
required
hostnames
required
Array of strings

The hostnames for which to generate an export. Your API key must be authorized to export these hostnames.

start
string <date-time>

The optional start date of the export, inclusive. You may specify a time zone offset other than UTC, if you like.

If not specified, defaults to 1 month ago.

end
string <date-time>

The optional end date of the export, exclusive. You may specify a time zone offset other than UTC, if you like.

If not specified, defaults to midnight of the current UTC day (i.e. "last night")

Responses

Request samples

Content type
application/json
{
  • "hostnames": [
    ],
  • "start": "2019-08-24T14:15:22Z",
  • "end": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json