Introduction

Medallia Experience Cloud APIs are either REST-based or GraphQL-based. The REST APIs are used for manipulating objects or bulk importing data, while the GraphQL APIs are used for real-time analytics and pulling data from Experience Cloud.

Experience Cloud APIs are secured using OAuth 2.0. For more information, see Authentication.

Experience Cloud offers both sandbox environments where partner and client developers test and develop configuration, code, and integrations before going live. If you are interested in building solutions and joining the partner ecosystem, sign up here.

API Gateway URLs

Medallia's API Gateway URLs are derived from the Reporting URL which is set when your Experience Cloud instance is first provisioned.

This section provides a quick start guide for determining your API Gateway URL; see our product documentation to find additional details.

Some Medallia products, such as Conversations, may have dedicated API gateways or other ways of accessing their content due to unique requirements or operating conditions. Check the product-specific API documentation for more details.

Production Instances and Partner Sandboxes

API Gateway URLs are of the form:

instance-tenant.apis.medallia.com

The instance and tenant values are taken from the Reporting URL, such as instance.medallia.com/tenant. The suffix apis.medallia.com is constant, independent of the data center.

The below table shows several examples of this mapping being applied on fictional instances:

📘

Partner sandboxes similar to production

Partner sandboxes are environments that partners use for development and follow the same URL patterns as production environments.

Client Sandboxes

Client sandboxes are copies of a customer's production environment that a customer can create or delete at will.

API Gateway URLs are of the form:

sbxname-instance-tenant.apis.sbx.dc.medallia.tld

Similar to the production instance URLs, these values are derived from the sandbox's Reporting URL, just with more parts being used.

The below table shows several examples of this mapping being applied to fictional instances:

Error Handling

Medallia's APIs return both an HTTP response code and an error message. Typical errors and response codes are shown below.  Check the documentation for the specific APIs with which you are integrating for any API-specific behaviors.

Rates and Limits

In general, most APIs are available on all instances of Medallia. Some APIs related to add-on features, such as the Speech API, are only available to customers who have purchased those features.

When these limits are exceeded, the app or user may be throttled. API requests made by a throttled user or app will fail.

Experience Cloud APIs will return the following HTTP headers to enable the caller to track rate limits. For further details, see IETF draft-polli-ratelimit-headers.

API-specific Limits

The standard API call limits are listed in the table below. Note that these are not hard limits; Medallia limits the number of API calls per company to prevent unintended bugs in API client code or malicious code from taking down production systems.

In addition, the below APIs have unique aspects of rating limiting that are orthogonally applied:

• Query API calls have a cost. Requests are subject to cost limits and are throttled once the 3,000,000 cost-units-per-query limit is reached.
• Import API calls are restricted to a data payload size limit of 100 MB for concurrent processing and 1.5 GB for non-concurrent processing.
• The feed file detailed results show up to the first 5,000 input records per result status for an import request. Examples of result status include records successfully created, updated, or discarded.

Examples

• Simultaneously make 10 API calls/sec to the Users API and 10 API calls/sec to the Roles API on your production instance - OK
• Simultaneously make 10 API calls/sec to the Users API on your production instance and 10 API calls/sec to the Users API on your sandbox - OK
• Make 15 calls/sec to the Roles API on your production instance - 5 calls will return with HTTP 429

All instances of Medallia have an allowance of at least 60,000 API calls per 24-hour window. Certain APIs may have different baseline allowances, so please check the API documentation for any additional details. Allowances are based on your Experience Cloud subscription. If you require a higher daily call volume, contact your account representative or Medallia Support.

📘

Cost and limits

Medallia limits the number of API calls per company to prevent unintended bugs in API client code or malicious code from taking down production systems. If you need higher limits, contact your Medallia representative to make the request.