Importing Keys

We have a fully featured importer that makes adding license keys in bulk easy. If you have generated keys off-site or have another service providing keys you can import them into our system. You can then use BatchKeys’ API and dashboard to manage them.

Imports have a few requirements. Notably the file must be in CSV format and include the necessary formatted fields in a way the importer can recognize. We will go over each one of these these below.

Additionally, you can only upload a maximum of 200,000 keys per file, and 50,000 is optimal. If you would like to import more than 200k keys please split the data into multiple files.

CSV Format #

CSV (Comma-Separated Values) files are a type of plain text file that use specific structuring to arrange tabular data. Each line in a CSV file corresponds to a data record. Each record consists of one or more fields, separated by commas.

This format is widely used because it is simple, compact, and supported by a wide range of applications, including spreadsheet programs like Microsoft Excel, databases, and many more.

Creating a CSV (Comma-Separated Values) file can be easily done using a plain text editor like Notepad or a spreadsheet program like Microsoft Excel.

Sample CSV Files And Data #

We have created a sample CSV file that you can download and edit with your data in a program such as Excel.

Download: batchkeys-sample-import.csv

For additional details, here is some example CSV data. If you use a plain text editor like Notepad your CSV data would look more like this:

Activated,Activation Date,Expiration Date,Domains Allowed,UUIDs Allowed,Key,First Checked,Last Checked,Checked Counter,Days Valid,Tokens Used,Token Limit
0,NULL,NULL,0,0,0000000-0000000-0000000-0000000-0000000,NULL,NULL,0,NULL,0,NULL
0,NULL,NULL,0,0,1111111-1111111-1111111-1111111-1111111,NULL,NULL,0,NULL,0,NULL
0,NULL,NULL,0,0,2222222-2222222-2222222-2222222-2222222,NULL,NULL,0,NULL,0,NULL
0,NULL,NULL,0,0,3333333-3333333-3333333-3333333-3333333,NULL,NULL,0,NULL,0,NULL

You’ll notice in this data we have identifiable headers in the top row and then multiple data layers in the subsequent rows. You only need to include the headers once. Each line of data should be on it’s own row in the file and you can include as many data rows as you want. Each row will be a new entry in your key library.

Headers #

The importer expects the following headers, and they must always be included and be in this order, whether there is data for them or not.

• Activated
• Activation Date
• Expiration Date
• Domains Allowed
• UUIDs Allowed
• Key
• First Checked
• Last Checked
• Checked Counter
• Days Valid
• Tokens Used
• Token Limit

Many of these data fields can be empty if you don’t have any data for them. You could leave them blank or use NULL, but some data fields do require data (as we will explain below).

NOTE: No matter if there is data for a header or not, the header itself must be included. All headers must be included in the CSV file or it will fail to upload.

Let’s look at each header in greater detail….

Activated #

This sets the key as either activated or deactivated. It must be either a 0 or 1.

Activation Date #

This is the date the key was first activated.

Expiration Date #

This is the set date the key will expire. After this date the key will no longer work. Used for date-based expiration licenses.

Domains Allowed #

This sets the amount of domains a key can be locked to. Used for domain locking a key.

UUIDs Allowed #

This sets the amount of UUIDs (devices) a key can be locked to. Used for device locking a key.

Key #

This is the license key. Keys must be formatted as upper and lower case letters, numbers, and hyphens only. Keys contain five blocks of 7 characters separated by hyphens. Visually, a sample key looks like: yG6UHZB-9NVc103-Cy8hGmq-UYR7qbX-WS9oO2T

First Checked #

This is the date the key was checked for the very first time, whether it was activated or not.

Last Checked #

This is the date the key was last checked. Every time the key is checked this date will update.

Checked Counter #

The amount of times a key has been checked. Each time the key is checked this number increases.

Days Valid #

This sets how many days the key will work after activation. Used for trial and limited time offer license keys.

Tokens Used #

This is the amount of tokens a key has consumed. Used by token-based license keys.

Token Limit #

This sets the maximum amount of tokens a token-based key can consume before needing to be topped off or simply expiring. Used by token-based license keys.

Assigning Domains/UUIDs To Keys When Importing #

Imported keys will automatically add any domains or UUID’s they are calling from during their first API call. We recommend forcing your app to make a call after importing new keys. See our documentation on adding domains or adding UUIDs to your app. Additionally, if you are using UUIDs to lock keys to a device your app will need to generate a UUID for the end user if they have never been assigned one. Both domains and UUID’s are optional depending on your apps configuration.

You could also manually add the domains/UUIDs by going to the key details of each key to enter the domains/UUIDs. While you can only enter one key’s information at a time, you can enter all of the domains or UUIDs for that key at once. See the documentation on editing a key’s details for more info.

There is currently no way to import a list of domains or UUIDs to the keys during import. We are hoping to add this feature in the future. If this is something you would like to see sooner than later please submit a feature request so it gets moved higher up the list.

NOTE: To deactivate a subscription-based key (such as when the end user misses a payment) that key must have 1. been activated at least once 2. have either a domain or UUID assigned to it. Otherwise the key will be treated as needing assignment and will reactivate. See our documentation on subscription-based keys for more details.

Best Practices #

Always import just one or two keys first to ensure you don’t encounter any errors. If you don’t see any errors on the importer, go check your key library for the keys and make sure they have saved correctly. Click on each key and check the details also.

If your small list of test keys looks ok then you’re ready to import a larger batch. We recommend keeping batch sizes to a reasonable amount to simplify fixing any formatting issues or other errors you may encounter.

If you find the importer is taking too long try decreasing the amount of keys you import at once, but you should have no trouble importing thousands of keys at once. We recommend staying under 10,000 keys per CSV file.

You can only import keys up to the maximum key limit of your plan. Any keys beyond that limit will fail to import.

Avoid leaving completely empty rows between your rows of data when using a spreadsheet program to create your CSV, as the importer may think the file has ended and will stop importing too soon.

Troubleshooting #

The importer has robust error handling and will display any errors encountered. You can use this information to fix the CSV file and try again.

The most common error by far is formatting. Please see the above documentation on how to format the data rows.

If you still cannot get your keys to import or if you don’t understand an error please open a support ticket, we’re happy to help.