Command-line automation of Qualtrics™ surveys
Quautomatrics can perform basic operations on Qualtrics™ contacts, mailing lists, distributions, and responses
Usage:
quautomatrics [command]
Available Commands:
createContacts Add contacts to a mailing list
createDistribution Create a distribution file in JSON format
deleteContacts Remove all contacts from a mailing list
exportResponses Export survey responses in CSV format
help Help about any command
listLibraries List all libraries. A library is needed in order to create a Distribution.
listMailingLists Get a mailing-list ID
listSurveys Get a survey ID.
replaceContacts Replace all mailing list entries with CSV entries
uploadDistribution Upload a distribution file
Flags:
--config string config file (default is quautomatrics_config.json)
-h, --help help for quautomatrics
-v, --version version for quautomatrics
Use "quautomatrics [command] --help" for more information about a command.
- A Qualtrics™ account with access to the
Research Core Contacts
API. -
- This program does not use the
XM Directory
API.
- This program does not use the
- You will need an
API Token
which is located under: -
Account Settings
=>Qualtrics IDs
=>API
- Your
Datacenter ID
which is located under: -
Account Settings
=>Qualtrics IDs
=>User
- Rename
quautomatrics_config-dist.json
toquautomatrics_config.json
-
- Edit these fields:
X-API-TOKEN
,DATACENETR
- Edit these fields:
- A
CSV
file must use this format, with no header line: -
first name,last name,email address
A survey mailing list
must already be created through the Qualtrics web interface.
In the examples below it is called My_Fancy_Survey
.
Adding Contacts
quautomatrics createContacts -m My_Fancy_Survey -c people.csv
Removing All Contacts
quautomatrics deleteContacts -m My_Fancy_Survey
Replace Contacts
- This will first remove all contacts and then add new contacts from a
CSV
file.
quautomatrics replaceContacts -m My_Fancy_Survey -c newPeople.csv
List
- The
listLibraries
,listMailingLists
andlistSurveys
commands will list all items returned by the API. -
- The
-n
command-line switch can also be used to limit the listing to just one entry.
- The
quautomatrics listLibraries
libraryId: UR_12xxxxxxxxxxxxx name: Test Library
libraryId: GR_34xxxxxxxxxxxxx name: Qualtrics Library
- To list all messages within an individual library, use the
-M
switch.
quautomatrics.exe listLibraries -n "Test Library" -M
libraryId: UR_12xxxxxxxxxxxxx
messageId: MS_45xxxxxxxxxxxxx name: Invite A
messageId: MS_56xxxxxxxxxxxxx name: Invite B
messageId: MS_67xxxxxxxxxxxxx name: Invite C
Contents of quautomatrics_config.json
{
"X-API-TOKEN": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"DATACENTER": "zz1",
"fromName": "My Company Name",
"replyToEmail": "noreply@qualtrics.com",
"fromEmail": "noreply@qualtrics.com",
"subject": "Please take our survey"
}
Creating a Distribution
quautomatrics.exe createDistribution -c quautomatrics_config.json -o distribution.json -l "Inquiry Survey"
-m "Invitation Email" -n "My_Contacts" -s "My_Fancy_Survey" -d "_NOW_" -e "_DAYS:5_T23:59:59Z"
Uploading a Distribution
quautomatrics.exe uploadDistribution -d distribution.json
Export Survey Responses to a CSV File
quautomatrics.exe exportResponses -s My_Fancy_Survey
[1] waiting for survey export completion...
[2] waiting for survey export completion...
Saved CSV file: My_Fancy_Survey.csv
These macros can be used in the createDistribution
command with the -d
and -e
options:
Macro | Description |
---|---|
_NOW_ |
replaced with current date/time such as 2006-01-02T15:04:05Z |
_TODAY_ |
replaced with current date such as 2006-01-02 |
_YMD_ |
same as _TODAY_ |
_HMS_ |
replaced with current time such as 15:04:05 |
_TOMORROW_ |
replaced with tomorrow's date such as 2006-01-03 |
_DAYS:n_ |
replaced with n days into the future; when n=3 then 2006-01-05 |
This program does not use the XM Directory API. Instead, it uses the Research Core Contacts
API.
APIs used:
- Create Distribution
- List Libraries
- List Library Messages
- List Mailing Lists
- Update Mailing List
- List Contacts
- Delete Contacts
- Create Contacts
- Surveys Response Import/Export API
- cobra
- viper
- jsonparser
- Please note that there is no official affiliation between Qualtrics™ and
quautomatrics