Download OpenAPI specification:Download
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.
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
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/...
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 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.
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
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
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
| 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") |
{- "hostnames": [
- "example.turbovote.org"
], - "start": "2019-08-24T14:15:22Z",
- "end": "2019-08-24T14:15:22Z"
}{
}