Introspection API
Use this metadata API to discover all available web feeds — i.e. Import API endpoints — for a Medallia Experience Cloud instance via HTTP request, or introspect a specific web feed to see its data structure. API users can further introspect a singular endpoint to understand the data requirements of the input data needed to import into Experience Cloud.
To discover all available endpoints that can be used for import, authenticated API users can make a GET request to the /inbound/v2 endpoint, which will provide the following pathways in the response.
{
"openapi": "3.0.1",
"info": {
"title": "Import API",
"version": "1.0.0"
},
"servers": [
{
"url": "https://instance.apis.medallia.com"
}
],
"paths": {
"/inbound/v2/async/active_b2b_onboarding_invitation": {
"post": {
"summary": "active_b2b_onboarding_invitation",
"description": "This web feed is for the client to send Medallia invitation data for the B2B Onboarding program ON ACTIVE..."
}
},
"/inbound/v2/async/active_b2b_org": {
"post": {
"summary": "active_b2b_org",
"description": "This web feed is for the client to send Medallia org hierarchy data for the B2B program WITH ACTIVE PROCESSING..."
}
},
"/inbound/v2/async/active_b2b_relationship_invitation": {
"post": {
"summary": "active_b2b_relationship_invitation",
"description": "This web feed is for the client to send Medallia invitation data for the B2B Relationship program ON ACTIVE..."
}
}
}
}To investigate the specific data input requirements of a certain endpoint, the API user can then make a GET call to /inbound/v2/{webfeed_name} to retrieve the exact data requirements.
Each path entry reflects the exact API endpoint that is available to post data to along with the description from the Web Feeds screen to explain the purpose of that API endpoint.
The input object within the response outlines all the input properties needed to submit data to this particular Import API endpoint, including the data types of each property (for example: strings, enums, integers, etc.) and which properties are required.
e_bp_development_cycle_alt — the API will indicate it is an enumerated property and display all possible enumerated values of that field.type = string given the complexity of possible JS transforms that can be set up within an Auto Importer that makes it difficult to ascertain exact data types.{
"openapi": "3.0.1",
"info": {
"title": "Import API",
"version": "1.0.0"
},
"servers": [
{
"url": "https://instance.apis.medallia.com"
}
],
"paths": {
"/inbound/v2/async/active_b2b_onboarding_invitation": {
"post": {
"summary": "active_b2b_onboarding_invitation",
"description": "This web feed is for the client to send Medallia invitation data for the B2B Onboarding program ON ACTIVE..",
"requestBody" : {...},
"responses" : {...},
"security" : [...]
}
}
},
"components": {
"schemas": {
"input-object": {
"required": [
"ACCOUNT_ID",
"DATE_TO_SURVEY",
"DEVELOPMENT_CYCLE",
"EMAIL_ADDRESS",
"FIRST_NAME"
],
"type": "object",
"properties": {
"ACCOUNT_ID": {
"type": "string"
},
"DATE_TO_SURVEY": {
"type": "string"
},
"DEVELOPMENT_CYCLE": {
"type": "string",
"enum": [
"QA",
"DEV",
"TEACH",
"UAT",
"DEMO",
"LIVE"
]
},
"FIRST_NAME": {
"type": "string"
},
"LAST_NAME": {
"type": "string"
},
"EMAIL_ADDRESS": {
"type": "string",
"format": "email"
},
"LANGUAGE": {
"type": "string",
"enum": [
"English",
"Spanish (Spain)",
"French (France)",
"German (Germany)",
"Spanish (Mexico)",
"French (Canada)",
"Italian (Italy)",
"Portuguese (Brazil)",
"Chinese",
"Norwegian"
]
}
}
}
}
}
}Restrictions and limits
The API can handle up to 10 requests per second and 10,000 requests per day.
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 Authenticating APIs with OAuth.
To use the Introspection API:
The application must have an account.
- The account's role must have permission to access the API.
Import Data via Web Feed
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.
Request/response formats
A required
Content-Typeheader field describing the content. The acceptable type is: application/json for JSON.An optional
Acceptfield tells the Introspection API how to format the response. The acceptable type is: application/json for JSON and application/yaml for YAML.Parameter Description Required Values Bearer Access token Required See Authentication and authorization. Content-Type Format of request data Required application/json. Accept Format of response data Optional The default value is "application/json". The supported values are: application/json
application/yaml
No other header fields are expected.
The request URL:
Always use the base instance for the company's Medallia installation.
URLs and endpoints
The Introspection API accesses resources from a URL that follows this format to introspect all active or pretend web feeds made available to the API user:
https://<api-host>/<service>/<api-version>api-host is the server for your company's Medallia Experience Cloud instance. For detailed information about identifying the host, see API hosts.
service is
inbound.api-version is
v2.
And a URL that follows the format below to introspect a specific feed:
https://<api-host>/<service>/<api-version>/<URL-unique-name>api-host is the server for your company's Medallia Experience Cloud instance. For detailed information about identifying the host, see API hosts.
service is
inbound.api-version is
v2.URL-unique-name identifies the web feed endpoint. This web-feed specification (which also maps to an import specification). A company may have multiple workflows through Web Feeds, each of which has a different endpoint.
Response
The API is synchronous. By default, the response is a JSON object that conforms to OpenAPI specification version 3.0 standards.
Sample requests
The following samples show how use the Introspection API to introspect Import API endpoints.
Sample request - Introspection API request to introspect all web feeds
GET https://instance.apis.medallia.com/inbound/v2
Content-Type: application/jsonSample response - Status 200 - OK
{
"openapi": "3.0.1",
"info": {
"title": "Import API",
"version": "1.0.0"
},
"servers": [
{
"url": "https://instance.apis.medallia.com"
}
],
"paths": {
"/inbound/v2/async/uat_voe_rel_user": {
"post": {
"summary": "uat_voe_rel_user",
"description": "This web feed is for the client to send Medallia user account data for UAT of the VOE Relationship program WITH ACTIVE PROCESSING."
}
},
"/inbound/v2/async/uat_wm_advisor_org": {
"post": {
"summary": "uat_wm_advisor_org",
"description": "This web feed is for the firm to send Medallia advisor-based org hierarchy data for the UAT of Wealth Management programs WITH ACTIVE PROCESSING."
}
},
"/inbound/v2/async/uat_wm_client_onboarding_invitation": {
"post": {
"summary": "uat_wm_client_onboarding_invitation",
"description": "This web feed is for the firm to send Medallia invitation data for the UAT of the Wealth Management client onboarding program WITH ACTIVE PROCESSING."
}
}
}
}
Sample request - Introspection API request to introspect one web feed
GET https://instance.apis.medallia.com/inbound/v2/active_cc_transactional_agent_invitation
Content-Type: application/json
Sample response - Status 200 - OK
{
"openapi": "3.0.1",
"info": {
"title": "Import API",
"version": "1.0.0"
},
"servers": [
{
"url": "https://instance.apis.medallia.com"
}
],
"paths": {
"/inbound/v2/async/active_cc_transactional_agent_invitation": {
"post": {
"summary": "active_cc_transactional_agent_invitation",
"description": "This web feed is for the client to send Medallia invitation data for the Contact Center Transactional Agent program WITH ACTIVE PROCESSING.",
"requestBody": {
"description": "The data to be imported",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"$ref": "#/components/schemas/input-object"
},
{
"type": "array",
"items": {
"$ref": "#/components/schemas/input-object"
}
}
]
}
},
"text/xml": {
"schema": {
"oneOf": [
{
"$ref": "#/components/schemas/input-object"
},
{
"type": "array",
"items": {
"$ref": "#/components/schemas/input-object"
}
}
]
}
},
"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": {
"schema": {
"type": "string",
"format": "binary"
}
},
"text/csv": {
"schema": {
"type": "string"
}
}
},
"required": true
},
"responses": {
"202": {
"description": "The response to a data import that is processed asynchronously. Refer to Medallia's Developer Portal for latest rate limit information returned in the headers.",
"content": {
"application/json": {
"schema": {
"required": [
"feed_file_id"
],
"type": "object",
"properties": {
"feed_file_id": {
"type": "string",
"description": "The unique ID of the feed file record created. Use this ID to retrieve the results of the import request."
}
}
}
}
}
},
"401": {
"description": "Unauthorized"
},
"403": {
"description": "Forbidden"
},
"404": {
"description": "Object not found. Refer to Medallia's Developer Portal for latest rate limit information returned in the headers."
},
"412": {
"description": "Precondition failed"
},
"500": {
"description": "Internal server error"
}
},
"security": [
{
"mecOauth": []
}
]
}
}
},
"components": {
"schemas": {
"input-object": {
"required": [
"AGENT_ID",
"DEVELOPMENT_CYCLE",
"EMAIL_ADDRESS",
"FIRST_NAME",
"INTERACTION_DATETIME",
"INTERACTION_ID"
],
"type": "object",
"properties": {
"DEVELOPMENT_CYCLE": {
"type": "string",
"enum": [
"QA",
"DEV",
"TEACH",
"UAT",
"DEMO",
"LIVE"
]
},
"INTERACTION_ID": {
"type": "string"
},
"INTERACTION_DATETIME": {
"type": "string",
"description": "yyyy-MM-dd HH:mm:ssZZ"
},
"INTERACTION_DURATION": {
"type": "number"
},
"INTERACTION_TYPE": {
"type": "string",
"enum": [
"Phone",
"Chat"
]
},
"INTERACTION_REASON": {
"type": "string",
"enum": [
"Product inquiry",
"Product availability",
"Process assistance",
"Billing & finances",
"Shipping & logistics",
"Overall feedback",
"[Additional, Optional Field]",
"Other"
]
},
"AGENT_ID": {
"type": "string"
},
"AGENT_DISPLAY_NAME": {
"type": "string"
},
"ALL_AGENT_IDS": {
"type": "string"
},
"ALL_AGENT_NAMES": {
"type": "string"
},
"CUSTOMER_ID": {
"type": "string"
},
"FIRST_NAME": {
"type": "string"
},
"LAST_NAME": {
"type": "string"
},
"EMAIL_ADDRESS": {
"type": "string",
"format": "email"
},
"PHONE_NUMBER": {
"type": "string"
},
"GENDER": {
"type": "string",
"enum": [
"Male",
"Female"
]
},
"AGE_GROUP": {
"type": "string",
"enum": [
"Age Group 1",
"Age Group 2"
]
},
"COUNTRY": {
"type": "string"
},
"JOURNEY_SEGMENT": {
"type": "string",
"enum": [
"Journey Segment 1",
"Journey Segment 2"
]
},
"CONTACT_METHOD": {
"type": "string",
"enum": [
"Phone",
"Email",
"Chat"
]
},
"DATE_TIME_OF_FIRST_CALL": {
"type": "string"
},
"LANGUAGE": {
"type": "string",
"enum": [
"English",
"Spanish (Spain)",
"French (France)",
"German (Germany)",
"Spanish (Mexico)",
"French (Canada)",
"Italian (Italy)",
"Portuguese (Brazil)",
"Chinese",
"Norwegian"
]
},
"NUM_HOLDS": {
"type": "integer"
},
"NUM_TRANSFERS": {
"type": "integer"
},
"WAIT_TIME": {
"type": "number"
},
"CALL_QUEUE": {
"type": "string"
},
"CALL_RECORDING_URL": {
"type": "string"
},
"ACCOUNT_ID": {
"type": "string"
},
"ACCOUNT_NAME": {
"type": "string"
},
"RECORD_TYPE": {
"type": "string"
}
}
}
},
"securitySchemes": {
"mecOauth": {
"type": "oauth2",
"flows": {
"clientCredentials": {
"tokenUrl": "instance.apis.medallia.com/oauth/company/token"
}
}
}
}
}
}
Error handling
Client problems e.g., rate-limited, unauthorized, etc. (4xx HTTP codes).
The user-supplied parameters or context are bad (cannot find the specified web feed).
For the errors above, the application gets an HTTP error, the response will not be a Introspection API response because the error happened before processing the request.
