The VGSx API

This section defines the API endpoints for the VGSx service.

The xDeTECH Gateway can be used to trigger xDeTECH operations in a Streaming Audio context (SIPREC or Audiohook)

The xDeTECH Gateway exposes a set of REST calls which will interact on a callID
The primary operations for the xDeTECH Gateway are:
- Ping xDeTECH Gateway
- List Current Phone Calls
- Start Analysis of a Phone Call
- Get Analysis Status of a Phone Call
- Stop Analysis of a Phone Call

Error Handling

Errors from the xDeTECH Gateway will be returned as a simple JSON record in the format:

JSON
    
 
{ "code": an integer "message": a message}
Copy

HTTP Status codes representing errors will either be in the 400-499 range or 500 where 500 represents an expected error occurring in the Gateway which is preventing execution of the request.

Likely error codes and their meanings are listed in each API description below.

Ping

This call can be used to ensure the xDeTECH Gateway is running and accessible.

Request

Response

JSON
    
 
{  "system": "SentinelVgsx",  "id": "1",  "systemTime": "2025-09-30T10:39:57.211+0000",  "sentinelVersion": "2.0.0.0",  "receivedInitFromSIPRECStack": false,  "analysisServiceAvailable": true,  "acceptsNewActionCommands": false}
Copy

Health Actuator

This call can be used to ensure the xDeTECH Gateway is running and accessible.

Request

Response

JSON
    
 
{   "status":"UP",   "components":{      "diskSpace":{         "status":"UP",         "details":{            "total":1081101176832,            "free":1021563572224,            "threshold":10485760,            "path":"/sentinel-vgsx/bin/.",            "exists":true         }      },      "livenessState":{         "status":"UP"      },      "ping":{         "status":"UP"      },      "readinessState":{         "status":"UP"      }   },   "groups":[      "liveness",      "readiness"   ]}
Copy

Response Errors

HTTP Status 400

Code	Description
1	An unexpected error occurred
5	The xDeTECH voice clone detection service is not available.

A set of APIs are available to list calls in various states from the xDeTECH Gateway. The API to list current calls is used as an example. A list of alternative APIs for listing calls in different states is provided below.

Refer to the Get Call Status API below for a description of the response fields.

Request

Response

JSON
    
​x
 
[  {   "nativeCallId" : "c51ca7f4-d693-4027-b594-449e1215c7f2",  "callId" : "c51ca7f4-d693-4027-b594-449e1215c7f2",  "agentPhoneNumber" : "3125550001",  "phoneNumber" : "3125551234",  "createdDtm" : 1758196325767,  "lastUpdatedDtm" : 1758196325767,  "endedDtm" : 1758196353258,  "callStatus" : "ENDED",  "callAuthentication" : {    "callAuthEnabled" : "false"  },  "actions" : {    "analysis" : {      "action" : "ANALYSIS",      "analysisStatus" : "NO_ANOMALY_DETECTED",      "isReplay" : false,      "replayConfidenceR1" : 0.9861,      "replayConfidenceR2" : 0.5105,      "isClone" : false,      "cloneConfidences" : {        "v1" : 0.9997,        "v2" : 0.9673,        "v3" : 1.0,        "v4" : 0.9942      },      "confidenceIndicator" : "HIGH",      "millisOfSpeechReceived" : 23064,      "audioSampleLimit" : 500,      "audioSampleCount" : 0,      "audioSampleSizeMB" : 0,      "speechSampleCount" : 0,      "speechSampleSizeMB" : 0    }  },  "active" : false,  "current" : false,  "callDuration" : 27491,  "audioFileName" : "Research_Genuine.wav"​  }]
Copy

Response Errors

HTTP Status 400

Code	Description
1	An unexpected error occurred

List Call Variants

The table below lists all the API variants which list calls in various states. All calls are of the form

where the optional suffix indicates which calls to return.

Code	Description
None	List all calls known to the gateway.
active	List calls being analyzed.
current	List calls which are being analyzed or are able to be analyzed.
ended	List calls which have ended.
error	List calls for which an error occurred.
pending	List calls which are in progress but have not be analysed yet.
stopped	List calls for which analysis has stopped but the call is ongoing.

Start Analysis on a Call

Causes xDeTECH to start analyzing the audio stream of a particular call.

Refer to the Get Call Status API below for a description of the response fields.

Request

JSON
    
 
POST https://{{host}}:{{port}}/tenants/{{tenant}}/calls/{{callid}}/actionAnalysis​{  "action": "ANALYSIS”}
Copy

Response

JSON
    
 
{  "nativeCallId": "{callId}",  "callId": "{callId}",  "agentPhoneNumber": "3125550001",  "phoneNumber": "3125551234",  "createdDtm": "2023-09-07T12:53:48.220+0000",  "lastUpdatedDtm": "2023-09-07T12:53:48.220+0000",  "callStatus": "PROCESSING",  "callAuthentication": {    "callAuthEnabled": false  },  "actions": {    "analysis": {      "action": "ANALYSIS",      "analysisStatus": "PENDING"    }  },  "active": true,  "current": true,  "callDuration": 5386}
Copy

Response Errors

HTTP Status 400

Code	Description
1	An unexpected error occurred
11	The call ID was not specified.
13	The call action (ANALYSIS) was not specified.
15	The call has ended so no further processing is possible.
30	The specified call action is invalid.

HTTP Status 404

Code	Description
10	A call with the specified call ID is not registered with the xDeTECH Gateway.

HTTP Status 503

The HTTP status for this error is configurable via the sentinel.action.processor.http.response.on.stopped property.

Whether this error is generated is configurable via the sentinel.action.processor.http.error.on.stopped property.

See VGSx-Properties for details.

Code	Description
4	The server is no longer available to action calls because it has been instructed to stop processing calls using the /gatewayNode/actionStatus API

Call Errors

Errors which occur during call streaming will not be returned in the API call, they will result in the call information containing a callStatus of ERROR. See Get Call Status below for more details.

Get Call Status

Gets the current status of a call, indicating the current call status and analysis status.

See below for a description of the response fields.

Request

JSON
    
 
GET https://{{host}}:{{port}}/tenants/{{tenant}}/calls/{{callid}}
Copy

Response

JSON
    
 
{  "nativeCallId" : "c51ca7f4-d693-4027-b594-449e1215c7f2",  "callId" : "c51ca7f4-d693-4027-b594-449e1215c7f2",  "agentPhoneNumber" : "3125550001",  "phoneNumber" : "3125551234",  "createdDtm" : 1758196325767,  "lastUpdatedDtm" : 1758196325767,  "endedDtm" : 1758196353258,  "callStatus" : "ENDED",  "callAuthentication" : {    "callAuthEnabled" : "false"  },  "actions" : {    "analysis" : {      "action" : "ANALYSIS",      "analysisStatus" : "NO_ANOMALY_DETECTED",      "isReplay" : false,      "replayConfidenceR1" : 0.9861,      "replayConfidenceR2" : 0.5105,      "isClone" : false,      "cloneConfidences" : {        "v1" : 0.9997,        "v2" : 0.9673,        "v3" : 1.0,        "v4" : 0.9942      },      "confidenceIndicator" : "HIGH",      "millisOfSpeechReceived" : 23064,      "audioSampleLimit" : 500,      "audioSampleCount" : 0,      "audioSampleSizeMB" : 0,      "speechSampleCount" : 0,      "speechSampleSizeMB" : 0    }  },  "active" : false,  "current" : false,  "callDuration" : 27491,  "audioFileName" : "Research_Genuine.wav"}
Copy

Response Field Descriptions

{% image url="https://uploads.developerhub.io/prod/ZGzN/c9dai89s8p41m70ib1mwiwy8vmsupkzn822kdsw13ybrs0szlnv6i93n3kbdgky1.png" mode="responsive" height="705" width="1292" %} {% /image %}

callId is a unique ID which identifies the call in the Start Analysis and Get Analysis Status APIs.
callStatus indicates the status of the call. Possible values are:
- PENDING: the call has been received but no processing has been requested on the call.
- PROCESSING: the call is currently being analyzed.
- STOPPED: processing on the call has completed but the call has not ended. The call can re-enter a processing state if a new analysis request is received.
- ENDING: the call with the user has ended but VGSx still has data which can be sent to the VCDx for analysis.
- ENDED: the call has ended and all the data has been analysed.
- ERROR: an error has occurred while attempting to process the call.
active indicates whether an analysis action is in progress on the call
current indicates whether the call has ended
analysisStatus indicates the overall processing status of the call. If WHOLE_CALL mode is enabled, this will be the overall results for the averaging of all samples. For LAST_N_SAMPLES mode, this will be the overall results for the averaging of the last N samples. Possible values are:
- PENDING: VGSx has not started processing audio. Not enough audio has been obtained by VGSx to send to VCDx.
  - NOTE: VGSx only considers audio with noise above a certain level as suitable for sending to VCDx. The noise threshold can be configured as shown in the VGS configuration section above.
- NOT_PROCESSED: VGSx has started processing audio but no valid speech has been found yet or not enough samples have been received by VCDx to provide an overall result.
- NO_ANOMALY_DETECTED: VGSx has started processing audio and valid speech has been found but the average score of the entire call (WHOLE_CALL mode) or last N samples (LAST_N_SAMPLES mode) is less than the threshold to identify the call as an attack. Call processing can continue on additional segments.
- ANOMALY_DETECTED: VGSx has started processing audio and the average score of the whole call or last N samples is higher than the threshold to mark the call as an attack. When the call state reaches ANOMALY_DETECTED VGSx stops processing audio for that call (sets the callStatus to STOPPED) and the state will remain ANOMALY_DETECTED unless stopAnalysis and startAnalysis are called again.
  - Note: To reduce the impact on multiple segments diluting anomaly results, use LAST_N_SAMPLES mode and set a low number of segments (2).
  - Note: Calling stopAnalysis and startAnalysis with the same callId will result in processing resuming for the same call and segments from the previous analysis will be included in score averaging.
- COMPLETE: The maximum number of attempts to call VGSx has been made and processing is complete without finding an anomaly. By default there is no maximum number of attempts and processing will continue until the call ends. The maximum number of attempts can be configured as shown in the VGS configuration section above.
- ERROR: An unexpected error occurred during call processing and audio processing was aborted.
millisOfSpeechReceived : The length of speech received in milliseconds.
isReplay: Determines whether VCDx has flagged the audio sample (segment) as a replay attack.
- Note: A replay result for a single segment may not result in the analysisStatus being set to ANOMALY_DETECTED. To reduce the impact on multiple segments diluting anomaly results, use LAST_N_SAMPLES mode and set a low number of segments (2).
replayConfidenceR1: Score value obtained from the replay detection model that detects low quality pattern devices, value can be from 0 to 1. The lower the score the more likely the file is a spoof.
replayConfidenceR2: Score value obtained from the replay detection model that detects high quality pattern devices, value can be from 0 to 1. The lower the score the more likely the file is a spoof.
isClone: Determines whether VCDx has flagged this segment as a voice cloning attack
- Note: A replay result for a single segment may not result in the analysisStatus being set to ANOMALY_DETECTED. To reduce the impact on multiple segments diluting anomaly results, use LAST_N_SAMPLES mode and set a low number of segments (2).
cloneConfidences: Clone attack confidences for each clone-detection algorithm between 0 and 1 where 1 is the highest confidence.
confidenceIndicator: an overall confidence indicator based on the BPCER of the lowest confidence score. The confidence is either:
- HIGH if an anomaly is detected or there is a high confidence of no anomaly.
- MEDIUM if there is a medium confidence of no anomaly.
callDuration is the duration of the call in milliseconds.

Response Errors

HTTP Status 400

Code	Description
1	An unexpected error occurred

HTTP Status 404

Code	Description
10	A call with the specified call ID is not registered with the xDeTECH Gateway.

Call Errors

This section lists the cases in which a call error is generated.

Error Description:

Streaming cannot be started because a streaming URL associated with this host is not configured. See https://daon.atlassian.net/wiki/spaces/SKY/pages/edit-v2/3616473145#Orkaudio-Server-Locations for details.
The audio stream could not be started on the provided URL. It may already be terminated.
An exception occurred while processing the audio stream.
An unexpected exception occurred while processing a speech segment for dispatch to the xDeTECH Voice Clone Analysis service.
The xDeTECH Voice Clone Analysis service returned an unexpected error.

Stop Analysis of a Call

Causes xDeTECH to stop analyzing the audio stream of a particular call. This will stop speech segments from being sent to the VCDx for analysis but will not end the call. Once analysis has been stopped, it may be re-started by calling the API above.

Refer to the Get-Call-Status API for a description of the response fields.

Request

Response

JSON
    
 
{  "nativeCallId" : "c51ca7f4-d693-4027-b594-449e1215c7f2",  "callId" : "c51ca7f4-d693-4027-b594-449e1215c7f2",  "agentPhoneNumber" : "3125550001",  "phoneNumber" : "3125551234",  "createdDtm" : 1758196325767,  "lastUpdatedDtm" : 1758196325767,  "endedDtm" : 1758196353258,  "callStatus" : "STOPPED",  "callAuthentication" : {    "callAuthEnabled" : "false"  },  "actions" : {    "analysis" : {      "action" : "ANALYSIS",      "analysisStatus" : "NO_ANOMALY_DETECTED",      "isReplay" : false,      "replayConfidenceR1" : 0.9861,      "replayConfidenceR2" : 0.5105,      "isClone" : false,      "cloneConfidences" : {        "v1" : 0.9997,        "v2" : 0.9673,        "v3" : 1.0,        "v4" : 0.9942      },      "confidenceIndicator" : "HIGH",      "millisOfSpeechReceived" : 23064,      "audioSampleLimit" : 500,      "audioSampleCount" : 0,      "audioSampleSizeMB" : 0,      "speechSampleCount" : 0,      "speechSampleSizeMB" : 0    }  },  "active" : false,  "current" : false,  "callDuration" : 27491,  "audioFileName" : "Research_Genuine.wav"}
Copy

Response Errors

HTTP Status 400

Code	Description
1	An unexpected error occurred
14	The specified call is not being processed.
15	The call has ended so no further processing is possible.

HTTP Status 404

Code	Description
10	A call with the specified call ID is not registered with the xDeTECH Gateway.

Last updated on