Qualtrics REST API

The Qualtrics v3 REST API provides programmatic access to the Qualtrics Experience Management platform. Endpoints cover organizations, divisions, groups, users, surveys, survey responses, response imports, message library, graphic library, distributions, event subscriptions, XM Directory, and Insights Platform contacts.

Documentation

Specifications

Schemas & Data

Other Resources

OpenAPI Specification

qualtrics-api-openapi-3.0.json Raw ↑
{
    "openapi": "3.0.0",
    "info": {
        "version": "0.2",
        "title": "Qualtrics API",
        "description": "Work with Qualtrics surveys, distributions and response events"
    },
    "servers": [
        {
            "url": "https://{apiRegion}.qualtrics.com/API/{apiVersion}",
            "description": "Qualtrics API endpoint for EU region",
            "variables": {
                "apiRegion": {
                    "default": "fra1",
                    "description": "Specify the Qualtrics datacenter prefix according to your account (find it at <your URL>/Q/QualtricsIdsSection/IdsSection)"
                },
                "apiVersion": {
                    "default": "v3",
                    "description": "API version to use - default v3"
                }
            }
        }
    ],
    "security": [
        {
            "QualtricsAPIKeyAuth": []
        }
    ],
    "paths": {
        "/survey-definitions/{Id}": {
            "get": {
                "summary": "Get a specific survey by its 'id' (e.g SV_123)",
                "operationId": "Getsurveys",
                "parameters": [
                    {
                        "name": "Id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },"example":"SV_123"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "The requested survey",
                        "headers": {},
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/SurveyResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/distributions": {
            "get": {
                "summary": "Get distributions for a given survey",
                "operationId": "Getdistributions",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/DistributionSurveyId"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "headers": {},
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/DistributionsResponse"
                                }
                            }
                        }
                    }
                }
            },
            "post": {
                "summary": "Generate distribution links for a given survey",
                "operationId": "Generatedistributionlinks",
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "OK",
                        "headers": {}
                    }
                },
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/requestBodies/CreateDistributionLinks"
                            }
                        }
                    }
                }
            }
        },
        "/distributions/{DistributionId}/links": {
            "get": {
                "summary": "Retrieve distribution links",
                "operationId": "Retrievedistributionlinks",
                "parameters": [
                    {
                        "name": "surveyId",
                        "in": "query",
                        "required": true,
                        "style": "form",
                        "schema": {
                            "type": "string",
                            "example": "SV_daqxBqkZ5Di8aJU"
                        }
                    },
                    {
                        "$ref": "#/components/parameters/DistributionId"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "",
                        "headers": {},
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/RetrieveDistributionLinksResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/directories/{DirectoryId}/mailinglists/{MailingListId}/contacts": {
            "post": {
                "summary": "Create a contact in a given mailing list",
                "operationId": "Createcontactinmailinglist",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/Content-Type"
                    },
                    {
                        "$ref": "#/components/parameters/DirectoryId"
                    },
                    {
                        "$ref": "#/components/parameters/MailingListId"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "",
                        "headers": {}
                    }
                },
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/requestBodies/CreateContactInMailingList"
                            }
                        }
                    }
                }
            }
        },
        "/eventsubscriptions/": {
            "post": {
                "summary": "Subscribe to response event",
                "operationId": "webhook-trigger",
                "x-ms-trigger": "single",
                "parameters": [],
                "x-ms-notification-content": {
                    "description": "Response schema",
                    "schema": {
                        "$ref": "#/components/schemas/EventSubscriptionHookSchema"
                    }
                },
                "responses": {
                    "200": {
                        "description": "",
                        "headers": {},
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/EventSubscriptionsResponse"
                                }
                            }
                        }
                    }
                },
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/requestBodies/SubscribeToEventBody"
                            },
                            "example": {
                                "topics": "surveyengine.completedResponse.{SurveyID}",
                                "publicationUrl": "https://prod-142.westeurope.logic.azure.com:443/workflows/",
                                "encrypt": false
                            }
                        }
                    }
                }
            },"delete":{
                "summary": "Remove subscription to response event",
                "operationId": "WebhookDelete",
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "",
                        "headers": {},
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/EventSubscriptionsResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/eventsubscriptions/{SubscripionId}": {
            "get": {
                "summary": "Get event subscriptions",
                "operationId": "Geteventsubscriptions",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/SubscriptionId"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "",
                        "headers": {},
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/EventSubscriptionsResponse"
                                }
                            }
                        }
                    }
                }
            }
        }
    },
    "components": {
        "securitySchemes": {
            "QualtricsAPIKeyAuth": {
                "type": "apiKey",
                "in": "header",
                "name": "X-API-TOKEN"
            }
        },
        "responses": {
            "UnauthorizedError": {
                "description": "API key is missing or invalid",
                "headers": {
                    "WWW-Authenticate": {
                        "schema": {
                            "type": "string"
                        }
                    }
                }
            }
        },
        "parameters": {
            "DistributionSurveyId": {
                "name": "surveyId",
                "in": "query",
                "required": true,
                "style": "form",
                "schema": {
                    "type": "string",
                    "example": "SV_123"
                }
            },
            "DistributionId": {
                "name": "DistributionId",
                "in": "path",
                "required": true,
                "style": "simple",
                "schema": {
                    "type": "string",
                    "example": "DistributionId"
                }
            },
            "DirectoryId": {
                "name": "DirectoryId",
                "required": true,
                "in": "path",
                "schema": {
                    "type": "string"
                }
            },
            "MailingListId": {
                "name": "MailingListId",
                "required": true,
                "in": "path",
                "schema": {
                    "type": "string"
                }
            },
            "SubscriptionId": {
                "name": "SubscriptionId",
                "required": true,
                "in": "path",
                "schema": {
                    "type": "string"
                }
            },
            "Content-Type": {
                "name": "Content-Type",
                "in": "header",
                "required": true,
                "style": "simple",
                "schema": {
                    "type": "string",
                    "example": "application/json"
                }
            }
        },
        "requestBodies": {
            "CreateDistributionLinks": {
                "required": true,
                "content": {
                    "application/json": {
                        "schema": {
                            "type": "object",
                            "properties": {
                                "surveyId": {
                                    "type": "string"
                                },
                                "linkType": {
                                    "type": "string"
                                },
                                "description": {
                                    "type": "string"
                                },
                                "action": {
                                    "type": "string",
                                    "default": "CreateDistribution"
                                },
                                "expirationDate": {
                                    "type": "string",
                                    "example": "2021-01-21 00:00:00"
                                },
                                "mailingListId": {
                                    "type": "string"
                                }
                            }
                        }
                    }
                }
            },
            "CreateContactInMailingList": {
                "required": true,
                "content": {
                    "application/json": {
                        "schema": {
                            "type": "object",
                            "properties": {
                                "firstName": {
                                    "type": "string"
                                },
                                "lastName": {
                                    "type": "string"
                                },
                                "email": {
                                    "type": "string"
                                },
                                "unsubscribed": {
                                    "type": "boolean"
                                }
                            }
                        }
                    }
                }
            },
            "SubscribeToEventBody": {
                "required": true,
                "content": {
                    "application/json": {
                        "schema": {
                            "type": "object",
                            "properties": {
                                "topics": {
                                    "type": "string"
                                },
                                "publicationUrl": {
                                    "type": "string"
                                },
                                "encrypt": {
                                    "type": "boolean"
                                }
                            }
                        }
                    }
                }
            }
        },
        "schemas": {
            "RetrieveDistributionLinksResponse": {
                "type": "object",
                "properties": {
                    "result": {
                        "type": "object",
                        "properties": {
                            "elements": {
                                "type": "array",
                                "items": {
                                    "type": "object",
                                    "properties": {
                                        "contactId": {
                                            "type": "string"
                                        },
                                        "transactionId": {},
                                        "link": {
                                            "type": "string"
                                        },
                                        "exceededContactFrequency": {
                                            "type": "boolean"
                                        },
                                        "linkExpiration": {
                                            "type": "string"
                                        },
                                        "status": {
                                            "type": "string"
                                        },
                                        "lastName": {
                                            "type": "string"
                                        },
                                        "firstName": {
                                            "type": "string"
                                        },
                                        "externalDataReference": {},
                                        "email": {
                                            "type": "string"
                                        },
                                        "unsubscribed": {
                                            "type": "boolean"
                                        }
                                    },
                                    "required": [
                                        "contactId",
                                        "transactionId",
                                        "link",
                                        "exceededContactFrequency",
                                        "linkExpiration",
                                        "status",
                                        "lastName",
                                        "firstName",
                                        "externalDataReference",
                                        "email",
                                        "unsubscribed"
                                    ]
                                }
                            },
                            "nextPage": {}
                        }
                    },
                    "meta": {
                        "type": "object",
                        "properties": {
                            "httpStatus": {
                                "type": "string"
                            },
                            "requestId": {
                                "type": "string"
                            }
                        }
                    }
                }
            },
            "SurveyResponse": {
                "type": "object",
                "properties": {
                    "result": {
                        "type": "object",
                        "properties": {
                            "QuestionCount": {
                                "type": "string"
                            },
                            "SurveyOptions": {
                                "type": "object",
                                "properties": {
                                    "ActiveResponseSet": {
                                        "type": "string"
                                    },
                                    "AnonymizeResponse": {
                                        "type": "string"
                                    },
                                    "Autoadvance": {
                                        "type": "string"
                                    },
                                    "AutoadvancePages": {
                                        "type": "string"
                                    },
                                    "Autofocus": {
                                        "type": "string"
                                    },
                                    "AvailableLanguages": {
                                        "type": "object",
                                        "properties": {
                                            "EN": {
                                                "type": "array"
                                            }
                                        }
                                    },
                                    "BackButton": {
                                        "type": "string"
                                    },
                                    "BallotBoxStuffingPrevention": {
                                        "type": "string"
                                    },
                                    "CollectGeoLocation": {
                                        "type": "string"
                                    },
                                    "CustomStyles": {
                                        "type": "object",
                                        "properties": {
                                            "altRowStyles": {
                                                "type": "object",
                                                "properties": {
                                                    "selector": {
                                                        "type": "string"
                                                    },
                                                    "styles": {
                                                        "type": "object",
                                                        "properties": {
                                                            "backgroundColor": {}
                                                        }
                                                    }
                                                }
                                            },
                                            "borderStyles": {
                                                "type": "object",
                                                "properties": {
                                                    "selector": {
                                                        "type": "string"
                                                    },
                                                    "styles": {
                                                        "type": "object",
                                                        "properties": {
                                                            "borderColor": {}
                                                        }
                                                    }
                                                }
                                            },
                                            "choiceStyles": {
                                                "type": "object",
                                                "properties": {
                                                    "selector": {
                                                        "type": "string"
                                                    },
                                                    "styles": {
                                                        "type": "object",
                                                        "properties": {
                                                            "color": {},
                                                            "fontFamily": {},
                                                            "fontSize": {},
                                                            "fontStyle": {},
                                                            "fontWeight": {},
                                                            "textDecoration": {}
                                                        }
                                                    }
                                                }
                                            },
                                            "customCSS": {},
                                            "errorStyles": {
                                                "type": "object",
                                                "properties": {
                                                    "selector": {
                                                        "type": "string"
                                                    },
                                                    "styles": {
                                                        "type": "object",
                                                        "properties": {
                                                            "backgroundColor": {},
                                                            "borderColor": {},
                                                            "color": {}
                                                        }
                                                    }
                                                }
                                            },
                                            "errorStylesBG": {
                                                "type": "object",
                                                "properties": {
                                                    "selector": {
                                                        "type": "string"
                                                    },
                                                    "styles": {
                                                        "type": "object",
                                                        "properties": {
                                                            "backgroundColor": {},
                                                            "color": {}
                                                        }
                                                    }
                                                }
                                            },
                                            "footerStyles": {
                                                "type": "object",
                                                "properties": {
                                                    "selector": {
                                                        "type": "string"
                                                    },
                                                    "styles": {
                                                        "type": "object",
                                                        "properties": {
                                                            "color": {}
                                                        }
                                                    }
                                                }
                                            },
                                            "headerStyles": {
                                                "type": "object",
                                                "properties": {
                                                    "selector": {
                                                        "type": "string"
                                                    },
                                                    "styles": {
                                                        "type": "object",
                                                        "properties": {
                                                            "color": {}
                                                        }
                                                    }
                                                }
                                            },
                                            "highlightStyles": {
                                                "type": "object",
                                                "properties": {
                                                    "selector": {
                                                        "type": "string"
                                                    },
                                                    "styles": {
                                                        "type": "object",
                                                        "properties": {
                                                            "backgroundColor": {}
                                                        }
                                                    }
                                                }
                                            },
                                            "highlightStylesAlt": {
                                                "type": "object",
                                                "properties": {
                                                    "selector": {
                                                        "type": "string"
                                                    },
                                                    "styles": {
                                                        "type": "object",
                                                        "properties": {
                                                            "backgroundColor": {}
                                                        }
                                                    }
                                                }
                                            },
                                            "pageStyles": {
                                                "type": "object",
                                                "properties": {
                                                    "selector": {
                                                        "type": "string"
                                                    },
                                                    "styles": {
                                                        "type": "object",
                                                        "properties": {
                                                            "backgroundColor": {}
                                                        }
                                                    }
                                                }
                                            },
                                            "questionSeparatorStyles": {
                                                "type": "object",
                                                "properties": {
                                                    "selector": {
                                                        "type": "string"
                                                    },
                                                    "styles": {
                                                        "type": "object",
                                                        "properties": {
                                                            "backgroundColor": {},
                                                            "display": {}
                                                        }
                                                    }
                                                }
                                            },
                                            "questionStyles": {
                                                "type": "object",
                                                "properties": {
                                                    "selector": {
                                                        "type": "string"
                                                    },
                                                    "styles": {
                                                        "type": "object",
                                                        "properties": {
                                                            "color": {},
                                                            "fontFamily": {},
                                                            "fontSize": {},
                                                            "fontStyle": {},
                                                            "fontWeight": {},
                                                            "textDecoration": {}
                                                        }
                                                    }
                                                }
                                            },
                                            "textEntryStyles": {
                                                "type": "object",
                                                "properties": {
                                                    "selector": {
                                                        "type": "string"
                                                    },
                                                    "styles": {
                                                        "type": "object",
                                                        "properties": {
            

# --- truncated at 32 KB (210 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/qualtrics/refs/heads/main/openapi/qualtrics-api-openapi-3.0.json