Data API is an ODATA based API providing export capabilities for Moveworks analytics data. Learn more about the data exposed via the API through this data dictionary and understand the process of building the integrations by referring to these guides.

1. Learn how to build integration with the API : link
2. Build custom metrics in your BI tools: link

Authentication and Authorization

Data API support API key and Oauth2 - Client credentials authentication methods. The credential generation is controlled by Moveworks and credentials generated for any other Moveworks API will not work for Data API.

If you are part of the limited preview program you should already have the credentials sent by the product team at Moveworks. We are only sharing credentials with customer who are part of the limited preview program.

The Data API also support scope based access. Each table i.e conversations, interactions, plugin calls, plugin resources & users have a readonly scope attached to it. If you need a scope with controlled access over these tables. Please reachout to [email protected] and share the requirements.

How to use the shared credentials

Using the shared credentials is simple, the credentials should be a part of the header in the API request. This allows Moveworks to authenticate and provide relevant data in the API response.

1. API key

The API key can be directly sent in the API headers. Please refer to the sample CURL below.

curl --request GET \
     --url https://api.moveworks.ai/export/v1beta2/records/conversations \
     --header 'Authorization: Your API key' \
     --header 'accept: application/json'

1. Oauth2 - Client credentials grant

The Oauth2 method uses a temporary access token generated by utilizing the client ID and client secret. This token expires every 3600 seconds and needs to be generated again in order to authenticate with the API. Please refer to the sample CURL below to understand the process

1. Generating temporary access token

curl --request POST \
     --url https://api.moveworks.ai/oauth/v1/token \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "client_id": "sample client id",
  "grant_type": "client_credentials",
  "client_secret": "sample client secret"
}
'

1. Passing the access token in the API request

curl --request GET \
     --url https://api.moveworks.ai/export/v1beta2/records/conversations \
     --header 'accept: application/json' \
     --header 'authorization: Bearer Test token'

Pagination

Data API supports pagination to optimize the API experience and enables sharing of large data broken down into small chunks. Pagination is a important aspect to ensure the response time and payload size are optimal in building an integration.

Data API utilizes the native pagination capabilities of ODATA and provides odata.nextlink in the API response in order to fetch next set of results.

The current page size of Data API is set to 500 records per page.

In order to fetch the next set of 500 records we need to use the $skip and $orderby parameter. This ensures no records are repeated in the next page.

The odata.nextlink provides the exact URL to call in order to fetch the next set of 500 records. Once all records are provided via the API, the response now doesn’t contain the odata.nextlink thus we have an indication that there are no records to be fetched now.

Check the following sample API response for the same.

{
  "@odata.context": "https://api.moveworks.ai/export/v1beta2/records/metadata#conversations",
  "@odata.nextLink": "https://api.moveworks.ai/export/v1beta2/records/conversations?$skip=500&$orderby=created_time",
  "value": [
    {
      "id": "12345",
      "user_id": "1812312452353242",
      "conversation_domain": "IT",
      "route": "DM",
      "created_time": "2023-01-01T00:00:00Z",
      "last_updated_time": "2023-01-01T00:00:00Z"
    }
    .
    .
    . // Total 500 records
  ]
}

Rate limiting

Data API hosts API rate limit to ensure all requests are processed by Moveworks and we are able to provide response to each API query. This prevents security attacks like DDOS.

The current rate limit for Data API is around 40 req/min for each URL. For example: Conversations & Interactions API have their own rate limits.

Please note, this API is in beta phase and we want to learn more about the customer usage patterns and infrastructure scalability on our end before increasing the rate limits

Supported query parameters.