Metadata is useful for associating additional, structured information with a TurboVote user account. For example, you could store your user's corresponding unique identifier from your system on a TurboVote account.
Partners can now associate metadata with newly created TurboVote accounts by appending key/value pair query parameters (prefixed with x-) to any TurboVote URL visited by an Adult user resulting in a new sign-up.
By default, partner-provided metadata isn't used by TurboVote features but can be accessed by partners via:
- Account Exports:
- TurboVote Bulk Export API
- The User Export tool in the Admin Console
- All TurboVote Webhooks
Partners can opt to associate metadata with Adult user accounts. (Soon, partners will be able to associate with Youth accounts, as well).
Metadata Key Value Pairs
Partners can specify up to alphanumeric (keyword-safe) 50 keys.
Key names
Key names can be up to 40 characters long.
The first character of a key name must be a letter (a-z or A-Z), underscore _, or hyphen -, followed by zero or more characters that can be letters, digits (0-9), underscores _, or hyphens -.
If a metadata query parameter is deemed invalid, it is not associated with the new user account created.
Here are some examples of sample data that match this spec:
Valid names
-
variable -
_underscore -
ClassName -
variable123 -
my-variable -
User_ID
Invalid Names
-
123invalid(starts with a digit) -
spaces are invalid(contains spaces) -
special@character(contains a special character)
Key values
Key values can be up to 500 characters long.
Don't store any sensitive information (bank account numbers, card details, and so on) in metadata (or in similar account-associated query parameters like r or embed placement).
Associating Metadata with New Accounts
To start, metadata can only be associated with new Adult TurboVote user accounts by appending metadata as query parameters to any TurboVote web page URL.
Associating Metadata with New Accounts via Query Parameter using x- Parameter Prefix
Partners can append their own query parameters to any TurboVote destination site and embed URLs by including the x- prefix enabling TurboVote to validate and translate down the query parameter and value into arbitrary key/value pairs associated with new user account.
For instance, to associate the following key value pairs:
| Key Name | Key Value | Query Parameter Prefixed with x- |
variable |
123ABC |
x-variable=123ABC |
underscore |
123ABC |
x-underscore=123ABC |
ClassName |
123ABC |
x-ClassName=123ABC |
Prefix key names with x- and assemble along with key value into URL query parameters appended to any web page off your TurboVote partner site (here shown as example):
https://example.turbovote.org?x-variable=123ABC&x-_underscore=123ABC&x-ClassName=123ABC
Once a user clicks the URL, metadata will be stored in the current user session and associated with any new user account created.
We recommend using x- query parameters along with other Pre-populated Form Fields, particularly when embedding TurboVote on your site. For example, the following URL would include
https://example.turbovote.org/reminders/voter-info?embed=window&partner=01gzpamk4zqm16ts3yjxt668tk&placement=vote-reminders&r=tvhub&lang=en&first-name=Harvey&middle-name=Bernard&last-name=Milk&preferred-name=Harvs&email=harvey.milk@gmail.com&sms=999-999-9878&birth-date=1930-05-22&street=575 Castro Street&street2=5B&city=Fresno&state=CA&zip=94114&zip4=3333&x-variable=123ABC&x-_underscore=123ABC&x-ClassName=123ABC
End-users won't see metadata unless you show it to users in a URL or they inspect the URL powering an TurboVote Embed on your site.
Associating Metadata with Accounts via other methods
Stay tuned for other ways to associate metadata with new and existing accounts.
Accessing Account-associated Metadata
To start, partners access associated metadata via Webhook new user account creation events.
Soon, partners will be able to access associated metadata via The User Export and other methods.
Contact partnerships@turbovote.org for more information.