Query API

Important: Set up Experience Programs in the target instance before using this API. They create a necessary referenceable schema for feedback and invitations fields, and for program record fields. .

The Query API is a powerful analytics API that harnesses GraphQL to give you access to Medallia Experience Cloud data through a single endpoint. Send a standard HTTP POST request to the server through a single endpoint, specify what data you need, and get back exactly that.

Experience Cloud generates valuable information and, although it has its own robust analytics engine, and integrated collecting and reporting capabilities, sometimes it is necessary to retrieve and manipulate experience data.

The Query API is an API that applications can use to pull Experience Cloud record-level data into your BI tool, data warehouse or data visualization app to create tailored insights for stakeholders, or pull aggregated data for ad-hoc analysis, to identify improvement opportunities in your business.

Note: This documentation does not teach GraphQL. Read the GraphQL documentation to learn about the language and how to write queries. For a more interactive learning experience with video tutorials, different scenarios, sandbox environments, sample requests, and exercises, visit How to GraphQL.

The Experience Cloud security framework uses OAuth 2.0 for authenticating access to data. Applications that access the Medallia Experience Cloud APIs are OAuth clients. That means all Query API requests require an OAuth access token. For details about getting a token, see Authentication and authorization.

Usage

The Query API is the primary way for apps to access Experience Cloud raw survey data. All of our analytics tools interact with the Query API in some way, especially our Report modules.

The API is a GraphQL interface. GraphQL is a standard and well known language, ideal for querying interactive data. Moreover, the API is self-documented through it's schema, since GraphQL supports introspection. Developers can explore the graph in an interactive way using any GraphQL IDE (such as Altair GraphQL Client, GraphiQL, Insomnia, and Postman).

Use Query API to:

Fetch record-level data (for invitations, feedback, and customer experience profiles).
- Filter the data using complex filters.
  - Filter using standard logical and comparison operators.
  - Filter by date range.
  - Filter by segment.
  - Filter by field and unit field value.
- Sort data by a field.
- Pull an incremental data set.
- Pull a paginated data set.
Aggregate record-level data using simple aggregations: AVG, SUM and Count.
- User single number aggregation — it returns a number given a field.
- Use 2D table aggregation — each cell in the table aggregates the data given the row and column.
- Query R-fields.
Fetch field metadata.
- Filter metadata by type or name.

See Data queries and Metadata queries for more details.

Restriction: Do not use Query API in front-end implementations where data is requested upon website load, for example, requesting NPS score to display on the brand site. For this and similar use cases, we recommend using a back-end integration to store the desired value and only update periodically.

Authentication and authorization

Authentication identifies who is making an API request, and authorization identifies what data the requester may access. OAuth is an industry standard for authorizing limited access to services and data. Applications must obtain a secure token that identifies the application that makes the request. The token is passed to the resource server (API server) with each API request. For more information, see Authenticate APIs with OAuth.

To use the Query API:

The application must have an account
The account's role must have permission to access the API. .
API access is authenticated with OAuth. To use OAuth, the application must first obtain an OAuth access token, by requesting one for the application's client ID and secret. .

Request/response formats

Requests sent to Experience Cloud Query API are generally HTTP POST protocol. The information in the request includes:

A required Bearer header type field with the access token.
The request URL:
- Always use the base instance for the company's Medallia installation; do not try to bypass the API gateway.

URL and endpoint

The Query API accesses resources from a URL that follows this format:

https://<api-host>/<resource-group>/<resource-group-version>/<endpoint>

Where:

api-host is the server for your company's Medallia Experience Cloud instance.
resource-group is data.
resource-group-version is v0.
endpoint is query.

Note: To identify the instance for your company, look at the URL that accesses Medallia Web. For more details see API hosts.

For example, if that URL is:

https://instance.medallia.com/company


Environment	API URL
Production (company and instance names are the same)	https://<instance>.apis.medallia.com/data/v0/query
Production (company and instance names are different)	https://<instance>-<company>.apis.medallia.com/data/v0/query
Sandbox	https://<sandbox-name>-<company>.apis.sbx.<data-center>.medallia.com/data/v0/query

POST body

Instead of using several requests to different endpoints, with GraphQL, you can send a single HTTP POST request with detailed information about your data needs in the form of a query in the body of the request.

The queries are done with this basic JSON structure:

Examples of metadata and data queries with call-outs to the sections: filter, pagination, pagination info, cost info, and data

Where:

Filtering to apply to the request.
- filter identifies the records to retrieve. See Filter and sort data for details.
Pagination limits the count of elements (records) returned, and their relationship to the previous query. See Pagination for details.
- after is a cursor that identifies where to start the page. For the initial query, the value is null, but for subsequent queries, it is the last record at the end of the previous page, as identified by the endCursor value.
- first is the page size: return up to this many results.
Pagination info used in the next "paged" query. See Pagination for details.
- endCursor is the last result in the page, and is the value to use as the after in the next page.
- hasNextPage is true when there are more records after the current page.
Total count of records returned.
- totalCount is the number of records that match the filter criteria.
Data requested.
- nodes is the container for the requested data, and defines the record data to return.
- dataTable allows formatting the response as a table to optimize the response for better data consumption.

Response

Regardless of the request method, the response is a JSON object in this format:

{
  "data": { },
  "errors": null,
  "_links": null,
  "_allowed": [
    "POST",
    "GET"
  ]
}

Where data and errors are the two important attributes.


Element	Description	Type	Notes
data	Container for the requested data.	Data object
errors	Brief description of the error that occurred.	String
_allowed	Allowed HTTP requests.	String	Values: POST GET

If you are unfamiliar with Query API, we recommend that you start with these documents:

If you want to dive right in and begin using the API, follow the steps in Quickstart: Query API.