Three Sixty API Documentation

Qualtrics Three Sixty REST API Documentation

Versions:

Contents:

The Qualtrics REST API allows you to query our system using a simple URL syntax. The REST API allows you to interact with any part of the Qualtrics system allowing for full integration with our client’s systems.

REST Input Parameters
Root URLs

The root URL for communicating with the Qualtrics system is:

https://new.qualtrics.com/WRAPI/ThreeSixty/api.php

Please note the use of the https protocol. This ensures that all data that travels between the server and your program are encrypted. This protects your credentials and the transmitted data.
Parameters

The parameters are passed using the standard query string syntax. All parameters and values are case sensitive.
Query String Documentation: http://en.wikipedia.org/wiki/Query_string
The data can be passed in the URL itself (GET parameters) or be passed in the body of the request (POST parameters). Both methods follow the same query string syntax.

Example
https://new.qualtrics.com/WRAPI/ThreeSixty/api.php?Request=getResponseData&Token=lksjdfJdJklajdf3asdae3&SurveyID=SV_123456789&Format=XML

Required Parameters

The following parameters are required for all requests:

Parameter Description

Request The name of the API call to be made.
User Qualtrics username.
Password Qualtrics password.

Each individual request will have additional required parameters in addition to the above required parameters.

REST Response

When a request is made to the API, it is processed and a response is returned. If the API correctly understood the request and was able to process it the request is marked as a success and the appropriate data is returned. If the API was unable to process the request because the request was unknown, the user had insufficient privileges, or there was an error the request is marked as a failure and the error data is returned.

HTTP Headers
The following headers are returned:

Header Description

RequestStatus The status of the request. If “Success” then the request was received and processed correctly. If “Failure” there was an error processing the request.

Response Body
The response can be in any number of different formats depending upon the specific request made to the API. Generally the API responds with xml. In all error situations the API responds in xml.

Parameter	Description
Request	The name of the API call to be made.
User	Qualtrics username.
Password	Qualtrics password.

Header	Description
RequestStatus	The status of the request. If “Success” then the request was received and processed correctly. If “Failure” there was an error processing the request.

The Qualtrics REST API allows you to query our system using a simple URL syntax. All requests are simple GET or POST requests that return XML or JSON. The REST API allows you to interact with any part of the Qualtrics system allowing for full integration with our client’s systems.

Making a Request
To make a request to the API you need both a root URL and some basic parameters.
Root URL

The root URL for communicating with the Qualtrics system is:

https://yourdatacenterid.qualtrics.com/WRAPI/ThreeSixty/api.php

To find the correct value for yourdatacenterid please follow these instructions (Note these instructions are from the most recent version of the API).

Please note the use of the https protocol.  This ensures that all data that travels between the server and your program are encrypted.  This protects your credentials and the transmitted data.
Parameters

The parameters are passed using the standard query string syntax. All parameters and values are case sensitive. For more information see Query String Documentation: http://en.wikipedia.org/wiki/Query_string

The data can be passed in the URL itself (GET parameters) or be passed in the body of the request (POST parameters).  Both methods follow the same query string syntax.

Example:
https://yourdatacenterid.qualtrics.com/WRAPI/ThreeSixty/api.php?Request=getLegacyResponseData&User=apiuser&Token=lksjdfJdJklajdf3asdae3&Format=XML&SurveyID=SV_123456789

JSON parameters
Parameters may also be passed as JSON data through the request body. If using a JSON request body, you must specify a Content-Type header of 'application/json' or 'text/json'. You may use both url parameters and JSON parameters with the same request.

Example:
Request URI:	https://yourdatacenterid.qualtrics.com/WRAPI/ThreeSixty/api.php?Request=getLegacyResponseData&Format=XML
Content-Type:	application/json
Request Body:	{"User":"apiuser","Token":"lksjdfJdJklajdf3asdae3","SurveyID":"SV_123456789"}


Required Parameters

The following parameters are required for all requests:


	Parameter Description
	
		Request The name of the API call to be made.
		User Qualtrics username.
		Token Qualtrics API token (see The Token).
		Format The format of the response. Valid value are XML, JSON or PPJSON (Pretty Print Formatted JSON) unless otherwise noted.
		Version The version of the API to use.
	


Each individual request will have additional required parameters in addition to the above required parameters.


The Response
When a request is made to the API, it is processed and a response is returned.  The response will always have two sections. The first is the 'Meta' section where information about the success or failure of the request is stored. The other is the 'Result' section where the request specific response is found. The response will come back in the format you specified with your request.

CR This indicates that the request has a custom response format and does not follow the standard.

Note: If an error occurs and the 'Format' parameter is missing, invalid, or a custom format for a request then the error format will be XML.

Example Responses:


XML:

<xml>
	<Meta>
		<Status>Success</Status>
	</Meta>
	<Result>
		...
	</Result>
<xml>

or

JSON:

{
	Meta: {
		Status : "Failed",
		ErrorCode: 400,
		ErrorMessage : "Missing parameter 'Version'."
	},
	Result : {
		...
	}
}

HTTP Result Codes

In the event of an error or redirect the Qualtrics API will attempt to return an appropriate HTTP error code.


	
	
		302/307 (Redirect) The request should be redirected to a new address.
		400 (Bad Request) The request was invalid, because of missing or invalid parameters.
		401 (Unauthorized) Authentication failed. For more details on authentication see Authentication.
		403 (Forbidden)	 The user provided does not have permission to make the desired request.
		404 (Not Found) The specified request does not exists.
		500 (Internal Server Error) An unknown error occurred. Try the request later.
	



Example Request
The following is an example request to get basic information about a user.

URL:

https://new.qualtrics.com/WRAPI/ThreeSixty/api.php?Request=getUserInfo&User=apiuser&Token=lksjdfJdJklajdf3asdae3&Format=XML

Response:

<xml>
	<Meta>
		<Status>Success</Status>
	</Meta>
	<Result>
		<UserID>UR_12345678</UserID>
		<UserName>apiuser</UserName>
		<UserFirstName>John</UserFirstName>
		<UserLastName>Doe</UserLastName>
		<UserEmail>johndoe@example.com</UserFirstName>
		<UserLanguage>EN</UserLanguage>
		<Libraries>
			...
		</LIbraries>
		...
	</Result>
<xml>



Redirects

The API can redirect you to a new address. The redirect is done with the appropriate header and HTTP code. This is done to ensure you are requesting the data from the location most appropriate for you. You should make sure your client expects and honors these potential redirects.

Parameter	Description
Request	The name of the API call to be made.
User	Qualtrics username.
Token	Qualtrics API token (see The Token).
Format	The format of the response. Valid value are XML, JSON or PPJSON (Pretty Print Formatted JSON) unless otherwise noted.
Version	The version of the API to use.

302/307 (Redirect)	The request should be redirected to a new address.
400 (Bad Request)	The request was invalid, because of missing or invalid parameters.
401 (Unauthorized)	Authentication failed. For more details on authentication see Authentication.
403 (Forbidden)	The user provided does not have permission to make the desired request.
404 (Not Found)	The specified request does not exists.
500 (Internal Server Error)	An unknown error occurred. Try the request later.

The API uses a token based authentication system. This prevents you from needing to give out your password to third parties. Qualtrics needs both your user name and your token to authenticate your request. A request will be authenticated if a valid user name and token pair are passed as the 'User' and 'Token' parameters.

The Token
Each Qualtrics user account can have one and only one token associated with it. The token never expires and can be regenerated at any time.

To generate/regenerate your token:

Login to Qualtrics via your browser. Click your name in the upper right, then go to 'Account Settings.'
Select 'Qualtrics IDs,' just under the main tabs.
Under 'API' click 'Generate Token.'
Your token will be displayed. Copy it into a safe place to use with your application.

You can view your current token at any time by navigating to the 'Qualtrics IDs' section. You can also generate a new token at any time and regenerate it as often as needed.

Administration Requests

changeUserName

Changes the user name from the old to the new user name

Name	Value(s)/Formatting	Required	Default	Description
User	<String>	Yes		The username.
Token	<String>	Yes		API token for the user.
Format	{XML, JSON, JSONP}	Yes		The desired format of the response.
Version	Version number like 'X.X' >= 2.0	Yes		The version of the API to use.
OldUserName	<String>	Yes		The user name to be changed
NewUserName	<String>	Yes		The new user name
UserNameIsEmail	[0,1]	No	1	Default is 1. If 1 the user name must be an email address and the user’s email address will be updated in the system. It is strongly recommended to use email addresses as the user name.

Response: Basic request status

Example: https://survey.qualtrics.com/WRAPI/ThreeSixty/api.php?Request=changeUserName&User=user%40qualtrics.com&Token=jkf0AjdYXWU76B2kd0SifklbFOtoVPfXuhd9e274&Format=XML&Version=2.0&OldUserName=String&NewUserName=String&UserNameIsEmail=1

Attribute	Type	Description
Status	String	Active or Inactive, the result will be 'Active' if successful.
SurveyID	GUID	The Survey ID of the survey that has been activated

Attribute	Type	Description
Status	String	The status will always be Compete if successful.
SurveyID	GUID	The Survey ID of the survey whose response has been completed.
ResponseID	GUID	The Response ID of the response that has been completed.
RecipientID	GUID	The Recipient ID of the response that has been completed. Will only be included if non-null
ResponseEventContext	String	Custom context that can be set via the ResponseEventContext embeded data. 50 character limit

Attribute	Type	Description
Status	String	The status will always be Partial if successful.
SurveyID	GUID	The Survey ID of the survey whose partial response has been saved.
ResponseID	GUID	The Response ID of the response that has been recorded.
RecipientID	GUID	The Recipient ID of the response that has been recorded. Will only be included if non-null
ResponseEventContext	String	Custom context that can be set via the ResponseEventContext embeded data. 50 character limit

Attribute	Type	Description
ThreeSixtyID	GUID	The 360 the nomination was created for
SubjectID	GUID	The PersonID of the one doing the nominating; the one that will be evaluated
EvaluatorID	GUID	The PersonID of the one being nominated that will perform the evaluation
EvaluatorEmail	String	The Email Address of the person that will perform the evaluation
Relationship	String	The Relationship of the nomination
EvaluationURL	String	The Link to perform the evaluation (Survey Engine Link)

Attribute	Type	Description
ThreeSixtyID	GUID	The 360 the nomination was removed for
SubjectID	GUID	The PersonID of the one doing the nominating; the one that was to be evaluated
EvaluatorID	GUID	The PersonID of the one being nominated that was to perform the evaluation
Relationship	String	The Relationship of the nomination

Attribute	Type	Description
ThreeSixtyID	GUID	The ID of the newly-created 360
SurveyID	GUID	The ID of associated survey
Workflow	JSON	The Workflow Settings

Attribute	Type	Description
ThreeSixtyID	GUID	The ID of the 360
SubjectID	GUID	The PersonID of the subject of the report
ReportURL	String	The URL to view the report (Currently the link to log in to the Qualtrics Portal to view the report)

Parameter	Format	Description
JSONPCallback	JSONP	Required. The callback to be used when applying the JSONP technique.
JSONPrettyPrint	JSON, JSONP	Optional. Outputs JSON so that it is more readable.

Name	Value(s)/Formatting	Required	Default	Description
User	<String>	Yes		The username.
Token	<String>	Yes		API token for the user.
Format	{XML, JSON, JSONP}	Yes		The desired format of the response.
Version	Version number like 'X.X' >= 2.0	Yes		The version of the API to use.
Name	<String>	Yes		Unique Textual Description of the subscriber (we will make sure this is globally unique. All callers of this just need to ensure they are locally-unique.)
PublicationURL	<URL>	Yes		The FULLY-Qualified URL to publish events to. For Example, if "http://mydomain.com/REST.php" it will publish messages to you via HTTP REST. The data pushed to the publication URL will be of Content-Type: application/x-www-urlencoded, NOT Content-Type: application/json
Topics	<String>	Yes		String Value of Topics to subscribe to. Ex:’threesixty.*’ will subscribe to all 360 events from Qualtrics.
Encrypt	[0,1]	No	0	If true, will encrypt the event messages using the supplied Shared Key. Encryption will be AES 128 or 256 depending on Shared Key length (16 bytes = 128 bit, 32 bytes = 256 bit). Encryption is not necessary if publishing to an https URL. * Encrypted MSG is Base64 encoded for transport purposes, therefore you must base64 decode the MSG before decrypting it. MSG plaintext will be in JSON format.
SharedKey	<String>	No		If specified, all event messages will be emitted with an HMAC using this key to guarantee message authenticity, and optionally encrypted using this key (if Encrypt = true).
BrandID	<String>	No		If specified, subscribe on behalf of the supplied organization. For administrators of multiple organizations only.