Caller ID validation |

Notes:

To download Gatekeeper proto files, click download Gatekeeper proto files.
Default values are determined by the gRPC specification. For more information, go to protocol buffers language guide .

calleridvalidation/ne/caller_id_validation_processor_service.proto

CallerIdValidationProcessor

This service allows validating caller IDs.

gRPC method definitions

gRPC method definitions
Method Name	Request Type	Response Type	Description
ValidateCallerId	ValidateCallerId Request	ValidateCallerId Response	Validates the caller ID.
ValidateCallerIdExt	ValidateCallerIdExt Request	ValidateCallerIdExt Response	Validates the externally processed caller id.

Methods with HTTP bindings

Notes:

REST API responses use the camel case naming convention, such as gkPersonId, but the REST API requests can either use the camel case or snake case naming convention, such as gk_person_id.
The following example displays root prefix and endpoint to build a complete URL, such as https://gatekeeper.api.nuance.com/v1/audios/upload-url:
- Root prefix for API: https://gatekeeper.api.nuance.com
- Endpoint: /v1/audios/upload-url
To know more about root prefixes for API that can be used for different geographies, go to Sites.

ValidateCallerId

POST /v1/calleridvalidation/ne/validation

Validates the caller ID.

For more information, see ValidateCallerId.

Endpoint

/v1/calleridvalidation/ne/validation

Request

{
    "context": {
        "gk_engagement_id": {
            "value": "3363b39e-697a-4edf-977a-7d76f483e7c6"
        },
        "gk_session_id": {
            "value": "7ad3221e-f4fe-4049-a839-4ce8a071670a"
        },
        "gk_scope_id": {
            "value": "3809e857-f8f6-418b-8954-2de39bd7b0f4"
        },
        "configset_id": "AutoSourceConfigset"
    },
    "reference_id": "b562d615-919a-4c4b-bbe0-3a0e81b7850e"
}

Response

{
    "status": {
        "statusCode": "OK",
        "statusSubCode": 0,
        "httpTransCode": 0,
        "fieldViolations": [],
        "statusDetails": [],
        "diagnosticDetails": []
    },
    "referenceId": "b562d615-919a-4c4b-bbe0-3a0e81b7850e",
    "result": {
        "processingResult": {
            "vendorId": "NE",
            "additionalData": {
                "NANPLine": "true",
                "TIDV": "01",
                "TTID": "REDACTED",
                "accountLinkability": "false",
                "bizIndicator": "false",
                "blacklist": "false",
                "callCountLast24Hour": "10",
                "callStartTimestamp": "2024-10-29 00:22:49.242",
                "calledNumber": "REDACTED",
                "callingNumberAni": "REDACTED",
                "carrierName": "AT&T Wireless",
                "coin": "false",
                "countryCode": "US",
                "excluded": "false",
                "geoCity": "Portland",
                "geoPostalCode": "97224",
                "geoState": "OR",
                "highlyProbableFalsified": "false",
                "invalidPhoneFormat": "false",
                "landline": "false",
                "mobile": "false",
                "noCarrier": "false",
                "pager": "false",
                "prepayLine": "U",
                "reassignedIndicator": "N",
                "referenceId": "b562d615-919a-4c4b-bbe0-3a0e81b7850e",
                "requestCreationTimestamp": "2024-10-29 00:22:49.453",
                "requestTimestamp": "2024-10-29 00:22:49.655",
                "responseTimestamp": "2024-10-29 00:22:54.688",
                "satellite": "false",
                "serviceProviderName": "AT&T Wireless",
                "smsCompatible": "false",
                "source": "REDACTED",
                "specialServices": "false",
                "telecomNetworkId": "REDACTED",
                "timeZone": "MST",
                "trustIndicator": "100",
                "version": "5.0",
                "vipNumber": "false",
                "virtualNumber": "false",
                "voip": "false",
                "watchlistIndicator": "false"
            },
            "trustIndicator": 100
        },
        "riskEngineResult": {
            "risk": 827,
            "reliability": 48
        },
        "decision": "DECISION_UNCERTAIN",
        "decisionReason": "DECISION_REASON_LOW_RELIABILITY"
    }
}

ValidateCallerIdExt

POST /v1/calleridvalidation/ne/validation-ext

calleridvalidation/caller_id_validation_service_service.proto

CallerIdValidationService

This service allows validating caller IDs before the agent answers the call.

gRPC method definitions

gRPC method definitions
Method Name	Request Type	Response Type	Description
ProcessPreAnswer	ProcessPreAnswer Request	ProcessPreAnswer Response	This method processes the caller ID once the call is initiated, before the agent answers the call. The system implicitly starts a new Engagement and a pre-call session after returning an API response. The reference_id sets to the engagement_id of the new engagement automatically.

Methods with HTTP bindings

Notes:

REST API responses use the camel case naming convention, such as gkPersonId, but the REST API requests can either use the camel case or snake case naming convention, such as gk_person_id.
The following example displays root prefix and endpoint to build a complete URL, such as https://gatekeeper.api.nuance.com/v1/audios/upload-url:
- Root prefix for API: https://gatekeeper.api.nuance.com
- Endpoint: /v1/audios/upload-url
To know more about root prefixes for API that can be used for different geographies, go to Sites.

ProcessPreAnswer

POST /v1/calleridvalidation/pre-answer

calleridvalidation/caller_id_risk_assessment_service.proto

CallerIdRiskAssessment

gRPC method definitions

gRPC method definitions
Method Name	Request Type	Response Type	Description
AssessCallerIdRisk	AssessCallerIdRisk Request	AssessCallerIdRisk Response	Assess the caller ID’s risk-level against all known caller ID rules within a watchlist. If no match is found for the given caller ID, then RISK_LEVEL is CALLER_ID_RISK_LEVEL_NO_RISK. If the caller ID matches with multiple caller ID rules that contains the caller ID regex, the preference is given to caller ID rule with RISK_LEVEL CALLER_ID_RISK_LEVEL_NO_RISK otherwise the rule with higher RISK_LEVEL is preferred. If the caller ID matches with the caller ID rules with exact phone number and multiple rules that contains caller ID regex preference is given to RISK_LEVEL of caller ID rule with phone number. Rules for caller ID risk assessments are cached and refreshed every 5 minutes.

Methods with HTTP bindings

Notes:

REST API responses use the camel case naming convention, such as gkPersonId, but the REST API requests can either use the camel case or snake case naming convention, such as gk_person_id.
The following example displays root prefix and endpoint to build a complete URL, such as https://gatekeeper.api.nuance.com/v1/audios/upload-url:
- Root prefix for API: https://gatekeeper.api.nuance.com
- Endpoint: /v1/audios/upload-url
To know more about root prefixes for API that can be used for different geographies, go to Sites.

AssessCallerIdRisk

PUT /v1/calleridwatchlists/{gk_callerid_watchlist_id.value}:assessrisk

Assess the caller ID's risk-level against all known caller ID rules within a watchlist.

If no match is found for the given caller ID, then [RISK_LEVEL](/help/api-reference/common-protos/#nuance.biosec.v1.CallerIdRiskLevel) is CALLER_ID_RISK_LEVEL_NO_RISK.
If the caller ID matches with multiple caller ID rules that contains the caller ID regex, the preference is given to caller ID rule with [RISK_LEVEL](/help/api-reference/common-protos/#nuance.biosec.v1.CallerIdRiskLevel) CALLER_ID_RISK_LEVEL_NO_RISK otherwise the rule with higher [RISK_LEVEL](/help/api-reference/common-protos/#nuance.biosec.v1.CallerIdRiskLevel) is preferred.
If the caller ID matches with the caller ID rules with exact phone number and multiple rules that contains caller ID regex preference is given to [RISK_LEVEL](/help/api-reference/common-protos/#nuance.biosec.v1.CallerIdRiskLevel) of caller ID rule with phone number.

Rules for caller ID risk assessments are cached and refreshed every 5 minutes.

For more information, see AssessCallerIdRisk.

Endpoint

/v1/calleridwatchlists/00000000-0000-0000-0000-000000000000:assessrisk

Request

{
    "context": {
        "gk_engagement_id": {
            "value": "3363b39e-697a-4edf-977a-7d76f483e7c6"
        },
        "gk_scope_id": {
            "value": "3809e857-f8f6-418b-8954-2de39bd7b0f4"
        },
        "gk_session_id": {
            "value": "7ad3221e-f4fe-4049-a839-4ce8a071670a"
        },
        "configset_id": "AutoSourceConfigset"
    },
    "gk_callerid_watchlist_id": {
        "value": "00000000-0000-0000-0000-000000000000"
    },
    "caller_id": "12345_75790"
}

Response

{
    "status": {
        "statusCode": "OK",
        "statusSubCode": 0,
        "httpTransCode": 0,
        "fieldViolations": [],
        "statusDetails": [],
        "diagnosticDetails": []
    },
    "result": {
        "referenceGkCalleridRuleId": {
            "value": "89e6dbe4-d834-41a0-b6d0-09c834035a56"
        },
        "riskLevel": "CALLER_ID_RISK_LEVEL_LOW",
        "riskEngineResult": {
            "risk": 714,
            "reliability": 14
        },
        "decision": "DECISION_UNCERTAIN",
        "decisionReason": "DECISION_REASON_LOW_RELIABILITY"
    }
}

calleridvalidation/ne/caller_id_validation_processor_messages.proto

CallerIdData

Input caller ID data. Included in ValidateCallerIdRequest.

CallerIdData
Field	Type	Description
reference_id	string	Optional. The reference ID of the caller ID processing result.
call_start_timestamp	google.protobuf.Timestamp	Mandatory. Date and time when the call started.
calling_number	string	Mandatory. The calling phone number. May contain numbers, spaces, dashes, the plus sign, or parenthesis. Included in the user of the ‘FROM’ header URI.
called_number	string	Mandatory. The called phone number. May contain numbers, spaces, dashes, the plus sign, or parenthesis. Included in the user of the ‘TO’ header URI.
telecom_network_id	string	Mandatory. The telecom network ID.
One of call_signaling_info:		Mandatory. The call signaling info.
sip_message	string	The SIP message in the RFC-3261 format. It must contain the raw SIP-INVITE message including headers and body.
gk_person_id	nuance.biosec.v1.UniqueId	Optional. The owner of the caller ID data. When set, the system refers to the caller ID data as personal information.

ProcessCallerIdResult

Contains caller ID processing results. Included in ValidateCallerIdResult.

ProcessCallerIdResult
Field	Type	Description
vendor_id	string	Mandatory. The ID of the vendor.
trust_indicator	google.protobuf.FloatValue	Mandatory. The raw trust indicator score.
additional_data	repeated ProcessCallerIdResult .AdditionalDataEntry	Mandatory. Additional processing result data.

ProcessCallerIdResult.AdditionalDataEntry

ProcessCallerIdResult.AdditionalDataEntry
Field	Type	Description
key	string
value	string

ValidateCallerIdExtRequest

Input message that defines parameters for ValidateCallerIdExt.

Uses the context field as follows:

gk_engagement_id: Mandatory
gk_session_id: Mandatory
gk_scope_id: Mandatory
configset_id: Optional

ValidateCallerIdExtRequest
Field	Type	Description
context	nuance.biosec.v1.Context	Mandatory. General request context.
version	string	Mandatory. The vendor API version used by the original query. The API returns the NOT_IMPLEMENTED status if version mismatch occurs.
raw_data	string	Mandatory. The raw result by the vendor.
gk_person_id	nuance.biosec.v1.UniqueId	Optional. The person with whom the caller ID result is associated with. When set, the system refers to the caller ID result as personal information.

ValidateCallerIdExtResponse

Output message that defines parameters returned by ValidateCallerIdExt.

ValidateCallerIdExtResponse
Field	Type	Description
status	nuance.rpc.Status	Mandatory. General operation status.
result	ValidateCallerIdExtResult	Mandatory. The caller ID validation result.

ValidateCallerIdExtResult

Contains the caller ID validation result. Included in ValidateCallerIdExtResponse.

ValidateCallerIdExtResult
Field	Type	Description
vendor_data	VendorData	Mandatory. The vendor specific data.
risk_engine_result	nuance.biosec.v1.RiskEngineResult	Mandatory. The level of risk and its reliability, computed by the risk engine.
decision	nuance.biosec.v1.Decision	Mandatory. The caller ID validation decision.
decision_reason	DecisionReason	Mandatory. The reason for the decision.

ValidateCallerIdRequest

Input message that defines parameters for ValidateCallerId.

Uses the context field as follows:

gk_engagement_id: Mandatory
gk_session_id: Mandatory
gk_scope_id: Mandatory
configset_id: Optional

ValidateCallerIdRequest
Field	Type	Description
context	nuance.biosec.v1.Context	Mandatory. General request context.
One of Data:		Mandatory. Specifies caller ID data.
reference_id	string	The reference ID of a previously set caller ID validation result.
caller_id_data	CallerIdData	The caller ID details.

ValidateCallerIdResponse

Output message that defines parameters returned by ValidateCallerId.

ValidateCallerIdResponse
Field	Type	Description
status	nuance.rpc.Status	Mandatory. General operation status.
reference_id	string	Mandatory. The reference ID of the caller ID validation result.
result	ValidateCallerIdResult	Mandatory. The caller ID validation result.

ValidateCallerIdResult

Contains the caller ID validation result. Included in ValidateCallerIdResponse.

ValidateCallerIdResult
Field	Type	Description
processing_result	ProcessCallerIdResult	Mandatory. The caller ID processing result.
risk_engine_result	nuance.biosec.v1.RiskEngineResult	Mandatory. The level of risk and its reliability, computed by the risk engine.
decision	nuance.biosec.v1.Decision	Mandatory. The caller ID validation decision.
decision_reason	DecisionReason	Mandatory. The reason for the decision.

VendorData

Contains the vendor specific data.

VendorData
Field	Type	Description
trust_indicator	google.protobuf.FloatValue	Mandatory. The raw trust indicator score.

calleridvalidation/caller_id_validation_service_messages.proto

CallerIdData

Input caller ID data. Included in ProcessPreAnswerRequest.

CallerIdData
Field	Type	Description
reference_id	string	Optional. Reference ID of the caller ID processing result.
call_start_timestamp	google.protobuf.Timestamp	Mandatory. Date and time when the call started.
calling_number	string	Mandatory. The calling phone number. May contain numbers, spaces, dashes, the plus sign, or parenthesis. Included in the user of the ‘FROM’ header URI.
called_number	string	Mandatory. The called phone number. May contain numbers, spaces, dashes, the plus sign, or parenthesis. Included in the user of the ‘TO’ header URI.
telecom_network_id	string	Mandatory. The telecom network ID.
One of call_signaling_info:		Mandatory. The call signaling info.
sip_message	string	The SIP message in the RFC-3261 format. It must contain the raw SIP-INVITE message including headers and body.

ProcessPreAnswerRequest

Input message that defines parameters for ProcessPreAnswer.

Uses the context field as follows:

gk_engagement_id: Optional
gk_session_id: Optional
gk_scope_id: Mandatory
configset_id: Optional

ProcessPreAnswerRequest
Field	Type	Description
context	nuance.biosec.v1.Context	Mandatory. General request context.
caller_id_data	CallerIdData	Mandatory. Caller ID details.
correlation_id	string	Optional. The engagement’s correlation ID provided by the client.

ProcessPreAnswerResponse

Output message that defines parameters returned by ProcessPreAnswer.

ProcessPreAnswerResponse
Field	Type	Description
status	nuance.rpc.Status	Mandatory. General operation status.
reference_id	string	Mandatory. Reference ID of the caller ID processing result.
result	ProcessPreAnswerResult	Mandatory. Caller ID processing result.
gk_engagement_id	nuance.biosec.v1.UniqueId	Mandatory. Unique ID of the newly created engagement.

ProcessPreAnswerResult

Contains caller ID processing results. Included in ProcessPreAnswerResponse.

ProcessPreAnswerResult
Field	Type	Description
result_attributes	repeated ProcessPreAnswerResult.ResultAttributesEntry	Mandatory. Caller ID processing result attributes. Contains a list of results for the configured caller ID vendor.

ProcessPreAnswerResult.ResultAttributesEntry

ProcessPreAnswerResult.ResultAttributesEntry
Field	Type	Description
key	string
value	string

calleridvalidation/caller_id_risk_assessment_messages.proto

AssessCallerIdRiskRequest

Input message that defines parameters for AssessCallerIdRisk.

Uses the context field as follows:

gk_engagement_id: Mandatory
gk_session_id: Mandatory
gk_scope_id: Mandatory
configset_id: Mandatory

AssessCallerIdRiskRequest
Field	Type	Description
context	nuance.biosec.v1.Context	Mandatory. General request context. Defines the scope in which the caller ID rule should be created.
gk_callerid_watchlist_id	nuance.biosec.v1.UniqueId	Mandatory. The ID of caller ID watchlist which contains the caller ID rules. For each scope there is a default caller ID watchlist with the ID “00000000-0000-0000-0000-000000000000” created at the time of the scope creation, empty by default.
caller_id	string	Mandatory. Telephone number to be evaluated against caller ID rules.
gk_person_id	nuance.biosec.v1.UniqueId	Optional, owner of the caller ID. When set, the system handles the caller ID as personal information.

AssessCallerIdRiskResponse

Output message that defines parameters returned by AssessCallerIdRisk.

AssessCallerIdRiskResponse
Field	Type	Description
status	nuance.rpc.Status	General operation status.
result	AssessCallerIdRiskResult	The caller ID risk assessment result.

AssessCallerIdRiskResult

Contains the caller ID risk assessment result. Included in AssessCallerIdRiskResponse.

AssessCallerIdRiskResult
Field	Type	Description
reference_gk_callerid_rule_id	nuance.biosec.v1.UniqueId	Optional. The caller ID rule matched for given caller ID. It is set only when the match is found.
risk_level	nuance.biosec.v1.CallerIdRiskLevel	Mandatory. The Risk level of the caller ID rule
risk_engine_result	nuance.biosec.v1.RiskEngineResult	Mandatory. The level of risk and its reliability, computed by the risk engine.
decision	nuance.biosec.v1.Decision	Mandatory. The caller ID risk evaluation decision.
decision_reason	DecisionReason	Mandatory. The reason for the decision.

calleridvalidation/ne/caller_id_validation_processor_enums.proto

DecisionReason

The reason for the decision

Name	Number	Description
DECISION_REASON_UNSPECIFIED	0	Decision reason is not specified.
DECISION_REASON_LOW_RELIABILITY	1	The system could not reach a reliable decision.
DECISION_REASON_NO_RISK_DETECTED	2	Risk is not detected.
DECISION_REASON_FRAUD_RISK	3	Fraud risk is detected.
DECISION_REASON_INTERNAL_ERROR	999	An error occurred while making the decision.