Request and response formats

Make query requests with URLs that contain the MQL query options. MQL is Medallia’s SQL-like language to request feedback data. As such, knowledge of how to use SQL is a prerequisite to using the API.

For example, to request the count of available survey records, an SQL query looks like this:

select count(*) from survey

In the URL, the same query looks like this

…&query=select+count(*)+from+survey

To make a request you will need either an OAuth access token (required for all new instances) or an API key (for some existing instances). Eventually all MQL requests will require OAuth.

Make requests to an API endpoint: the resource that responds to query request. The endpoint is OAuth is different from the one for API key.

OAuth access

To use OAuth to access MQL, you need an OAuth access token. For detailed information, see Authenticating APIs with OAuth.

Once you have the token, you can make the request. The host you make the request to depends on your instance configuration. See Making an API call using the access (bearer) token for an overview.

This curl example requests the count of available survey records from a host where the instance and company names are different:

curl -H 'Authorization: Bearer 4db959af42885e28b3619697cffafe6' -H 'Content-Type: application/json' \
  "https://instance-company.apis.medallia.com/data/v0/mql?output=csv&version=1&query=select+count(*)+from+survey"

If the instance and company names are the same, the request would be:

curl -H 'Authorization: Bearer 4db959af42885e28b3619697cffafe6' -H 'Content-Type: application/json' \
  "https://instance.apis.medallia.com/data/v0/mql?output=csv&version=1&query=select+count(*)+from+survey"

API key access

Restriction: Medallia no longer issues API keys. This option is only available to companies that already have a key.

To use API key access, you need a username, password, and the API key for the user account. The endpoint for API keys all use the same instance, but each company has its own resource. The API key endpoint is:

https://api.medallia.com/company?…

The rest of the URL includes options to identify the account, API key, query, and query options, similar to this:

https://api.medallia.com/company?user=username&pass=password&…&apikey=value

Query options

Express the query and options as URL parameters.

query
The MQL query. For example, to request the count of available survey records, an SQL query looks like this: 
select count(*) from survey

In the URL, the same MQL query looks like this

…&query=select+count(*)+from+survey
output
Format of the response data. The options are:

  • json

  • xml

  • csv — common CSV

  •  excel_csv — MS Excel-compatible, escapes double quotes with "" rather than standard \"

For example:
…&output=json
delimiter

When output is csv or excel_csv, use this argument changes the character that separates column values.

The default is a comma (',').

version
The APi version. Use 1 until further notice.
offSet
(For List query only) List Queries return up to 10,000 records (a query returning any more than that will result in an error). To gather more records than that, you'll need to paginate the results by making multiple queries with offset 0, 10000, 20000 etc. and adding a LIMIT 10000 clause to each query. In addition, a SELECT COUNT (*) query should be used at the outset to determine the number of paginated calls necessary.

You can also bundle queries, as described in Query bundling.

If the query contains quoted strings, then the quotes must be single quotes ('), and any single quotes within the string itself should be escaped with another single quote. So the correct way to quote a given string is to first replace all single quotes with two single quotes, and then add a single quote to the front and to the end of the string.

Example request

These examples are complete urls for making a query that returns the count of available record in CSV format.

OAuth query

https://instance-company.apis.medallia.com/data/v0/mql?output=csv&version=1&query=select+count(*)+from+survey

API key query

https://api.medallia.com/company?user=john&pass=Ypass12&query=select+count%28*%29+from+survey&output=csv&version=1&apikey=5hxf4qz2qzjuxm46686csnwk

CSV result

count(*)
38999.0