V1 Data API is now released

The Data API is now available in the V1 version. If you are still using the Beta2 or Beta1 version please migrate your active workflows to this version.

For customer using Beta2

There is no change in the API structure, you can even use the same credentials that were shared with you during the beta program. The only change you need to make on your end is to update the API URL

Beta2 URL : https://api.moveworks.ai/export/v1beta2/records/conversations

V1 URL : https://api.moveworks.ai/export/v1/records/conversations

For customer using Beta1

Beta1 API is severely outdated at this point. If you are still using this API migrate to the beta2 version as fast as possible.

We have published a new course on Data API here. This aims to give you a complete overview of what is Data API and what can you achieve using Data API.

Overview

The Data API is a product offered by Moveworks that is designed to allow customers to ingest AI Assistant conversations and interaction data through a REST API. The Data API exposes all interactions, including user utterances, button clicks, link clicks, and UI form submissions. It also provides information on the plugins invoked by the LLM, resources used to generate summarized responses, and users who have been ingested into Moveworks and have access to the AI Assistant.

What is a rest API?

A REST API (Representational State Transfer Application Programming Interface) enables systems to communicate over HTTP using a set of architectural principles. It is stateless, meaning each request from a client to the server must contain all necessary information. The key HTTP methods used are GET (retrieve data), POST (create data), PUT (update data), and DELETE (remove data). Resources are accessed via standard URLs, and JSON format is typically used for data exchange. REST APIs are known for their simplicity, scalability, and flexibility, making them ideal for web services and mobile applications.

Learn more about REST API here.

API version

Data API is currently in Beta2 version which is a beta version of the API. To read more on the API lifecycle management please refer to this documentation.

Which REST Endpoints are exposed via Data API

In the beta2 version, The Data API exposes base tables related to AI Assistant conversations data. The following tables are exposed through individual REST endpoint. Only GET method is supported on these endpoints.

Name of the table	Data exposed through the tables	URL
Conversations	Conversations are the top level objects over all interactions. Conversations are grouped based on the context of the interaction. All interactions within a conversation share the same conversation ID.	https://api.moveworks.ai/export/v1/records/conversations
Interactions	All user and AI Assistant exchanges are defined as interactions. These are the building blocks for a conversation.	https://api.moveworks.ai/export/v1/records/interactions
Plugin calls	Whenever a plugin is called by a copilot in a conversation all of these entries are recorded in this table. The plugin calls object provides details on the plugin name, whether the plugin served the request or not, and whether the plugin was used in the interaction.	https://api.moveworks.ai/export/v1/records/plugin-calls
Plugin resources	Resources used by the plugin to serve the end user are recorded in this table. The resource object provides details on the Service portal name, URL, and ID of the resource. There can be multiple resource types, such as Knowledge, Forms, Users, or Tickets.	https://api.moveworks.ai/export/v1/records/plugin-resources
Users	Users who are ingested into Moveworks are stored in this table. This table provides details on the ingested user’s ID from the end systems that are configured in identity setup, which can be used to pull additional information from external systems such as Okta or Active Directory.	https://api.moveworks.ai/export/v1/records/users

How is the Data Model structured

The Data Model follows an hierarchical approach to allow additional data for nested object. The relationship can be understood by the following image.

The parent object shares 1-Many relationship with the subsequent child object. Users API fetches data from a standalone table which provides details around the user ingested into Moveworks.

API structure

All REST endpoints will respond in JSON format defined by OData. Each JSON object represents a new unique entry in that table

$ {
> "odata.context": "...",
> "odata.nextlink": "...",
> "value" : [
> 
> 	{ //object 1
> 
> 	},
> 	{ //object 2
> 
> 	}
> 
> 	]
> 	
> }

If there is no entries present in the table, the value array is empty.
All attributes in each entity either contains a “value” or will be NULL . There will be no empty strings or empty JSON if data is not present for a certain field.
All attributes are exposed as STRING, nested JSON with STRING key <> value pair and array of STRING. We are not exposing any other data type from the API.

For API documentation refer here.

Data Dictionary

The following tables cover what attributes are available in through individual REST API’s. To understand the exact attribute names for each REST endpoints please refer to the API documentation.

Conversations

Field name	Description
ID	UUID assigned by the system to a conversation. Conversations are grouped based on the context of interactions. All interactions within a conversation share the same conversation ID.
User ID	User record ID assigned by the system to a user.
Conversation Domain	Primary domain detected by an LLM model after going through all detected domains of free text interactions belonging to a particular conversation.
Route	This field contains details on how a conversation was started either through DM, Notification engagement, Ticket interception engagement, or Channel resolver engagement.
Created time	Timestamp when the conversation was initiated.
Last updated time	Timestamp when the conversations entry is last updated in this table.

Interactions

Field name	Description
ID	UUID assigned by a system to a interaction. An interaction is either an input from a user to the system, or a response from the system the the user.
Conversation ID	ID of the parent conversation.
User ID	User record ID assigned by the system to a user.
Actor	This field differentiates user v/s AI Assistant interactions.
Platform	This field denotes the platform where the interaction took place. For example: slack, msteam
Type	This field defines the type of the interaction. The interaction can belong to one of the following types. 1.INTERACTION_TYPE_FREE_TEXT - user types an utterance 2.INTERACTION_TYPE_CONTENT_UPLOAD - user uploads content, for example a file 3.INTERACTION_TYPE_AI Assistant_MESSAGE - text of the AI Assistant response to a user 4.INTERACTION_TYPE_UIFORM_SUBMISSION - user submits a UI form 5.INTERACTION_TYPE_LINK_CLICK - user clicks on a URL link (Moveworks wrapped links or Unwrapped Service portal link), citation, global action emoji (For example: Helpful, Unhelpful, Information) or a link presented as a button. 6.INTERACTION_TYPE_BUTTON_CLICK - user clicks on a button in chat
Label	This field defines the label for UI form submission interaction type. This can contain any one of the following values feedback - User has submitted a “feedback” form by clicking on the Helpful/Unhelpful button file_ticket - In-chat fillable “file ticket” form submitted by the end user. mw_form - User has submitted a Internal MW form. For example: Change language form. handoff - User has submitted a form after clicking on the “Get help” button.
Parent Interaction ID	Parent interaction ID for AI Assistant messages and User follow-up actions as button clicks, link clicks & UI form submission.
Detail	This is a JSON object which contains metadata per interaction type. The detailed description of each field is covered in the below table.
Created time	Timestamp when the interaction was initiated.
Last updated time	Timestamp when the interaction entry is last updated in this table.

Fields inside the “detail” JSON object

Field name	Description
content	This field contains the free form text, link URL, Button name according to interaction type. For feedback it contains the free text feedback provided by the end user. In case of label = “mw_form” and detail = “CSAT feedback” - This field will contain the free text message provided by the end-user in the form.
domain	This the interaction level detected domain . Domain is only predicted for free form text interaction type. In some cases, domain of individual utterances may differ from the primary domain detected per conversation.
entity	This field contains the topic as detected per each interaction. Topic is only predicted for free form text interaction type.
type	This field indicates which type of resource were accessed during an link click interaction.
detail	This field indicates the form name which was submitted. For feedback this attribute contains either Helpful (or) Unhelpful indicating which feedback form was filed.
resource_id	This field provides the resource ID that was accessed by the end user during an link click interaction, or when a user submits a ticket via UI form INTERACTION_TYPE_LINK_CLICK INTERACTION_TYPE_UIFORM_SUBMISSION
file_types	This field provides list of types of files that were uploaded during a file upload interaction (INTERACTION_TYPE_CONTENT_UPLOAD). We do not record the file names as user can also upload a private file

Plugin calls

Field name	Description
ID	UUID assigned by the system to a plugin being called by AI Assistant for a interaction.
Interaction ID	ID of the interaction for which the plugin is called
Conversation ID	ID of the parent conversation.
User ID	User record ID assigned by the system to a user.
Plugin name	Name of the plugin being called. Native plugins For example: Knowledge Base, Create ticket, Grant Software Access Custom plugins : Represents the plugin name configured in Creator studio For examples: Ariba_PTO_LOOKUP, Apply_Holiday_leave
Served	This field defines if the plugin was served to the end user. Plugin are considered served when they are offered to the end user through the AI Assistant response. For example: Knowledge base plugin is served when citations fetched by the plugin are used to generated the summarized response. Action plugins such as Create ticket are considered as “Served” when the workflow is initiated and is offered to the end users._
Used	This field defines if the plugin was used by the AI Assistant in the interaction. Plugins such as Knowledge base, Forms or productivity plugins if served are also considered as Used. Plugins such as File ticket, Update Approval are only considered as used if the end user has completed the workflow.
Created time	Timestamp when the plugin call was initiated.
Plugin update time	Timestamp of the last update for the plugin call.
Last updated time	Timestamp when the plugin call entry is last updated in this table

Plugin resources

Field name	Description
ID	UUID assigned by the system to a resource being used by a plugin called during an interaction.
Plugin call ID	ID of the plugin being called.
Interaction ID	ID of the interaction.
Conversation ID	ID of the parent conversation.
User ID	User record ID assigned by the system to a user.
Resource ID	ID of the resource stored in Moveworks.
Type	This field represents the type of resource utilized by a plugin call. The type can be one of the following values. 1.RESOURCE_TYPE_FORM - Ingested forms from service desk. 2.RESOURCE_TYPE_TICKET - Tickets created by the AI assistant in service desk (or) fetched from the service desk. 3.RESOURCE_TYPE_FILE - Files ingested in Moveworks 4.RESOURCE_TYPE_KNOWLEDGE - Internal knowledge articles, FAQ, External knowledge ingested/configured in Moveworks. 5.RESOURCE_TYPE_APPROVAL - Approvals fetched from the Approval systems. 6.RESOURCE_TYPE_RECORD - Entries fetched from external systems through Queries in creator studio 7.RESOURCE_TYPE_IDENTITY_SYSTEM - Identity systems configured in Moveworks. 8.RESOURCE_TYPE_PERSON - User ingested into Moveworks. 9.RESOURCE_TYPE_SOFTWARE - Softwares provision workflows and entities configured in Moveworks. 10.RESOURCE_TYPE_GROUP - Distribution lists ingested into Moveworks 11.RESOURCE_TYPE_INTERNAL_KNOWLEDGE - Moveworks AI assistant internal knowledge. 12.RESOURCE_TYPE_UPLOADED_CONTENT - Content uploaded by end users. 13.RESOURCE_TYPE_ROOM - Room information ingested into moveworks 14.RESOURCE_TYPE_UNSPECIFIED - Unknown resource types. Please check the AI Assistant’s response to learn more.
Detail	This is a JSON object which contains metadata per resource type. The detailed description of each field is covered in the below table.
Cited	This field denotes if the utilized resource was cited in the AI Assistant response or not.
Created time	Timestamp when the resource was utilized by a plugin
Last updated time	Timestamp when the plugin resource entry was last updated in this table.

Field included in the “detail” JSON object

Field name	Description
Domain	This field denotes the resource domain configured in Moveworks Setup while configuring Content ingestion & Ticketing. Domain is defined for resources of types: RESOURCE_TYPE_APPROVAL RESOURCE_TYPE_FORM RESOURCE_TYPE_TICKET RESOURCE_TYPE_KNOWLEDGE
External Resource ID	Service portal ID for the resource of type RESOURCE_TYPE_KNOWLEDGE. This field can be used to join data from external system. Please note external resource ID is not provided for FILE & EXTERNAL KNOWLEDGE (Public knowledge enabled in Moveworks)
Name	Name of the resource being used by the plugin, populated for resources of types: RESOURCE_TYPE_FILE RESOURCE_TYPE_FORM RESOURCE_TYPE_KNOWLEDGE
Snippet	Exact snippet from the resource being used to provide the summarized response, populated for resource types RESOURCE_TYPE_FILE RESOURCE_TYPE_KNOWLEDGE
Source	Name of the external sources from which the resource is being fetched from, populated for resource types RESOURCE_TYPE_TICKET RESOURCE_TYPE_APPROVAL
Type	Contains sub-type of approval or type of the ticket creation : User initiated v/s AI Assistant initiated, populated for resource types RESOURCE_TYPE_TICKET RESOURCE_TYPE_APPROVAL
URL	External system URL of the resource, populated for resource types RESOURCE_TYPE_TICKET RESOURCE_TYPE_KNOWLEDGE RESOURCE_TYPE_FILE

Users

Field name	Description
ID	User record id generated and stored in Moveworks for the end user
Email Addr	Email of the end user stored in Moveworks. This field is ingested from your systems and reflect the value present in your systems. Learn more about user profile here .
Access to AI Assistant	Denotes if the end user has access to Moveworks Assistant or not. This is evaluated through the AI Assistant access rule configured in Moveworks Setup.
First name	First name of the end user. This field is ingested from your systems and reflect the value present in your systems. Learn more about user profile here .
Last name	Last name of the end user.This field is ingested from your systems and reflect the value present in your systems. Learn more about user profile here .
User preferred language	User preferred language set from the end user. EN-US is the default value for this field
First interaction time	Time stamp for the first interaction for the end user.
Last interaction time	Time stamp for the latest interaction of the end user.
External Ids	This array contains External system details configured during identity ingestion Connector name : Name of the connector created in Moveworks Setup External ID : External ID from the source system Source : Identifier for the source system.
Last updated time	Last updated time for the user entry in this table.

FAQ

What is the SLA for Data API to provide new data in the API response ?

The Data API follows a 24-hour SLA, consistent with the Moveworks Analytics platform. The table below outlines the expected SLA for our analytics pipelines. Please note that this SLA is subject to change based on the timing of the latest analytics pipeline run.

Is there a sample data for Data API?

To access the sample data click on this link and download the “Sample responses” ZIP through the Github repository. This will contain JSON responses for - Conversations, Interactions, Plugin-calls, Plugin-resources and Users file. Please note we have anonymized the user details so the email address, first name and last name are replaced with a placeholder value.