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
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:
- The application must have an account.
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.
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}
- 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"]}