RESTful APIs

REST is an API standard that uses HTTP protocols to create, read, update, and delete data. The Medallia Experience Cloud RESTful APIs provide inbound and outbound access, and manipulate textual representations of web resources by using a uniform and predefined set of stateless operations.

Restrictions and limits

The REST APIs have these limits:

  • Up to 70 requests/second
  • Up to 10,000 requests/day
Important: The timeout for a request is 180 seconds. The API Gateway discards any request that takes longer than that.

URL and endpoint

The REST APIs access 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 Experience Cloud instance. For detailed information about identifying the host, see API hosts.

  • resource-group is admin.

  • resource-group-version is v1.

  • endpoint is the resource you are accessing. For detailed information about the API endpoint, see Roles API and Users API.

For example, to access the account information whose username is cc_executive, the URL, path, and endpoint might look like this:

https://instance.apis.medallia.com/admin/v1/users/cc_executive

Accessing the REST APIs

To use the REST APIs:

  1. The application must have an account.

  2. The account's role must have permission to access the specific APIs. For example, to access user accounts, the role needs the Manage Users permission.

  3. 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. For detailed information, see Authenticating APIs with OAuth. Here is an example using curl that returns a token whose value is "abc123":

    curl https://instance.medallia.com/oauth/company/token -X POST -u 'client_id:client_secret' -d grant_type=client_credentials
{"access_token":"abc123","token_type":"Bearer","expires_in":3600}
  4. Make the call to the REST API endpoint. The endpoint begins with the host, followed by the apis subdomain, the instance domain, and ends with /admin/v1/<rest-api>, like this: 
    https://<api-host>/admin/v1/<rest-api>

    See API hosts to identify the host for your instance.

    This curl example requests the user record (/users/<username>) for the account whose username is "cc_executive", and it uses the access token obtained in the previous step:

    curl -X GET -H 'Authorization: Bearer abc123' -H 'Content-Type: application/json' "https://company.apis.medallia.com/admin/v1/users/cc_executive" {"username":"cc_executive","first_name":"Tim","last_name":"Baker","salutation":null,"email":null,"phone":null,"automatic_update":true,"excluded_from_user_activity":false,"company_account_id":null,"login_blocked":false,"roles":{"primary_role":{"role":"[CC] Executive"},"extra_roles":[]},"data-access":{"organization":[{"role":"[CC] Executive","data_view":"fs","unit_group":"unittype_cc_agent","unit_group_display_name":"Contact Center"}],"segments":[]},"_system_properties":{"status":"ACTIVE","created_on":"2017-10-10T13:55:30.924Z","created_by":null,"modified_on":"2018-11-20T20:12:06.670Z","modified_by":"userdemo","login_blocked_reason":null,"last_login":null,"login_count":0,"failed_login_count":0,"password_last_set":"2017-12-05T11:59:16.680Z","password_last_emailed":null,"password_not_set_reason":null},"_links":null,"_allowed":["GET","PUT"]}