Sift API Documentation (1.0.0)

Download OpenAPI specification:Download

Introduction

Gridspace Sift is an API for building voice analysis and communication systems. It allows you to do deep language processing on live calls and recorded speech.

Authentication

Gridspace Sift offers two forms of authentication:

  • Account Basic Authentication
  • Temporary User Bearer Tokens

Sign up for an account here

Account

The account ID and secret key can be viewed on /account page of the Sift dashboard. The credentials are only visible to users with the "View the root api credentials" permission assigned. The account ID is the username and the account key is the password using Basic Authentication. Activity logging will show this as an account level action.

Security Scheme Type HTTP
HTTP Authorization Scheme basic

Temporary Key

Temporary keys can be created from the /organization/keys page of the Sift dashboard. The key has the same permissions as the authorized issuing user unless specified. The secret key should be sent as a Bearer token. Activity logging will show this as a user level action (the user who issued the token).

Security Scheme Type HTTP
HTTP Authorization Scheme bearer

Media Upload

Upload Media for Processing

Upload your audio file to Sift and return an audio ID to be used for other conversation processing operations.

Authorizations:
Request Body schema: multipart/form-data
audio
Array of strings <binary>

Responses

Request samples

curl --request POST \
--url https://api.gridspace.com/v0/media/upload \
--user <<ACCOUNT ID>>:<<TOKEN>> \
-F audio=@audio_file.wav

Response samples

Content type
application/json
{
  • "audio_id": "string"
}

List Conversations

List Conversations

Return a list of conversions in the account. For more advanced filtering capabilities, use the Search endpoint.

Authorizations:
query Parameters
min_created
string <date-time>

The minimum created date for returned conversations. This may be different from the start date of the conversation if the conversation was uploaded later.

max_created
string <date-time>

The maximum created date for returned conversations. This may be different from the start date of the conversation if the conversation was uploaded later.

updated_after
string
Example: updated_after=2015-05-05T12:14:00.0000Z

Return conversations that were created or modified after the given date. This is useful for writing applications that continuously poll for new conversations.

name
string

Match conversations by exact name.

status
string
Enum: "in-progress" "ended" "processing" "finished" "failed"

Only return conversations that are currently in a given state of processing with Gridspace Sift

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "is_approx_total": true,
  • "results": [
    ],
  • "next": "string",
  • "previous": "string",
  • "total": 0
}

Conversation Upload

Post Conversation Metadata and Events - One Conversation

Once an audio object has been created, the audio can be partitioned into one Conversation with this request. Provide the returned audio id from the media upload and a chronologically ordered list of call events, each with a timestamp.

Authorizations:
Request Body schema: application/json
audio_id
integer

ID of the audio file from media upload

name
string

Name of conversation set during initial conversation upload

processors
Array of strings
Items Enum: "transcribe" "redaction"

Array of processors used on the conversation

object

Call center agent information

permission_groups
Array of strings

Array of permission group names. Only those users in the correct permission groups with the correct values will be able to see the conversation.

call_events
Array of objects (CallEventMinimal)

Array of timestamped call events

media_start_time
string <date-time>

An ISO-8601 compatible string representing the exact date and time that the start of the recorded audio was captured

start_time
string <date-time>

ISO-8601 compliant datetime in UTC that the conversation started

metadata
object

Metadata object that will be associated with the conversation

end_time
string <date-time>

ISO-8601 compliant datetime in UTC that the conversation ended

Responses

Request samples

Content type
application/json
{
  • "audio_id": 0,
  • "name": "string",
  • "processors": [
    ],
  • "agent": {
    },
  • "permission_groups": [
    ],
  • "call_events": [
    ],
  • "media_start_time": "2018-03-20T02:52:32Z",
  • "start_time": "2019-08-24T14:15:22Z",
  • "metadata": { },
  • "end_time": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
{
  • "conversation_ids": [
    ]
}

Search for conversations

The search endpoint lets you perform searches on transcripts of conversations associated with your account. Parameters sent with the request will limit the conversations to satisfy the parameter constraint. If multiple parameters are used, then only conversations that satisfy ALL parameter constraints will be returned.

Authorizations:
query Parameters
query
string

Only conversations that contain the query will be returned.

conversation_ids
Array of strings

A list of ids of conversations to search in. If this parameter is not supplied, then we search through all conversations.

sort_by
string
Default: "start_time"
Enum: "start_time" "metadata.value"

Value to use to sort the conversation, only conversation start time and metadata values are supported

sort_order
string
Default: "desc"
Enum: "asc" "desc"

Order in which the sort_by value is sorted, only ascending and descending are supported

min_date
string <date>
Example:

Oldest date of conversations to return, must be in ISO-8601 compliant format

max_date
string <date>
Example:

Most recent date of conversations to reutrn, must be in ISO-8601 compliant format

updated_after
string
Example: updated_after=2015-05-05T12:14:00.0000Z

Return conversations that were created or modified after the given date. This is useful for writing applications that continuously poll for new conversations.

max_days_ago
integer

Maximum number of days from today of conversations to return

min_time
string <HH:MM:SS>
Example: min_time=13:21:00

Only return conversations that started after the minimum time of day specified here. Note that this filter applies to each day in the search result date range. So if you set min_date to October 5th and min_time to noon, conversations that started on October 6th at 9 am will not be included in the result set. This parameter is relative to the time zone specified in the timezone parameter.

max_time
string <HH:MM:SS>
Example: max_time=01:45:16

Only return conversations that started before the minimum time of day specified here. See the description of min_time above for more details.

min_duration
integer

Return conversations that have a duration greater than this value. Duration is calculated as the number of seconds between the end time and start time of the conversation.

max_duration
integer

Return conversations that have a duration less than this value. Duration is calculated as the number of seconds between the end time and start time of the conversation.

metadata.{value}
string

Return conversations with the matching metadata value in dot notation Replace {value} with the metadata field to match conversations on.

agent_ids
Array of strings

Array of Agent IDs to filter conversations

status
string
Enum: "in-progress" "ended" "processing" "finished" "failed"

Only return conversations that are currently in a given state of processing with Gridspace Sift

group
string

Only return conversations belonging to the group specified

is_evaluated
boolean

Only return conversations that are evaluated (true) or not evaluated (false)

missing_metadata_fields
Array of strings

Only return conversations where the metadata field specified in this array are unset

annotation_labels
Array of strings

Return conversations where a user has annotated a part of the transcript with the given label.

search_after
string

An opaque pagination token copied from a previous response to the search endpoint.

size
integer
Default: 50

The number of search results to return per page. Defaults to 50.

expand
Array of strings
Items Enum: "alert_matches" "evaluations"

Array of fields to expand the linked object in the response, currently only supports alerts and evaluations

timezone
string
Default: "UTC"
Example: timezone=America/Los_Angeles

This setting only applies to max_date and min_date. It is not frozen with this call, if you change time zones or share a search with folks in another time zone, the dates will appear correct to them.

include_quotes
any

If true, then each result in the list will include a "match_quote" field containing a snippet from the transcript containing the search term. This field is ignored if no "query" is provided.

Responses

Request samples

curl --request GET \
--url 'https://api.gridspace.com/v0/search?max_duration=200&query=hello&conversation_ids=0aacee4676de444f&conversation_ids=d31c88d6c6154cf2&metadata.ObserveItSessionId=20-04-53&is_evaluated=false&timezone=America%2FLos_Angeles&max_date=2018-10-27&min_date=2018-10-25' \
--user <<ACCOUNT ID>>:<<TOKEN>>

Response samples

Content type
application/json
{
  • "success": true,
  • "is_approx_total": true,
  • "results": [
    ],
  • "next": "string",
  • "previous": "string",
  • "total": 0
}

Conversation View

View Conversation Data

This operation retrieves the available data about the conversation. The information returned includes details about the conversation start and end times, audio files, duration, trending topics, and other associated metadata.

Authorizations:

Responses

Response samples

Content type
application/json
{
  • "conversation_id": "string",
  • "name": "string",
  • "start_time": "2019-08-24T14:15:22Z",
  • "end_time": "2019-08-24T14:15:22Z",
  • "mixed_audio": {
    },
  • "channels": [
    ],
  • "status": "in-progress",
  • "processors": [
    ],
  • "topics": [
    ],
  • "created": "2019-08-24T14:15:22Z",
  • "updated": "2019-08-24T14:15:22Z",
  • "domain": "string",
  • "permission_groups": [
    ],
  • "evaluations": [
    ],
  • "metadata": { },
  • "redaction_safe": true,
  • "agent": {
    },
  • "transcript": {
    },
  • "total_hold_ms": 0,
  • "duration_ms": 0
}

View Conversation Transcript

This operation retrieves the redacted (if available) utterances of a conversation with all words and their offsets and durations in ms.

Authorizations:

Responses

Response samples

Content type
application/json
{
  • "transcript": [
    ],
  • "type": "string"
}

Conversation Events

Post Conversation Metadata and Events - Up to many conversations

Once an audio object has been created, the audio can be partitioned into one or more Conversations with this request. Provide the returned audio id from the media upload and a chronologically ordered list of call events, each with a timestamp.

If a call event marks the beginning of a new Conversation, then a "conversation" attribute may be provided along with the call event. This allows the client to specify different metadata and permissions for different sections of a single recording. Sift will use the timestamp for the call event, and the recording's start time to find the right region of audio to copy to the Conversation.

Authorizations:
Request Body schema: application/json
audio_id
required
string

Audio ID from media upload response

media_start_time
required
string <date-time>

An ISO-8601 compatible string representing the exact date and time that the start of the recorded audio was captured

required
Array of objects (CallEvent)

Array of timestamped call events with or without Conversations

Note: The first call event MUST also include a conversation

Responses

Request samples

Content type
application/json
{
  • "audio_id": "7eb1cf517b8d4614",
  • "media_start_time": "2018-03-20T02:52:32Z",
  • "call_events": [
    ]
}

Response samples

Content type
application/json
{
  • "conversation_ids": [
    ]
}

Activity Log

Retrieve Activity Events

API endpoint for retrieving a system-wide list of user activity on the Gridspace Sift platform. The purpose of this API is to allow privileged users to audit all user behavior on the system.

All query parameters are optional and are treated as filters for the returned activity log.

Authorizations:
query Parameters
event_type
string
Enum: "sign_in" "sign_out" "view_conversation" "play_audio" "run_search" "search_conversation" "save_search" "export_search_results" "unredact_audio" "add_group_permissions" "set_group_permissions" "delete_group_permissions" "create_group" "update_group" "delete_group" "create_temporary_key" "delete_temporary_key" "delete_users" "regen_master_key" "add_annotation" "delete_annotation" "evaluate_conversation" "delete_evaluation"

Filters by one of these event types

  • sign_in -- started a new session by signing in through the SAML provider.
  • sign_out -- ended a session by manually signing out.
  • view_conversation -- viewed the page for a conversation, including transcript and metadata.
  • play_audio -- pressed the “play” button on the conversation audio page. Note: that the temporary streaming audio url is generated at the view_conversation step, so a malicious user could load the conversation page, retrieve the audio url, and play it directly in the browser without triggering this event. Therefore, the view_conversation events provide a more comprehensive list of times that a user potentially accessed conversation audio.
  • run_search -- performed a search query across all conversations.
  • search_conversation -- performed a search query within a single conversation.
  • save_search -- saved a search query.
  • export_search_results -- exported the results of a search query to a csv.
  • unredact_audio -- retrieved the unredacted audio URL
  • add_group_permissions -- added permissions to a group
  • set_group_permissions -- set permissions on a group
  • delete_group_permissions -- removed permissions from a group
  • create_group -- created a user group
  • update_group -- updated a user group
  • delete_group -- deleted a user group
  • create_temporary_key -- created a temporary key
  • delete_users -- deleted a user
  • regen_master_key -- regenerated the master account key
  • add_annotation -- added an annotation to a conversation
  • delete_annotation -- deleted an annotation from a conversation
  • evaluate_conversaton -- evaluated a conversation
  • delete_evaluation -- deleted an evaluation from a conversation
user
string

Filters by user id

timestamp_gt
string <date-time>

Only include results that occurred after the given timestamp. Timestamp is an ISO-8601 compliant string.

timestamp_lt
string <date-time>

Only include results that occurred before the given timestamp. Timestamp is an ISO-8601 compliant string.

expand
string

A comma-separated list of sub-objects to expand in the response. Currently, the only allowed value is "conversation", which will replace the "conversation_id" attribute in event objects with a "conversation" attribute containing the full JSON representation of the conversation. This can be used to access conversation metadata without having to query the api for each individual conversation.

temporary_key_id
string

Only include actions that were performed using the temporary key with the given ID.

Responses

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "next": "string"
}

Evaluation Templates

Update Evaluation Template

This endpoint allows the client to change the evaluation form that appears on the conversation details page. Clients can change the sections, questions, and choices that are presented in order to customize the form to their organization. Existing evaluations that have already started to be filled out will not be modified, but new evaluations will match the format provided.

path Parameters
name
string
Example: default

The name of the evaluation. Currently, only "default" is supported. However, future Sift releases will add the ability to define multiple Evaluation Templates for a single organization.

Request Body schema:
enable_auto_qa
boolean
Default: false

If true, automatically evaluate the conversation as soon as it ends, using the "auto_fill_query" attributes specified for each choice. If a question has no "auto_fill_query" choices, then that question is skipped.

Array of objects

Request samples

Content type
sections:
- title: "Greeting"
  key: "greeting"
  type: "select"
  questions:
  - key: "thank-caller"
    text: "Did the agent thank the caller for calling?"
    choices:
    - display_name: "Yes"
      value: "yes"
      max_points: 5
      points: 5
      auto_fill_query:
        metadata:
          CallType: ["CustomerSupport"]
        query: '~~"thank you for calling"'
    - display_name: "No"
      value: "no"
      max_points: 5
      points: 0
      auto_fail: true
    - display_name: "N/A"
      value: "na"
      max_points: 0
      points: 0
      subquestions:
      - key: "did-not-thank-reason"
        text: "Please check the reasons this does not apply"
        type: "multiselect"
        choices:
        - display_name: "Caller hung up"
          value: "hungup"
        - display_name: "Call was a transfer"
          value: "transfer"
        - display_name: "Agent forgot"
          value: "forgot"

Evaluation Exports

Export Evaluations in Bulk

API endpoint for exporting in bulk evaluations from the Gridspace Sift platform. The purpose of this API is to allow privileged users to get a JSON serialized version of the exports.

All query parameters are optional except for the start-date and are treated as filters for the returned evaluations.

query Parameters
agent
Array of strings <email>

Email of the desired agents. If passed, only evaluations for the given agent(s) will be returned, otherwise all will be returned. Can pass multiple.

evaluator
Array of strings <email>

Email of the desired evaluators. If passed, only evaluations completed by the given evaluator(s) will be returned, otherwise all will be returned. Can pass multiple.

timestamp_gt
required
string <date-time>

Only include results that occurred after the given timestamp. Timestamp is an ISO-8601 compliant string.

timestamp_lt
string <date-time>

Only include results that occurred before the given timestamp. Timestamp is an ISO-8601 compliant string.

Request samples

import requests
import datetime

ACCOUNT_ID = "460b7bd05df64926"
SECRET_KEY = "E25X65FZMFQUI3ZW5V6R37I4VNS1MDQS" # Found in Account page in Sift


payload = {
            "timestamp_gt": datetime.date(2019,01,01).isoformat(),
            "timestamp_lt": datetime.date(2019,01,10).isoformat(),
            "agent": ["higgins@gridspace.com", "trevi@gridspace.com"],
            "evaluator": ["matilda@gridspace.com"]
        }


resp = requests.get("https://api.gridspace.com/v0/evaluations_bulk_export", params=payload, auth=(ACCOUNT_ID, SECRET_KEY))
resp.raise_for_status()
print(resp.json())

List Users

listUsers

List users in the current Sift account

query Parameters
q
string

Search phrase to filter returned queries. The query applies to the user's first name, last name, and email address.

external_id
string

A customer-supplied user identifier. This ID is usually provided automatically when a user is created through a Single Sign-On provider. The string must match the user's external ID exactly.

sort_by
string
Enum: "first_name" "last_name"

If provided, sort the result list by the given field. If the string is prefixed with a minus sign (-) then results are returned in descending order.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get User

Get User by ID

Retrieve information about a single sift user by their user ID.

Responses

Response samples

Content type
application/json
{
  • "user_id": "69c37f0f555b42c1",
  • "display_name": "Sparky Higgins",
  • "initials": "SH",
  • "status": "active",
  • "role": "admin",
  • "first_name": "Sparky",
  • "last_name": "Higgins",
  • "external_id": "SHiggins",
  • "org_node": {
    }
}

Update User

updateUser

Authorizations:
Request Body schema: application/json
org_node
string

ID of the node in the org hierarchy where the user resides

role
string

The name of the role assigned to the user

first_name
string

The user's first name

last_name
string

The user's last name

Responses

Request samples

Content type
application/json
{
  • "org_node": "string",
  • "role": "string",
  • "first_name": "string",
  • "last_name": "string"
}

Batch Create Users

Create multiple new users in a single API request.

Create multiple new users in a single API request.

Request Body schema: application/json
send_activation_emails
bool
Default: false

If true, sends an email to each provided email address with a link to set the user's password.

make_admin
bool
Default: false

If true, all the created users will be given administrator privileges on the account.

groups
Array of strings

List of permission groups to associate with the user.

org_node
string

Default node in the org hierarchy where new users will be created. This can be overridden for individual users in the list.

role
string

Default role for new users. This can be overridden for individual users in the list.

Array of objects

List of users to create

Request samples

Content type
application/json
{
  • "send_activation_emails": false,
  • "make_admin": false,
  • "org_node": "632cb63a71244ac0",
  • "role": "agent",
  • "users": [
    ]
}

Create Org Node

Create a node in the org hierarchy

Create a new node at a particular tier in the organizational hierarcy. An org node represents a department within an organization that can contain many users. Each node has a "tier" which represents the level of the organization at which the node resides.

Authorizations:
path Parameters
plural_tier_name
required
string
Example: teams

The pluralized name of the heirarchy tier to which the nodes belong.

Request Body schema: application/json
name
string

Human-readable name for the node

parent
string

The node ID of the parent node in the hierarchy. If this node is at the highest tier, then this parameter may be omitted. Otherwise, this must be set to the ID of a node in the tier above this node.

external_id
string

Optional unique identifier for this node. This can be used to synchronize the id with external systems. Maximum length is 255 characters.

Request samples

Content type
application/json
{
  • "name": "Joe's Schmos",
  • "parent": "94df6a367bc34d7c"
}

Retrieve Org Node

Retrieve an org node by id

Authorizations:
path Parameters
id
string

The id of the org node

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "tier": "string",
  • "external_id": "string",
  • "href": "string",
  • "subordinate_count": 0,
  • "subordinate_counts_by_role": {
    },
  • "children": [
    ],
  • "child_count": 0,
  • "parent": {
    }
}

Retrieve an org node by external id

Authorizations:
path Parameters
external_id
string

The external id of the org node

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "tier": "string",
  • "external_id": "string",
  • "href": "string",
  • "subordinate_count": 0,
  • "subordinate_counts_by_role": {
    },
  • "children": [
    ],
  • "child_count": 0,
  • "parent": {
    }
}

Update Org Node

Update an org node by id

Authorizations:
path Parameters
id
string

The id of the org node

Request Body schema: application/json
name
string

The name of the node

external_id
string <= 255 characters

User-supplied alternate identifier for this node. This can be used to synchronize the id with external systems. Must be unique.

parent
string

ID of the parent node in the hierarchy. If provided, moves the node from its current position in the hierarchy to a child of the given node. The new parent must be the in the same tier as the previous parent. For example, if the hierarchy contains sites, teams, and subteams, you may not change the parent of a subteam to a site.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "external_id": "string",
  • "parent": "string"
}

Update an org node by external id

Authorizations:
path Parameters
external_id
string

The external id of the org node

Request Body schema: application/json
name
string

The name of the node

external_id
string <= 255 characters

User-supplied alternate identifier for this node. This can be used to synchronize the id with external systems. Must be unique.

parent
string

ID of the parent node in the hierarchy. If provided, moves the node from its current position in the hierarchy to a child of the given node. The new parent must be the in the same tier as the previous parent. For example, if the hierarchy contains sites, teams, and subteams, you may not change the parent of a subteam to a site.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "external_id": "string",
  • "parent": "string"
}

Delete Org Node

Deletes an org node by id

Authorizations:
path Parameters
id
string

The id of the org node

Responses

Deletes an org node by external id

Authorizations:
path Parameters
external_id
string

The external id of the org node

Responses

List Nodes in Org Tier

List nodes in an organizational tier

List departments in the organization hierarchy for a single tier. For instance, list all the teams in a company. Each User may be associated with a single node in the organization. When an agent has an org node, all of that agent's Conversations are associated with their position in the hierarchy at the time that they took the call.

path Parameters
plural_tier_name
required
string
Example: teams

The pluralized name of the heirarchy tier to which the nodes belong.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create Document Source

Create a new Document Source

A document source will contain a collection of documents that can be made searchable/unsearchable together

Authorizations:
Request Body schema: application/json
name
string

Name of the document source

type
any
Value: "api"

Type of the document source

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "type": "api"
}

List Document Sources

List Document Sources

Authorizations:

Responses

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "next": "string",
  • "previous": "string",
  • "count": 0
}

View Document Source

View Document Source

Authorizations:

Responses

Response samples

Content type
application/json
{
  • "name": "string",
  • "created": "2019-08-24T14:15:22Z",
  • "type": "api",
  • "status": "scraping",
  • "target_id": "string",
  • "last_index_time": "2019-08-24T14:15:22Z",
  • "last_update_time": "2019-08-24T14:15:22Z"
}

Delete Document Source

Delete Document Source

Authorizations:

Responses

Add Documents to Source

Add Documents to Source

Authorizations:
Request Body schema: application/json
Array ()
title
string

Title of document

url
string

URL of document. This uniquely identifies a document within an account. Note that uploaded or scraped documents with the same URL will replace each other in the document source.

metadata
object

Custom metadata object associated with the document

content
string

Document text. This may contain html markup.

Responses

Request samples

Content type
application/json
[
  • {
    }
]

List Documents in Source

List Documents in Source

Authorizations:

Responses

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "next": "string",
  • "previous": "string",
  • "count": 0
}

View Document in Source

View Document in Source

Authorizations:

Responses

Response samples

Content type
application/json
{
  • "title": "string",
  • "url": "string",
  • "metadata": { },
  • "created": "2019-08-24T14:15:22Z",
  • "content": "string"
}

Update Document in Source

Update Document in Source

Authorizations:
Request Body schema: application/json
title
string

Title of document

url
string

URL of document. This uniquely identifies a document within an account. Note that uploaded or scraped documents with the same URL will replace each other in the document source.

metadata
object

Custom metadata object associated with the document

content
string

Document text. This may contain html markup.

Responses

Request samples

Content type
application/json
{
  • "title": "string",
  • "url": "string",
  • "metadata": { },
  • "content": "string"
}

Delete Document from Source

Delete Document from Source

Authorizations:

Responses

Index Source Documents for Search

Indexes all documents in the document source and makes them available for search in the agent desktop. The latest version of each document (as identified by its url field) will be used. This will place the document source in the 'indexing' status. Indexing may take several minutes to complete. When finished, the status of the document source will transition to 'indexed'. If indexing fails for any reason, the status will change to 'failed'.

Authorizations:

Responses

Deindex Source Documents from Search

Deindexes all documents in the document source and makes them unavailable for search in the agent desktop. Note that the documents are not deleted, they will just not appear in searches.

Authorizations:

Responses