V-Spark Online Help

/metadata API Reference

The /metadata endpoint adds, updates, or deletes metadata values associated with a transcript. /metadata supports the PATCH and DELETE HTTP methods.

Synopsis

PATCH /metadata/CO_SHORT/ORG_SHORT/transcriptID?token=TOKEN --data @FIELDS.json
DELETE /metadata/CO_SHORT/ORG_SHORT/transcriptID?token=TOKEN --data @FIELDS.json

The preceding example shows the required components of a /metadata request path and uses the following variables:

CO_SHORT

The short name of the company with which the transcript is associated.

ORG_SHORT

The short name of the organization with which the transcript is associated. Note that a folder is not required because transcriptIDs are unique to organizations.

transcriptID

Unique identifier for the transcript to be updated.

TOKEN

An authorization token with write permissions for the transcript's organization.

FIELDS.json

JSON-formatted data that specifies the metadata to be changed. The required JSON data varies by HTTP method. PATCH requests must include a JSON-formatted object literal of metadata key-value pairs. DELETE requests must include a JSON-formatted array of metadata field names. This JSON data may be submitted in the body of the request or with a file. Due to the JSON's potential complexity, using a file is recommended.

Description

Requests to /metadata add, modify, or delete transcript metadata. The PATCH method adds or modifies metadata values, and the DELETE method removes metadata.

V‑Spark writes metadata changes to three places: the database, Elasticsearch, and long-term storage. Metadata is saved to the database and to Elasticsearch only if that metadata field has been configured for the transcript's folder; however, any request to /metadata updates the last_modified field associated with the request's transcriptID.

Requests to /metadata do not change a folder's metadata field configuration. As a result, to add new custom metadata key-value pairs that are indexed and searchable, the new metadata fields must be added to the transcript's folder configuration before the request is made. Values for fields specified in the request but not configured for the folder will not be stored in the database or in Elasticsearch. When metadata fields and values for non-configured fields are submitted using /metadata, those fields and values are not fully lost; they are passed through and saved in the JSON transcript in long-term storage only.

Note that changing a transcript's metadata with /metadata does not trigger transcript-application reprocessing. Note also that a request that includes metadata field names in the reserved list will be rejected. For more information about the metadata field name reserved list and other requirements, refer to Metadata Restrictions. Making multiple /metadata requests for the same transcriptID at the exact same time may result in an error with HTTP code 400 and an "Error uploading metadata" message. The solution in this case is to retry the request.

Content Types

  • PATCH requests must include a JSON-formatted object literal of key-value pairs with the "application/json" MIME type.

  • DELETE requests must include a JSON-formatted array of metadata field names with the "application/json" MIME type.

  • PATCH and DELETE requests return success messages with HTTP code 200 and the full updated metadata result for the transcript with the "application/json" MIME type.

  • PATCH and DELETE requests return error messages with HTTP code 400 with the "text/html" MIME type.

Example /metadata Requests

The following example PATCH /metadata request specifies a transcriptID of 3 associated with the company Co-Short and the organization Org-Short. The request includes a JSON-formatted object literal with one key-value pair corresponding to metadata to be added or modified. 

curl -H 'Content-type: application/json' -d '{"agentgroup":"2"}' -X PATCH 'http://example.com:3000/metadata/Co-Short/Org-Short/3?token=123'

The following example PATCH /metadata request is similar to the preceding example, but specifies a file named fields.json for the request's JSON data.

curl -H 'Content-type: application/json' -d @fields.json -X PATCH 'http://example.com:3000/metadata/Co-Short/Org-Short/3?token=123'

The following example DELETE /metadata request specifies a transcriptID of 6 associated with the company Co-Short and the organization Org-Short. The request includes a JSON-formatted array with one field name, transfers, to be deleted from the transcript.

curl -H 'Content-type: application/json' -d '["transfers"]' -X DELETE 'http://example.com:3000/metadata/Co-Short/Org-Short/6?token=123'

Upon success, the preceding examples return JSON data containing the full updated metadata for the specified transcript.

Example /metadata JSON input

The following example of a JSON object literal shows the format required for PATCH requests:

{
    "direction":"inbound",
    "hold time":"78",
    "transfers":"3"
}

On a successful PATCH request, the keys and values for the direction, hold time, and transfers fields are added to a transcriptID associated with a folder that has these fields configured. If those metadata fields are already associated with that transcriptID, the values for those fields are updated.

The following example of a JSON array shows the format required for DELETE requests:

[
    "clientname",
    "agentname",
    "employeegroup"
]

On a successful DELETE request, the preceding example removes metadata fields and values for the clientname, agentname, and employeegroup elements from the database, Elasticsearch, and long-term storage for the specified transcriptID.

In this section: