/search

Use /search to search transcript records with GET and POST requests, or to delete transcript records with DELETE requests.

Refine and filter /search requests with search term and output parameters.

Test GET and POST /search requests with get_search.py and post_search.py.

GET

Specify search terms as query parameters.

POST

Specify search terms as name-value pairs in JSON data sent with the request.

DELETE

Specify a transcript ID as a query parameter to queue its audio and JSON data for deletion.

Deletion entails the removal of the audio file, its transcript and transcription results, and the rest of its system record.

Summary charts and tables are not updated when an individual record is removed. Deleted record data is not available in the dashboard icon Dashboard Files View, and the record no longer appears in search results. A system under heavy load may take several minutes to fully delete a record, but this situation is unlikely.

Files to be deleted with /search must be filtered by company and organization, and may also be filtered by folder. Each file to be deleted must be specified individually by tId.

By default, the maximum number of audio files that can be deleted at once is 1000. This maximum can be changed by updating the simultaneous_tid_deletion_max system configuration option.

Synopsis

Search records

GET /search/$co_short/$org_short?token=$token&$options...
GET /search/$co_short/$org_short/$folder?token=$token&$options...
POST /search/$co_short/$org_short?token=$token&$options...
POST /search/$co_short/$org_short/$folder?token=$token&$options...

Delete individual records

DELETE /search/$co_short/$org_short?token=$token&terms.tid=$tId
DELETE /search/$co_short/$org_short?token=$token&tid=$tId
DELETE /search/$co_short/$org_short/$folder?token=$token&terms.tid=$tId
DELETE /search/$co_short/$org_short/$folder?token=$token&tid=$tId

Delete multiple records

DELETE /search/$co_short/$org_short?tid=$tId1,$tId2,...&token=$token&multi=true
DELETE /search/$co_short/$org_short/$folder?terms.tid=$tId1,$tId2,...&token=$token&multi=true
DELETE /search/$co_short/$org_short/$folder?terms.tid=$tId1,$tId2,...&token=$token&multi=true
DELETE /search/$co_short/$org_short/$folder?tid=$tId1,$tId2,...&token=$token&multi=true

Note: The parameters tid and terms.tid are equivalent.

$co_short: Company short name used to filter the request.
$org_short: Organization short name used to filter the request.
$folder: Folder used to filter the request.
$token: Authorization token with the required read or write permissions for the request.
$options: Optional parameters used to further refine the request and results.
$tId or $tId1,$tId2,...: UUID for the transcript(s) to be queried.
multi: Required to enable the deletion of multiple entities with a single request.

Content types

/search request content types depend on the request's method and parameters.


Method	Expects	Returns
DELETE	text/html query parameters	text/html
GET	application/json multipart/form	text/html JSON-format text/html CSV-format text/html application/zip
POST	application/json	text/html JSON-format text/html CSV-format text/html application/zip
`output=count`		text/html
`output=summary&type=json`		JSON-format text/html
`output=summary&type=csv`		CSV-format text/html
`output=details`		JSON-format text/html
`output=zip`		application/zip
Errors		text/html

Note: When CSV reports are generated with the API, columns are always sorted alphabetically. Prior to V‑Spark version 4.3.2, columns were sorted in the order specified for the fields parameter.

Example search requests

This example queries /search with GET. The request includes a duration search filter as a query parameter.

curl 'http://example.company.com:3000/search/Test/Test-Testing/Test01?token=$token&duration=4:30-5:30'

The next example queries /search with POST. The request includes a JSON-format daterange search filter.

curl -H 'Content-type: application/json' -d '{"daterange":"20190613-20190614"}' -X POST 'https://example.company.com:3000/search/Test/Test-Testing/CallCenterDemosTest01?token=$token'

Example DELETE requests

The following is an example cURL call using the /search endpoint's DELETE method to delete a single file:

curl -X DELETE 'http://example.com:3000/search/docs-co/docs-org?token=12345678&tid=999'

The preceding example deletes an audio file that is associated with the docs-co company and docs-org organization, using the token parameter 12345678 and a transcriptID of 999.

The following cURL example uses the /search endpoint's DELETE method to delete three files:

curl -X DELETE 'http://example.com:3000/search/docs-co/docs-org?token=12345678&tid=9991,9992,9993&multi=true'

The preceding example deletes three audio files associated with the docs-co company and docs-org organization, using the token parameter 12345678 and the transcriptIDs 9991, 9992, and 9993.

Example JSON

This example output shows the JSON results of a /search request. This output was generated with default summary output fields.

[
    {
        "filename": "file1json.wav",
        "agentid": "105",
        "datetime": "2017-07-18 17:07:12",
        "duration": "0:05:25",
        "score": "1.0000",
        "tid": 5,
        "requestid": "11723359-d790-4a88-aff8-7925296e7df2",
        "agent_gender": "Female",
        "client_gender": "Male",
        "overall_emotion": "Improving",
        "client_emotion": "Negative",
        "agent_emotion": "Positive",
        "overtalk": "0.0000",
        "silence": "0.4269",
        "agent_clarity": "0.0000",
        "client_clarity": "0.8298",
        "diarization": "2.0000",
        "preview": {}
    },...
]