Overview
Neustar’s Certified Caller Id (CCID) Verification Service (VS) implements the emerging industry standard of IETF RFC8224 specification, as well as ATIS SHAKEN extension, for verifying SIP Identity headers to assist with SIP call setup. Additionally, it provides Ownership Validation, Subscriber-based Policy (SDPR) processing, CNAM, Enhanced CNAM (ECNAM) and/or Robocall Call Insight (RM) services, and Call Validation Treatment (CVT) service for originating telephone numbers.
In the following sections, the cURL utility is used as an exemplar REST API client to issue API requests. The API consumers will likely leverage the programming language of their choice to issue API requests.
API Customer Profile
An API consumer must be provisioned in the CCID VS with the following data elements:
-
A numeric customer id, uniquely assigned by Neustar.
-
The name of the customer.
-
The permission for performing CNAM or ECNAM queries
-
The permission for performing Robocall Call Insight data queries
-
The permission for obtaining policies from SDPR
-
The permission for obtaining CNAM/ECNAM/Robocall data via CVT
-
The API key supplied or generated, or client CIDR value provisioned, for for accessing the CCID VS.
-
The default SIP Identity header verification requirement.
-
The default list of originator country codes, for converting non-global telephone numbers into e.164 format.
-
The default destination country code, for converting non-global telephone numbers into e.164 format.
-
The certificate cache expiration time, or if the caching should be disabled.
-
The time-to-live time of trust stores loaded in the memory.
-
The options to check X.509 Certificate trust chain and revocation status at the time of certificate retrieval.
-
The options to check X.509 Certificate "TN Authorization List" (TNAuthList) and "Subject Alternative Names" (SAN) extensions with SIP call originators (TN or SIP URL host) at the time of SIP Identity header verification.
-
The options to associate IP CIDR blocks and port ranges with API keys for processing requests from SIP proxies, along with optional next hop for message routing, policy data for SIP header manipulation and error condition processing, as well as CNAM/ECNAM/Robocall/CVT options and CNAM prefixes for verified and unverified calls.
-
Optional "Asset" objects for selecting various parameters used for verifying SIP Identity headers, based on ingress and/or egress routes, etc.
High-Level Processing Flow
The following diagram depicts the high-level processing flow of CCID VS business logic in verifying SIP Identity headers, for both REST and SIP interfaces.
Sequence Diagram
The following sequence diagram demonstrates all potential components or micro-services involved in processing a SIP Identity verification request. Actor Client can be a REST API client or a SIP Proxy interfacing with a network element via SIP protocol.
Currently, if CVT service is invoked, SDPR, SCP and DAS services will not be invoked for CVT processing. Additionally, SCP and DAS services will be invoked concurrently if both of them are required for CVT processing. |
Post-Processing Flow
The post-processing flow of CCID VS business logic in handling SDPR/CNAM/ECNAM/RM data for originating telephone numbers after SIP Identity header verification depends on the requirement of invoking CVT microservice.
The following condition must be met for invoking CVT microservice for CNAM/ECNAM/RM data processing:
-
The associated Customer has CVT service enabled, and
-
The verification request in JSON format has the cvt value as true, or
-
The verification request in TEXT format has the cvt query parameter as true, or
-
The associated Interface for a SIP Proxy request has the cvt option set as true
Without CVT
The following diagram depicts the high-level processing flow of CCID VS business logic in handling SDPR/CNAM/ECNAM/RM data for originating telephone numbers after SIP Identity header verification is performed, when CVT microservice is not required:
With CVT
The following diagram depicts the high-level processing flow of CCID VS business logic in handling CVT data for originating telephone numbers after SIP Identity header verification is performed, when CVT microservice is enabled for a specific customer:
Certificate Cache Processing
The certificate cache maintained for a customer profile, if enabled, is controlled by the following three time-to-live (TTL) parameters:
-
The certificate cache TTL for validated certificates
-
The cache TTL extension for expired certificates or certificate cache entry
-
The negative cache TTL for invalid certificates or certificates failed to be fetched
The following diagram depicts the high-level processing flow of resolving a certificate based on the info URL parameter embedded in a SIP Identity header:
REST API Server
Currently, the base URL of the CCID VS REST API server is:
http://ca-verify.neustarlab.biz/ccid/verify/v2
or
https://ca-verify.neustarlab.biz/ccid/verify/v2
if HTTPs is required.
REST API Authentication
Currently, a REST API client is required to provide an apiKey
query
parameter with a pre-provisioned value to access API calls that are
restricted. If the apiKey
parameter is not specified, the client
IP address may be used as the backup authentication mechanism if the
client CIDR block is pre-provisioned.
REST API Entry Points
The CCID VS provides four categories of API entry points:
-
Verifies SIP Identity headers
Four different API entry points are defined for SIP Identity header verification:-
Accepts requests in JSON format and produces responses in JSON format
-
Accepts SIP INVITE messages and produces responses in JSON format
-
Accepts SIP INVITE messages and produces responses in SIP format
-
Accepts SIP INVITE messages and produces responses in JSON format for SIP proxies
-
-
Performs CNAM queries
Two different API entry points are defined to return the CNAM data for a specific telephone number:-
Accepts a GET request with telephone number as a URL path parameter
-
Accepts a POST request in JSON format with the "from" attribute
-
-
Performs ECNAM queries
Two different API entry points are defined to return the ECNAM data for a specific telephone number:-
Accepts a GET request with telephone number as a URL path parameter
-
Accepts a POST request in JSON format with the "from" attribute
-
-
Gets a list of all potential errors generated
This API entry point is to return a list of all potential errors that could be generated by the CCID VS for SIP Identity header verification.
Verifies SIP Identity Headers
The CCID VS uses the following data elements in SIP INVITE messages for SIP Identity header verification, in addition to the required "apiKey" URL parameter for uniquely identifying an API client:
SIP Header/SDP Attribute | JSON Attribute Name | Description |
---|---|---|
SIP From header |
from |
Required |
SIP To header |
to |
Required |
SIP Identity headers |
identity |
Required |
SIP Date header |
date |
Optional |
SIP P-Asserted-Identity headers |
pai |
Optional |
SIP P-Attestation-Indicator header |
attest |
Optional |
SIP P-Origination-Id header |
origid |
Optional |
SIP Diversion headers |
diversion |
Optional |
SIP Resource-Priority headers |
resource_priority |
Optional |
SIP Priority header |
priority |
Optional |
SIP Call-Info header |
call_info |
Optional |
SIP Request-URI |
ruri |
Optional |
SDP a=fingerprint attributes |
finger_print |
Optional |
Currently, the ruri JSON attribute is only for internal usage in processing
API calls for SIP proxies in verifying SIP Identity headers for Diverted calls.
|
Additionally, an API client may provide additional parameters, either specified in a request message in JSON format, or as API URL parameters if a SIP INVITE message is provided as the input. Those parameters are:
JSON Attribute Name | URL Parameter Name | Description |
---|---|---|
status |
status |
Optional verification status requirement |
orig_cc |
origcc |
Optional list of originator country codes. If specified as a URL parameter, it must be contain country codes separated by ',' or white spaces. |
dest_cc |
destcc |
Optional destination country code |
cnam |
cnam |
Optional boolean flag indicating if CNAM query is to be performed |
ecnam |
ecnam |
Optional boolean flag indicating if ECNAM query is to be performed |
robocall |
robocall |
Optional boolean flag indicating if Robocall Call Insight data is returned |
cvt |
cvt |
Optional boolean flag to invoke CVT service for CNAM/ECNAM/Robocall data |
verstat |
N/A |
Optional boolean flag indicating if a verstat value is returned after SIP Identity headers are verified |
identity_info |
N/A |
Optional boolean flag indicating if information about decoded SIP Identity headers to be returned after SIP Identity headers are verified |
request_id |
N/A |
Optional client-supplied request identifier that will be included in the response for tracking purpose |
Currently, URL parameters for verstat , identity_info and request_id JSON attributes are not supported.
|
Furthermore, the following optional parameters are specific to Rich Call Data (RCD) PASSporT extension, and to SHAKEN PASSporT extension if RCD data fields are enabled.
JSON Attribute Name | URL Parameter Name | Description |
---|---|---|
caller_reason |
N/A |
Optional "crn" value specified by RCD PASSporT extension |
caller_name |
N/A |
Optional "nam" value specified by RCD PASSporT extension |
caller_logo_uri |
N/A |
Optional "icn" value specified by RCD PASSporT extension |
alt_present_number |
N/A |
Optional "apn" value specified by RCD PASSporT extension |
jcard |
N/A |
Optional JSON string for "jcd" value specified by RCD PASSporT extension |
jcard_uri |
N/A |
Optional "jcl" value specified by RCD PASSporT extension |
rcd_issuer |
N/A |
Optional "iss" value specified by RCD PASSporT extension |
rcd_integrity |
N/A |
Optional boolean flag for validating "rcdi" value |
call_info |
N/A |
Optional "Call-Info" header values for extracting "crn", "icn", "jcard_uri" values |
Currently, alt_present_number and rcd_issuer parameters are used in verifying the apn and iss claims in a RCD PASSporT extension or a SHAKEN PASSporT extension with RCD data fields. This subjects to change in the future. |
Finally, the following URL parameters can be specified with SIP INVITE message inputs for producing responses in SIP format.
URL Parameter Name | Description |
---|---|
cnamPrefix |
Optional prefix applied to to CNAM data field, indicating if SIP Identity header verification is successful or failed. If specified, the value must contain one token or two tokens separated by ',' or white spaces |
The following is an example of the requests in JSON format with all data fields specified:
{ "status" : "partial", "from" : "\"Alice\" <sip:alice@example.com>", "to" : "\"Bob\" <sip:5715550000@example.com>", "date" : "Fri, 11 Aug 2017 04:17:14 GMT", "pai" : [ "\"Alice\" <tel:+17035550001>", "\"Alice\" <sip:+17035550001@example.com>" ], "finger_print" : [ { "algorithm" : "SHA-1", "digest" : "4A:AD:B9:B1:3F:82:18:3B:54:02:12:DF:3E:5D:49:6B:19:E5:7C:AB" }, { "algorithm" : "SHA-256", "digest" : "36:3B:AE:12:95:95:F5:97:2D:F7:E0:84:FE:CD:F1:BC:AD:7A:70:64:F7:E7:4F:7E:A6:02:06:0E:37:54:CF:F7" } ], "identity" : [ "ey.x.oQ;info=<http://www.example.com/cert/123>;alg=ES256" ], "orig_cc" : [ 1, 44 ], "dest_cc" : "1", "cnam" : true, "ecnam" : true, "robocall" : true, "cvt" : true }
With Request & Response in JSON Format
This API entry point accepts requests and produces responses in JSON Format.
API Method |
|
|
API Path |
|
|
Required Parameters |
Name |
Description |
|
The API key uniquely identifying the API client |
|
Request |
Content-Type |
application/json |
Body (example) |
{ "from" : "\"Alice\" <sip:alice@example.com>", "to" : "\"Bob\" <sip:5715550000@example.com>" "date" : "Fri, 11 Aug 2017 04:17:14 GMT", "identity" : [ "ey.x.oQ;info=<http://www.example.com/cert/123>;alg=ES256" ] } |
|
Successful Response |
HTTP Code |
200 OK |
Content-Type |
application/json |
|
Body (example) |
{ "status" : "ok" } |
|
Error Response |
HTTP Code |
4xx, 5xx |
Content-Type |
application/json |
|
Body (example) |
{ "status" : "error", "error" : [ { "error_id" : "ApiKeyInvalid", "http_status_code" : 400, "sip_code" : 400, "reason" : "API key is invalid", "timestamp" : "Fri, 11 Aug 2017 14:50:48 GMT" } ] } |
A successful response in JSON format includes the "status" attribute as "ok" after the SIP Identity headers are validated with the required verification status.
There are three possible "status" values specified in the request:
-
none
This status value indicates that the SIP Identity headers specified in the request are not required to be verified -
partial
This status value indicates that one or more SIP Identity headers specified in the request are required to be verified -
all
This status value indicates that all SIP Identity headers specified in the request are required to be verified
Based on the verification status requirement specified in the request, the CCID VS will return a "status" attribute in the response with the following two possible values:
-
ok
This status value indicates that the verification result of SIP Identity headers has met the verification status requirement specified in the request -
error
This status value indicates that the verification result of SIP Identity headers has not met the verification status requirement specified in the request
If there are any errors encountered in the verification process, an "error" attribute in the response will list all of those errors.
If the "cnam" attribute is specified as "true" in the request, a "cnam" attribute will be returned in the response if the CNAM lookup is successful; otherwise, a "cnam_error" attribute will be returned for the specific error condition.
If the "ecnam" attribute is specified as "true" in the request, an "ecnam" attribute will be returned, if the ECNAM lookup is successful; otherwise, an "ecnam_error" attribute will be returned for the specific error condition.
If the "robocall" attribute is specified as "true" in the request, a "call_insight" attribute will be returned, if any.
If the "cvt" attribute is specified as "true" in the request, "cnam", "ecnam", and "call_insight" attribute will be returned, if any, by invoking CVT service.
If a SIP Identity header re-signing action is triggered, and a re-signed SIP Identity header is generated successfully, a "resigned_identity" attribute will be returned. If the re-signing request is failed to be processed, the error information will be recorded in the "error" field in the response.
If the "verstat" value is specified as "true" in the request, the "verstat" value returned may subject to override by local verstat-related policy, or CVT policy with an overlay verstat value.
ECNAM Object Data Fields
An ECNAM
object returned to a client contains various information related to the calling party
number, with various data set sources, such as ECNAM (Enhanced CNAM), BCD (Branded Call Display),
or CNO (Caller Name Optimization), etc. It contains the following data fields:
Path | Type | Optional | Description | Constraints |
---|---|---|---|---|
|
|
|
ECNAM data provider name, such as neustar, titan, etc. |
If specified, must be a valid token identifying the data provider name |
|
|
|
ECNAM source data set, such as ecnam, bcd, cno, bcd+cno, etc. |
If specified, must be a valid token identifying the data source |
|
|
|
BPO client name, from cno data set |
If specified, must be a valid token identifying BPO client name in CNO data set |
|
|
|
Branded profile client name, from bcd data set |
If specified, must be a valid token identifying branded profile name in BCD data set |
|
|
|
CNAM data, from ecnam, bcd, or cno data set |
If specified, must be a non-empty string as the CNAM value |
|
|
|
Generated value as SIP P-Asserted-Identity header |
If specified, must be a non-empty string as the value of a SIP P-Asserted-Identity header |
|
|
|
ECNAM data display template, from ecnam data set |
If specified, must be a valid template as defined in ECNAM data specification |
|
|
|
Full business name, from ecnam or bcd data set |
If specified, must be non-empty string as a valid business name |
|
|
|
Department name, from ecnam or bcd data set |
If specified, must be non-empty string as a valid department name within the business |
|
|
|
Line type, such as wireline, wireless, etc., from ecnam or bcd data set |
If specified, must be a valid token identifying the line type |
|
|
|
Subscriber type, such as business, residential, etc., from ecnam or bcd data set |
If specified, must be a valid token identifying the subscriber type |
|
|
|
Business type, from ecnam or bcd data set |
If specified, must be a valid token identifying the business type |
|
|
|
Business address, from ecnam or bcd data set |
If specified, must be a valid address identifying the business location |
|
|
|
Locality, such as 'c/o CMO Office', from ecnam data set |
If specified, must be a non-empty string identifying the locality of the business location |
|
|
|
City, such as 'Sterling', from ecnam or bcd data set |
If specified, must be a valid city nameidentifying the business location |
|
|
|
State or province, such as 'VA', from ecnam or bcd data set |
If specified, must be a valid state or province identifying the business location |
|
|
|
Country code, such as US, from ecnam or bcd data set |
If specified, must be a valid country code identifying the business location |
|
|
|
Postal code, such as 20166-1234, from ecnam or bcd data set |
If specified, must be a valid postal code identifying the business location |
|
|
|
Website URL, from ecnam or bcd data set |
If specified, must be a URL of the business website |
|
|
|
Logo URL, from ecnam or bcd data set |
If specified, must be a valid URL of the business logo image |
|
|
|
Tagline, from ecnam or bcd data set |
If specified, must be non-empty string of the tagline of the business |
|
|
|
Social media info, as an object map of name/value pairs, from ecnam or bcd data set |
If specified, must be non-empty attribute map containing name/value pairs, identifying social media name and URL location |
|
|
|
Employee’s full name, such as John Smith, from ecnam data set |
If specified, must be a valid employee full name |
|
|
|
Employee’s first name, such as John, from ecnam or bcd data set |
If specified, must be a valid first name of the employee |
|
|
|
Employee’s last name, such as Smith, from ecnam or bcd data set |
If specified, must be a valid last name of the employee |
|
|
|
Job title of the employee, from ecnam or bcd data set |
If specified, must be a non-empty string identifying the job title of the employee |
|
|
|
Headshot/avatar image URL, from ecnam or bcd data set |
If specified, must be a valid URL of the headshot/avatar image of the employee |
|
|
|
Email address, from ecnam or bcd data set |
If specified, must be a valid email address of the employee |
|
|
|
The purpose for calls originated from the telephone number, from ecnam or cno data set |
If specified, must be non-empty string identifying the purpose of the call |
|
|
|
The reason for calls originated from the telephone number, from bcd data set |
If specified, must be non-empty string identifying the reason of the call |
|
|
|
Name score, between 0 and 100, inclusive, from ecnam data set |
If specified, must be an integer between 0 and 100 inclusive |
|
|
|
Comments, from bcd data set |
If specified, must be a non-empty string |
The call_purpose field is mainly for internal use. The call_reason field is primarily for external use, such as constructing SIP Call-Info headers. |
The cnam value in an ECNAM object can be derived from the branded_caller_name value in a BCD data
object, if the data_source value is bcd; or the caller_name value in a CNO data object, if the data_source
value is cno. If the data_source value is bcd+cno, the branded_caller_name value will take
precedence over the caller_name value as the cnam value in the ECNAM object.
|
A P-Asserted-Identity header will be constructed based on ECNAM data under the following conditions:
|
Call Insight Data Fields
A Call Insight
object returned to a client contains robocall mitigation data related to
the calling party number. It contains the following data fields:
Path | Type | Optional | Description | Constraints |
---|---|---|---|---|
|
|
|
Call treatment method, such as 'allow', 'deny', 'send_to_vm', 'prefix', 'overlay', or 'none' |
If specified, must be a valid token identifying the call treatment method |
|
|
|
Numeric fraud score between 0 and 100 |
If specified, must be an integer between 0 and 100 inclusive |
|
|
|
TN category identifier, with global black list (DNO) in the range between 300 and 699, inclusive |
If specified, must be a 3-digit positive integer |
|
|
|
Category of robocall mitigation data, such as 'DNO' for telephone numbers in the Do not originate list, etc. |
If specified, must be a valid token identifying the category |
|
|
|
Data model of robocall mitigation data, such as 'titan', for Neustar TITAN, 'foproductplus' for FirstOrion ProductPlus etc. |
If specified, must be a valid token identifying the data model |
|
|
|
Prefix or overlay name for call treatment methods as 'prefix' or 'overlay' |
If specified, must be a non-empty string |
|
|
|
Original calling name supplied or found, if any |
If specified, must be a non-empty string |
|
|
|
Call validation data from incoming call insight data request |
If specified, must be a valid Call Validation Data object |
Call Validation Data Fields
A Call Validation Data
object returned to a client contains call verification result
after SIP Identity header verification is performed. It contains the following data fields:
Path | Type | Optional | Description | Constraints |
---|---|---|---|---|
|
|
|
Call verification status, verstat, as defined by ETSI TS 124 299 |
If specified, must be one of No-TN-Validation, TN-Validation-Failed, or TN-Validation-Passed |
|
|
|
PASSporT type value, such as shaken, div, etc. |
If specified, must be a valid PASSporT type value |
|
|
|
Attestation indicator value in a PASSporT with type as shaken |
If specified, must be one of A, B, or C |
|
|
|
Origination id value in a PASSporT with type as shaken |
If specified, must be a valid toekn for an origination id |
|
|
|
CNAM extracted from SIP From or P-Asserted-Identity headers |
If specified, must be a non-empty string representing a CNAM |
The verstat value is derived from SIP Identity verification result, subject to local policy related to verstat values. The final verstat value returned to a client may subject to additional override, as specified in a CVT policy, if any. |
Example with Minimum Input Data Set
The following is an example for verifying SIP Identity headers with minimum request data elements:
$ curl 'https://ca-verify.neustarlab.biz/ccid/verify/v2/identity?apiKey=%3CapiKey1%3E' -i -X POST \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
"from" : "\"alice\" <sip:+15715550000@example.com>",
"to" : "\"bob\" <sip:+15715550001@example.com>",
"identity" : [ "eyJhbGciOiJFUzI1NiIsInR5cCI6InBhc3Nwb3J0IiwieDV1IjoiaHR0cDovL2NhLmV4YW1wbGUuY29tL3Rlc3QuZGVyIn0.eyJkZXN0Ijp7InRuIjpbIjE1NzE1NTUwMDAxIl19LCJpYXQiOjE3MzI1NjY1MjIsIm9yaWciOnsidG4iOiIxNTcxNTU1MDAwMCJ9fQ.kaw4VD-59d75H9x2S7xYzGtyWdqvGS6LBhMZUSd5ghGbvGHe6OhRmblR6T2pb9PM_1n-RF6J-RgtvlE2PjEh8Q;info=<http://ca.example.com/test.der>;alg=ES256" ]
}'
The description of the fields in the request is as below:
Path | Type | Optional | Description | Constraints |
---|---|---|---|---|
|
|
|
'From' header value from SIP INVITE message |
Required |
|
|
|
'To' header value from SIP INVITE message |
Required |
|
|
|
A list of SIP Identity values to be verified |
Required |
The successful response message is as below:
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 21
{
"status" : "ok"
}
The description of the fields in the response is as below:
Path | Type | Optional | Description |
---|---|---|---|
|
|
|
Verification status |
Example with Minimum Input Data Set for Diverted Calls
The following is an example for verifying SIP Identity headers with minimum request data elements with PASSporT extension for a call diverted from sip:+15715550001@example.com to sip:bob@example.com.
$ curl 'https://ca-verify.neustarlab.biz/ccid/verify/v2/identity?apiKey=%3CapiKey1%3E' -i -X POST \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
"from" : "\"alice\" <sip:+15715550000@example.com>",
"to" : "\"bob\" <sip:bob@example.com>",
"identity" : [ "..mEZKr-DKUp39fXXBzxOBR69sVZkCl3hlZcqJvOsLio7Uez0mlp2xE9DLprjTaCzi9AQokW3HXc4-ujpWvwChJg;info=<http://ca.example.com/test.der>;alg=ES256", "..2o412faQ76lzFiEv9rCdXRNgO3CH3AaZcC61DJbUZ4R7T7MvNbUmj5TtNBUVNPNfM7AOv7PzDVyxr55v7gl-9w;info=<http://ca.example.com/test.der>;alg=ES256;ppt=\"div\"" ],
"diversion" : [ "\"bob\" <sip:+15715550001@example.com>;reason=away" ]
}'
The description of the fields in the request is as below:
Path | Type | Optional | Description | Constraints |
---|---|---|---|---|
|
|
|
'From' header value from SIP INVITE message |
Required |
|
|
|
'To' header value from SIP INVITE message |
Required |
|
|
|
A list of 'Diversion' header values from SIP INVITE message |
If specified, must be one as specified in RFC5806 Section 4 |
|
|
|
A list of SIP Identity values to be verified |
Required |
The successful response message is as below:
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 21
{
"status" : "ok"
}
The description of the fields in the response is as below:
Path | Type | Optional | Description |
---|---|---|---|
|
|
|
Verification status |
Example with Minimum Input Data Set for Resource Priority Authorization
The following is an example for verifying SIP Identity headers with minimum request data elements with PASSporT extension for Resource Priority Authorization with authorization values as "ets.1", "wps.2" and "esnet.1", along with an optional Priority value as psap-callback::
$ curl 'https://ca-verify.neustarlab.biz/ccid/verify/v2/identity?apiKey=%3CapiKey1%3E' -i -X POST \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
"from" : "\"alice\" <sip:+15715550000@example.com>",
"to" : "\"bob\" <sip:+15715550001@example.com>",
"identity" : [ "eyJhbGciOiJFUzI1NiIsInBwdCI6InJwaCIsInR5cCI6InBhc3Nwb3J0IiwieDV1IjoiaHR0cDovL2NhLmV4YW1wbGUuY29tL3Rlc3QuZGVyIn0.eyJkZXN0Ijp7InRuIjpbIjE1NzE1NTUwMDAxIl19LCJpYXQiOjE3MzI1NjY1MjIsIm9yaWciOnsidG4iOiIxNTcxNTU1MDAwMCJ9LCJycGgiOnsiYXV0aCI6WyJlc25ldC4xIiwiZXRzLjAiLCJ3cHMuMiJdfSwic3BoIjoicHNhcC1jYWxsYmFjayJ9.4n-45hgqLua1FjO5AxNmMGtxHQQErOgeQM84q40zyA8ekc2iJ-qVIO8bV0L9SEbG5sKgjYza21eK1yKZUAFLaA;info=<http://ca.example.com/test.der>;alg=ES256;ppt=\"rph\"" ],
"resource_priority" : [ "ets.0, wps.2", "q735.1, esnet.1" ],
"priority" : "psap-callback"
}'
The description of the fields in the request is as below:
Path | Type | Optional | Description | Constraints |
---|---|---|---|---|
|
|
|
'From' header value from SIP INVITE message |
Required |
|
|
|
'To' header value from SIP INVITE message |
Required |
|
|
|
A list of 'Resource-Priority' header values from SIP INVITE message |
If specified, must be one as specified in RFC4412 Section 3.1 |
|
|
|
The SIP 'Priority' header value from SIP INVITE message |
If specified, must be psap-callback |
|
|
|
A list of SIP Identity values to be verified |
Required |
The successful response message is as below:
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 21
{
"status" : "ok"
}
The description of the fields in the response is as below:
Path | Type | Optional | Description |
---|---|---|---|
|
|
|
Verification status |
Example with Input Data Set for Rich Call Data
The following is an example for verifying SIP Identity headers with request data elements with PASSporT extension for Rich Call Data (RCD):
$ curl 'https://ca-verify.neustarlab.biz/ccid/verify/v2/identity?apiKey=%3CapiKey1%3E' -i -X POST \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
"from" : "\"alice\" <sip:+15715550000@example.com>",
"to" : "\"bob\" <sip:+15715550001@example.com>",
"identity" : [ "eyJhbGciOiJFUzI1NiIsInBwdCI6InJjZCIsInR5cCI6InBhc3Nwb3J0IiwieDV1IjoiaHR0cDovL2NhLmV4YW1wbGUuY29tL3Rlc3QuZGVyIn0.eyJjcm4iOiJUcmF2ZWwiLCJkZXN0Ijp7InRuIjpbIjE1NzE1NTUwMDAxIl19LCJpYXQiOjE3MzI1NjY1MjIsImlzcyI6IkRpc25leSwgSW5jLiIsIm9yaWciOnsidG4iOiIxNTcxNTU1MDAwMCJ9LCJyY2QiOnsiYXBuIjoiMTgwMDU1NTAwMDAiLCJpY24iOiJkYXRhOmltYWdlL3BuZztiYXNlNjQsaVZCT1J3MEtHZ29BQUFBTlNVaEVVZ0FBQUFVQUFBQUZDQVlBQUFDTmJ5YmxBQUFBSEVsRVFWUUkxMlA0Ly84L3czOEdJQVhESUJLRTBESHhnbGpOQkFBTzlUWEwwWTRPSHdBQUFBQkpSVTVFcmtKZ2dnPT0iLCJqY2QiOlsidmNhcmQiLFtbInZlcnNpb24iLHt9LCJ0ZXh0IiwiNC4wIl0sWyJmbiIse30sInRleHQiLCJBbGljZSBMaWRkZWxsIl0sWyJlbWFpbCIse30sInRleHQiLCJhbGljZUBleGFtcGxlLmNvbSJdXV0sIm5hbSI6IkFsaWNlIn0sInJjZGkiOnsiL2FwbiI6InNoYTI1Ni12SENSRzEyakM2WE05Uk9PMXdzREZPcGplQUQ0STJjNzROVVFrbHpuNHpZPSIsIi9pY24iOiJzaGEyNTYtSjhsZ29yUTNCVG8zRk94ODVLQjBxVytrMFRUMWpGVk0zU0lhUnlLQkg5dz0iLCIvamNkIjoic2hhMjU2LUhaeC9OLzF4T0JwRW9mc2hiWjJYampRMzFPRHV2cGVGWnRrbG5xMnpaRzg9IiwiL25hbSI6InNoYTI1Ni1POFVRWXBjOFJZMWFieTJOWktBakpHTlVyWDRHU3g1T0FKN0lvR21hTUVNPSJ9fQ.GQrg8YgZtmIw2E7lwScP4WKrk368NTpUgpchsihTXaz6Zg-0iMwiwt4nFD-HKA0_xhpWjxHQgbrMm2KtaPsKGA;info=<http://ca.example.com/test.der>;alg=ES256;ppt=\"rcd\"" ],
"call_info" : [ "<cid:example.com/alice.json>;purpose=jcard;call-reason=Travel" ],
"caller_name" : "Alice",
"caller_logo_uri" : "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==",
"alt_present_number" : "<sip:+18005550000@example.com>",
"jcard" : "[\"vcard\",[[\"version\",{},\"text\",\"4.0\"],[\"fn\",{},\"text\",\"Alice Liddell\"],[ \"email\",{},\"text\",\"alice@example.com\"]]]",
"rcd_issuer" : "Disney, Inc.",
"rcd_integrity" : true,
"identity_info" : true
}'
The description of the fields in the request is as below:
Path | Type | Optional | Description | Constraints |
---|---|---|---|---|
|
|
|
'From' header value from SIP INVITE message |
Required |
|
|
|
'To' header value from SIP INVITE message |
Required |
|
|
|
The CNAM to be used for constructing RCD PASSporT |
If specified, must be not empty or blank |
|
|
|
The 'Call-Info' header values for extracting caller_logo_uri, jcard_uri and/or call_reason values used in constructing RCD PASSporT |
If specified, must be a list of valid SIP 'Call-Info' header values |
|
|
|
The URI identifying the location of the caller logo/icon image |
If specified, must be valid URI |
|
|
|
The alternate presentation number to be used for constructing RCD PASSporT |
If specified, must be a valid URI containing a numeric phone number |
|
|
|
The JSON string representing a valid JCARD |
If specified, must be valid JCARD in JSON format |
|
|
|
The third-party issuer of RCD data |
If specified, must be the Origination (O) value of the Subject Name field of the certificate used to sign the third party PASSporT |
|
|
|
The boolean flag for verifying RCD PASSporT integrity hash |
If specified, must be either true or false, with default as false |
|
|
|
Boolean flag for returning information related to SIP Identity values verified |
If specified, must be true or false |
|
|
|
A list of SIP Identity values to be verified |
Required |
The successful response message is as below:
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 1617
{
"status" : "ok",
"identity_info" : [ {
"status" : "Ok",
"params" : "info=<http://ca.example.com/test.der>;alg=ES256;ppt=\"rcd\"",
"header" : {
"alg" : "ES256",
"ppt" : "rcd",
"typ" : "passport",
"x5u" : "http://ca.example.com/test.der"
},
"claim" : {
"crn" : "Travel",
"dest" : {
"tn" : [ "15715550001" ]
},
"iat" : 1732566522,
"iss" : "Disney, Inc.",
"orig" : {
"tn" : "15715550000"
},
"rcd" : {
"apn" : "18005550000",
"icn" : "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==",
"jcd" : [ "vcard", [ [ "version", { }, "text", "4.0" ], [ "fn", { }, "text", "Alice Liddell" ], [ "email", { }, "text", "alice@example.com" ] ] ],
"nam" : "Alice"
},
"rcdi" : {
"/apn" : "sha256-vHCRG12jC6XM9ROO1wsDFOpjeAD4I2c74NUQklzn4zY=",
"/icn" : "sha256-J8lgorQ3BTo3FOx85KB0qW+k0TT1jFVM3SIaRyKBH9w=",
"/jcd" : "sha256-HZx/N/1xOBpEofshbZ2XjjQ31ODuvpeFZtklnq2zZG8=",
"/nam" : "sha256-O8UQYpc8RY1aby2NZKAjJGNUrX4GSx5OAJ7IoGmaMEM="
}
},
"certificate_info" : {
"subject" : "C=US, ST=VA, L=Somewhere, O=\"AcmeTelecom, Inc.\", OU=VOIP, CN=TEST-EC-256-EXT-TN-JWT",
"issuer" : "C=US, O=Neustar IOT Lab, CN=CallAuthnCA",
"tn_auth_list" : [ {
"spc" : "X001"
}, {
"range" : {
"start" : "15714340000",
"count" : 10000
}
}, {
"one" : "17035550000"
} ]
}
} ]
}
The description of the fields in the response is as below:
Path | Type | Optional | Description |
---|---|---|---|
|
|
|
Verification status |
|
|
|
A list of information related to SIP Identity headers verified |
The description of the fields in the identity_info
attribute is as below:
Path | Type | Optional | Description | Constraints |
---|---|---|---|---|
|
|
|
The verification status of a SIP Identity header |
Either "Ok" or an unique error identifier |
|
|
|
The parameters in a SIP Identity header |
Must be extracted from SIP Identity header |
|
|
|
The decoded PASSporT header object in a SIP Identity header |
Must be a valid PASSporT header object |
|
|
|
The decoded PASSporT claim object in a SIP Identity header |
Must be a valid PASSporT claim object |
|
|
|
The basic information of the certificate used in a SIP Identity header |
Must contain subject and issue fields with an optional tn_auth_list field |
The description of the fields in the certificate_info
attribute is as below:
Path | Type | Optional | Description | Constraints |
---|---|---|---|---|
|
|
|
The subject of the certificate used in a SIP Identity header |
Must contain the subject extracted from an X.509 certificate |
|
|
|
The issuer of the certificate used in a SIP Identity header |
Must contain the issuer extracted from an X.509 certificate |
|
|
|
The TN Authorization List of the certificate used in a SIP Identity header |
Must contain the TN Authorization List extracted from an X.509 certificate |
The description of the fields in the tn_auth_list
attribute is as below:
Path | Type | Optional | Description | Constraints |
---|---|---|---|---|
|
|
|
A Service Provider Code in TN Authorization List |
Must contain a non-empty string |
|
|
|
A telephone number in TN Authorization List |
Must contain a valid E.164 telephone number |
|
|
|
A telephone range in TN Authorization List |
Must be a valid A telephone range object |
|
|
|
The start telephone number of a telephone range in TN Authorization List |
Must contain a valid E.164 telephone number |
|
|
|
The total telephone numbers of a telephone range in TN Authorization List |
Must be a positive integer number |
Example with Request Id, Verstat and Identity Info
The following is an example for verifying SIP Identity headers with PASSporT as
"shaken"
, and optional request_id
, verstat
and identity_info
values in the request.
$ curl 'https://ca-verify.neustarlab.biz/ccid/verify/v2/identity?apiKey=%3CapiKey1%3E' -i -X POST \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
"from" : "\"alice\" <sip:+17035550001@example.com>",
"to" : "\"bob\" <sip:+15715550001@example.com>",
"identity" : [ "eyJhbGciOiJFUzI1NiIsInBwdCI6InNoYWtlbiIsInR5cCI6InBhc3Nwb3J0IiwieDV1IjoiaHR0cDovL2NhLmV4YW1wbGUuY29tL3Rlc3QuZGVyIn0.eyJhdHRlc3QiOiJBIiwiZGVzdCI6eyJ0biI6WyIxNTcxNTU1MDAwMSJdfSwiaWF0IjoxNzMyNTY2NTIyLCJta3kiOlt7ImFsZyI6IlNIQS0xIiwiZGlnIjoiNEFBREI5QjEzRjgyMTgzQjU0MDIxMkRGM0U1RDQ5NkIxOUU1N0NBQiJ9LHsiYWxnIjoiU0hBLTI1NiIsImRpZyI6IjM2M0JBRTEyOTU5NUY1OTcyREY3RTA4NEZFQ0RGMUJDQUQ3QTcwNjRGN0U3NEY3RUE2MDIwNjBFMzc1NENGRjcifV0sIm9yaWciOnsidG4iOiIxNzAzNTU1MDAwMSJ9LCJvcmlnaWQiOiIxMjM0NTYtQUJDRC05OTk5OTkiLCJyY2QiOnsibmFtIjoiQWxpY2UifX0.0rIXT_eKwPrmy1NfZDzcxX3jfGEzdARbPqsXgfc22VDOWsCqqnKfsC30SkhPTJPRYK6IqVH0YXUxW2c571w9AA;info=<http://ca.example.com/test.der>;alg=ES256;ppt=\"shaken\"" ],
"status" : "all",
"verstat" : true,
"identity_info" : true,
"request_id" : "X-REQUEST-ID-12345"
}'
The description of the fields in the request is as below:
Path | Type | Optional | Description | Constraints |
---|---|---|---|---|
|
|
|
Verification status requirement |
If specified, must be 'none', 'partial' or 'all' |
|
|
|
'From' header value from SIP INVITE message |
Required |
|
|
|
'To' header value from SIP INVITE message |
Required |
|
|
|
A list of SIP Identity values to be verified |
Required |
|
|
|
Boolean flag for returning verstat value after SIP Identity values are verified |
If specified, must be true or false |
|
|
|
Boolean flag for returning information related to SIP Identity values verified |
If specified, must be true or false |
|
|
|
Client supplied request identifier for tracking purpose |
If not null, it will be returned back in the response object |
The successful response message is as below:
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 1284
{
"status" : "ok",
"request_id" : "X-REQUEST-ID-12345",
"verstat" : "TN-Validation-Passed",
"identity_info" : [ {
"status" : "Ok",
"params" : "info=<http://ca.example.com/test.der>;alg=ES256;ppt=\"shaken\"",
"header" : {
"alg" : "ES256",
"ppt" : "shaken",
"typ" : "passport",
"x5u" : "http://ca.example.com/test.der"
},
"claim" : {
"attest" : "A",
"dest" : {
"tn" : [ "15715550001" ]
},
"iat" : 1732566522,
"mky" : [ {
"alg" : "SHA-1",
"dig" : "4AADB9B13F82183B540212DF3E5D496B19E57CAB"
}, {
"alg" : "SHA-256",
"dig" : "363BAE129595F5972DF7E084FECDF1BCAD7A7064F7E74F7EA602060E3754CFF7"
} ],
"orig" : {
"tn" : "17035550001"
},
"origid" : "123456-ABCD-999999",
"rcd" : {
"nam" : "Alice"
}
},
"certificate_info" : {
"subject" : "C=US, ST=VA, L=Somewhere, O=\"AcmeTelecom, Inc.\", OU=VOIP, CN=TEST-EC-256-EXT-TN-JWT",
"issuer" : "C=US, O=Neustar IOT Lab, CN=CallAuthnCA",
"tn_auth_list" : [ {
"spc" : "X001"
}, {
"range" : {
"start" : "15714340000",
"count" : 10000
}
}, {
"one" : "17035550000"
} ]
}
} ]
}
The description of the fields in the response is as below:
Path | Type | Optional | Description |
---|---|---|---|
|
|
|
Verification status |
|
|
|
'verstat' value defined by ETSI TS 124 299 |
|
|
|
A list of information related to SIP Identity headers verified |
|
|
|
Client supplied request identifier for tracking purpose |
The description of the fields in the identity_info
attribute is as below:
Path | Type | Optional | Description | Constraints |
---|---|---|---|---|
|
|
|
The verification status of a SIP Identity header |
Either "Ok" or an unique error identifier |
|
|
|
The parameters in a SIP Identity header |
Must be extracted from SIP Identity header |
|
|
|
The decoded PASSporT header object in a SIP Identity header |
Must be a valid PASSporT header object |
|
|
|
The decoded PASSporT claim object in a SIP Identity header |
Must be a valid PASSporT claim object |
|
|
|
The basic information of the certificate used in a SIP Identity header |
Must contain subject and issue fields with an optional tn_auth_list field |
The description of the fields in the certificate_info
attribute is as below:
Path | Type | Optional | Description | Constraints |
---|---|---|---|---|
|
|
|
The subject of the certificate used in a SIP Identity header |
Must contain the subject extracted from an X.509 certificate |
|
|
|
The issuer of the certificate used in a SIP Identity header |
Must contain the issuer extracted from an X.509 certificate |
|
|
|
The TN Authorization List of the certificate used in a SIP Identity header |
Must contain the TN Authorization List extracted from an X.509 certificate |
The description of the fields in the tn_auth_list
attribute is as below:
Path | Type | Optional | Description | Constraints |
---|---|---|---|---|
|
|
|
A Service Provider Code in TN Authorization List |
Must contain a non-empty string |
|
|
|
A telephone number in TN Authorization List |
Must contain a valid E.164 telephone number |
|
|
|
A telephone range in TN Authorization List |
Must be a valid A telephone range object |
|
|
|
The start telephone number of a telephone range in TN Authorization List |
Must contain a valid E.164 telephone number |
|
|
|
The total telephone numbers of a telephone range in TN Authorization List |
Must be a positive integer number |
Example with SHAKEN PASSporT Containing RCD PASSporT Fields
The following is an example for verifying SIP Identity headers with PASSporT as
"shaken"
, containing various RCD PASSporT claims:
$ curl 'https://ca-verify.neustarlab.biz/ccid/verify/v2/identity?apiKey=%3CapiKey1%3E' -i -X POST \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
"from" : "\"alice\" <sip:+17035550001@example.com>",
"to" : "\"bob\" <sip:+15715550001@example.com>",
"identity" : [ "eyJhbGciOiJFUzI1NiIsInBwdCI6InNoYWtlbiIsInR5cCI6InBhc3Nwb3J0IiwieDV1IjoiaHR0cDovL2NhLmV4YW1wbGUuY29tL3Rlc3QuZGVyIn0.eyJhdHRlc3QiOiJBIiwiY3JuIjoiVHJhdmVsIiwiZGVzdCI6eyJ0biI6WyIxNTcxNTU1MDAwMSJdfSwiaWF0IjoxNzMyNTY2NTIyLCJpc3MiOiJEaXNuZXksIEluYy4iLCJvcmlnIjp7InRuIjoiMTcwMzU1NTAwMDEifSwib3JpZ2lkIjoiMTIzNDU2LUFCQ0QtOTk5OTk5IiwicmNkIjp7ImFwbiI6IjE4MDA1NTUwMDAwIiwiamNkIjpbInZjYXJkIixbWyJ2ZXJzaW9uIix7fSwidGV4dCIsIjQuMCJdLFsiZm4iLHt9LCJ0ZXh0IiwiQWxpY2UgTGlkZGVsbCJdLFsiZW1haWwiLHt9LCJ0ZXh0IiwiYWxpY2VAZXhhbXBsZS5jb20iXV1dLCJuYW0iOiJBbGljZSJ9LCJyY2RpIjp7Ii9hcG4iOiJzaGEyNTYtdkhDUkcxMmpDNlhNOVJPTzF3c0RGT3BqZUFENEkyYzc0TlVRa2x6bjR6WT0iLCIvamNkIjoic2hhMjU2LUhaeC9OLzF4T0JwRW9mc2hiWjJYampRMzFPRHV2cGVGWnRrbG5xMnpaRzg9IiwiL25hbSI6InNoYTI1Ni1POFVRWXBjOFJZMWFieTJOWktBakpHTlVyWDRHU3g1T0FKN0lvR21hTUVNPSJ9fQ.858Ilx1-B6wOqQ486ksFlF87xnU3giLZ6qFu4e0S0JpavZr0026srjUuxb8CJC0F3qnwcto-4u6HLFjpBBwEmw;info=<http://ca.example.com/test.der>;alg=ES256;ppt=\"shaken\"" ],
"call_info" : [ "<cid:example.com/alice.json>;purpose=jcard;call-reason=Travel" ],
"caller_name" : "Alice",
"alt_present_number" : "<sip:+18005550000@example.com>",
"jcard" : "[\"vcard\",[[\"version\",{},\"text\",\"4.0\"],[\"fn\",{},\"text\",\"Alice Liddell\"],[ \"email\",{},\"text\",\"alice@example.com\"]]]",
"rcd_issuer" : "Disney, Inc.",
"rcd_integrity" : true,
"status" : "all",
"verstat" : true,
"identity_info" : true,
"request_id" : "X-REQUEST-ID-12345"
}'
The description of the fields in the request is as below:
Path | Type | Optional | Description | Constraints |
---|---|---|---|---|
|
|
|
Verification status requirement |
If specified, must be 'none', 'partial' or 'all' |
|
|
|
'From' header value from SIP INVITE message |
Required |
|
|
|
'To' header value from SIP INVITE message |
Required |
|
|
|
The CNAM to be used for constructing RCD PASSporT |
If specified, must be not empty or blank |
|
|
|
The 'Call-Info' header values for extracting caller_logo_uri, jcard_uri and/or call_reason values used in constructing RCD PASSporT |
If specified, must be a list of valid SIP 'Call-Info' header values |
|
|
|
The alternate presentation number to be used for constructing RCD PASSporT |
If specified, must be a valid URI containing a numeric phone number |
|
|
|
The JSON string representing a valid JCARD |
If specified, must be valid JCARD in JSON format |
|
|
|
The third-party issuer of RCD data |
If specified, must be the Origination (O) value of the Subject Name field of the certificate used to sign the third party PASSporT |
|
|
|
The boolean flag for verifying RCD PASSporT integrity hash |
If specified, must be either true or false, with default as false |
|
|
|
A list of SIP Identity values to be verified |
Required |
|
|
|
Boolean flag for returning verstat value after SIP Identity values are verified |
If specified, must be true or false |
|
|
|
Boolean flag for returning information related to SIP Identity values verified |
If specified, must be true or false |
|
|
|
Client supplied request identifier for tracking purpose |
If not null, it will be returned back in the response object |
The successful response message is as below:
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 1531
{
"status" : "ok",
"request_id" : "X-REQUEST-ID-12345",
"verstat" : "TN-Validation-Passed",
"identity_info" : [ {
"status" : "Ok",
"params" : "info=<http://ca.example.com/test.der>;alg=ES256;ppt=\"shaken\"",
"header" : {
"alg" : "ES256",
"ppt" : "shaken",
"typ" : "passport",
"x5u" : "http://ca.example.com/test.der"
},
"claim" : {
"attest" : "A",
"crn" : "Travel",
"dest" : {
"tn" : [ "15715550001" ]
},
"iat" : 1732566522,
"iss" : "Disney, Inc.",
"orig" : {
"tn" : "17035550001"
},
"origid" : "123456-ABCD-999999",
"rcd" : {
"apn" : "18005550000",
"jcd" : [ "vcard", [ [ "version", { }, "text", "4.0" ], [ "fn", { }, "text", "Alice Liddell" ], [ "email", { }, "text", "alice@example.com" ] ] ],
"nam" : "Alice"
},
"rcdi" : {
"/apn" : "sha256-vHCRG12jC6XM9ROO1wsDFOpjeAD4I2c74NUQklzn4zY=",
"/jcd" : "sha256-HZx/N/1xOBpEofshbZ2XjjQ31ODuvpeFZtklnq2zZG8=",
"/nam" : "sha256-O8UQYpc8RY1aby2NZKAjJGNUrX4GSx5OAJ7IoGmaMEM="
}
},
"certificate_info" : {
"subject" : "C=US, ST=VA, L=Somewhere, O=\"AcmeTelecom, Inc.\", OU=VOIP, CN=TEST-EC-256-EXT-TN-JWT",
"issuer" : "C=US, O=Neustar IOT Lab, CN=CallAuthnCA",
"tn_auth_list" : [ {
"spc" : "X001"
}, {
"range" : {
"start" : "15714340000",
"count" : 10000
}
}, {
"one" : "17035550000"
} ]
}
} ]
}
The description of the fields in the response is as below:
Path | Type | Optional | Description |
---|---|---|---|
|
|
|
Verification status |
|
|
|
'verstat' value defined by ETSI TS 124 299 |
|
|
|
A list of information related to SIP Identity headers verified |
|
|
|
Client supplied request identifier for tracking purpose |
The description of the fields in the identity_info
attribute is as below:
Path | Type | Optional | Description | Constraints |
---|---|---|---|---|
|
|
|
The verification status of a SIP Identity header |
Either "Ok" or an unique error identifier |
|
|
|
The parameters in a SIP Identity header |
Must be extracted from SIP Identity header |
|
|
|
The decoded PASSporT header object in a SIP Identity header |
Must be a valid PASSporT header object |
|
|
|
The decoded PASSporT claim object in a SIP Identity header |
Must be a valid PASSporT claim object |
|
|
|
The basic information of the certificate used in a SIP Identity header |
Must contain subject and issue fields with an optional tn_auth_list field |
The description of the fields in the certificate_info
attribute is as below:
Path | Type | Optional | Description | Constraints |
---|---|---|---|---|
|
|
|
The subject of the certificate used in a SIP Identity header |
Must contain the subject extracted from an X.509 certificate |
|
|
|
The issuer of the certificate used in a SIP Identity header |
Must contain the issuer extracted from an X.509 certificate |
|
|
|
The TN Authorization List of the certificate used in a SIP Identity header |
Must contain the TN Authorization List extracted from an X.509 certificate |
The description of the fields in the tn_auth_list
attribute is as below:
Path | Type | Optional | Description | Constraints |
---|---|---|---|---|
|
|
|
A Service Provider Code in TN Authorization List |
Must contain a non-empty string |
|
|
|
A telephone number in TN Authorization List |
Must contain a valid E.164 telephone number |
|
|
|
A telephone range in TN Authorization List |
Must be a valid A telephone range object |
|
|
|
The start telephone number of a telephone range in TN Authorization List |
Must contain a valid E.164 telephone number |
|
|
|
The total telephone numbers of a telephone range in TN Authorization List |
Must be a positive integer number |
Example with Full Input Data Set
The following is an example for verifying SIP Identity headers with ATIS SHAKEN extension, by specifying the full set of data elements in the request, including CNAM, ECNAM and Robocall lookup, request identifier, verstat value and decoded identity information:
$ curl 'https://ca-verify.neustarlab.biz/ccid/verify/v2/identity?apiKey=%3CapiKey1%3E' -i -X POST \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
"from" : "\"alice\" <sip:+15715550000@example.com>",
"to" : "\"bob\" <sip:+15715550001@example.com>",
"date" : "Mon, 25 Nov 2024 20:28:42 GMT",
"pai" : [ "\"Alice\" <tel:+17035550001>", "\"Alice\" <sip:+17035550001@example.com>" ],
"finger_print" : [ {
"algorithm" : "SHA-1",
"digest" : "4A:AD:B9:B1:3F:82:18:3B:54:02:12:DF:3E:5D:49:6B:19:E5:7C:AB"
}, {
"algorithm" : "SHA-256",
"digest" : "36:3B:AE:12:95:95:F5:97:2D:F7:E0:84:FE:CD:F1:BC:AD:7A:70:64:F7:E7:4F:7E:A6:02:06:0E:37:54:CF:F7"
} ],
"dest_cc" : "1",
"identity" : [ "eyJhbGciOiJFUzI1NiIsInBwdCI6InNoYWtlbiIsInR5cCI6InBhc3Nwb3J0IiwieDV1IjoiaHR0cDovL2NhLmV4YW1wbGUuY29tL3Rlc3QuZGVyIn0.eyJhdHRlc3QiOiJBIiwiZGVzdCI6eyJ0biI6WyIxNTcxNTU1MDAwMSJdfSwiaWF0IjoxNzMyNTY2NTIyLCJta3kiOlt7ImFsZyI6IlNIQS0xIiwiZGlnIjoiNEFBREI5QjEzRjgyMTgzQjU0MDIxMkRGM0U1RDQ5NkIxOUU1N0NBQiJ9LHsiYWxnIjoiU0hBLTI1NiIsImRpZyI6IjM2M0JBRTEyOTU5NUY1OTcyREY3RTA4NEZFQ0RGMUJDQUQ3QTcwNjRGN0U3NEY3RUE2MDIwNjBFMzc1NENGRjcifV0sIm9yaWciOnsidG4iOiIxNzAzNTU1MDAwMSJ9LCJvcmlnaWQiOiIxMjM0NTYtQUJDRC05OTk5OTkiLCJyY2QiOnsibmFtIjoiQWxpY2UifX0.FgS0hAj-Nt170KHU9mSaTvbscG9Aixfm61ei1wBIyF8lkBewC2yBlfj65ZpazPwfH9t7b2MEtyAGmxPt7f2bGw;info=<http://ca.example.com/test.der>;alg=ES256;ppt=\"shaken\"" ],
"orig_cc" : [ "1", "44" ],
"status" : "all",
"cnam" : true,
"ecnam" : true,
"robocall" : true,
"verstat" : true,
"identity_info" : true,
"request_id" : "X-REQUEST-ID-12345"
}'
The description of the fields in the request is as below:
Path | Type | Optional | Description | Constraints |
---|---|---|---|---|
|
|
|
Verification status requirement |
If specified, must be 'none', 'partial' or 'all' |
|
|
|
'From' header value from SIP INVITE message |
Required |
|
|
|
'To' header value from SIP INVITE message |
Required |
|
|
|
'Date' header value from SIP INVITE message |
If specified, must be in RFC1123 format |
|
|
|
A list of SIP Identity values to be verified |
Required |
|
|
|
A list of 'P-Asserted-Identity' header values from SIP INVITE message |
If specified, must be one as specified in RFC3325 Section 9.1 |
|
|
|
A list of SDP 'a=fingerprint' attribute values from SIP INVITE message |
If specified, must be one as specified in RFC3325 Section 9.1 |
|
|
|
Algorithm name of a SDP 'a=fingerprint' attribute from SIP INVITE message |
Cannot be null or empty |
|
|
|
Digest value of a SDP 'a=fingerprint' attribute from SIP INVITE message |
Cannot be null or empty |
|
|
|
Default country codes for the originator telephone number |
If specified, must be a valid country code |
|
|
|
Default country code for the destination telephone number |
If specified, must be a valid country code |
|
|
|
Boolean flag for performing CNAM lookup |
If specified, must be true or false |
|
|
|
Boolean flag for performing ECNAM lookup |
If specified, must be true or false |
|
|
|
Boolean flag for returning Robocall Call Insight data |
If specified, must be true or false |
|
|
|
Boolean flag for returning verstat value after SIP Identity values are verified |
If specified, must be true or false |
|
|
|
Boolean flag for returning information related to SIP Identity values verified |
If specified, must be true or false |
|
|
|
Client supplied request identifier for tracking purpose |
If not null, it will be returned back in the response object |
The successful response message is as below:
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 3451
{
"status" : "ok",
"request_id" : "X-REQUEST-ID-12345",
"verstat" : "TN-Validation-Passed",
"identity_info" : [ {
"status" : "Ok",
"params" : "info=<http://ca.example.com/test.der>;alg=ES256;ppt=\"shaken\"",
"header" : {
"alg" : "ES256",
"ppt" : "shaken",
"typ" : "passport",
"x5u" : "http://ca.example.com/test.der"
},
"claim" : {
"attest" : "A",
"dest" : {
"tn" : [ "15715550001" ]
},
"iat" : 1732566522,
"mky" : [ {
"alg" : "SHA-1",
"dig" : "4AADB9B13F82183B540212DF3E5D496B19E57CAB"
}, {
"alg" : "SHA-256",
"dig" : "363BAE129595F5972DF7E084FECDF1BCAD7A7064F7E74F7EA602060E3754CFF7"
} ],
"orig" : {
"tn" : "17035550001"
},
"origid" : "123456-ABCD-999999",
"rcd" : {
"nam" : "Alice"
}
},
"certificate_info" : {
"subject" : "C=US, ST=VA, L=Somewhere, O=\"AcmeTelecom, Inc.\", OU=VOIP, CN=TEST-EC-256-EXT-TN-JWT",
"issuer" : "C=US, O=Neustar IOT Lab, CN=CallAuthnCA",
"tn_auth_list" : [ {
"spc" : "X001"
}, {
"range" : {
"start" : "15714340000",
"count" : 10000
}
}, {
"one" : "17035550000"
} ]
}
} ],
"cnam" : "Alice In Wonderland",
"ecnam" : {
"cnam" : "Alice In Wonderland",
"display_template" : "none",
"business_name" : "Disney World",
"department" : "Theme Park",
"line_type" : "Wireline",
"subscriber_type" : "Business",
"business_type" : "Entertainment",
"business_address" : "Walt Disney World Resort",
"locality" : "Orlando, FL",
"city" : "Orlando",
"state" : "FL",
"country" : "US",
"postal_code" : "32830",
"website_url" : "http://movies.disney.com/alice-in-wonderland-1951",
"logo_url" : "https://static-mh.content.disney.io/matterhorn/assets/goc/nav-logo-dark@2x-2b3eb08c507c.png",
"tagline" : "#AliceInWonderLand",
"employee_name" : "Alice",
"first_name" : "Alice",
"last_name" : "Liddell",
"job_title" : "Adventurer",
"headshot_url" : "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcR2Q1GWX6hdmMr2dh10SoTeEKEn4S4toc4V3yAJCrPQHlzWvr_I",
"email" : "alice@disney.com",
"call_purpose" : "Customer Support",
"social_media_info" : {
"Facebook" : "https://www.facebook.com/DisneyAliceInWonderland",
"Twitter" : "https://twitter.com/Disney"
},
"p_asserted_identity" : "\"Alice In Wonderland\" <sip:alice@example.com;tmpl=none;bn=Disney%20World;dept=Theme%20Park;lt=Wireline;st=Business;bt=Entertainment;ba=Walt%20Disney%20World%20Resort;cs=Orlando, FL;city=Orlando;state=FL;ct=US;zip=32830;wb=http://movies.disney.com/alice-in-wonderland-1951;lg=https://static-mh.content.disney.io/matterhorn/assets/goc/nav-logo-dark@2x-2b3eb08c507c.png;tg=#AliceInWonderLand;sm=%7B%22Facebook%22%3A%22https%3A%2F%2Fwww.facebook.com%2FDisneyAliceInWonderland%22%2C%22Twitter%22%3A%22https%3A%2F%2Ftwitter.com%2FDisney%22%7D;nm=Alice;fn=Alice;ln=Liddell;jt=Adventurer;hs=https://encrypted-tbn0.gstatic.com/images?q%3dtbn:ANd9GcR2Q1GWX6hdmMr2dh10SoTeEKEn4S4toc4V3yAJCrPQHlzWvr_I;cp=Customer Support;email=alice@disney.com>"
},
"call_insight" : {
"call_treatment" : "allow",
"fraud_score" : 0,
"category_id" : 0,
"data_model" : "titan",
"category" : "N/A",
"overlay_name" : "[V] ",
"original_calling_name" : "Alice"
}
}
The description of the fields in the response is as below:
Path | Type | Optional | Description |
---|---|---|---|
|
|
|
Verification status |
|
|
|
Client supplied request identifier for tracking purpose |
|
|
|
'verstat' value defined by ETSI TS 124 299 |
|
|
|
A list of information related to SIP Identity headers verified |
|
|
|
CNAM data |
|
|
|
ECNAM data |
|
|
|
Call Insight object containing Robocall mitigation data |
Example with Re-signed Identity
The following is an example for verifying SIP Identity headers with minimum request data elements and generating a re-signed SIP Identity header:
$ curl 'https://ca-verify.neustarlab.biz/ccid/verify/v2/identity?apiKey=%3CapiKey6%3E' -i -X POST \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
"from" : "\"alice\" <sip:+15714340000@example.com>",
"to" : "\"bob\" <sip:+15714340001@example.com>",
"identity" : [ "eyJhbGciOiJFUzI1NiIsInR5cCI6InBhc3Nwb3J0IiwieDV1IjoiaHR0cDovL2NhLmV4YW1wbGUuY29tL3Rlc3QuZGVyIn0.eyJkZXN0Ijp7InRuIjpbIjE1NzE0MzQwMDAxIl19LCJpYXQiOjE3MzI1NjY1MjIsIm9yaWciOnsidG4iOiIxNTcxNDM0MDAwMCJ9fQ.KlkAPHarKgq0f4AdKYVy6ZRJU6hKSe9lKebRvRICGJ5u9ZrTEpJ1iT7H-bIyG_3eR3h8ENHWfZqtqqR5YSJ8EQ;info=<http://ca.example.com/test.der>;alg=ES256" ]
}'
The description of the fields in the request is as below:
Path | Type | Optional | Description | Constraints |
---|---|---|---|---|
|
|
|
'From' header value from SIP INVITE message |
Required |
|
|
|
'To' header value from SIP INVITE message |
Required |
|
|
|
A list of SIP Identity values to be verified |
Required |
The successful response message is as below with a re-signed SIP Identity header:
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 503
{
"status" : "ok",
"resigned_identity" : "eyJhbGciOiJFUzI1NiIsInBwdCI6InNoYWtlbiIsInR5cCI6InBhc3Nwb3J0IiwieDV1IjoiaHR0cDovL2NhLmV4YW1wbGUuY29tL3Rlc3QuZGVyIn0.eyJhdHRlc3QiOiJBIiwiZGVzdCI6eyJ0biI6WyIxNTcxNDM0MDAwMSJdfSwiaWF0IjoxNzMyNTY2NTIyLCJvcmlnIjp7InRuIjoiMTU3MTQzNDAwMDAifSwib3JpZ2lkIjoiMTIzNDU2LUFCQ0QtOTk5OTk5IiwicmNkIjp7Im5hbSI6ImFsaWNlIn19.weILmsEQ975EpkB-s7SL4NVe05UMSbEGXpmoXZsnN6bvz4gbyp-0fgLyVQ8xFB0_n5QOjx-f2186KjxHqI25RA;info=<http://ca.example.com/test.der>;alg=ES256;ppt=\"shaken\""
}
The description of the fields in the response is as below:
Path | Type | Optional | Description |
---|---|---|---|
|
|
|
Verification status |
|
|
|
The re-signed SIP Identity header that has been successfully generated |
Example with Re-signed Identity plus RCD Data
If the re-signing option has the with_rcd_data function enabled, a re-signed SIP Identity header may contain RCD data extracted from a verified SIP Identity header, with ppt as rcd, or shaken with RCD data, including the following data fields:
-
crn - Call reason
-
apn - Alternate Presentation Number
-
nam - Caller name
-
icn - Caller logo/icon URI
-
jcl - Jcard URL
-
jcd - Jcard data
-
iss - RCD data issuer
-
If the iss claim is not specified in the PASSporT, its value will be derived from the O, OU or CN fields of the Subject X500 name of the signing certificate of the verified SIP Identity header containing the RCD data
-
Currently, the rcdi data field in a PASSporT claim will not be used for re-signing with RCD data. |
The following is an example for verifying SIP Identity headers containing RCD data and generating a re-signed SIP Identity header containing extracted RCD data:
$ curl 'https://ca-verify.neustarlab.biz/ccid/verify/v2/identity?apiKey=%3CapiKey6%3E' -i -X POST \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
"from" : "\"alice\" <sip:+15714340000@example.com>",
"to" : "\"bob\" <sip:+15714340001@example.com>",
"identity" : [ "eyJhbGciOiJFUzI1NiIsInBwdCI6InJjZCIsInR5cCI6InBhc3Nwb3J0IiwieDV1IjoiaHR0cDovL2NhLmV4YW1wbGUuY29tL3Rlc3QuZGVyIn0.eyJjcm4iOiJUcmF2ZWwiLCJkZXN0Ijp7InRuIjpbIjE1NzE0MzQwMDAxIl19LCJpYXQiOjE3MzI1NjY1MjIsImlzcyI6IkRpc25leSwgSW5jLiIsIm9yaWciOnsidG4iOiIxNTcxNDM0MDAwMCJ9LCJyY2QiOnsiYXBuIjoiMTgwMDU1NTAwMDAiLCJpY24iOiJkYXRhOmltYWdlL3BuZztiYXNlNjQsaVZCT1J3MEtHZ29BQUFBTlNVaEVVZ0FBQUFVQUFBQUZDQVlBQUFDTmJ5YmxBQUFBSEVsRVFWUUkxMlA0Ly84L3czOEdJQVhESUJLRTBESHhnbGpOQkFBTzlUWEwwWTRPSHdBQUFBQkpSVTVFcmtKZ2dnPT0iLCJqY2QiOlsidmNhcmQiLFtbInZlcnNpb24iLHt9LCJ0ZXh0IiwiNC4wIl0sWyJmbiIse30sInRleHQiLCJBbGljZSBMaWRkZWxsIl0sWyJlbWFpbCIse30sInRleHQiLCJhbGljZUBleGFtcGxlLmNvbSJdXV0sIm5hbSI6IkFsaWNlIn0sInJjZGkiOnsiL2FwbiI6InNoYTI1Ni12SENSRzEyakM2WE05Uk9PMXdzREZPcGplQUQ0STJjNzROVVFrbHpuNHpZPSIsIi9pY24iOiJzaGEyNTYtSjhsZ29yUTNCVG8zRk94ODVLQjBxVytrMFRUMWpGVk0zU0lhUnlLQkg5dz0iLCIvamNkIjoic2hhMjU2LUhaeC9OLzF4T0JwRW9mc2hiWjJYampRMzFPRHV2cGVGWnRrbG5xMnpaRzg9IiwiL25hbSI6InNoYTI1Ni1POFVRWXBjOFJZMWFieTJOWktBakpHTlVyWDRHU3g1T0FKN0lvR21hTUVNPSJ9fQ.7_ycIbSBlmWlTlm1AJ8ASBfKMLqKLNmxDDjAarn2OJJv4hKKqaAvqksQjKdBKQ6wDcwnhzH0spJrr44jagPcjA;info=<http://ca.example.com/test.der>;alg=ES256;ppt=\"rcd\"" ]
}'
The description of the fields in the request is as below:
Path | Type | Optional | Description | Constraints |
---|---|---|---|---|
|
|
|
'From' header value from SIP INVITE message |
Required |
|
|
|
'To' header value from SIP INVITE message |
Required |
|
|
|
A list of SIP Identity values to be verified |
Required |
The successful response message is as below with a re-signed SIP Identity header:
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 993
{
"status" : "ok",
"resigned_identity" : "eyJhbGciOiJFUzI1NiIsInBwdCI6InNoYWtlbiIsInR5cCI6InBhc3Nwb3J0IiwieDV1IjoiaHR0cDovL2NhLmV4YW1wbGUuY29tL3Rlc3QuZGVyIn0.eyJhdHRlc3QiOiJBIiwiY3JuIjoiVHJhdmVsIiwiZGVzdCI6eyJ0biI6WyIxNTcxNDM0MDAwMSJdfSwiaWF0IjoxNzMyNTY2NTIyLCJpc3MiOiJEaXNuZXksIEluYy4iLCJvcmlnIjp7InRuIjoiMTU3MTQzNDAwMDAifSwib3JpZ2lkIjoiMTIzNDU2LUFCQ0QtOTk5OTk5IiwicmNkIjp7ImFwbiI6IjE4MDA1NTUwMDAwIiwiamNkIjpbInZjYXJkIixbWyJ2ZXJzaW9uIix7fSwidGV4dCIsIjQuMCJdLFsiZm4iLHt9LCJ0ZXh0IiwiQWxpY2UgTGlkZGVsbCJdLFsiZW1haWwiLHt9LCJ0ZXh0IiwiYWxpY2VAZXhhbXBsZS5jb20iXV1dLCJuYW0iOiJBbGljZSJ9LCJyY2RpIjp7Ii9hcG4iOiJzaGEyNTYtdkhDUkcxMmpDNlhNOVJPTzF3c0RGT3BqZUFENEkyYzc0TlVRa2x6bjR6WT0iLCIvamNkIjoic2hhMjU2LUhaeC9OLzF4T0JwRW9mc2hiWjJYampRMzFPRHV2cGVGWnRrbG5xMnpaRzg9IiwiL25hbSI6InNoYTI1Ni1POFVRWXBjOFJZMWFieTJOWktBakpHTlVyWDRHU3g1T0FKN0lvR21hTUVNPSJ9fQ.lDu9pVQ_QonbtaxMR6ExhbI8OClmzE5D9C3YkUF6qjyUIhGzmUcqBJMP5K_vrcHxzh4voXGYWCw0W17IccBRDw;info=<http://ca.example.com/test.der>;alg=ES256;ppt=\"shaken\""
}
The description of the fields in the response is as below:
Path | Type | Optional | Description |
---|---|---|---|
|
|
|
Verification status |
|
|
|
The re-signed SIP Identity header that has been successfully generated |
Example with Re-signing Error
The following is an example for verifying SIP Identity headers with minimum request data elements, and with re-signing request failed:
$ curl 'https://ca-verify.neustarlab.biz/ccid/verify/v2/identity?apiKey=%3CapiKey6%3E' -i -X POST \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
"from" : "\"alice\" <sip:+15714340000@example.com>",
"to" : "\"bob\" <sip:+15714340001@example.com>",
"identity" : [ "eyJhbGciOiJFUzI1NiIsInR5cCI6InBhc3Nwb3J0IiwieDV1IjoiaHR0cDovL2NhLmV4YW1wbGUuY29tL3Rlc3QuZGVyIn0.eyJkZXN0Ijp7InRuIjpbIjE1NzE0MzQwMDAxIl19LCJpYXQiOjE3MzI1NjY1MjIsIm9yaWciOnsidG4iOiIxNTcxNDM0MDAwMCJ9fQ.dhEZuCbBIN5oNKgfMRpdZpkPqmNpAO3hCg5hswJ7yaozPhpWBdlkIppm6GJIj8CgbPOi3n_CKxLk5UhlRAQVqA;info=<http://ca.example.com/test.der>;alg=ES256" ]
}'
The description of the fields in the request is as below:
Path | Type | Optional | Description | Constraints |
---|---|---|---|---|
|
|
|
'From' header value from SIP INVITE message |
Required |
|
|
|
'To' header value from SIP INVITE message |
Required |
|
|
|
A list of SIP Identity values to be verified |
Required |
The response message below shows that the SIP Identity header is successful verified, but contains an "error" field indicating that SIP Identity re-signing process failed, with an "external_error" attribute conveying the reason of the re-signing failure:
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 583
{
"status" : "ok",
"error" : [ {
"error_id" : "ServiceErrorInResigningIdentity",
"http_status_code" : 503,
"sip_code" : 503,
"reason" : "Service or request error in re-signing identity header",
"timestamp" : "Mon, 25 Nov 2024 20:28:42 GMT",
"developer_message" : "No authentication response",
"attributes" : {
"external_error" : {
"error_id" : "ApiKeyInvalid",
"http_status_code" : 400,
"sip_code" : 400,
"reason" : "API key is invalid",
"timestamp" : "Mon, 25 Nov 2024 20:28:42 GMT"
}
}
} ]
}
The description of the fields in the response is as below:
Path | Type | Optional | Description |
---|---|---|---|
|
|
|
Verification status |
|
|
|
A list of errors encountered in verifying SIP Identity headers |
Error Response Example
The following is an example of error responses produced by the CCID VS if there are any errors encountered during the SIP Identity header verification, and CNAM/ECNAM lookup:
$ curl 'https://ca-verify.neustarlab.biz/ccid/verify/v2/identity?apiKey=%3CapiKey5%3E' -i -X POST \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
"from" : "\"alice\" <sip:+15715550000@example.com>",
"to" : "\"bob\" <sip:+15715550001@example.com>",
"date" : "Mon, 25 Nov 2024 20:28:41 GMT",
"identity" : [ "..z1imdQUcMnkXsVarFLA_R_--zsuc2iq9LMu5heL1_QVEdtnqHb8R64O2X4qA1l4l5xmpm5azdNnZI0L4ftHLvQ;info=<http://ca.example.com/test.der>;alg=ES256" ],
"status" : "all",
"cnam" : true,
"ecnam" : true
}'
The description of the fields in the request is as below:
Path | Type | Optional | Description | Constraints |
---|---|---|---|---|
|
|
|
Verification status requirement |
If specified, must be 'none', 'partial' or 'all' |
|
|
|
'From' header value from SIP INVITE message |
Required |
|
|
|
'To' header value from SIP INVITE message |
Required |
|
|
|
'Date' header value from SIP INVITE message |
If specified, must be in RFC1123 format |
|
|
|
A list of SIP Identity values to be verified |
Required |
|
|
|
Boolean flag for performing CNAM lookup |
If specified, must be true or false |
|
|
|
Boolean flag for performing ECNAM lookup |
If specified, must be true or false |
The error response message is as below:
HTTP/1.1 400 Bad Request
Content-Type: application/json
Content-Length: 1038
{
"status" : "error",
"error" : [ {
"error_id" : "IdentitySignatureVerifyFailed",
"http_status_code" : 400,
"sip_code" : 438,
"reason" : "Identity signature failed to be verified",
"timestamp" : "Mon, 25 Nov 2024 20:28:41 GMT",
"attributes" : {
"payload" : "eyJhbGciOiJFUzI1NiIsInR5cCI6InBhc3Nwb3J0IiwieDV1IjoiaHR0cDovL2NhLmV4YW1wbGUuY29tL3Rlc3QuZGVyIn0.eyJkZXN0Ijp7InRuIjpbIjE1NzE1NTUwMDAxIl19LCJpYXQiOjE3MzI1NjY1MjQsIm9yaWciOnsidG4iOiIxNTcxNTU1MDAwMCJ9fQ",
"signature" : "z1imdQUcMnkXsVarFLA_R_--zsuc2iq9LMu5heL1_QVEdtnqHb8R64O2X4qA1l4l5xmpm5azdNnZI0L4ftHLvQ"
}
} ],
"cnam_error" : {
"error_id" : "CnamNotAuthorized",
"http_status_code" : 400,
"sip_code" : 400,
"reason" : "CNAM service not authorized",
"timestamp" : "Mon, 25 Nov 2024 20:28:41 GMT"
},
"ecnam_error" : {
"error_id" : "EcnamNotAuthorized",
"http_status_code" : 400,
"sip_code" : 400,
"reason" : "ECNAM service not authorized",
"timestamp" : "Mon, 25 Nov 2024 20:28:41 GMT"
}
}
The description of the fields in the response is as below:
Path | Type | Optional | Description |
---|---|---|---|
|
|
|
Verification status |
|
|
|
A list of errors encountered in verifying SIP Identity headers |
|
|
|
The unique error identifier |
|
|
|
The HTTP response status code |
|
|
|
The SIP response code associated with the error |
|
|
|
The detailed error text |
|
|
|
The timestamp when the error is generated |
|
|
|
The name/value pair .attribute map associated with the error |
|
|
|
The attribute name of 'payload' in the name/value pair |
|
|
|
The attribute name of 'signature' in the name/value pair |
|
|
|
The error encountered in CNAM lookup |
|
|
|
The unique error identifier |
|
|
|
The HTTP response status code |
|
|
|
The SIP response code associated with the error |
|
|
|
The detailed error text |
|
|
|
The timestamp when the error is generated |
|
|
|
The error encountered in ECNAM lookup |
|
|
|
The unique error identifier |
|
|
|
The HTTP response status code |
|
|
|
The SIP response code associated with the error |
|
|
|
The detailed error text |
|
|
|
The timestamp when the error is generated |
Error Response Example with Diverted Calls
The following is an example of error responses produced by the CCID VS if there are any errors encountered during the SIP Identity header verification, for a diverted call terminated at sip:bob@example.com that could not be traced back to the originator:
$ curl 'https://ca-verify.neustarlab.biz/ccid/verify/v2/identity?apiKey=%3CapiKey1%3E' -i -X POST \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
"from" : "\"alice\" <sip:+15715550000@example.com>",
"to" : "\"bob\" <sip:bob@example.com>",
"identity" : [ "..vUs-gs6PJoKQBJKIa48W5RYeu-rc2KJt75LVs_Zi7DT0X3gwFsUYii29nChFaJg1QA3hTFQBl902XUSc-yK8Cg;info=<http://ca.example.com/test.der>;alg=ES256", "..ux03BnKDXnWH5W40xBXb4K_KBeUW1Pee514F2UOwS8DHpQBLXfgDY7YtRno7O2Ie2W4MEKai5qmJY-7svuk4tQ;info=<http://ca.example.com/test.der>;alg=ES256;ppt=\"div\"" ],
"diversion" : [ "\"bob\" <sip:+15715550001@example.com>;reason=away", "\"bob\" <sip:+15715550002@example.com>;reason=away" ]
}'
The description of the fields in the request is as below:
Path | Type | Optional | Description | Constraints |
---|---|---|---|---|
|
|
|
'From' header value from SIP INVITE message |
Required |
|
|
|
'To' header value from SIP INVITE message |
Required |
|
|
|
A list of 'Diversion' header values from SIP INVITE message |
If specified, must be one as specified in RFC5806 Section 4 |
|
|
|
A list of SIP Identity values to be verified |
Required |
The error response message is as below:
HTTP/1.1 400 Bad Request
Content-Type: application/json
Content-Length: 901
{
"status" : "error",
"error" : [ {
"error_id" : "IdentityClaimDivEndNotFound",
"http_status_code" : 400,
"sip_code" : 438,
"reason" : "Identity diversion claim chain does not end with SIP To Header",
"timestamp" : "Mon, 25 Nov 2024 20:28:40 GMT",
"attributes" : {
"identity" : "..vUs-gs6PJoKQBJKIa48W5RYeu-rc2KJt75LVs_Zi7DT0X3gwFsUYii29nChFaJg1QA3hTFQBl902XUSc-yK8Cg;info=<http://ca.example.com/test.der>;alg=ES256"
}
}, {
"error_id" : "IdentityClaimDivStartInvalid",
"http_status_code" : 400,
"sip_code" : 438,
"reason" : "Identity diversion claim chain does start with a regular claim",
"timestamp" : "Mon, 25 Nov 2024 20:28:41 GMT",
"attributes" : {
"identity" : "..ux03BnKDXnWH5W40xBXb4K_KBeUW1Pee514F2UOwS8DHpQBLXfgDY7YtRno7O2Ie2W4MEKai5qmJY-7svuk4tQ;info=<http://ca.example.com/test.der>;alg=ES256;ppt=\"div\""
}
} ]
}
The description of the fields in the response is as below:
Path | Type | Optional | Description |
---|---|---|---|
|
|
|
Verification status |
|
|
|
Verification status |
|
|
|
A list of errors encountered in verifying SIP Identity headers |
|
|
|
The unique error identifier |
|
|
|
The HTTP response status code |
|
|
|
The SIP response code associated with the error |
|
|
|
The detailed error text |
|
|
|
The timestamp when the error is generated |
|
|
|
The name/value pair .attribute map associated with the error |
|
|
|
The attribute name of 'identity' in the name/value pair |
With SIP INVITE Message & Response in JSON Format
This API entry point accepts SIP INVITE messages with SIP Identity headers as requests and produces responses in JSON Format.
API Method |
|
|
API Path |
|
|
Required Parameters |
Name |
Description |
|
The API key uniquely identifying the API client |
|
Optional Parameters |
Name |
Description |
status |
The verification status requirement |
|
origcc |
Default country codes for the originator telephone number |
|
destcc |
Default country code for the destination telephone number |
|
cnam |
Boolean flag for performing CNAM lookup |
|
ecnam |
Boolean flag for performing ECNAM lookup |
|
robocall |
Boolean flag for returning Robocall Call Insight data |
|
cvt |
Boolean flag to invoke CVT service for CNAM/ECNAM/Robocall data |
Request |
Content-Type |
application/text |
|
Body (example) |
INVITE sip:+15715550001@proxy.example.com;transport=UDP SIP/2.0 From: "alice" <sip:+15715550000@example.com>;tag=1f4e4f40 To: "bob" <sip:+15715550001@example.com> Date: Thu, 17 Aug 2017 15:09:27 GMT Identity: ey.x.oQ;info=<http://www.example.com/cert/123>;alg=ES256 ... |
Successful Response |
HTTP Code |
200 OK |
|
Content-Type |
application/json |
|
Body (example) |
{ "status" : "ok" } |
Error Response |
HTTP Code |
4xx, 5xx |
|
Content-Type |
application/json |
Same as described in the previous section with the "status" attribute, the "status" parameter in the request URL will specify the verification status requirement. And the "cnam" and "ecnam" parameters will have the same functions as the "cnam" and "ecnam" attributes described in the previous section.
Example with SIP INVITE Message
The following is an example for verifying SIP Identity headers by submitting a SIP INVITE message as the request:
$ curl 'https://ca-verify.neustarlab.biz/ccid/verify/v2/identity?apiKey=%3CapiKey1%3E' -i -X POST \
-H 'Content-Type: text/plain' \
-H 'Accept: application/json' \
-d 'INVITE sip:+15715550001@proxy.example.com;transport=UDP SIP/2.0
Via: SIP/2.0/UDP proxy.example.com:39089;branch=z9hG4bK-d8754za
Max-Forwards: 70
Contact: "alice" <sip:alice@proxy.example.com:39089;transport=UDP>
From: "alice" <sip:+15715550000@example.com>;tag=1f4e4f40
To: "bob" <sip:+15715550001@example.com>
Date: Mon, 25 Nov 2024 20:28:42 GMT
Call-ID: YzRlZDFlYzYyM2IwOTdlMzk0MDA3MTRmZmY3OGIzODM.
Identity: eyJhbGciOiJFUzI1NiIsInR5cCI6InBhc3Nwb3J0IiwieDV1IjoiaHR0cDovL2NhLmV4YW1wbGUuY29tL3Rlc3QuZGVyIn0.eyJkZXN0Ijp7InRuIjpbIjE1NzE1NTUwMDAxIl19LCJpYXQiOjE3MzI1NjY1MjIsIm9yaWciOnsidG4iOiIxNTcxNTU1MDAwMCJ9fQ.dYohcxX8Dr6S9AeQSpaiPsF1avSz5Sn2VsnKI53IWo-q8kUqhxKc2nDh-OY77W0FevLPg80ezyFRX74FXKJlhA;info=<http://ca.example.com/test.der>;alg=ES256
CSeq: 2 INVITE
Content-Type: application/sdp
User-Agent: Z 3.3.25608 r25552
Supported: replaces, norefersub, extended-refer, timer
Allow-Events: presence, kpml
Content-Length: 239
v=0
o=Z 0 0 IN IP4 10.31.32.251
s=Z
c=IN IP4 10.31.32.251
t=0 0
m=audio 8000 RTP/AVP 8 0 3 110 98 101
a=rtpmap:110 speex/8000
a=rtpmap:98 iLBC/8000
a=fmtp:98 mode=20
a=rtpmap:101 telephone-event/8000
a=fmtp:101 0-15
a=sendrecv
'
The successful response message is as below:
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 21
{
"status" : "ok"
}
The description of the fields in the response is as below:
Path | Type | Optional | Description |
---|---|---|---|
|
|
|
Verification status |
Example with Full Set of Parameters
The following is an example for verifying SIP Identity headers by submitting a SIP INVITE message as the request with all available URL parameters:
$ curl 'https://ca-verify.neustarlab.biz/ccid/verify/v2/identity?apiKey=%3CapiKey1%3E&status=all&origcc=1,44&destcc=1&cnam=true&ecnam=true&robocall=true' -i -X POST \
-H 'Content-Type: text/plain' \
-H 'Accept: application/json' \
-d 'INVITE sip:+15714340001@proxy.example.com;transport=UDP SIP/2.0
v: SIP/2.0/UDP proxy.example.com:39089;branch=z9hG4bK-d8754za
Max-Forwards: 70
m: "alice" <sip:alice@proxy.example.com:39089;transport=UDP>
f: "alice" <sip:+15714340000@example.com>;tag=1f4e4f40
t: "bob" <sip:+15714340001@example.com>
Date: Mon, 25 Nov 2024 20:28:42 GMT
i: YzRlZDFlYzYyM2IwOTdlMzk0MDA3MTRmZmY3OGIzODM.
y: eyJhbGciOiJFUzI1NiIsInBwdCI6InNoYWtlbiIsInR5cCI6InBhc3Nwb3J0IiwieDV1IjoiaHR0cDovL2NhLmV4YW1wbGUuY29tL3Rlc3QuZGVyIn0.eyJhdHRlc3QiOiJBIiwiZGVzdCI6eyJ0biI6WyIxNTcxNDM0MDAwMSJdfSwiaWF0IjoxNzMyNTY2NTIyLCJta3kiOlt7ImFsZyI6IlNIQS0xIiwiZGlnIjoiNEFBREI5QjEzRjgyMTgzQjU0MDIxMkRGM0U1RDQ5NkIxOUU1N0NBQiJ9LHsiYWxnIjoiU0hBLTI1NiIsImRpZyI6IjM2M0JBRTEyOTU5NUY1OTcyREY3RTA4NEZFQ0RGMUJDQUQ3QTcwNjRGN0U3NEY3RUE2MDIwNjBFMzc1NENGRjcifV0sIm9yaWciOnsidG4iOiIxNzAzNTU1MDAwMSJ9LCJvcmlnaWQiOiIxMjM0NTYtQUJDRC05OTk5OTkiLCJyY2QiOnsibmFtIjoiQWxpY2UifX0.pSeovtPuH2xcdxFIJlK61LdcUHpkhl_PxxdC3hdqfCM1rmJOMEWtJMc5eBJ-gN2jAigE2hzxP0nit_v8YJGTug;info=<http://ca.example.com/test.der>;alg=ES256;ppt="shaken"
P-Asserted-Identity: "Alice" <tel:+17035550001>
P-Asserted-Identity: "Alice" <sip:+17035550001@example.com>
CSeq: 2 INVITE
c: application/sdp
User-Agent: Z 3.3.25608 r25552
k: replaces, norefersub, extended-refer, timer
Allow-Events: presence, kpml
l: 439
v=0
o=Z 0 0 IN IP4 10.31.32.251
s=Z
c=IN IP4 10.31.32.251
t=0 0
m=audio 8000 RTP/AVP 8 0 3 110 98 101
a=fingerprint:SHA-1 4A:AD:B9:B1:3F:82:18:3B:54:02:12:DF:3E:5D:49:6B:19:E5:7C:AB
a=fingerprint:SHA-256 36:3B:AE:12:95:95:F5:97:2D:F7:E0:84:FE:CD:F1:BC:AD:7A:70:64:F7:E7:4F:7E:A6:02:06:0E:37:54:CF:F7
a=rtpmap:110 speex/8000
a=rtpmap:98 iLBC/8000
a=fmtp:98 mode=20
a=rtpmap:101 telephone-event/8000
a=fmtp:101 0-15
a=sendrecv
'
The description of the parameters in the request URL is as below:
Parameter | Type | Optional | Description | Constraints |
---|---|---|---|---|
|
|
|
The API key for identifying the API client |
Cannot be null or empty |
|
|
|
Verification status requirement |
If specified, must be 'none', 'partial' or 'all' |
|
|
|
Default country codes for the originator telephone number |
If specified, must be a list of valid country codes separated by ',' or white spaces |
|
|
|
Default country code for the destination telephone number |
If specified, must be a valid country code |
|
|
|
Boolean flag for performing CNAM lookup |
If specified, must be 'true' or 'false' |
|
|
|
Boolean flag for performing ECNAM lookup |
If specified, must be 'true' or 'false' |
|
|
|
Boolean flag for returning Robocall Call Insight data |
If specified, must be 'true' or 'false' |
The successful response message is as below:
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 2188
{
"status" : "ok",
"cnam" : "Alice In Wonderland",
"ecnam" : {
"cnam" : "Alice In Wonderland",
"display_template" : "none",
"business_name" : "Disney World",
"department" : "Theme Park",
"line_type" : "Wireline",
"subscriber_type" : "Business",
"business_type" : "Entertainment",
"business_address" : "Walt Disney World Resort",
"locality" : "Orlando, FL",
"city" : "Orlando",
"state" : "FL",
"country" : "US",
"postal_code" : "32830",
"website_url" : "http://movies.disney.com/alice-in-wonderland-1951",
"logo_url" : "https://static-mh.content.disney.io/matterhorn/assets/goc/nav-logo-dark@2x-2b3eb08c507c.png",
"tagline" : "#AliceInWonderLand",
"employee_name" : "Alice",
"first_name" : "Alice",
"last_name" : "Liddell",
"job_title" : "Adventurer",
"headshot_url" : "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcR2Q1GWX6hdmMr2dh10SoTeEKEn4S4toc4V3yAJCrPQHlzWvr_I",
"email" : "alice@disney.com",
"call_purpose" : "Customer Support",
"social_media_info" : {
"Facebook" : "https://www.facebook.com/DisneyAliceInWonderland",
"Twitter" : "https://twitter.com/Disney"
},
"p_asserted_identity" : "\"Alice In Wonderland\" <sip:alice@example.com;tmpl=none;bn=Disney%20World;dept=Theme%20Park;lt=Wireline;st=Business;bt=Entertainment;ba=Walt%20Disney%20World%20Resort;cs=Orlando, FL;city=Orlando;state=FL;ct=US;zip=32830;wb=http://movies.disney.com/alice-in-wonderland-1951;lg=https://static-mh.content.disney.io/matterhorn/assets/goc/nav-logo-dark@2x-2b3eb08c507c.png;tg=#AliceInWonderLand;sm=%7B%22Facebook%22%3A%22https%3A%2F%2Fwww.facebook.com%2FDisneyAliceInWonderland%22%2C%22Twitter%22%3A%22https%3A%2F%2Ftwitter.com%2FDisney%22%7D;nm=Alice;fn=Alice;ln=Liddell;jt=Adventurer;hs=https://encrypted-tbn0.gstatic.com/images?q%3dtbn:ANd9GcR2Q1GWX6hdmMr2dh10SoTeEKEn4S4toc4V3yAJCrPQHlzWvr_I;cp=Customer Support;email=alice@disney.com>"
},
"call_insight" : {
"call_treatment" : "allow",
"fraud_score" : 0,
"category_id" : 0,
"data_model" : "titan",
"category" : "N/A",
"overlay_name" : "[V] ",
"original_calling_name" : "Alice"
}
}
The description of the fields in the response is as below:
Path | Type | Optional | Description |
---|---|---|---|
|
|
|
Verification status |
|
|
|
CNAM data |
|
|
|
ECNAM data |
|
|
|
Call Insight object containing Robocall mitigation data |
Example with Re-signed Identity
The following is an example for verifying SIP Identity headers by submitting a SIP INVITE message as the request and generating a re-signed SIP Identity header:
$ curl 'https://ca-verify.neustarlab.biz/ccid/verify/v2/identity?apiKey=%3CapiKey6%3E' -i -X POST \
-H 'Content-Type: text/plain' \
-H 'Accept: application/json' \
-d 'INVITE sip:+15714340001@proxy.example.com;transport=UDP SIP/2.0
Via: SIP/2.0/UDP proxy.example.com:39089;branch=z9hG4bK-d8754za
Max-Forwards: 70
Contact: "alice" <sip:alice@proxy.example.com:39089;transport=UDP>
From: "alice" <sip:+15714340000@example.com>;tag=1f4e4f40
To: "bob" <sip:+15714340001@example.com>
Date: Mon, 25 Nov 2024 20:28:42 GMT
Call-ID: YzRlZDFlYzYyM2IwOTdlMzk0MDA3MTRmZmY3OGIzODM.
Identity: eyJhbGciOiJFUzI1NiIsInR5cCI6InBhc3Nwb3J0IiwieDV1IjoiaHR0cDovL2NhLmV4YW1wbGUuY29tL3Rlc3QuZGVyIn0.eyJkZXN0Ijp7InRuIjpbIjE1NzE0MzQwMDAxIl19LCJpYXQiOjE3MzI1NjY1MjIsIm9yaWciOnsidG4iOiIxNTcxNDM0MDAwMCJ9fQ.272E0UsPcPUGVuVr7B-gHkRp_oa7CcvJppe7FBK9rim4W1hDXi5tmxaAil5OHeg1CfRFdFS1CbQm02EmSbMZRQ;info=<http://ca.example.com/test.der>;alg=ES256
CSeq: 2 INVITE
Content-Type: application/sdp
User-Agent: Z 3.3.25608 r25552
Supported: replaces, norefersub, extended-refer, timer
Allow-Events: presence, kpml
Content-Length: 239
v=0
o=Z 0 0 IN IP4 10.31.32.251
s=Z
c=IN IP4 10.31.32.251
t=0 0
m=audio 8000 RTP/AVP 8 0 3 110 98 101
a=rtpmap:110 speex/8000
a=rtpmap:98 iLBC/8000
a=fmtp:98 mode=20
a=rtpmap:101 telephone-event/8000
a=fmtp:101 0-15
a=sendrecv
'
The successful response message is as below with a re-signed SIP Identity header:
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 503
{
"status" : "ok",
"resigned_identity" : "eyJhbGciOiJFUzI1NiIsInBwdCI6InNoYWtlbiIsInR5cCI6InBhc3Nwb3J0IiwieDV1IjoiaHR0cDovL2NhLmV4YW1wbGUuY29tL3Rlc3QuZGVyIn0.eyJhdHRlc3QiOiJBIiwiZGVzdCI6eyJ0biI6WyIxNTcxNDM0MDAwMSJdfSwiaWF0IjoxNzMyNTY2NTIyLCJvcmlnIjp7InRuIjoiMTU3MTQzNDAwMDAifSwib3JpZ2lkIjoiMTIzNDU2LUFCQ0QtOTk5OTk5IiwicmNkIjp7Im5hbSI6ImFsaWNlIn19.mw0hSLqAmGdDN9H6_ijED7ogiBrYOpXJCFS8arV60oeqjIkkJJcUFsl8AN91Gv8x-RbJbkwvsObTUskWDP62yw;info=<http://ca.example.com/test.der>;alg=ES256;ppt=\"shaken\""
}
The description of the fields in the response is as below:
Path | Type | Optional | Description |
---|---|---|---|
|
|
|
Verification status |
|
|
|
The re-signed SIP Identity header that has been successfully generated |
Example with Re-signing Error
The following is an example for verifying SIP Identity headers submitting a SIP INVITE message as the request and with re-signing request failed:
$ curl 'https://ca-verify.neustarlab.biz/ccid/verify/v2/identity?apiKey=%3CapiKey6%3E' -i -X POST \
-H 'Content-Type: text/plain' \
-H 'Accept: application/json' \
-d 'INVITE sip:+15714340001@proxy.example.com;transport=UDP SIP/2.0
Via: SIP/2.0/UDP proxy.example.com:39089;branch=z9hG4bK-d8754za
Max-Forwards: 70
Contact: "alice" <sip:alice@proxy.example.com:39089;transport=UDP>
From: "alice" <sip:+15714340000@example.com>;tag=1f4e4f40
To: "bob" <sip:+15714340001@example.com>
Date: Mon, 25 Nov 2024 20:28:42 GMT
Call-ID: YzRlZDFlYzYyM2IwOTdlMzk0MDA3MTRmZmY3OGIzODM.
Identity: eyJhbGciOiJFUzI1NiIsInR5cCI6InBhc3Nwb3J0IiwieDV1IjoiaHR0cDovL2NhLmV4YW1wbGUuY29tL3Rlc3QuZGVyIn0.eyJkZXN0Ijp7InRuIjpbIjE1NzE0MzQwMDAxIl19LCJpYXQiOjE3MzI1NjY1MjIsIm9yaWciOnsidG4iOiIxNTcxNDM0MDAwMCJ9fQ.7-OuXYaluXKuZAo_gswXAt_J98myIpWOCVp8898eyqFAzcrfTrnTx7HH84pqTjaBjhJP7vcqzTZ-mQDdJ3BJvQ;info=<http://ca.example.com/test.der>;alg=ES256
CSeq: 2 INVITE
Content-Type: application/sdp
User-Agent: Z 3.3.25608 r25552
Supported: replaces, norefersub, extended-refer, timer
Allow-Events: presence, kpml
Content-Length: 239
v=0
o=Z 0 0 IN IP4 10.31.32.251
s=Z
c=IN IP4 10.31.32.251
t=0 0
m=audio 8000 RTP/AVP 8 0 3 110 98 101
a=rtpmap:110 speex/8000
a=rtpmap:98 iLBC/8000
a=fmtp:98 mode=20
a=rtpmap:101 telephone-event/8000
a=fmtp:101 0-15
a=sendrecv
'
The response message below shows that the SIP Identity header is successful verified, but contains an "error" field indicating that SIP Identity re-signing process failed, with an "external_error" attribute conveying the reason of the re-signing failure:
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 733
{
"status" : "ok",
"error" : [ {
"error_id" : "ServiceErrorInResigningIdentity",
"http_status_code" : 503,
"sip_code" : 503,
"reason" : "Service or request error in re-signing identity header",
"timestamp" : "Mon, 25 Nov 2024 20:28:42 GMT",
"developer_message" : "No authentication response",
"attributes" : {
"external_error" : {
"error_id" : "CredentialExpired",
"http_status_code" : 403,
"sip_code" : 437,
"reason" : "Credential has expired",
"timestamp" : "Mon, 25 Nov 2024 20:28:42 GMT",
"developer_message" : "Certificate has expired at current date/time",
"attributes" : {
"alias" : "test1"
}
}
}
} ]
}
The description of the fields in the response is as below:
Path | Type | Optional | Description |
---|---|---|---|
|
|
|
Verification status |
|
|
|
A list of errors encountered in verifying SIP Identity headers |
Error Response Example
The following is an example of error responses produced by the CCID VS if there are any errors encountered during the SIP Identity header verification for a SIP INVITE message:
$ curl 'https://ca-verify.neustarlab.biz/ccid/verify/v2/identity?apiKey=%3CapiKey5%3E&status=all&origcc=1,44&destcc=1&cnam=true&ecnam=true' -i -X POST \
-H 'Content-Type: text/plain' \
-H 'Accept: application/json' \
-d 'INVITE sip:+15715550001@proxy.example.com;transport=UDP SIP/2.0
Via: SIP/2.0/UDP proxy.example.com:39089;branch=z9hG4bK-d8754za
Max-Forwards: 70
Contact: "alice" <sip:alice@proxy.example.com:39089;transport=UDP>
From: "alice" <sip:+15715550000@example.com>;tag=1f4e4f40
To: "bob" <sip:+15715550001@example.com>
Date: Mon, 25 Nov 2024 20:28:42 GMT
Call-ID: YzRlZDFlYzYyM2IwOTdlMzk0MDA3MTRmZmY3OGIzODM.
Identity: eyJhbGciOiJFUzI1NiIsInR5cCI6InBhc3Nwb3J0IiwieDV1IjoiaHR0cDovL2NhLmV4YW1wbGUuY29tL3Rlc3QuZGVyIn0.eyJkZXN0Ijp7InRuIjpbIjE1NzE1NTUwMDAxIl19LCJpYXQiOjE3MzI1NjY1MjIsIm9yaWciOnsidG4iOiIxNTcxNTU1MDAwMCJ9fQ.bbX-hmXetcFILZING4-bQf2wer5gnBSnczFlYKhiJx9dSyWPoYv-xSKoK9_eI4z4IDfq4US34LzkpeiugNmz5Q;info=<http://ca.example.com/test.der>;alg=ES256
CSeq: 2 INVITE
Content-Type: application/sdp
User-Agent: Z 3.3.25608 r25552
Supported: replaces, norefersub, extended-refer, timer
Allow-Events: presence, kpml
Content-Length: 239
v=0
o=Z 0 0 IN IP4 10.31.32.251
s=Z
c=IN IP4 10.31.32.251
t=0 0
m=audio 8000 RTP/AVP 8 0 3 110 98 101
a=rtpmap:110 speex/8000
a=rtpmap:98 iLBC/8000
a=fmtp:98 mode=20
a=rtpmap:101 telephone-event/8000
a=fmtp:101 0-15
a=sendrecv
'
The description of the parameters in the request URL is as below:
Parameter | Type | Optional | Description | Constraints |
---|---|---|---|---|
|
|
|
The API key for identifying the API client |
Cannot be null or empty |
|
|
|
Verification status requirement |
If specified, must be 'none', 'partial' or 'all' |
|
|
|
Default country codes for the originator telephone number |
If specified, must be a list of valid country codes separated by ',' or white spaces |
|
|
|
Default country code for the destination telephone number |
If specified, must be a valid country code |
|
|
|
Boolean flag for performing CNAM lookup |
If specified, must be 'true' or 'false' |
|
|
|
Boolean flag for performing ECNAM lookup |
If specified, must be 'true' or 'false' |
The error response message is as below:
HTTP/1.1 400 Bad Request
Content-Type: application/json
Content-Length: 1038
{
"status" : "error",
"error" : [ {
"error_id" : "IdentitySignatureVerifyFailed",
"http_status_code" : 400,
"sip_code" : 438,
"reason" : "Identity signature failed to be verified",
"timestamp" : "Mon, 25 Nov 2024 20:28:42 GMT",
"attributes" : {
"payload" : "eyJhbGciOiJFUzI1NiIsInR5cCI6InBhc3Nwb3J0IiwieDV1IjoiaHR0cDovL2NhLmV4YW1wbGUuY29tL3Rlc3QuZGVyIn0.eyJkZXN0Ijp7InRuIjpbIjE1NzE1NTUwMDAxIl19LCJpYXQiOjE3MzI1NjY1MjIsIm9yaWciOnsidG4iOiIxNTcxNTU1MDAwMCJ9fQ",
"signature" : "bbX-hmXetcFILZING4-bQf2wer5gnBSnczFlYKhiJx9dSyWPoYv-xSKoK9_eI4z4IDfq4US34LzkpeiugNmz5Q"
}
} ],
"cnam_error" : {
"error_id" : "CnamNotAuthorized",
"http_status_code" : 400,
"sip_code" : 400,
"reason" : "CNAM service not authorized",
"timestamp" : "Mon, 25 Nov 2024 20:28:42 GMT"
},
"ecnam_error" : {
"error_id" : "EcnamNotAuthorized",
"http_status_code" : 400,
"sip_code" : 400,
"reason" : "ECNAM service not authorized",
"timestamp" : "Mon, 25 Nov 2024 20:28:42 GMT"
}
}
The description of the fields in the response is as below:
Path | Type | Optional | Description |
---|---|---|---|
|
|
|
Verification status |
|
|
|
A list of errors encountered in verifying SIP Identity headers |
|
|
|
The unique error identifier |
|
|
|
The HTTP response status code |
|
|
|
The SIP response code associated with the error |
|
|
|
The detailed error text |
|
|
|
The timestamp when the error is generated |
|
|
|
The name/value pair .attribute map associated with the error |
|
|
|
The attribute name of 'payload' in the name/value pair |
|
|
|
The attribute name of 'signature' in the name/value pair |
|
|
|
The error encountered in CNAM lookup |
|
|
|
The unique error identifier |
|
|
|
The HTTP response status code |
|
|
|
The SIP response code associated with the error |
|
|
|
The detailed error text |
|
|
|
The timestamp when the error is generated |
|
|
|
The error encountered in ECNAM lookup |
|
|
|
The unique error identifier |
|
|
|
The HTTP response status code |
|
|
|
The SIP response code associated with the error |
|
|
|
The detailed error text |
|
|
|
The timestamp when the error is generated |
With SIP INVITE Message & Response in SIP Format
This API entry point accepts SIP INVITE messages with SIP Identity headers as requests and produces responses in SIP Format. If the API client prefers full SIP INVITE messages in the responses with SIP Identity headers embedded in, the following HTTP header needs be specified in the request:
Accept: text/plain
If the verification result of SIP Identity headers has met the verification status requirement, the SIP INVITE message will be returned in the response. The returned SIP INVITE message may have the CNAM field modified if CNAM lookup operation is performed, and/or the "cnamPrefix" parameter is specified. Additionally, the returned SIP INVITE message may include a new SIP P-Asserted-Identity header if a successful ECNAM lookup operation is performed.
If the verification result does not meet the verification status requirement, an error message in SIP format will be returned with proper HTTP status code, SIP code and SIP Reason header, such as:
HTTP/1.1 403 Forbidden Content-Type: text/plain;charset=UTF-8 Content-Length: 197 SIP/2.0 437 Credential has expired ... Reason: SIP;cause=437;text="Credential has expired" ...
If the "verstat" parameter is not specified, i.e. not for tagging, SIP Identity header re-signing process may be triggered, and a new SIP Identity header inserted into the SIP INVITE message, according to pre-defined policy associated with the API key. Additionally, the existing SIP Identity header can be removed by specifying the "identity" parameter as "false". If the re-signing process is failed, a SIP Reason header will be inserted into the SIP INVITE message, indicating the error related to the re-signing failure.
API Method |
|
|
API Path |
|
|
Required Parameters |
Name |
Description |
|
The API key uniquely identifying the API client |
|
Optional Parameters |
Name |
Description |
status |
The verification status requirement |
|
origcc |
Default country codes for the originator telephone number |
|
destcc |
Default country code for the destination telephone number |
|
cnam |
Boolean flag for performing CNAM lookup |
|
ecnam |
Boolean flag for performing ECNAM lookup |
|
robocall |
Boolean flag for returning error based on Robocall Insight data |
|
cvt |
Boolean flag to invoke CVT service for CNAM/ECNAM/Robocall data |
|
cnamPrefix |
Prefix applied to to CNAM data field, indicating if SIP Identity header is verified or not |
|
verstat |
Verstat value as defined in ETSI TS 124 299, for performing tagging and SIP Identity headers optionally removed |
|
identity |
Boolean flag for including SIP Identity header when the "verstat" parameter is specified, with the default value as "true"; or for keeping existing SIP Identity headers after re-signing, if the "verstat" parameter is not specified |
Request |
Content-Type |
application/text |
|
Body (example) |
SIP sip:17035550021@proxy.example.com;transport=UDP SIP/2.0 From: "Alice" <sip:+15714345500@example.com> To: "Bob" <sip:+447035550000@example.com> Date: Fri, 11 Aug 2017 04:17:14 GMT Identity: ey.x.oQ;info=<http://www.example.com/cert/123>;alg=ES256 ... |
Successful Response |
HTTP Code |
200 OK |
|
Content-Type |
application/text |
|
Body (example) |
SIP sip:17035550021@proxy.example.com;transport=UDP SIP/2.0 From: "✔Alice" <sip:+15714345500@example.com> To: "Bob" <sip:+447035550000@example.com> Identity: ey.x.oQ;info=<http://www.example.com/cert/123>;alg=ES256 Date: Fri, 11 Aug 2017 04:17:14 GMT ... |
Error Response |
HTTP Code |
4xx, 5xx |
|
Content-Type |
application/text |
Note if the "verstat" parameter is specified as "TN-Validation-Passed", any errors generated prior to SIP Identity header signature validation will result in a SIP error message to be returned; otherwise, the SIP INVITE message will be returned with SIP/TEL URIs in SIP From/P-Asserted-Identity headers tagged with specified "verstat" value. If there are no errors prior to SIP Identity header signature validation, the SIP/TEL URIs in SIP From/P-Asserted-Identity headers will be tagged with a proper "verstat" value based on the validation result. Additionally, if there are any verified ATIS-SHAKEN PASSporT claims in the SIP Identity headers, new SIP P-Attestation-Indicator/P-Origination-Id headers recorded in the claims will be inserted into the returned SIP INVITE message, with old ones stripped off if any.
Example with Request & Response as SIP INVITE Message
The following is an example of submitting a SIP INVITE message with a SIP Identity header as the request and returning the original SIP INVITE message after the SIP Identity header is successfully verified:
$ curl 'https://ca-verify.neustarlab.biz/ccid/verify/v2/identity?apiKey=%3CapiKey1%3E' -i -X POST \
-H 'Content-Type: text/plain' \
-H 'Accept: text/plain' \
-d 'INVITE sip:+15715550001@proxy.example.com;transport=UDP SIP/2.0
v: SIP/2.0/UDP proxy.example.com:39089;branch=z9hG4bK-d8754za
Max-Forwards: 70
m: "alice" <sip:alice@proxy.example.com:39089;transport=UDP>
f: "alice" <sip:+15715550000@example.com>;tag=1f4e4f40
t: "bob" <sip:+15715550001@example.com>
Date: Mon, 25 Nov 2024 20:28:42 GMT
i: YzRlZDFlYzYyM2IwOTdlMzk0MDA3MTRmZmY3OGIzODM.
y: eyJhbGciOiJFUzI1NiIsInR5cCI6InBhc3Nwb3J0IiwieDV1IjoiaHR0cDovL2NhLmV4YW1wbGUuY29tL3Rlc3QuZGVyIn0.eyJkZXN0Ijp7InRuIjpbIjE1NzE1NTUwMDAxIl19LCJpYXQiOjE3MzI1NjY1MjIsIm9yaWciOnsidG4iOiIxNTcxNTU1MDAwMCJ9fQ.eLPcl5Sw2qUP0nlLgoWao0WzdAKt0EXSbAYLAC6L8iGdjAPNAeqciJ3td3f8ITmBIdt8cKnBW4Dg5FWmV6g2oA;info=<http://ca.example.com/test.der>;alg=ES256
CSeq: 2 INVITE
c: application/sdp
User-Agent: Z 3.3.25608 r25552
k: replaces, norefersub, extended-refer, timer
Allow-Events: presence, kpml
l: 239
v=0
o=Z 0 0 IN IP4 10.31.32.251
s=Z
c=IN IP4 10.31.32.251
t=0 0
m=audio 8000 RTP/AVP 8 0 3 110 98 101
a=rtpmap:110 speex/8000
a=rtpmap:98 iLBC/8000
a=fmtp:98 mode=20
a=rtpmap:101 telephone-event/8000
a=fmtp:101 0-15
a=sendrecv
'
The successful response message is as below, same as the original SIP INVITE message:
HTTP/1.1 200 OK
Content-Type: text/plain;charset=UTF-8
Content-Length: 1124
INVITE sip:+15715550001@proxy.example.com;transport=UDP SIP/2.0
v: SIP/2.0/UDP proxy.example.com:39089;branch=z9hG4bK-d8754za
Max-Forwards: 70
m: "alice" <sip:alice@proxy.example.com:39089;transport=UDP>
f: "alice" <sip:+15715550000@example.com>;tag=1f4e4f40
t: "bob" <sip:+15715550001@example.com>
Date: Mon, 25 Nov 2024 20:28:42 GMT
i: YzRlZDFlYzYyM2IwOTdlMzk0MDA3MTRmZmY3OGIzODM.
y: eyJhbGciOiJFUzI1NiIsInR5cCI6InBhc3Nwb3J0IiwieDV1IjoiaHR0cDovL2NhLmV4YW1wbGUuY29tL3Rlc3QuZGVyIn0.eyJkZXN0Ijp7InRuIjpbIjE1NzE1NTUwMDAxIl19LCJpYXQiOjE3MzI1NjY1MjIsIm9yaWciOnsidG4iOiIxNTcxNTU1MDAwMCJ9fQ.eLPcl5Sw2qUP0nlLgoWao0WzdAKt0EXSbAYLAC6L8iGdjAPNAeqciJ3td3f8ITmBIdt8cKnBW4Dg5FWmV6g2oA;info=<http://ca.example.com/test.der>;alg=ES256
CSeq: 2 INVITE
c: application/sdp
User-Agent: Z 3.3.25608 r25552
k: replaces, norefersub, extended-refer, timer
Allow-Events: presence, kpml
l: 239
v=0
o=Z 0 0 IN IP4 10.31.32.251
s=Z
c=IN IP4 10.31.32.251
t=0 0
m=audio 8000 RTP/AVP 8 0 3 110 98 101
a=rtpmap:110 speex/8000
a=rtpmap:98 iLBC/8000
a=fmtp:98 mode=20
a=rtpmap:101 telephone-event/8000
a=fmtp:101 0-15
a=sendrecv
Example with CNAM Prefix for Verified SIP Identity Header
The following is an example of submitting a SIP INVITE message with a SIP Identity header and the "cnamPrefix" parameter in the request, and producing a new SIP INVITE message with the CNAM field modified for indicating verified SIP Identity header:
$ curl 'https://ca-verify.neustarlab.biz/ccid/verify/v2/identity?apiKey=%3CapiKey1%3E&status=all&cnamPrefix=%E2%9C%94,%E2%9C%98' -i -X POST \
-H 'Content-Type: text/plain' \
-H 'Accept: text/plain' \
-d 'INVITE sip:+15715550001@proxy.example.com;transport=UDP SIP/2.0
Via: SIP/2.0/UDP proxy.example.com:39089;branch=z9hG4bK-d8754za
Max-Forwards: 70
Contact: "alice" <sip:alice@proxy.example.com:39089;transport=UDP>
From: "alice" <sip:+15715550000@example.com>;tag=1f4e4f40
To: "bob" <sip:+15715550001@example.com>
Date: Mon, 25 Nov 2024 20:28:42 GMT
Call-ID: YzRlZDFlYzYyM2IwOTdlMzk0MDA3MTRmZmY3OGIzODM.
Identity: eyJhbGciOiJFUzI1NiIsInR5cCI6InBhc3Nwb3J0IiwieDV1IjoiaHR0cDovL2NhLmV4YW1wbGUuY29tL3Rlc3QuZGVyIn0.eyJkZXN0Ijp7InRuIjpbIjE1NzE1NTUwMDAxIl19LCJpYXQiOjE3MzI1NjY1MjIsIm9yaWciOnsidG4iOiIxNTcxNTU1MDAwMCJ9fQ.LLeDb06bpxkFs8dmrXyXvUej95hLdEbxR7O8YbTwYqEEkuwsiyRJahqs_w0202nzFZqONRdyfqUSGJiVB9pnGg;info=<http://ca.example.com/test.der>;alg=ES256
CSeq: 2 INVITE
Content-Type: application/sdp
User-Agent: Z 3.3.25608 r25552
Supported: replaces, norefersub, extended-refer, timer
Allow-Events: presence, kpml
Content-Length: 239
v=0
o=Z 0 0 IN IP4 10.31.32.251
s=Z
c=IN IP4 10.31.32.251
t=0 0
m=audio 8000 RTP/AVP 8 0 3 110 98 101
a=rtpmap:110 speex/8000
a=rtpmap:98 iLBC/8000
a=fmtp:98 mode=20
a=rtpmap:101 telephone-event/8000
a=fmtp:101 0-15
a=sendrecv
'
The description of the parameters in the request URL is as below:
Parameter | Type | Optional | Description | Constraints |
---|---|---|---|---|
|
|
|
The API key for identifying the API client |
Cannot be null or empty |
|
|
|
Verification status requirement |
If specified, must be 'none', 'partial' or 'all' |
|
|
|
Prefix applied to to CNAM data field, indicating if SIP Identity header is verified or not |
If specified, must contain one token or two tokens separated by ',' or white spaces |
The successful response message is as below, with CNAM field modified:
HTTP/1.1 200 OK
Content-Type: text/plain;charset=UTF-8
Content-Length: 1184
INVITE sip:+15715550001@proxy.example.com;transport=UDP SIP/2.0
Via: SIP/2.0/UDP proxy.example.com:39089;branch=z9hG4bK-d8754za
Max-Forwards: 70
Contact: "alice" <sip:alice@proxy.example.com:39089;transport=UDP>
From: "✔alice" <sip:+15715550000@example.com>;tag=1f4e4f40
To: "bob" <sip:+15715550001@example.com>
Date: Mon, 25 Nov 2024 20:28:42 GMT
Call-ID: YzRlZDFlYzYyM2IwOTdlMzk0MDA3MTRmZmY3OGIzODM.
Identity: eyJhbGciOiJFUzI1NiIsInR5cCI6InBhc3Nwb3J0IiwieDV1IjoiaHR0cDovL2NhLmV4YW1wbGUuY29tL3Rlc3QuZGVyIn0.eyJkZXN0Ijp7InRuIjpbIjE1NzE1NTUwMDAxIl19LCJpYXQiOjE3MzI1NjY1MjIsIm9yaWciOnsidG4iOiIxNTcxNTU1MDAwMCJ9fQ.LLeDb06bpxkFs8dmrXyXvUej95hLdEbxR7O8YbTwYqEEkuwsiyRJahqs_w0202nzFZqONRdyfqUSGJiVB9pnGg;info=<http://ca.example.com/test.der>;alg=ES256
CSeq: 2 INVITE
Content-Type: application/sdp
User-Agent: Z 3.3.25608 r25552
Supported: replaces, norefersub, extended-refer, timer
Allow-Events: presence, kpml
Content-Length: 239
v=0
o=Z 0 0 IN IP4 10.31.32.251
s=Z
c=IN IP4 10.31.32.251
t=0 0
m=audio 8000 RTP/AVP 8 0 3 110 98 101
a=rtpmap:110 speex/8000
a=rtpmap:98 iLBC/8000
a=fmtp:98 mode=20
a=rtpmap:101 telephone-event/8000
a=fmtp:101 0-15
a=sendrecv
Example with CNAM Prefix for Unverified SIP Identity Header
The following is an example of submitting a SIP INVITE message with a SIP Identity header and the "cnamPrefix" parameter in the request, and producing a new SIP INVITE message with the CNAM field modified for indicating unverified SIP Identity header:
$ curl 'https://ca-verify.neustarlab.biz/ccid/verify/v2/identity?apiKey=%3CapiKey1%3E&status=none&cnamPrefix=%E2%9C%94,%E2%9C%98' -i -X POST \
-H 'Content-Type: text/plain' \
-H 'Accept: text/plain' \
-d 'INVITE sip:+15715550001@proxy.example.com;transport=UDP SIP/2.0
Via: SIP/2.0/UDP proxy.example.com:39089;branch=z9hG4bK-d8754za
Max-Forwards: 70
Contact: "alice" <sip:alice@proxy.example.com:39089;transport=UDP>
From: "alice" <sip:+15715550000@example.com>;tag=1f4e4f40
To: "bob" <sip:+15715550001@example.com>
Date: Mon, 25 Nov 2024 20:28:42 GMT
Call-ID: YzRlZDFlYzYyM2IwOTdlMzk0MDA3MTRmZmY3OGIzODM.
Identity: eyJhbGciOiJFUzI1NiIsInR5cCI6InBhc3Nwb3J0IiwieDV1IjoiaHR0cDovL2NhLmV4YW1wbGUuY29tL3Rlc3QuZGVyIn0.eyJkZXN0Ijp7InRuIjpbIjE1NzE1NTUwMDAxIl19LCJpYXQiOjE3MzI1NjY1MjIsIm9yaWciOnsidG4iOiIxNTcxNTU1MDAwMCJ9fQ.OXQqeYoyIYc0HFvwY-vdy3DY1krCgtBA1Ha5eixzY4958RE_xEHog3g1Rdu6HmjAMZ34Qshw0sCIaEDaKqXCUA;info=<http://ca.example.com/test.der>;alg=ES256
CSeq: 2 INVITE
Content-Type: application/sdp
User-Agent: Z 3.3.25608 r25552
Supported: replaces, norefersub, extended-refer, timer
Allow-Events: presence, kpml
Content-Length: 239
v=0
o=Z 0 0 IN IP4 10.31.32.251
s=Z
c=IN IP4 10.31.32.251
t=0 0
m=audio 8000 RTP/AVP 8 0 3 110 98 101
a=rtpmap:110 speex/8000
a=rtpmap:98 iLBC/8000
a=fmtp:98 mode=20
a=rtpmap:101 telephone-event/8000
a=fmtp:101 0-15
a=sendrecv
'
The description of the parameters in the request URL is as below:
Parameter | Type | Optional | Description | Constraints |
---|---|---|---|---|
|
|
|
The API key for identifying the API client |
Cannot be null or empty |
|
|
|
Verification status requirement |
If specified, must be 'none', 'partial' or 'all' |
|
|
|
Prefix applied to to CNAM data field, indicating if SIP Identity header is verified or not |
If specified, must contain one token or two tokens separated by ',' or white spaces |
The successful response message is as below, with CNAM field modified:
HTTP/1.1 200 OK
Content-Type: text/plain;charset=UTF-8
Content-Length: 1184
INVITE sip:+15715550001@proxy.example.com;transport=UDP SIP/2.0
Via: SIP/2.0/UDP proxy.example.com:39089;branch=z9hG4bK-d8754za
Max-Forwards: 70
Contact: "alice" <sip:alice@proxy.example.com:39089;transport=UDP>
From: "✘alice" <sip:+15715550000@example.com>;tag=1f4e4f40
To: "bob" <sip:+15715550001@example.com>
Date: Mon, 25 Nov 2024 20:28:42 GMT
Call-ID: YzRlZDFlYzYyM2IwOTdlMzk0MDA3MTRmZmY3OGIzODM.
Identity: eyJhbGciOiJFUzI1NiIsInR5cCI6InBhc3Nwb3J0IiwieDV1IjoiaHR0cDovL2NhLmV4YW1wbGUuY29tL3Rlc3QuZGVyIn0.eyJkZXN0Ijp7InRuIjpbIjE1NzE1NTUwMDAxIl19LCJpYXQiOjE3MzI1NjY1MjIsIm9yaWciOnsidG4iOiIxNTcxNTU1MDAwMCJ9fQ.OXQqeYoyIYc0HFvwY-vdy3DY1krCgtBA1Ha5eixzY4958RE_xEHog3g1Rdu6HmjAMZ34Qshw0sCIaEDaKqXCUA;info=<http://ca.example.com/test.der>;alg=ES256
CSeq: 2 INVITE
Content-Type: application/sdp
User-Agent: Z 3.3.25608 r25552
Supported: replaces, norefersub, extended-refer, timer
Allow-Events: presence, kpml
Content-Length: 239
v=0
o=Z 0 0 IN IP4 10.31.32.251
s=Z
c=IN IP4 10.31.32.251
t=0 0
m=audio 8000 RTP/AVP 8 0 3 110 98 101
a=rtpmap:110 speex/8000
a=rtpmap:98 iLBC/8000
a=fmtp:98 mode=20
a=rtpmap:101 telephone-event/8000
a=fmtp:101 0-15
a=sendrecv
Example with Full Set of Parameters
The following is an example of submitting a SIP INVITE message with a SIP Identity header and full set of available URL parameters as the request and producing a new SIP INVITE message with modified CNAM field and a new SIP P-Asserted-Identity header, including "verstat" tagging on SIP From/P-Asserted-Identity headers and added SIP P-Attestation-Indicator/P-Origination-Id headers:
$ curl 'https://ca-verify.neustarlab.biz/ccid/verify/v2/identity?apiKey=%3CapiKey1%3E&status=all&origcc=1,44&destcc=1&cnam=true&ecnam=true&robocall=true&cvt=false&cnamPrefix=%E2%9C%94,%E2%9C%98&verstat=TN-Validation-Passed&identity=true' -i -X POST \
-H 'Content-Type: text/plain' \
-H 'Accept: text/plain' \
-d 'INVITE sip:+15715550001@proxy.example.com;transport=UDP SIP/2.0
v: SIP/2.0/UDP proxy.example.com:39089;branch=z9hG4bK-d8754za
Max-Forwards: 70
m: "alice" <sip:alice@proxy.example.com:39089;transport=UDP>
f: "alice" <sip:+15715550000@example.com>;tag=1f4e4f40
t: "bob" <sip:+15715550001@example.com>
Date: Mon, 25 Nov 2024 20:28:42 GMT
i: YzRlZDFlYzYyM2IwOTdlMzk0MDA3MTRmZmY3OGIzODM.
y: eyJhbGciOiJFUzI1NiIsInBwdCI6InNoYWtlbiIsInR5cCI6InBhc3Nwb3J0IiwieDV1IjoiaHR0cDovL2NhLmV4YW1wbGUuY29tL3Rlc3QuZGVyIn0.eyJhdHRlc3QiOiJBIiwiZGVzdCI6eyJ0biI6WyIxNTcxNTU1MDAwMSJdfSwiaWF0IjoxNzMyNTY2NTIyLCJta3kiOlt7ImFsZyI6IlNIQS0xIiwiZGlnIjoiNEFBREI5QjEzRjgyMTgzQjU0MDIxMkRGM0U1RDQ5NkIxOUU1N0NBQiJ9LHsiYWxnIjoiU0hBLTI1NiIsImRpZyI6IjM2M0JBRTEyOTU5NUY1OTcyREY3RTA4NEZFQ0RGMUJDQUQ3QTcwNjRGN0U3NEY3RUE2MDIwNjBFMzc1NENGRjcifV0sIm9yaWciOnsidG4iOiIxNzAzNTU1MDAwMSJ9LCJvcmlnaWQiOiIxMjM0NTYtQUJDRC05OTk5OTkiLCJyY2QiOnsibmFtIjoiQWxpY2UifX0.GXSy3i81zb7B4OFCGGNaNqTFTwsm37LW3y_cp-pKccRGknAfHj55hMLKYyXQ7k2ZzXJhMhDlBlxD1DwZVFKC4w;info=<http://ca.example.com/test.der>;alg=ES256;ppt="shaken"
P-Asserted-Identity: "Alice" <tel:+17035550001>
P-Asserted-Identity: "Alice" <sip:+17035550001@example.com>
CSeq: 2 INVITE
c: application/sdp
User-Agent: Z 3.3.25608 r25552
k: replaces, norefersub, extended-refer, timer
Allow-Events: presence, kpml
l: 439
v=0
o=Z 0 0 IN IP4 10.31.32.251
s=Z
c=IN IP4 10.31.32.251
t=0 0
m=audio 8000 RTP/AVP 8 0 3 110 98 101
a=fingerprint:SHA-1 4A:AD:B9:B1:3F:82:18:3B:54:02:12:DF:3E:5D:49:6B:19:E5:7C:AB
a=fingerprint:SHA-256 36:3B:AE:12:95:95:F5:97:2D:F7:E0:84:FE:CD:F1:BC:AD:7A:70:64:F7:E7:4F:7E:A6:02:06:0E:37:54:CF:F7
a=rtpmap:110 speex/8000
a=rtpmap:98 iLBC/8000
a=fmtp:98 mode=20
a=rtpmap:101 telephone-event/8000
a=fmtp:101 0-15
a=sendrecv
'
The description of the parameters in the request URL is as below:
Parameter | Type | Optional | Description | Constraints |
---|---|---|---|---|
|
|
|
The API key for identifying the API client |
Cannot be null or empty |
|
|
|
Verification status requirement |
If specified, must be 'none', 'partial' or 'all' |
|
|
|
Default country codes for the originator telephone number |
If specified, must be a list of valid country codes separated by ',' or white spaces |
|
|
|
Default country code for the destination telephone number |
If specified, must be a valid country code |
|
|
|
Boolean flag for performing CNAM lookup |
If specified, must be 'true' or 'false' |
|
|
|
Boolean flag for performing ECNAM lookup |
If specified, must be 'true' or 'false' |
|
|
|
Boolean flag for returning Robocall Call Insight data |
If specified, must be 'true' or 'false' |
|
|
|
Boolean flag for invoking CVT service for CNAM/ECNAM/Robocall data |
If specified, must be 'true' or 'false' |
|
|
|
Prefix applied to to CNAM data field, indicating if SIP Identity header is verified or not |
If specified, must contain one token or two tokens separated by ',' or white spaces |
|
|
|
'verstat' value defined by ETSI TS 124 299, for enabling tagging |
If specified, must be a valid 'verstat' value |
|
|
|
Boolean flag for keeping existing SIP Identity header if tagging is enabled or re-signing is successfully performed |
If specified, must be true or false |
The successful response message is as below, with SIP Identity header embedded:
HTTP/1.1 200 OK
Content-Type: text/plain;charset=UTF-8
Content-Length: 2611
INVITE sip:+15715550001@proxy.example.com;transport=UDP SIP/2.0
v: SIP/2.0/UDP proxy.example.com:39089;branch=z9hG4bK-d8754za
Max-Forwards: 70
m: "alice" <sip:alice@proxy.example.com:39089;transport=UDP>
f: "✔Alice In Wonderland" <sip:+15715550000;verstat=TN-Validation-Passed@example.com>;tag=1f4e4f40
t: "bob" <sip:+15715550001@example.com>
Date: Mon, 25 Nov 2024 20:28:42 GMT
i: YzRlZDFlYzYyM2IwOTdlMzk0MDA3MTRmZmY3OGIzODM.
P-Attestation-Indicator: A
P-Origination-Id: 123456-ABCD-999999
y: eyJhbGciOiJFUzI1NiIsInBwdCI6InNoYWtlbiIsInR5cCI6InBhc3Nwb3J0IiwieDV1IjoiaHR0cDovL2NhLmV4YW1wbGUuY29tL3Rlc3QuZGVyIn0.eyJhdHRlc3QiOiJBIiwiZGVzdCI6eyJ0biI6WyIxNTcxNTU1MDAwMSJdfSwiaWF0IjoxNzMyNTY2NTIyLCJta3kiOlt7ImFsZyI6IlNIQS0xIiwiZGlnIjoiNEFBREI5QjEzRjgyMTgzQjU0MDIxMkRGM0U1RDQ5NkIxOUU1N0NBQiJ9LHsiYWxnIjoiU0hBLTI1NiIsImRpZyI6IjM2M0JBRTEyOTU5NUY1OTcyREY3RTA4NEZFQ0RGMUJDQUQ3QTcwNjRGN0U3NEY3RUE2MDIwNjBFMzc1NENGRjcifV0sIm9yaWciOnsidG4iOiIxNzAzNTU1MDAwMSJ9LCJvcmlnaWQiOiIxMjM0NTYtQUJDRC05OTk5OTkiLCJyY2QiOnsibmFtIjoiQWxpY2UifX0.GXSy3i81zb7B4OFCGGNaNqTFTwsm37LW3y_cp-pKccRGknAfHj55hMLKYyXQ7k2ZzXJhMhDlBlxD1DwZVFKC4w;info=<http://ca.example.com/test.der>;alg=ES256;ppt="shaken"
P-Asserted-Identity: "✔Alice In Wonderland,Walt Disney World Resort,Orlando,FL 32830" <sip:+15715550000@example.com;tmpl=none;bn=Disney%20World;dept=Theme%20Park;lt=Wireline;st=Business;bt=Entertainment;ba=Walt%20Disney%20World%20Resort;cs=Orlando, FL;city=Orlando;state=FL;ct=US;zip=32830;wb=http://movies.disney.com/alice-in-wonderland-1951;lg=https://static-mh.content.disney.io/matterhorn/assets/goc/nav-logo-dark@2x-2b3eb08c507c.png;tg=#AliceInWonderLand;sm=%7B%22Facebook%22%3A%22https%3A%2F%2Fwww.facebook.com%2FDisneyAliceInWonderland%22%2C%22Twitter%22%3A%22https%3A%2F%2Ftwitter.com%2FDisney%22%7D;nm=Alice;fn=Alice;ln=Liddell;jt=Adventurer;hs=https://encrypted-tbn0.gstatic.com/images?q%3dtbn:ANd9GcR2Q1GWX6hdmMr2dh10SoTeEKEn4S4toc4V3yAJCrPQHlzWvr_I;cp=Customer Support;email=alice@disney.com;verstat=TN-Validation-Passed>
CSeq: 2 INVITE
c: application/sdp
User-Agent: Z 3.3.25608 r25552
k: replaces, norefersub, extended-refer, timer
Allow-Events: presence, kpml
l: 439
v=0
o=Z 0 0 IN IP4 10.31.32.251
s=Z
c=IN IP4 10.31.32.251
t=0 0
m=audio 8000 RTP/AVP 8 0 3 110 98 101
a=fingerprint:SHA-1 4A:AD:B9:B1:3F:82:18:3B:54:02:12:DF:3E:5D:49:6B:19:E5:7C:AB
a=fingerprint:SHA-256 36:3B:AE:12:95:95:F5:97:2D:F7:E0:84:FE:CD:F1:BC:AD:7A:70:64:F7:E7:4F:7E:A6:02:06:0E:37:54:CF:F7
a=rtpmap:110 speex/8000
a=rtpmap:98 iLBC/8000
a=fmtp:98 mode=20
a=rtpmap:101 telephone-event/8000
a=fmtp:101 0-15
a=sendrecv
Example with Re-signed Identity
The following is an example of submitting a SIP INVITE message with a SIP Identity header as the request and returning the SIP INVITE message with a re-signed SIP Identity header, after the original SIP Identity header is successfully verified and removed:
$ curl 'https://ca-verify.neustarlab.biz/ccid/verify/v2/identity?apiKey=%3CapiKey6%3E&identity=false' -i -X POST \
-H 'Content-Type: text/plain' \
-H 'Accept: text/plain' \
-d 'INVITE sip:+15714340001@proxy.example.com;transport=UDP SIP/2.0
Via: SIP/2.0/UDP proxy.example.com:39089;branch=z9hG4bK-d8754za
Max-Forwards: 70
Contact: "alice" <sip:alice@proxy.example.com:39089;transport=UDP>
From: "alice" <sip:+15714340000@example.com>;tag=1f4e4f40
To: "bob" <sip:+15714340001@example.com>
Date: Mon, 25 Nov 2024 20:28:43 GMT
Call-ID: YzRlZDFlYzYyM2IwOTdlMzk0MDA3MTRmZmY3OGIzODM.
Identity: eyJhbGciOiJFUzI1NiIsInR5cCI6InBhc3Nwb3J0IiwieDV1IjoiaHR0cDovL2NhLmV4YW1wbGUuY29tL3Rlc3QuZGVyIn0.eyJkZXN0Ijp7InRuIjpbIjE1NzE0MzQwMDAxIl19LCJpYXQiOjE3MzI1NjY1MjMsIm9yaWciOnsidG4iOiIxNTcxNDM0MDAwMCJ9fQ.A7etoxtDuXuHSi3Fh1CUnPh-8GDyNewFJF5YlkP2Bc0OHv1dfv8SSpS7ptRfwqzEbyQH1aPpt3n3h064uS7_zw;info=<http://ca.example.com/test.der>;alg=ES256
CSeq: 2 INVITE
Content-Type: application/sdp
User-Agent: Z 3.3.25608 r25552
Supported: replaces, norefersub, extended-refer, timer
Allow-Events: presence, kpml
Content-Length: 239
v=0
o=Z 0 0 IN IP4 10.31.32.251
s=Z
c=IN IP4 10.31.32.251
t=0 0
m=audio 8000 RTP/AVP 8 0 3 110 98 101
a=rtpmap:110 speex/8000
a=rtpmap:98 iLBC/8000
a=fmtp:98 mode=20
a=rtpmap:101 telephone-event/8000
a=fmtp:101 0-15
a=sendrecv
'
The description of the parameters in the request URL is as below:
Parameter | Type | Optional | Description | Constraints |
---|---|---|---|---|
|
|
|
The API key for identifying the API client |
Cannot be null or empty |
|
|
|
Boolean flag for keeping existing SIP Identity header if tagging is enabled or re-signing is successfully performed |
If specified, must be true or false |
The successful response message is as below, as the original SIP Identity header replaced by the re-signed SIP Identity header:
HTTP/1.1 200 OK
Content-Type: text/plain;charset=UTF-8
Content-Length: 1300
INVITE sip:+15715550001@proxy.example.com;transport=UDP SIP/2.0
Via: SIP/2.0/UDP proxy.example.com:39089;branch=z9hG4bK-d8754za
Max-Forwards: 70
Contact: "alice" <sip:alice@proxy.example.com:39089;transport=UDP>
From: "alice" <sip:+15715550000@example.com>;tag=1f4e4f40
To: "bob" <sip:+15715550001@example.com>
Date: Mon, 25 Nov 2024 20:28:43 GMT
Call-ID: YzRlZDFlYzYyM2IwOTdlMzk0MDA3MTRmZmY3OGIzODM.
Identity: eyJhbGciOiJFUzI1NiIsInBwdCI6InNoYWtlbiIsInR5cCI6InBhc3Nwb3J0IiwieDV1IjoiaHR0cDovL2NhLmV4YW1wbGUuY29tL3Rlc3QuZGVyIn0.eyJhdHRlc3QiOiJBIiwiZGVzdCI6eyJ0biI6WyIxNTcxNDM0MDAwMSJdfSwiaWF0IjoxNzMyNTY2NTIzLCJvcmlnIjp7InRuIjoiMTU3MTQzNDAwMDAifSwib3JpZ2lkIjoiMTIzNDU2LUFCQ0QtOTk5OTk5IiwicmNkIjp7Im5hbSI6ImFsaWNlIn19.kI3zpagw-wY6wNpuMyqgOU6h-lmVjZ-lPI-CRtCFYsqJa0R6i_A6f8EHJRKVq8G_SW13m4G1P0ZOAVy5t44Xwg;info=<http://ca.example.com/test.der>;alg=ES256;ppt="shaken"
CSeq: 2 INVITE
Content-Type: application/sdp
User-Agent: Z 3.3.25608 r25552
Supported: replaces, norefersub, extended-refer, timer
Allow-Events: presence, kpml
Content-Length: 239
v=0
o=Z 0 0 IN IP4 10.31.32.251
s=Z
c=IN IP4 10.31.32.251
t=0 0
m=audio 8000 RTP/AVP 8 0 3 110 98 101
a=rtpmap:110 speex/8000
a=rtpmap:98 iLBC/8000
a=fmtp:98 mode=20
a=rtpmap:101 telephone-event/8000
a=fmtp:101 0-15
a=sendrecv
Example with Re-signing Error
The following is an example of submitting a SIP INVITE message with a SIP Identity header as the request and returning the SIP INVITE message with a SIP Reason header, after the original SIP Identity header is successfully verified, but the re-signing process is failed:
$ curl 'https://ca-verify.neustarlab.biz/ccid/verify/v2/identity?apiKey=%3CapiKey6%3E&identity=false' -i -X POST \
-H 'Content-Type: text/plain' \
-H 'Accept: text/plain' \
-d 'INVITE sip:+15714340001@proxy.example.com;transport=UDP SIP/2.0
Via: SIP/2.0/UDP proxy.example.com:39089;branch=z9hG4bK-d8754za
Max-Forwards: 70
Contact: "alice" <sip:alice@proxy.example.com:39089;transport=UDP>
From: "alice" <sip:+15714340000@example.com>;tag=1f4e4f40
To: "bob" <sip:+15714340001@example.com>
Date: Mon, 25 Nov 2024 20:28:42 GMT
Call-ID: YzRlZDFlYzYyM2IwOTdlMzk0MDA3MTRmZmY3OGIzODM.
Identity: eyJhbGciOiJFUzI1NiIsInR5cCI6InBhc3Nwb3J0IiwieDV1IjoiaHR0cDovL2NhLmV4YW1wbGUuY29tL3Rlc3QuZGVyIn0.eyJkZXN0Ijp7InRuIjpbIjE1NzE0MzQwMDAxIl19LCJpYXQiOjE3MzI1NjY1MjIsIm9yaWciOnsidG4iOiIxNTcxNDM0MDAwMCJ9fQ.FDRMMImiNf4J-LcAHx-7bLAuhtS46W-z3PxGKsgSjla83wRn2e2B6Y5WIlFPN_7TjRweCkIJz_d6jaaL1udduw;info=<http://ca.example.com/test.der>;alg=ES256
CSeq: 2 INVITE
Content-Type: application/sdp
User-Agent: Z 3.3.25608 r25552
Supported: replaces, norefersub, extended-refer, timer
Allow-Events: presence, kpml
Content-Length: 239
v=0
o=Z 0 0 IN IP4 10.31.32.251
s=Z
c=IN IP4 10.31.32.251
t=0 0
m=audio 8000 RTP/AVP 8 0 3 110 98 101
a=rtpmap:110 speex/8000
a=rtpmap:98 iLBC/8000
a=fmtp:98 mode=20
a=rtpmap:101 telephone-event/8000
a=fmtp:101 0-15
a=sendrecv
'
The description of the parameters in the request URL is as below:
Parameter | Type | Optional | Description | Constraints |
---|---|---|---|---|
|
|
|
The API key for identifying the API client |
Cannot be null or empty |
|
|
|
Boolean flag for keeping existing SIP Identity header if tagging is enabled or re-signing is successfully performed |
If specified, must be true or false |
The response message is as below, with the original SIP Identity header and a newly inserted SIP Reason header, indicating the re-signing failure:
HTTP/1.1 200 OK
Content-Type: text/plain;charset=UTF-8
Content-Length: 1328
INVITE sip:+15714340001@proxy.example.com;transport=UDP SIP/2.0
Reason: SIP;cause=503;text="ServiceErrorInResigningIdentity: Service or request error in re-signing identity header - No authentication response"
Via: SIP/2.0/UDP proxy.example.com:39089;branch=z9hG4bK-d8754za
Max-Forwards: 70
Contact: "alice" <sip:alice@proxy.example.com:39089;transport=UDP>
From: "alice" <sip:+15714340000@example.com>;tag=1f4e4f40
To: "bob" <sip:+15714340001@example.com>
Date: Mon, 25 Nov 2024 20:28:42 GMT
Call-ID: YzRlZDFlYzYyM2IwOTdlMzk0MDA3MTRmZmY3OGIzODM.
Identity: eyJhbGciOiJFUzI1NiIsInR5cCI6InBhc3Nwb3J0IiwieDV1IjoiaHR0cDovL2NhLmV4YW1wbGUuY29tL3Rlc3QuZGVyIn0.eyJkZXN0Ijp7InRuIjpbIjE1NzE0MzQwMDAxIl19LCJpYXQiOjE3MzI1NjY1MjIsIm9yaWciOnsidG4iOiIxNTcxNDM0MDAwMCJ9fQ.FDRMMImiNf4J-LcAHx-7bLAuhtS46W-z3PxGKsgSjla83wRn2e2B6Y5WIlFPN_7TjRweCkIJz_d6jaaL1udduw;info=<http://ca.example.com/test.der>;alg=ES256
CSeq: 2 INVITE
Content-Type: application/sdp
User-Agent: Z 3.3.25608 r25552
Supported: replaces, norefersub, extended-refer, timer
Allow-Events: presence, kpml
Content-Length: 239
v=0
o=Z 0 0 IN IP4 10.31.32.251
s=Z
c=IN IP4 10.31.32.251
t=0 0
m=audio 8000 RTP/AVP 8 0 3 110 98 101
a=rtpmap:110 speex/8000
a=rtpmap:98 iLBC/8000
a=fmtp:98 mode=20
a=rtpmap:101 telephone-event/8000
a=fmtp:101 0-15
a=sendrecv
Error Response Example
The following is an example of error responses in SIP format produced by the CCID VS if there are any errors encountered during the SIP Identity header verification for a SIP INVITE message:
$ curl 'https://ca-verify.neustarlab.biz/ccid/verify/v2/identity?apiKey=%3CapiKey1%3E' -i -X POST \
-H 'Content-Type: text/plain' \
-H 'Accept: text/plain' \
-d 'INVITE sip:+15715550001@proxy.example.com;transport=UDP SIP/2.0
Via: SIP/2.0/UDP proxy.example.com:39089;branch=z9hG4bK-d8754za
Max-Forwards: 70
Contact: "alice" <sip:alice@proxy.example.com:39089;transport=UDP>
From: "alice" <sip:+15715550000@example.com>;tag=1f4e4f40
To: "bob" <sip:+15715550001@example.com>
Date: Mon, 25 Nov 2024 20:28:42 GMT
Call-ID: YzRlZDFlYzYyM2IwOTdlMzk0MDA3MTRmZmY3OGIzODM.
Identity: eyJhbGciOiJFUzI1NiIsInR5cCI6InBhc3Nwb3J0IiwieDV1IjoiaHR0cDovL2NhLmV4YW1wbGUuY29tL3Rlc3QuZGVyIn0.eyJkZXN0Ijp7InRuIjpbIjE1NzE1NTUwMDAxIl19LCJpYXQiOjE3MzI1NjY1MjIsIm9yaWciOnsidG4iOiIxNTcxNTU1MDAwMCJ9fQ.obv4VKz-qUxyWIG9KB33M7fIBw7Q_KWq9i0ghe4DpWxfMjDBWsPtJQPDBIZ1ZDZdlUytePqhnM2tBIp9cOz91g;info=<http://ca.example.com/test.der>;alg=ES256
CSeq: 2 INVITE
Content-Type: application/sdp
User-Agent: Z 3.3.25608 r25552
Supported: replaces, norefersub, extended-refer, timer
Allow-Events: presence, kpml
Content-Length: 239
v=0
o=Z 0 0 IN IP4 10.31.32.251
s=Z
c=IN IP4 10.31.32.251
t=0 0
m=audio 8000 RTP/AVP 8 0 3 110 98 101
a=rtpmap:110 speex/8000
a=rtpmap:98 iLBC/8000
a=fmtp:98 mode=20
a=rtpmap:101 telephone-event/8000
a=fmtp:101 0-15
a=sendrecv
'
The error response message is as below with proper HTTP status code and SIP Reason header:
HTTP/1.1 400 Bad Request
Content-Type: text/plain;charset=UTF-8
Content-Length: 505
SIP/2.0 438 Identity signature failed to be verified
Via: SIP/2.0/UDP proxy.example.com:39089;branch=z9hG4bK-d8754za
Contact: "alice" <sip:alice@proxy.example.com:39089;transport=UDP>
From: "alice" <sip:+15715550000@example.com>;tag=1f4e4f40
To: "bob" <sip:+15715550001@example.com>
Call-ID: YzRlZDFlYzYyM2IwOTdlMzk0MDA3MTRmZmY3OGIzODM.
CSeq: 2 INVITE
Supported: replaces, norefersub, extended-refer, timer
Reason: SIP;cause=438;text="Identity signature failed to be verified"
Content-Length: 0
The following is an example of error responses in SIP format produced by the CCID VS
if the calling telephone number is marked with call_treatment
as`deny` in Robocall
Call Insight data, although the SIP Identity header verification is successful:
$ curl 'https://ca-verify.neustarlab.biz/ccid/verify/v2/identity?apiKey=%3CapiKey1%3E&robocall=true' -i -X POST \
-H 'Content-Type: text/plain' \
-H 'Accept: text/plain' \
-d 'INVITE sip:+15715550001@proxy.example.com;transport=UDP SIP/2.0
Via: SIP/2.0/UDP proxy.example.com:39089;branch=z9hG4bK-d8754za
Max-Forwards: 70
Contact: "alice" <sip:alice@proxy.example.com:39089;transport=UDP>
From: "alice" <sip:+15715550000@example.com>;tag=1f4e4f40
To: "bob" <sip:+15715550001@example.com>
Date: Mon, 25 Nov 2024 20:28:43 GMT
Call-ID: YzRlZDFlYzYyM2IwOTdlMzk0MDA3MTRmZmY3OGIzODM.
Identity: eyJhbGciOiJFUzI1NiIsInR5cCI6InBhc3Nwb3J0IiwieDV1IjoiaHR0cDovL2NhLmV4YW1wbGUuY29tL3Rlc3QuZGVyIn0.eyJkZXN0Ijp7InRuIjpbIjE1NzE1NTUwMDAxIl19LCJpYXQiOjE3MzI1NjY1MjMsIm9yaWciOnsidG4iOiIxNTcxNTU1MDAwMCJ9fQ.KwPAi2EpKvKG7dxs_Lbo1b5GK_8kAuTNOlGwcVhoBjTCeXRS-eFIyvSFkqc9ZCyamrImNeY8FKAsG2QzU12o_Q;info=<http://ca.example.com/test.der>;alg=ES256
CSeq: 2 INVITE
Content-Type: application/sdp
User-Agent: Z 3.3.25608 r25552
Supported: replaces, norefersub, extended-refer, timer
Allow-Events: presence, kpml
Content-Length: 239
v=0
o=Z 0 0 IN IP4 10.31.32.251
s=Z
c=IN IP4 10.31.32.251
t=0 0
m=audio 8000 RTP/AVP 8 0 3 110 98 101
a=rtpmap:110 speex/8000
a=rtpmap:98 iLBC/8000
a=fmtp:98 mode=20
a=rtpmap:101 telephone-event/8000
a=fmtp:101 0-15
a=sendrecv
'
The error response message is as below with proper HTTP status code and SIP Reason header:
HTTP/1.1 403 Forbidden
Content-Type: text/plain;charset=UTF-8
Content-Length: 501
SIP/2.0 603 Call to be blocked - Fraud Score = 100
Via: SIP/2.0/UDP proxy.example.com:39089;branch=z9hG4bK-d8754za
Contact: "alice" <sip:alice@proxy.example.com:39089;transport=UDP>
From: "alice" <sip:+15715550000@example.com>;tag=1f4e4f40
To: "bob" <sip:+15715550001@example.com>
Call-ID: YzRlZDFlYzYyM2IwOTdlMzk0MDA3MTRmZmY3OGIzODM.
CSeq: 2 INVITE
Supported: replaces, norefersub, extended-refer, timer
Reason: SIP;cause=603;text="Call to be blocked - Fraud Score = 100"
Content-Length: 0
With SIP INVITE Message & Response in JSON Format for SIP Proxies
This API entry point accepts SIP INVITE messages as requests and produces responses in JSON Format for SIP Proxies.
API Method |
|
|
API Path |
|
|
Request Path Variable |
Name |
Description |
|
The remote IP address from which the SIP INVITE message is originated |
|
|
The remote port from which the SIP INVITE message is originated |
|
Required Parameters |
Name |
Description |
|
The API key uniquely identifying the API client |
|
Request Path (example) |
${BASEURL}/identity/proxy/192.168.1.1/5060?apiKey=... |
|
Request |
Content-Type |
application/text |
Body (example) |
SIP sip:17035550021@proxy.example.com;transport=UDP SIP/2.0 From: Alice <sip:+15714345500@example.com> To: Bob <sip:+447035550000@example.com> Identity: ey.x.oQ;info=<http://.../cert/123>;alg=ES256 ... |
|
Successful Response |
HTTP Code |
200 OK |
Content-Type |
application/json |
|
Body (example) |
{ "status" : "ok", "next_hop" : "udp:192.168.1.1:5060", "policy" : "policy...", "header" : [ { "operation" : "add", "name" : "From", "value" : "*Alice <sip:+15714345500@example.com;verstat=TN-Validation-Passed>" }, { "operation" : "remove", "name" : "From", "value" : "Alice <sip:+15714345500@example.com>" } ] } |
|
Error Response |
HTTP Code |
4xx, 5xx |
Content-Type |
application/json |
|
Body (example) |
{ "status" : "error", "error" : [ { "error_id" : "RequestStaleDate", "http_status_code" : 403, "sip_code" : 403, "reason" : "Stale date value", "timestamp" : "Thu, 12 Jul 2018 17:24:15 GMT", "attributes" : { "allowed_clock_skew" : 60, "difference" : 56090619 } } ], "next_hop" : "udp:192.168.1.1:5060", "policy" : "policy..." } |
A successful response in JSON format includes the "status" attribute with a value of "ok". It also contains an optional "next_hop" attribute for indicating the next hop for routing the SIP messages, and an optional "policy" attribute with an opaque string to be consumed by the SIP proxy for manipulating SIP headers and mapping error conditions. Finally, it contains an optional "header" attribute, containing a list of SIP headers to be added to or removed from the SIP INVITE message.
Additionally, a successful response in JSON format may include an optional "error" attribute, containing a list of error conditions encountered in the verification process, if the SIP proxy has been provisioning for tagging, accepting partial verification errors, or ignoring any verification errors.
A failure response in JSON format includes the "status" attribute with a value of "error". In addition to the optional "next_hop" and "policy" attributes, the failure response contains an "error" attribute, containing a list of error conditions that result in the failure.
If the SIP Interface is not provisioned for tagging, re-signing SIP Identity headers can be optionally triggered, according to pre-defined policy associated with the API key object. After the re-signing process is successfully performed, a new SIP Identity header will be added into the "header" attribute, with the existing SIP Identity header optionally removed, if the "keep_identity" attribute is "false". If the re-signing process is failed, the relevant error information will added to the the "error" attribute.
Additionally, the "verstat" value used for tagging may subject to override by local verstat-related policy or CVT policy with an overlay verstat value.
Example of Successfully Verifying SIP Identity Header
The following is an example for verifying a SIP Identity header by submitting a SIP INVITE message as the request. The response in JSON format instructs the SIP proxy that the SIP Identity header has been verified and no changes needed to be made to the SIP INVITE message:
$ curl 'https://ca-verify.neustarlab.biz/ccid/verify/v2/identity/proxy/127.0.0.2/5060?apiKey=%3CapiKey7%3E' -i -X POST \
-H 'Content-Type: text/plain' \
-H 'Accept: application/json' \
-d 'INVITE sip:+15714340001@proxy.example.com;transport=UDP SIP/2.0
Via: SIP/2.0/UDP proxy.example.com:39089;branch=z9hG4bK-d8754za
Max-Forwards: 70
Contact: "alice" <sip:alice@proxy.example.com:39089;transport=UDP>
From: "alice" <sip:+15714340000@example.com>;tag=1f4e4f40
To: "bob" <sip:+15714340001@example.com>
Date: Mon, 25 Nov 2024 20:28:41 GMT
Call-ID: YzRlZDFlYzYyM2IwOTdlMzk0MDA3MTRmZmY3OGIzODM.
Identity: eyJhbGciOiJFUzI1NiIsInR5cCI6InBhc3Nwb3J0IiwieDV1IjoiaHR0cDovL2NhLmV4YW1wbGUuY29tL3Rlc3QuZGVyIn0.eyJkZXN0Ijp7InRuIjpbIjE1NzE0MzQwMDAxIl19LCJpYXQiOjE3MzI1NjY1MjEsIm9yaWciOnsidG4iOiIxNTcxNDM0MDAwMCJ9fQ.XXhG5WJ0Lxl7DXRdNYDjFwZr5eSg43RNvFWmjcTYCHBTM21qQ_fDBx61mWlDFuEYlcoMehaf615iytakxB1DaQ;info=<http://ca.example.com/test.der>;alg=ES256
CSeq: 2 INVITE
Content-Type: application/sdp
User-Agent: Z 3.3.25608 r25552
Supported: replaces, norefersub, extended-refer, timer
Allow-Events: presence, kpml
Content-Length: 239
v=0
o=Z 0 0 IN IP4 10.31.32.251
s=Z
c=IN IP4 10.31.32.251
t=0 0
m=audio 8000 RTP/AVP 8 0 3 110 98 101
a=rtpmap:110 speex/8000
a=rtpmap:98 iLBC/8000
a=fmtp:98 mode=20
a=rtpmap:101 telephone-event/8000
a=fmtp:101 0-15
a=sendrecv
'
The successful response message is as below:
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 240
{
"status" : "ok",
"next_hop" : "udp:192.168.1.1:5060",
"policy" : "{\"stateful\":false,\"via\":false,\"max_forwards\":false,\"route\":false,\"record_route\":false,\"error_action\":[{\"error\":\"default\",\"action\":\"passthru\"}]}"
}
The description of the fields in the response is as below:
Path | Type | Optional | Description |
---|---|---|---|
|
|
|
Verification status |
|
|
|
The URI of next hop |
|
|
|
The policy for processing the SIP message |
Example of Successfully Verifying SIP Identity Header with SIP INVITE Message in Compact Form
The following is an example for verifying a SIP Identity header by submitting a SIP INVITE message as the request, with SIP headers in compact form. The response in JSON format instructs the SIP proxy that the SIP Identity header has been verified, and CNAM/ECNAM lookup has been performed and SIP From and P-Asserted-Identity headers need to be changed or added.
$ curl 'https://ca-verify.neustarlab.biz/ccid/verify/v2/identity/proxy/127.0.0.1/5060?apiKey=%3CapiKey1%3E' -i -X POST \
-H 'Content-Type: text/plain' \
-H 'Accept: application/json' \
-d 'INVITE sip:+15714340001@proxy.example.com;transport=UDP SIP/2.0
v: SIP/2.0/UDP proxy.example.com:39089;branch=z9hG4bK-d8754za
Max-Forwards: 70
m: "alice" <sip:alice@proxy.example.com:39089;transport=UDP>
f: "alice" <sip:+15714340000@example.com>;tag=1f4e4f40
t: "bob" <sip:+15714340001@example.com>
Date: Mon, 25 Nov 2024 20:28:41 GMT
i: YzRlZDFlYzYyM2IwOTdlMzk0MDA3MTRmZmY3OGIzODM.
y: eyJhbGciOiJFUzI1NiIsInBwdCI6InNoYWtlbiIsInR5cCI6InBhc3Nwb3J0IiwieDV1IjoiaHR0cDovL2NhLmV4YW1wbGUuY29tL3Rlc3QuZGVyIn0.eyJhdHRlc3QiOiJBIiwiZGVzdCI6eyJ0biI6WyIxNTcxNDM0MDAwMSJdfSwiaWF0IjoxNzMyNTY2NTIxLCJta3kiOlt7ImFsZyI6IlNIQS0xIiwiZGlnIjoiNEFBREI5QjEzRjgyMTgzQjU0MDIxMkRGM0U1RDQ5NkIxOUU1N0NBQiJ9LHsiYWxnIjoiU0hBLTI1NiIsImRpZyI6IjM2M0JBRTEyOTU5NUY1OTcyREY3RTA4NEZFQ0RGMUJDQUQ3QTcwNjRGN0U3NEY3RUE2MDIwNjBFMzc1NENGRjcifV0sIm9yaWciOnsidG4iOiIxNzAzNTU1MDAwMSJ9LCJvcmlnaWQiOiIxMjM0NTYtQUJDRC05OTk5OTkiLCJyY2QiOnsibmFtIjoiQWxpY2UifX0.luxjOuyzrj2NhX6kqnA7TsS88Z4RvJ-jmFUJLYW-4fLyRnBGJAvcZhoo4XO4vWLxqQ_r_kWIEyEVWU-OUaStgA;info=<http://ca.example.com/test.der>;alg=ES256;ppt="shaken"
P-Asserted-Identity: "Alice" <tel:+17035550001>
P-Asserted-Identity: "Alice" <sip:+17035550001@example.com>
CSeq: 2 INVITE
c: application/sdp
User-Agent: Z 3.3.25608 r25552
k: replaces, norefersub, extended-refer, timer
Allow-Events: presence, kpml
l: 439
v=0
o=Z 0 0 IN IP4 10.31.32.251
s=Z
c=IN IP4 10.31.32.251
t=0 0
m=audio 8000 RTP/AVP 8 0 3 110 98 101
a=fingerprint:SHA-1 4A:AD:B9:B1:3F:82:18:3B:54:02:12:DF:3E:5D:49:6B:19:E5:7C:AB
a=fingerprint:SHA-256 36:3B:AE:12:95:95:F5:97:2D:F7:E0:84:FE:CD:F1:BC:AD:7A:70:64:F7:E7:4F:7E:A6:02:06:0E:37:54:CF:F7
a=rtpmap:110 speex/8000
a=rtpmap:98 iLBC/8000
a=fmtp:98 mode=20
a=rtpmap:101 telephone-event/8000
a=fmtp:101 0-15
a=sendrecv
'
The successful response message is as below:
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 1629
{
"status" : "ok",
"next_hop" : "udp:192.168.1.1:5060",
"policy" : "{\"stateful\":false,\"via\":false,\"max_forwards\":false,\"route\":false,\"record_route\":false,\"error_action\":[{\"error\":\"default\",\"action\":\"passthru\"}]}",
"header" : [ {
"operation" : "add",
"name" : "f",
"value" : "\"*Alice In Wonderland\" <sip:+15714340000@example.com>;tag=1f4e4f40"
}, {
"operation" : "add",
"name" : "P-Asserted-Identity",
"value" : "\"*Alice In Wonderland,Walt Disney World Resort,Orlando,FL 32830\" <sip:+15714340000@example.com;tmpl=none;bn=Disney%20World;dept=Theme%20Park;lt=Wireline;st=Business;bt=Entertainment;ba=Walt%20Disney%20World%20Resort;cs=Orlando, FL;city=Orlando;state=FL;ct=US;zip=32830;wb=http://movies.disney.com/alice-in-wonderland-1951;lg=https://static-mh.content.disney.io/matterhorn/assets/goc/nav-logo-dark@2x-2b3eb08c507c.png;tg=#AliceInWonderLand;sm=%7B%22Facebook%22%3A%22https%3A%2F%2Fwww.facebook.com%2FDisneyAliceInWonderland%22%2C%22Twitter%22%3A%22https%3A%2F%2Ftwitter.com%2FDisney%22%7D;nm=Alice;fn=Alice;ln=Liddell;jt=Adventurer;hs=https://encrypted-tbn0.gstatic.com/images?q%3dtbn:ANd9GcR2Q1GWX6hdmMr2dh10SoTeEKEn4S4toc4V3yAJCrPQHlzWvr_I;cp=Customer Support;email=alice@disney.com>"
}, {
"operation" : "remove",
"name" : "f",
"value" : "\"alice\" <sip:+15714340000@example.com>;tag=1f4e4f40"
}, {
"operation" : "remove",
"name" : "P-Asserted-Identity",
"value" : "\"Alice\" <tel:+17035550001>"
}, {
"operation" : "remove",
"name" : "P-Asserted-Identity",
"value" : "\"Alice\" <sip:+17035550001@example.com>"
} ]
}
The description of the fields in the response is as below:
Path | Type | Optional | Description |
---|---|---|---|
|
|
|
Verification status |
|
|
|
The URI of next hop |
|
|
|
The policy for processing the SIP message |
|
|
|
A list of SIP headers or RequestLine to be added into or removed from SIP INVITE message |
|
|
|
Either 'add' or 'remove' |
|
|
|
The name of the SIP header or RequestLine to be added or removed |
|
|
|
The value of the SIP header or RequestLine to be added or removed |
Example For Verifying SIP SIP Identity Header with Route Data Replacement
The following is an example for verifying for verifying a SIP Identity header by submitting a SIP INVITE message as the request, with the route data in Request-URI and Contact header to be modified in the outgoing SIP INVITE message, according to various policies provisioned, along with CNAM/ECNAM lookup:
$ curl 'https://ca-verify.neustarlab.biz/ccid/verify/v2/identity/proxy/127.0.0.1/5060?apiKey=%3CapiKey1%3E' -i -X POST \
-H 'Content-Type: text/plain' \
-H 'Accept: application/json' \
-d 'INVITE sip:+15714340001;tgrp=C;trunk-context=D@proxy.example.com;transport=UDP SIP/2.0
Via: SIP/2.0/UDP proxy.example.com:39089;branch=z9hG4bK-d8754za
Max-Forwards: 70
Contact: "alice" <sip:alice;tgrp=A;trunk-context=B@proxy.example.com:39089;transport=UDP>
From: "alice" <sip:+15714340000@example.com>;tag=1f4e4f40
To: "bob" <sip:+15714340001@example.com>
Date: Mon, 25 Nov 2024 20:28:42 GMT
Call-ID: YzRlZDFlYzYyM2IwOTdlMzk0MDA3MTRmZmY3OGIzODM.
Identity: eyJhbGciOiJFUzI1NiIsInBwdCI6InNoYWtlbiIsInR5cCI6InBhc3Nwb3J0IiwieDV1IjoiaHR0cDovL2NhLmV4YW1wbGUuY29tL3Rlc3QuZGVyIn0.eyJhdHRlc3QiOiJBIiwiZGVzdCI6eyJ0biI6WyIxNTcxNDM0MDAwMSJdfSwiaWF0IjoxNzMyNTY2NTIyLCJta3kiOlt7ImFsZyI6IlNIQS0xIiwiZGlnIjoiNEFBREI5QjEzRjgyMTgzQjU0MDIxMkRGM0U1RDQ5NkIxOUU1N0NBQiJ9LHsiYWxnIjoiU0hBLTI1NiIsImRpZyI6IjM2M0JBRTEyOTU5NUY1OTcyREY3RTA4NEZFQ0RGMUJDQUQ3QTcwNjRGN0U3NEY3RUE2MDIwNjBFMzc1NENGRjcifV0sIm9yaWciOnsidG4iOiIxNzAzNTU1MDAwMSJ9LCJvcmlnaWQiOiIxMjM0NTYtQUJDRC05OTk5OTkiLCJyY2QiOnsibmFtIjoiQWxpY2UifX0.qXz1vaIx5VvZRNbNxGbf_9IAcTpUE5LulHDYhfywnHsquobhIW0CDgmGIIO4DfqjgfCxQVJlKN9RGrlHN6rwQA;info=<http://ca.example.com/test.der>;alg=ES256;ppt="shaken"
P-Asserted-Identity: "Alice" <tel:+17035550001>
P-Asserted-Identity: "Alice" <sip:+17035550001@example.com>
CSeq: 2 INVITE
Content-Type: application/sdp
User-Agent: Z 3.3.25608 r25552
Supported: replaces, norefersub, extended-refer, timer
Allow-Events: presence, kpml
Content-Length: 439
v=0
o=Z 0 0 IN IP4 10.31.32.251
s=Z
c=IN IP4 10.31.32.251
t=0 0
m=audio 8000 RTP/AVP 8 0 3 110 98 101
a=fingerprint:SHA-1 4A:AD:B9:B1:3F:82:18:3B:54:02:12:DF:3E:5D:49:6B:19:E5:7C:AB
a=fingerprint:SHA-256 36:3B:AE:12:95:95:F5:97:2D:F7:E0:84:FE:CD:F1:BC:AD:7A:70:64:F7:E7:4F:7E:A6:02:06:0E:37:54:CF:F7
a=rtpmap:110 speex/8000
a=rtpmap:98 iLBC/8000
a=fmtp:98 mode=20
a=rtpmap:101 telephone-event/8000
a=fmtp:101 0-15
a=sendrecv
'
The successful response message is as below:
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 2277
{
"status" : "ok",
"next_hop" : "udp:192.168.1.1:5060",
"policy" : "{\"stateful\":false,\"via\":false,\"max_forwards\":false,\"route\":false,\"record_route\":false,\"error_action\":[{\"error\":\"default\",\"action\":\"passthru\"}]}",
"header" : [ {
"operation" : "add",
"name" : "RequestLine",
"value" : "INVITE sip:+15714340001;tgrp=Z;trunk-context=D@proxy.example.com;transport=UDP SIP/2.0"
}, {
"operation" : "add",
"name" : "Contact",
"value" : "\"alice\" <sip:alice;tgrp=X;trunk-context=B@proxy.example.com:39089;transport=UDP>"
}, {
"operation" : "add",
"name" : "From",
"value" : "\"*Alice In Wonderland\" <sip:+15714340000@example.com>;tag=1f4e4f40"
}, {
"operation" : "add",
"name" : "P-Asserted-Identity",
"value" : "\"*Alice In Wonderland,Walt Disney World Resort,Orlando,FL 32830\" <sip:+15714340000@example.com;tmpl=none;bn=Disney%20World;dept=Theme%20Park;lt=Wireline;st=Business;bt=Entertainment;ba=Walt%20Disney%20World%20Resort;cs=Orlando, FL;city=Orlando;state=FL;ct=US;zip=32830;wb=http://movies.disney.com/alice-in-wonderland-1951;lg=https://static-mh.content.disney.io/matterhorn/assets/goc/nav-logo-dark@2x-2b3eb08c507c.png;tg=#AliceInWonderLand;sm=%7B%22Facebook%22%3A%22https%3A%2F%2Fwww.facebook.com%2FDisneyAliceInWonderland%22%2C%22Twitter%22%3A%22https%3A%2F%2Ftwitter.com%2FDisney%22%7D;nm=Alice;fn=Alice;ln=Liddell;jt=Adventurer;hs=https://encrypted-tbn0.gstatic.com/images?q%3dtbn:ANd9GcR2Q1GWX6hdmMr2dh10SoTeEKEn4S4toc4V3yAJCrPQHlzWvr_I;cp=Customer Support;email=alice@disney.com>"
}, {
"operation" : "remove",
"name" : "RequestLine",
"value" : "INVITE sip:+15714340001;tgrp=C;trunk-context=D@proxy.example.com;transport=UDP SIP/2.0"
}, {
"operation" : "remove",
"name" : "Contact",
"value" : "\"alice\" <sip:alice;tgrp=A;trunk-context=B@proxy.example.com:39089;transport=UDP>"
}, {
"operation" : "remove",
"name" : "From",
"value" : "\"alice\" <sip:+15714340000@example.com>;tag=1f4e4f40"
}, {
"operation" : "remove",
"name" : "P-Asserted-Identity",
"value" : "\"Alice\" <tel:+17035550001>"
}, {
"operation" : "remove",
"name" : "P-Asserted-Identity",
"value" : "\"Alice\" <sip:+17035550001@example.com>"
} ]
}
The description of the fields in the response is as below:
Path | Type | Optional | Description |
---|---|---|---|
|
|
|
Verification status |
|
|
|
The URI of next hop |
|
|
|
The policy for processing the SIP message |
|
|
|
A list of SIP headers or RequestLine to be added into or removed from SIP INVITE message |
|
|
|
Either 'add' or 'remove' |
|
|
|
The name of the SIP header or RequestLine to be added or removed |
|
|
|
The value of the SIP header or RequestLine to be added or removed |
Example of Verifying SIP Identity Header without Identity Headers for Diverted Calls
The following is an example for verifying a SIP Identity header in a SIP INVITE message with SIP Diversion headers but without SIP Identity headers for Diverted Calls. The interface policy is configured that an error should be returned for identifying required SIP Identity headers for Diverted Calls, although the other SIP Identity header is verified successfully.
$ curl 'https://ca-verify.neustarlab.biz/ccid/verify/v2/identity/proxy/172.20.0.1/5060?apiKey=%3CapiKey1%3E' -i -X POST \
-H 'Content-Type: text/plain' \
-H 'Accept: application/json' \
-d 'INVITE sip:+15715550001@proxy.example.com;transport=UDP SIP/2.0
Via: SIP/2.0/UDP proxy.example.com:39089;branch=z9hG4bK-d8754za
Max-Forwards: 70
Contact: "alice" <sip:alice@proxy.example.com:39089;transport=UDP>
From: "alice" <sip:+15715550000@example.com>;tag=1f4e4f40
To: "bob" <sip:bob@example.com>
Diversion: "bob" <sip:bob@example.com>
Diversion: "bob" <tel:+17035550001>
Date: Mon, 25 Nov 2024 20:28:41 GMT
Call-ID: YzRlZDFlYzYyM2IwOTdlMzk0MDA3MTRmZmY3OGIzODM.
Identity: eyJhbGciOiJFUzI1NiIsInBwdCI6InNoYWtlbiIsInR5cCI6InBhc3Nwb3J0IiwieDV1IjoiaHR0cDovL2NhLmV4YW1wbGUuY29tL3Rlc3QuZGVyIn0.eyJhdHRlc3QiOiJBIiwiZGVzdCI6eyJ1cmkiOlsic2lwOmJvYkBleGFtcGxlLmNvbSJdfSwiaWF0IjoxNzMyNTY2NTIxLCJvcmlnIjp7InRuIjoiMTU3MTU1NTAwMDAifSwib3JpZ2lkIjoiMTIzNDU2LUFCQ0QtOTk5OTk5IiwicmNkIjp7Im5hbSI6ImFsaWNlIn19.eNZz597OtYB3_1ufDKspXlY3HPlbq7SGB6tdpjexjqP4L4HHoULPEsJpa-noNaptlC8Z_TZTpYS2QEgMqsmc-A;info=<http://ca.example.com/test.der>;alg=ES256;ppt="shaken"
P-Asserted-Identity: "alice" <sip:+15715550000@example.com;tag=abc123>
Resource-Priority: ets.0, wps.2
Resource-Priority: q735.1
CSeq: 2 INVITE
Content-Type: application/sdp
User-Agent: Z 3.3.25608 r25552
Allow-Events: presence, kpml
Content-Length: 239
v=0
o=Z 0 0 IN IP4 10.31.32.251
s=Z
c=IN IP4 10.31.32.251
t=0 0
m=audio 8000 RTP/AVP 8 0 3 110 98 101
a=rtpmap:110 speex/8000
a=rtpmap:98 iLBC/8000
a=fmtp:98 mode=20
a=rtpmap:101 telephone-event/8000
a=fmtp:101 0-15
a=sendrecv
'
The successful response message is as below, with an error identifier RequestIdentityHeaderDivRequired
:
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 1771
{
"status" : "ok",
"error" : [ {
"error_id" : "RequestIdentityHeaderDivRequired",
"http_status_code" : 403,
"sip_code" : 428,
"reason" : "Identity header with 'ppt' as 'div' required",
"timestamp" : "Mon, 25 Nov 2024 20:28:41 GMT"
} ],
"next_hop" : "udp:192.168.1.1:5060",
"policy" : "{\"stateful\":false,\"via\":false,\"max_forwards\":false,\"route\":false,\"record_route\":false,\"error_action\":[{\"error\":\"default\",\"action\":\"passthru\"}]}",
"header" : [ {
"operation" : "add",
"name" : "From",
"value" : "\"*Alice In Wonderland\" <sip:+15715550000@example.com>;tag=1f4e4f40"
}, {
"operation" : "add",
"name" : "P-Asserted-Identity",
"value" : "\"*Alice In Wonderland,Walt Disney World Resort,Orlando,FL 32830\" <sip:+15715550000@example.com;tmpl=none;bn=Disney%20World;dept=Theme%20Park;lt=Wireline;st=Business;bt=Entertainment;ba=Walt%20Disney%20World%20Resort;cs=Orlando, FL;city=Orlando;state=FL;ct=US;zip=32830;wb=http://movies.disney.com/alice-in-wonderland-1951;lg=https://static-mh.content.disney.io/matterhorn/assets/goc/nav-logo-dark@2x-2b3eb08c507c.png;tg=#AliceInWonderLand;sm=%7B%22Facebook%22%3A%22https%3A%2F%2Fwww.facebook.com%2FDisneyAliceInWonderland%22%2C%22Twitter%22%3A%22https%3A%2F%2Ftwitter.com%2FDisney%22%7D;nm=Alice;fn=Alice;ln=Liddell;jt=Adventurer;hs=https://encrypted-tbn0.gstatic.com/images?q%3dtbn:ANd9GcR2Q1GWX6hdmMr2dh10SoTeEKEn4S4toc4V3yAJCrPQHlzWvr_I;cp=Customer Support;email=alice@disney.com>"
}, {
"operation" : "remove",
"name" : "From",
"value" : "\"alice\" <sip:+15715550000@example.com>;tag=1f4e4f40"
}, {
"operation" : "remove",
"name" : "P-Asserted-Identity",
"value" : "\"alice\" <sip:+15715550000@example.com;tag=abc123>"
} ]
}
The description of the fields in the response is as below:
Path | Type | Optional | Description |
---|---|---|---|
|
|
|
Verification status |
|
|
|
The URI of next hop |
|
|
|
The policy for processing the SIP message |
|
|
|
A list of SIP headers or RequestLine to be added into or removed from SIP INVITE message |
|
|
|
Either 'add' or 'remove' |
|
|
|
The name of the SIP header or RequestLine to be added or removed |
|
|
|
The value of the SIP header or RequestLine to be added or removed |
|
|
|
A list of errors encountered in verifying SIP Identity headers |
|
|
|
The unique error identifier |
|
|
|
The HTTP response status code |
|
|
|
The SIP response code associated with the error |
|
|
|
The detailed error text |
|
|
|
The timestamp when the error is generated |
Example of Partially Verifying SIP Identity Headers
The following is an example for verifying two SIP Identity headers, one valid, the other invalid by submitting a SIP INVITE message as the request. The response in JSON format instructs the SIP proxy that the SIP Identity headers have been partially verified, as the originator of the SIP INVITE message accepts partially verified SIP INVITE message.
$ curl 'https://ca-verify.neustarlab.biz/ccid/verify/v2/identity/proxy/127.0.0.1/5060?apiKey=%3CapiKey2%3E' -i -X POST \
-H 'Content-Type: text/plain' \
-H 'Accept: application/json' \
-d 'INVITE sip:+15714340001@proxy.example.com;transport=UDP SIP/2.0
Via: SIP/2.0/UDP proxy.example.com:39089;branch=z9hG4bK-d8754za
Max-Forwards: 70
Contact: "alice" <sip:alice@proxy.example.com:39089;transport=UDP>
From: "alice" <sip:+15714340000@example.com>;tag=1f4e4f40
To: "bob" <sip:+15714340001@example.com>
Date: Mon, 25 Nov 2024 20:28:41 GMT
Call-ID: YzRlZDFlYzYyM2IwOTdlMzk0MDA3MTRmZmY3OGIzODM.
Identity: eyJhbGciOiJFUzI1NiIsInBwdCI6InNoYWtlbiIsInR5cCI6InBhc3Nwb3J0IiwieDV1IjoiaHR0cDovL2NhLmV4YW1wbGUuY29tL3Rlc3QuZGVyIn0.eyJhdHRlc3QiOiJBIiwiZGVzdCI6eyJ0biI6WyIxNTcxNDM0MDAwMCJdfSwiaWF0IjoxNzMyNTY2NTIxLCJta3kiOlt7ImFsZyI6IlNIQS0xIiwiZGlnIjoiNEFBREI5QjEzRjgyMTgzQjU0MDIxMkRGM0U1RDQ5NkIxOUU1N0NBQiJ9LHsiYWxnIjoiU0hBLTI1NiIsImRpZyI6IjM2M0JBRTEyOTU5NUY1OTcyREY3RTA4NEZFQ0RGMUJDQUQ3QTcwNjRGN0U3NEY3RUE2MDIwNjBFMzc1NENGRjcifV0sIm9yaWciOnsidG4iOiIxNzAzNTU1MDAwMSJ9LCJvcmlnaWQiOiIxMjM0NTYtQUJDRC05OTk5OTkiLCJyY2QiOnsibmFtIjoiQWxpY2UifX0.XNF8oOypdVttn-Wrk16GZpBHUQmQsOffsT9mVIKIpSg0QXiWC84AHnPw7Rvymo2st3IQWRwDR32oX6sZRkFIag;info=<http://ca.example.com/test.der>;alg=ES256;ppt="shaken"
Identity: eyJhbGciOiJFUzI1NiIsInBwdCI6InNoYWtlbiIsInR5cCI6InBhc3Nwb3J0IiwieDV1IjoiaHR0cDovL2NhLmV4YW1wbGUuY29tL3Rlc3QuZGVyIn0.eyJhdHRlc3QiOiJBIiwiZGVzdCI6eyJ0biI6WyIxNTcxNDM0MDAwMSJdfSwiaWF0IjoxNzMyNTY2NTIxLCJta3kiOlt7ImFsZyI6IlNIQS0xIiwiZGlnIjoiNEFBREI5QjEzRjgyMTgzQjU0MDIxMkRGM0U1RDQ5NkIxOUU1N0NBQiJ9LHsiYWxnIjoiU0hBLTI1NiIsImRpZyI6IjM2M0JBRTEyOTU5NUY1OTcyREY3RTA4NEZFQ0RGMUJDQUQ3QTcwNjRGN0U3NEY3RUE2MDIwNjBFMzc1NENGRjcifV0sIm9yaWciOnsidG4iOiIxNzAzNTU1MDAwMSJ9LCJvcmlnaWQiOiIxMjM0NTYtQUJDRC05OTk5OTkiLCJyY2QiOnsibmFtIjoiQWxpY2UifX0.IqYM8hmhwFCkcrtvlN9b0mH_U0Ny-nDQYhioFKr0c-4KS7xbfvUkZKOhwTA6SOkFjLW9PYMk-Df8dq-lwFtoiQ;info=<http://ca.example.com/test.der>;alg=ES256;ppt="shaken"
P-Asserted-Identity: "Alice" <tel:+17035550001>
P-Asserted-Identity: "Alice" <sip:+17035550001@example.com>
CSeq: 2 INVITE
Content-Type: application/sdp
User-Agent: Z 3.3.25608 r25552
Supported: replaces, norefersub, extended-refer, timer
Allow-Events: presence, kpml
Content-Length: 439
v=0
o=Z 0 0 IN IP4 10.31.32.251
s=Z
c=IN IP4 10.31.32.251
t=0 0
m=audio 8000 RTP/AVP 8 0 3 110 98 101
a=fingerprint:SHA-1 4A:AD:B9:B1:3F:82:18:3B:54:02:12:DF:3E:5D:49:6B:19:E5:7C:AB
a=fingerprint:SHA-256 36:3B:AE:12:95:95:F5:97:2D:F7:E0:84:FE:CD:F1:BC:AD:7A:70:64:F7:E7:4F:7E:A6:02:06:0E:37:54:CF:F7
a=rtpmap:110 speex/8000
a=rtpmap:98 iLBC/8000
a=fmtp:98 mode=20
a=rtpmap:101 telephone-event/8000
a=fmtp:101 0-15
a=sendrecv
'
The successful response message is as below:
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 2142
{
"status" : "ok",
"error" : [ {
"error_id" : "IdentityClaimDestMismatch",
"http_status_code" : 400,
"sip_code" : 438,
"reason" : "'dest' value specified in PASSporT claim does not match SIP To header value",
"timestamp" : "Mon, 25 Nov 2024 20:28:41 GMT",
"developer_message" : "TN is global already",
"attributes" : {
"dest" : "{\"global\":true,\"type\":\"TN\",\"value\":\"15714340001\",\"host\":\"example.com\"}",
"dest_expected" : "{\"tn\":[\"15714340000\"]}"
}
} ],
"next_hop" : "udp:[ff00::192.168.1.1]:5060",
"policy" : "{\"stateful\":false,\"via\":false,\"max_forwards\":false,\"route\":false,\"record_route\":false,\"error_action\":[{\"error\":\"default\",\"action\":\"passthru\"}]}",
"header" : [ {
"operation" : "add",
"name" : "From",
"value" : "\"*Alice In Wonderland\" <sip:+15714340000@example.com>;tag=1f4e4f40"
}, {
"operation" : "add",
"name" : "P-Asserted-Identity",
"value" : "\"*Alice In Wonderland,Walt Disney World Resort,Orlando,FL 32830\" <sip:+15714340000@example.com;tmpl=none;bn=Disney%20World;dept=Theme%20Park;lt=Wireline;st=Business;bt=Entertainment;ba=Walt%20Disney%20World%20Resort;cs=Orlando, FL;city=Orlando;state=FL;ct=US;zip=32830;wb=http://movies.disney.com/alice-in-wonderland-1951;lg=https://static-mh.content.disney.io/matterhorn/assets/goc/nav-logo-dark@2x-2b3eb08c507c.png;tg=#AliceInWonderLand;sm=%7B%22Facebook%22%3A%22https%3A%2F%2Fwww.facebook.com%2FDisneyAliceInWonderland%22%2C%22Twitter%22%3A%22https%3A%2F%2Ftwitter.com%2FDisney%22%7D;nm=Alice;fn=Alice;ln=Liddell;jt=Adventurer;hs=https://encrypted-tbn0.gstatic.com/images?q%3dtbn:ANd9GcR2Q1GWX6hdmMr2dh10SoTeEKEn4S4toc4V3yAJCrPQHlzWvr_I;cp=Customer Support;email=alice@disney.com>"
}, {
"operation" : "remove",
"name" : "From",
"value" : "\"alice\" <sip:+15714340000@example.com>;tag=1f4e4f40"
}, {
"operation" : "remove",
"name" : "P-Asserted-Identity",
"value" : "\"Alice\" <tel:+17035550001>"
}, {
"operation" : "remove",
"name" : "P-Asserted-Identity",
"value" : "\"Alice\" <sip:+17035550001@example.com>"
} ]
}
The description of the fields in the response is as below:
Path | Type | Optional | Description |
---|---|---|---|
|
|
|
Verification status |
|
|
|
The URI of next hop |
|
|
|
The policy for processing the SIP message |
|
|
|
A list of SIP headers or RequestLine to be added into or removed from SIP INVITE message |
|
|
|
Either 'add' or 'remove' |
|
|
|
The name of the SIP header or RequestLine to be added or removed |
|
|
|
The value of the SIP header or RequestLine to be added or removed |
|
|
|
A list of errors encountered in verifying SIP Identity headers |
|
|
|
The unique error identifier |
|
|
|
The HTTP response status code |
|
|
|
The SIP response code associated with the error |
|
|
|
The detailed error text |
|
|
|
The timestamp when the error is generated |
|
|
|
The additional developer message, if any |
|
|
|
The name/value pair .attribute map associated with the error |
|
|
|
The attribute name of 'dest_expected' in the name/value pair |
|
|
|
The attribute name of 'dest' in the name/value pair |
Example of Re-signing SIP Identity Header after Verification
The following is an example for verifying a SIP Identity header by submitting a SIP INVITE message as the request and triggering SIP Identity header re-signing process. The response in JSON format instructs the SIP proxy that the SIP Identity header has been verified, and a new SIP Identity header to be added to the SIP INVITE message, and the existing SIP Identity header removed.
$ curl 'https://ca-verify.neustarlab.biz/ccid/verify/v2/identity/proxy/127.0.0.1/5060?apiKey=%3CapiKey6%3E' -i -X POST \
-H 'Content-Type: text/plain' \
-H 'Accept: application/json' \
-d 'INVITE sip:+15714340001@proxy.example.com;transport=UDP SIP/2.0
Via: SIP/2.0/UDP proxy.example.com:39089;branch=z9hG4bK-d8754za
Max-Forwards: 70
Contact: "Alice" <sip:alice@proxy.example.com:39089;transport=UDP>
From: "Alice" <sip:+15714340000@example.com>;tag=1f4e4f40
To: "bob" <sip:+15714340001@example.com>
Date: Mon, 25 Nov 2024 20:28:41 GMT
Call-ID: YzRlZDFlYzYyM2IwOTdlMzk0MDA3MTRmZmY3OGIzODM.
Identity: eyJhbGciOiJFUzI1NiIsInR5cCI6InBhc3Nwb3J0IiwieDV1IjoiaHR0cDovL2NhLmV4YW1wbGUuY29tL3Rlc3QuZGVyIn0.eyJkZXN0Ijp7InRuIjpbIjE1NzE0MzQwMDAxIl19LCJpYXQiOjE3MzI1NjY1MjEsIm9yaWciOnsidG4iOiIxNTcxNDM0MDAwMCJ9fQ.j4se6mNYxPcQ0roAMV12qlFDf8QLx55iAe7YVAT9l49V3g3XS_LdUs6vbYLTs_Wj0B7-6h9vzed9ueoKXer-gA;info=<http://ca.example.com/test.der>;alg=ES256
CSeq: 2 INVITE
Content-Type: application/sdp
User-Agent: Z 3.3.25608 r25552
Supported: replaces, norefersub, extended-refer, timer
Allow-Events: presence, kpml
Content-Length: 239
v=0
o=Z 0 0 IN IP4 10.31.32.251
s=Z
c=IN IP4 10.31.32.251
t=0 0
m=audio 8000 RTP/AVP 8 0 3 110 98 101
a=rtpmap:110 speex/8000
a=rtpmap:98 iLBC/8000
a=fmtp:98 mode=20
a=rtpmap:101 telephone-event/8000
a=fmtp:101 0-15
a=sendrecv
'
The successful response message is as below:
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 1193
{
"status" : "ok",
"next_hop" : "udp:192.168.1.1:5060",
"policy" : "{\"stateful\":false,\"via\":false,\"max_forwards\":false,\"route\":false,\"record_route\":false,\"error_action\":[{\"error\":\"default\",\"action\":\"reject\"}]}",
"header" : [ {
"operation" : "remove",
"name" : "Identity",
"value" : "eyJhbGciOiJFUzI1NiIsInR5cCI6InBhc3Nwb3J0IiwieDV1IjoiaHR0cDovL2NhLmV4YW1wbGUuY29tL3Rlc3QuZGVyIn0.eyJkZXN0Ijp7InRuIjpbIjE1NzE0MzQwMDAxIl19LCJpYXQiOjE3MzI1NjY1MjEsIm9yaWciOnsidG4iOiIxNTcxNDM0MDAwMCJ9fQ.j4se6mNYxPcQ0roAMV12qlFDf8QLx55iAe7YVAT9l49V3g3XS_LdUs6vbYLTs_Wj0B7-6h9vzed9ueoKXer-gA;info=<http://ca.example.com/test.der>;alg=ES256"
}, {
"operation" : "add",
"name" : "Identity",
"value" : "eyJhbGciOiJFUzI1NiIsInBwdCI6InNoYWtlbiIsInR5cCI6InBhc3Nwb3J0IiwieDV1IjoiaHR0cDovL2NhLmV4YW1wbGUuY29tL3Rlc3QuZGVyIn0.eyJhdHRlc3QiOiJBIiwiZGVzdCI6eyJ0biI6WyIxNTcxNDM0MDAwMSJdfSwiaWF0IjoxNzMyNTY2NTIxLCJvcmlnIjp7InRuIjoiMTU3MTQzNDAwMDAifSwib3JpZ2lkIjoiMTIzNDU2LUFCQ0QtOTk5OTk5IiwicmNkIjp7Im5hbSI6ImFsaWNlIn19.j0HJX2xnv-d8jkrVDwxRyg156v_8Ky5ECVskA518SaI_v-4su_K7sn_Zfl3X5rZqI7oYydIhf13j5BL6vZC0WQ;info=<http://ca.example.com/test.der>;alg=ES256;ppt=\"shaken\""
} ]
}
The description of the fields in the response is as below:
Path | Type | Optional | Description |
---|---|---|---|
|
|
|
Verification status |
|
|
|
The URI of next hop |
|
|
|
The policy for processing the SIP message |
|
|
|
A list of SIP headers or RequestLine to be added into or removed from SIP INVITE message |
|
|
|
Either 'add' or 'remove' |
|
|
|
The name of the SIP header or RequestLine to be added or removed |
|
|
|
The value of the SIP header or RequestLine to be added or removed |
Example of Re-signing Failure after Verification
The following is an example for verifying a SIP Identity header by submitting a SIP INVITE message as the request and triggering SIP Identity header re-signing process that is failed. The response in JSON format instructs the SIP proxy that the SIP Identity header has been verified and no changes needed to be made to the SIP INVITE message, with an error entry indicating that the re-signing process is failed.
$ curl 'https://ca-verify.neustarlab.biz/ccid/verify/v2/identity/proxy/127.0.0.1/5060?apiKey=%3CapiKey6%3E' -i -X POST \
-H 'Content-Type: text/plain' \
-H 'Accept: application/json' \
-d 'INVITE sip:+15714340001@proxy.example.com;transport=UDP SIP/2.0
Via: SIP/2.0/UDP proxy.example.com:39089;branch=z9hG4bK-d8754za
Max-Forwards: 70
Contact: "Alice" <sip:alice@proxy.example.com:39089;transport=UDP>
From: "Alice" <sip:+15714340000@example.com>;tag=1f4e4f40
To: "bob" <sip:+15714340001@example.com>
Date: Mon, 25 Nov 2024 20:28:41 GMT
Call-ID: YzRlZDFlYzYyM2IwOTdlMzk0MDA3MTRmZmY3OGIzODM.
Identity: eyJhbGciOiJFUzI1NiIsInR5cCI6InBhc3Nwb3J0IiwieDV1IjoiaHR0cDovL2NhLmV4YW1wbGUuY29tL3Rlc3QuZGVyIn0.eyJkZXN0Ijp7InRuIjpbIjE1NzE0MzQwMDAxIl19LCJpYXQiOjE3MzI1NjY1MjEsIm9yaWciOnsidG4iOiIxNTcxNDM0MDAwMCJ9fQ.2a9A3f3j5TotIq4VHtvsP2qIQ5nOlklAPisIwJJGbAU68jXJOV-juHukcBUzeA-VITWUfSfqM0vNBU7tvjF8cg;info=<http://ca.example.com/test.der>;alg=ES256
CSeq: 2 INVITE
Content-Type: application/sdp
User-Agent: Z 3.3.25608 r25552
Supported: replaces, norefersub, extended-refer, timer
Allow-Events: presence, kpml
Content-Length: 239
v=0
o=Z 0 0 IN IP4 10.31.32.251
s=Z
c=IN IP4 10.31.32.251
t=0 0
m=audio 8000 RTP/AVP 8 0 3 110 98 101
a=rtpmap:110 speex/8000
a=rtpmap:98 iLBC/8000
a=fmtp:98 mode=20
a=rtpmap:101 telephone-event/8000
a=fmtp:101 0-15
a=sendrecv
'
The response message below shows that the SIP Identity header is successful verified, but contains an "error" field indicating that SIP Identity re-signing process failed, with an "external_error" attribute conveying the reason of the re-signing failure:
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 1017
{
"status" : "ok",
"error" : [ {
"error_id" : "ServiceErrorInResigningIdentity",
"http_status_code" : 503,
"sip_code" : 503,
"reason" : "Service or request error in re-signing identity header",
"timestamp" : "Mon, 25 Nov 2024 20:28:41 GMT",
"developer_message" : "No authentication response",
"attributes" : {
"external_error" : {
"status" : "error",
"error" : [ {
"error_id" : "SipInterfaceNotAuthorized",
"http_status_code" : 400,
"sip_code" : 400,
"reason" : "SIP interface IP address/port not authorized",
"timestamp" : "Mon, 25 Nov 2024 20:28:41 GMT",
"attributes" : {
"address" : "192.168.1.1",
"port" : "5060"
}
} ]
}
}
} ],
"next_hop" : "udp:192.168.1.1:5060",
"policy" : "{\"stateful\":false,\"via\":false,\"max_forwards\":false,\"route\":false,\"record_route\":false,\"error_action\":[{\"error\":\"default\",\"action\":\"reject\"}]}"
}
The description of the fields in the response is as below:
Path | Type | Optional | Description |
---|---|---|---|
|
|
|
Verification status |
|
|
|
The URI of next hop |
|
|
|
The policy for processing the SIP message |
|
|
|
A list of errors encountered in verifying SIP Identity headers |
|
|
|
The unique error identifier |
|
|
|
The HTTP response status code |
|
|
|
The SIP response code associated with the error |
|
|
|
The detailed error text |
|
|
|
The timestamp when the error is generated |
Example of Failure in Verifying SIP Identity Headers
The following is an example of failure in verifying a SIP Identity header, by submitting a SIP INVITE message as the request. The response in JSON format instructs the SIP proxy that the SIP Identity header has been failed to be verified, as the originator of the SIP INVITE message requires all SIP headers to be verified.
$ curl 'https://ca-verify.neustarlab.biz/ccid/verify/v2/identity/proxy/127.0.0.1/5060?apiKey=%3CapiKey1%3E' -i -X POST \
-H 'Content-Type: text/plain' \
-H 'Accept: application/json' \
-d 'INVITE sip:+15714340001@proxy.example.com;transport=UDP SIP/2.0
Via: SIP/2.0/UDP proxy.example.com:39089;branch=z9hG4bK-d8754za
Max-Forwards: 70
Contact: "alice" <sip:alice@proxy.example.com:39089;transport=UDP>
From: "alice" <sip:+15714340000@example.com>;tag=1f4e4f40
To: "bob" <sip:+15714340001@example.com>
Date: Mon, 25 Nov 2024 20:28:41 GMT
Call-ID: YzRlZDFlYzYyM2IwOTdlMzk0MDA3MTRmZmY3OGIzODM.
Identity: eyJhbGciOiJFUzI1NiIsInR5cCI6InBhc3Nwb3J0IiwieDV1IjoiaHR0cDovL2NhLmV4YW1wbGUuY29tL3Rlc3QuZGVyIn0.eyJkZXN0Ijp7InRuIjpbIjE1NzE0MzQwMDAwIl19LCJpYXQiOjE3MzI1NjY1MjEsIm9yaWciOnsidG4iOiIxNTcxNDM0MDAwMSJ9fQ.L6IguJYsCyVxOJVAg0yaAAmDSEhs5qvLe3SHRQt2iLv0ekqMdzNAS3FbrnDvaoX5KK27qHpqrBvfJbrbBWiwKQ;info=<http://ca.example.com/test.der>;alg=ES256
CSeq: 2 INVITE
Content-Type: application/sdp
User-Agent: Z 3.3.25608 r25552
Supported: replaces, norefersub, extended-refer, timer
Allow-Events: presence, kpml
Content-Length: 239
v=0
o=Z 0 0 IN IP4 10.31.32.251
s=Z
c=IN IP4 10.31.32.251
t=0 0
m=audio 8000 RTP/AVP 8 0 3 110 98 101
a=rtpmap:110 speex/8000
a=rtpmap:98 iLBC/8000
a=fmtp:98 mode=20
a=rtpmap:101 telephone-event/8000
a=fmtp:101 0-15
a=sendrecv
'
The successful response message is as below:
HTTP/1.1 400 Bad Request
Content-Type: application/json
Content-Length: 742
{
"status" : "error",
"error" : [ {
"error_id" : "IdentityClaimDestMismatch",
"http_status_code" : 400,
"sip_code" : 438,
"reason" : "'dest' value specified in PASSporT claim does not match SIP To header value",
"timestamp" : "Mon, 25 Nov 2024 20:28:41 GMT",
"developer_message" : "TN is global already",
"attributes" : {
"dest" : "{\"global\":true,\"type\":\"TN\",\"value\":\"15714340001\",\"host\":\"example.com\"}",
"dest_expected" : "{\"tn\":[\"15714340000\"]}"
}
} ],
"next_hop" : "udp:192.168.1.1:5060",
"policy" : "{\"stateful\":false,\"via\":false,\"max_forwards\":false,\"route\":false,\"record_route\":false,\"error_action\":[{\"error\":\"default\",\"action\":\"passthru\"}]}"
}
The description of the fields in the response is as below:
Path | Type | Optional | Description |
---|---|---|---|
|
|
|
Verification status |
|
|
|
The URI of next hop |
|
|
|
The policy for processing the SIP message |
|
|
|
A list of errors encountered in verifying SIP Identity headers |
|
|
|
The unique error identifier |
|
|
|
The HTTP response status code |
|
|
|
The SIP response code associated with the error |
|
|
|
The detailed error text |
|
|
|
The timestamp when the error is generated |
|
|
|
The additional developer message, if any |
|
|
|
The name/value pair .attribute map associated with the error |
|
|
|
The attribute name of 'dest_expected' in the name/value pair |
|
|
|
The attribute name of 'dest' in the name/value pair |
Example For Tagging SIP INVITE Message with a Valid SIP Identity Header
The following is an example for tagging SIP INVITE message, in addition to generate a SIP Identity header with ATIS SHAKEN passport. The response in JSON format instructs the SIP proxy that SIP Identity/P-Attestation-Indicator/P-Originator headers to be added, and SIP From/P-Asserted-Id headers to be updated.
$ curl 'https://ca-verify.neustarlab.biz/ccid/verify/v2/identity/proxy/192.168.1.129/5060?apiKey=%3CapiKey7%3E' -i -X POST \
-H 'Content-Type: text/plain' \
-H 'Accept: application/json' \
-d 'INVITE sip:+15715550001@proxy.example.com;transport=UDP SIP/2.0
Via: SIP/2.0/UDP proxy.example.com:39089;branch=z9hG4bK-d8754za
Max-Forwards: 70
Contact: "alice" <sip:alice@proxy.example.com:39089;transport=UDP>
From: "alice" <sip:+15715550000@example.com>;tag=1f4e4f40
To: "bob" <sip:+15715550001@example.com>
Date: Mon, 25 Nov 2024 20:28:41 GMT
Call-ID: YzRlZDFlYzYyM2IwOTdlMzk0MDA3MTRmZmY3OGIzODM.
Identity: eyJhbGciOiJFUzI1NiIsInBwdCI6InNoYWtlbiIsInR5cCI6InBhc3Nwb3J0IiwieDV1IjoiaHR0cDovL2NhLmV4YW1wbGUuY29tL3Rlc3QuZGVyIn0.eyJhdHRlc3QiOiJBIiwiZGVzdCI6eyJ0biI6WyIxNTcxNTU1MDAwMSJdfSwiaWF0IjoxNzMyNTY2NTIxLCJta3kiOlt7ImFsZyI6IlNIQS0xIiwiZGlnIjoiNEFBREI5QjEzRjgyMTgzQjU0MDIxMkRGM0U1RDQ5NkIxOUU1N0NBQiJ9LHsiYWxnIjoiU0hBLTI1NiIsImRpZyI6IjM2M0JBRTEyOTU5NUY1OTcyREY3RTA4NEZFQ0RGMUJDQUQ3QTcwNjRGN0U3NEY3RUE2MDIwNjBFMzc1NENGRjcifV0sIm9yaWciOnsidG4iOiIxNzAzNTU1MDAwMSJ9LCJvcmlnaWQiOiIxMjM0NTYtQUJDRC05OTk5OTkiLCJyY2QiOnsibmFtIjoiQWxpY2UifX0.Sho_dQYWK8Jm2ngfbTMTwcZmzQgSb1mFr4Na-khJ6ByWtqjO9ZN2OoC9Fgni-qfTGcQyDpY7HeaF2Xz5BNzimA;info=<http://ca.example.com/test.der>;alg=ES256;ppt="shaken"
P-Asserted-Identity: "Alice" <tel:+17035550001>
P-Asserted-Identity: "Alice" <sip:+17035550001@example.com>
CSeq: 2 INVITE
Content-Type: application/sdp
User-Agent: Z 3.3.25608 r25552
Supported: replaces, norefersub, extended-refer, timer
Allow-Events: presence, kpml
Content-Length: 439
v=0
o=Z 0 0 IN IP4 10.31.32.251
s=Z
c=IN IP4 10.31.32.251
t=0 0
m=audio 8000 RTP/AVP 8 0 3 110 98 101
a=fingerprint:SHA-1 4A:AD:B9:B1:3F:82:18:3B:54:02:12:DF:3E:5D:49:6B:19:E5:7C:AB
a=fingerprint:SHA-256 36:3B:AE:12:95:95:F5:97:2D:F7:E0:84:FE:CD:F1:BC:AD:7A:70:64:F7:E7:4F:7E:A6:02:06:0E:37:54:CF:F7
a=rtpmap:110 speex/8000
a=rtpmap:98 iLBC/8000
a=fmtp:98 mode=20
a=rtpmap:101 telephone-event/8000
a=fmtp:101 0-15
a=sendrecv
'
The successful response message is as below:
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 2018
{
"status" : "ok",
"next_hop" : "tcp:192.168.1.1:5060",
"policy" : "{\"stateful\":false,\"via\":false,\"max_forwards\":false,\"route\":false,\"record_route\":false,\"error_action\":[{\"error\":\"default\",\"action\":\"passthru\"}]}",
"header" : [ {
"operation" : "add",
"name" : "From",
"value" : "\"*Alice\" <sip:+15715550000;verstat=TN-Validation-Passed@example.com>;tag=1f4e4f40"
}, {
"operation" : "add",
"name" : "P-Attestation-Indicator",
"value" : "A"
}, {
"operation" : "add",
"name" : "P-Origination-Id",
"value" : "123456-ABCD-999999"
}, {
"operation" : "add",
"name" : "P-Asserted-Identity",
"value" : "\"*Alice\" <tel:+17035550001;verstat=TN-Validation-Passed>"
}, {
"operation" : "add",
"name" : "P-Asserted-Identity",
"value" : "\"*Alice\" <sip:+17035550001;verstat=TN-Validation-Passed@example.com>"
}, {
"operation" : "remove",
"name" : "From",
"value" : "\"alice\" <sip:+15715550000@example.com>;tag=1f4e4f40"
}, {
"operation" : "remove",
"name" : "Identity",
"value" : "eyJhbGciOiJFUzI1NiIsInBwdCI6InNoYWtlbiIsInR5cCI6InBhc3Nwb3J0IiwieDV1IjoiaHR0cDovL2NhLmV4YW1wbGUuY29tL3Rlc3QuZGVyIn0.eyJhdHRlc3QiOiJBIiwiZGVzdCI6eyJ0biI6WyIxNTcxNTU1MDAwMSJdfSwiaWF0IjoxNzMyNTY2NTIxLCJta3kiOlt7ImFsZyI6IlNIQS0xIiwiZGlnIjoiNEFBREI5QjEzRjgyMTgzQjU0MDIxMkRGM0U1RDQ5NkIxOUU1N0NBQiJ9LHsiYWxnIjoiU0hBLTI1NiIsImRpZyI6IjM2M0JBRTEyOTU5NUY1OTcyREY3RTA4NEZFQ0RGMUJDQUQ3QTcwNjRGN0U3NEY3RUE2MDIwNjBFMzc1NENGRjcifV0sIm9yaWciOnsidG4iOiIxNzAzNTU1MDAwMSJ9LCJvcmlnaWQiOiIxMjM0NTYtQUJDRC05OTk5OTkiLCJyY2QiOnsibmFtIjoiQWxpY2UifX0.Sho_dQYWK8Jm2ngfbTMTwcZmzQgSb1mFr4Na-khJ6ByWtqjO9ZN2OoC9Fgni-qfTGcQyDpY7HeaF2Xz5BNzimA;info=<http://ca.example.com/test.der>;alg=ES256;ppt=\"shaken\""
}, {
"operation" : "remove",
"name" : "P-Asserted-Identity",
"value" : "\"Alice\" <tel:+17035550001>"
}, {
"operation" : "remove",
"name" : "P-Asserted-Identity",
"value" : "\"Alice\" <sip:+17035550001@example.com>"
} ]
}
The description of the fields in the response is as below:
Path | Type | Optional | Description |
---|---|---|---|
|
|
|
Verification status |
|
|
|
The URI of next hop |
|
|
|
The policy for processing the SIP message |
|
|
|
A list of SIP headers or RequestLine to be added into or removed from SIP INVITE message |
|
|
|
Either 'add' or 'remove' |
|
|
|
The name of the SIP header or RequestLine to be added or removed |
|
|
|
The value of the SIP header or RequestLine to be added or removed |
Example For Tagging SIP INVITE Message without SIP Identity Header
The following is an example for tagging an incoming SIP INVITE message without a SIP Identity header. The response in JSON format instructs the SIP proxy that the "verstat" value of "No-TN-Validation" to be appended to SIP From/P-Asserted-Id headers.
$ curl 'https://ca-verify.neustarlab.biz/ccid/verify/v2/identity/proxy/192.168.1.1/5060?apiKey=%3CapiKey7%3E' -i -X POST \
-H 'Content-Type: text/plain' \
-H 'Accept: application/json' \
-d 'INVITE sip:+15715550001@proxy.example.com;transport=UDP SIP/2.0
Via: SIP/2.0/UDP proxy.example.com:39089;branch=z9hG4bK-d8754za
Max-Forwards: 70
Contact: "alice" <sip:alice@proxy.example.com:39089;transport=UDP>
From: "alice" <sip:+15715550000@example.com>;tag=1f4e4f40
To: "bob" <sip:+15715550001@example.com>
Date: Mon, 25 Nov 2024 20:28:41 GMT
Call-ID: YzRlZDFlYzYyM2IwOTdlMzk0MDA3MTRmZmY3OGIzODM.
P-Asserted-Identity: "Alice" <tel:+17035550001>
P-Asserted-Identity: "Alice" <sip:+17035550001@example.com>
CSeq: 2 INVITE
Content-Type: application/sdp
User-Agent: Z 3.3.25608 r25552
Supported: replaces, norefersub, extended-refer, timer
Allow-Events: presence, kpml
Content-Length: 439
v=0
o=Z 0 0 IN IP4 10.31.32.251
s=Z
c=IN IP4 10.31.32.251
t=0 0
m=audio 8000 RTP/AVP 8 0 3 110 98 101
a=fingerprint:SHA-1 4A:AD:B9:B1:3F:82:18:3B:54:02:12:DF:3E:5D:49:6B:19:E5:7C:AB
a=fingerprint:SHA-256 36:3B:AE:12:95:95:F5:97:2D:F7:E0:84:FE:CD:F1:BC:AD:7A:70:64:F7:E7:4F:7E:A6:02:06:0E:37:54:CF:F7
a=rtpmap:110 speex/8000
a=rtpmap:98 iLBC/8000
a=fmtp:98 mode=20
a=rtpmap:101 telephone-event/8000
a=fmtp:101 0-15
a=sendrecv
'
The successful response message is as below:
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 1290
{
"status" : "ok",
"error" : [ {
"error_id" : "RequestIdentityHeaderRequired",
"http_status_code" : 403,
"sip_code" : 428,
"reason" : "Identity header value required",
"timestamp" : "Mon, 25 Nov 2024 20:28:41 GMT"
} ],
"next_hop" : "udp:192.168.1.1:5060",
"policy" : "{\"stateful\":false,\"via\":false,\"max_forwards\":false,\"route\":false,\"record_route\":false,\"error_action\":[{\"error\":\"default\",\"action\":\"passthru\"}]}",
"header" : [ {
"operation" : "add",
"name" : "From",
"value" : "\"xAlice\" <sip:+15715550000;verstat=No-TN-Validation@example.com>;tag=1f4e4f40"
}, {
"operation" : "add",
"name" : "P-Asserted-Identity",
"value" : "\"xAlice\" <tel:+17035550001;verstat=No-TN-Validation>"
}, {
"operation" : "add",
"name" : "P-Asserted-Identity",
"value" : "\"xAlice\" <sip:+17035550001;verstat=No-TN-Validation@example.com>"
}, {
"operation" : "remove",
"name" : "From",
"value" : "\"alice\" <sip:+15715550000@example.com>;tag=1f4e4f40"
}, {
"operation" : "remove",
"name" : "P-Asserted-Identity",
"value" : "\"Alice\" <tel:+17035550001>"
}, {
"operation" : "remove",
"name" : "P-Asserted-Identity",
"value" : "\"Alice\" <sip:+17035550001@example.com>"
} ]
}
The description of the fields in the response is as below:
Path | Type | Optional | Description |
---|---|---|---|
|
|
|
Verification status |
|
|
|
The URI of next hop |
|
|
|
The policy for processing the SIP message |
|
|
|
A list of SIP headers or RequestLine to be added into or removed from SIP INVITE message |
|
|
|
Either 'add' or 'remove' |
|
|
|
The name of the SIP header or RequestLine to be added or removed |
|
|
|
The value of the SIP header or RequestLine to be added or removed |
|
|
|
A list of errors encountered in verifying SIP Identity headers |
|
|
|
The unique error identifier |
|
|
|
The HTTP response status code |
|
|
|
The SIP response code associated with the error |
|
|
|
The detailed error text |
|
|
|
The timestamp when the error is generated |
Example For Tagging SIP INVITE Message with a Valid SIP Identity Header
The following is an example for tagging an incoming SIP INVITE message with a valid SIP Identity header. The response in JSON format instructs the SIP proxy that the "verstat" value of "TN-Validation-Passed" to be appended to SIP From/P-Asserted-Id headers, and SIP Identity header removed, and SIP P-Attestation-Indicator/P-Origination-Id headers added.
$ curl 'https://ca-verify.neustarlab.biz/ccid/verify/v2/identity/proxy/192.168.1.129/5060?apiKey=%3CapiKey7%3E' -i -X POST \
-H 'Content-Type: text/plain' \
-H 'Accept: application/json' \
-d 'INVITE sip:+15715550001@proxy.example.com;transport=UDP SIP/2.0
Via: SIP/2.0/UDP proxy.example.com:39089;branch=z9hG4bK-d8754za
Max-Forwards: 70
Contact: "alice" <sip:alice@proxy.example.com:39089;transport=UDP>
From: "alice" <sip:+15715550000@example.com>;tag=1f4e4f40
To: "bob" <sip:+15715550001@example.com>
Date: Mon, 25 Nov 2024 20:28:41 GMT
Call-ID: YzRlZDFlYzYyM2IwOTdlMzk0MDA3MTRmZmY3OGIzODM.
Identity: eyJhbGciOiJFUzI1NiIsInBwdCI6InNoYWtlbiIsInR5cCI6InBhc3Nwb3J0IiwieDV1IjoiaHR0cDovL2NhLmV4YW1wbGUuY29tL3Rlc3QuZGVyIn0.eyJhdHRlc3QiOiJBIiwiZGVzdCI6eyJ0biI6WyIxNTcxNTU1MDAwMSJdfSwiaWF0IjoxNzMyNTY2NTIxLCJta3kiOlt7ImFsZyI6IlNIQS0xIiwiZGlnIjoiNEFBREI5QjEzRjgyMTgzQjU0MDIxMkRGM0U1RDQ5NkIxOUU1N0NBQiJ9LHsiYWxnIjoiU0hBLTI1NiIsImRpZyI6IjM2M0JBRTEyOTU5NUY1OTcyREY3RTA4NEZFQ0RGMUJDQUQ3QTcwNjRGN0U3NEY3RUE2MDIwNjBFMzc1NENGRjcifV0sIm9yaWciOnsidG4iOiIxNzAzNTU1MDAwMSJ9LCJvcmlnaWQiOiIxMjM0NTYtQUJDRC05OTk5OTkiLCJyY2QiOnsibmFtIjoiQWxpY2UifX0.Sho_dQYWK8Jm2ngfbTMTwcZmzQgSb1mFr4Na-khJ6ByWtqjO9ZN2OoC9Fgni-qfTGcQyDpY7HeaF2Xz5BNzimA;info=<http://ca.example.com/test.der>;alg=ES256;ppt="shaken"
P-Asserted-Identity: "Alice" <tel:+17035550001>
P-Asserted-Identity: "Alice" <sip:+17035550001@example.com>
CSeq: 2 INVITE
Content-Type: application/sdp
User-Agent: Z 3.3.25608 r25552
Supported: replaces, norefersub, extended-refer, timer
Allow-Events: presence, kpml
Content-Length: 439
v=0
o=Z 0 0 IN IP4 10.31.32.251
s=Z
c=IN IP4 10.31.32.251
t=0 0
m=audio 8000 RTP/AVP 8 0 3 110 98 101
a=fingerprint:SHA-1 4A:AD:B9:B1:3F:82:18:3B:54:02:12:DF:3E:5D:49:6B:19:E5:7C:AB
a=fingerprint:SHA-256 36:3B:AE:12:95:95:F5:97:2D:F7:E0:84:FE:CD:F1:BC:AD:7A:70:64:F7:E7:4F:7E:A6:02:06:0E:37:54:CF:F7
a=rtpmap:110 speex/8000
a=rtpmap:98 iLBC/8000
a=fmtp:98 mode=20
a=rtpmap:101 telephone-event/8000
a=fmtp:101 0-15
a=sendrecv
'
The successful response message is as below:
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 2018
{
"status" : "ok",
"next_hop" : "tcp:192.168.1.1:5060",
"policy" : "{\"stateful\":false,\"via\":false,\"max_forwards\":false,\"route\":false,\"record_route\":false,\"error_action\":[{\"error\":\"default\",\"action\":\"passthru\"}]}",
"header" : [ {
"operation" : "add",
"name" : "From",
"value" : "\"*Alice\" <sip:+15715550000;verstat=TN-Validation-Passed@example.com>;tag=1f4e4f40"
}, {
"operation" : "add",
"name" : "P-Attestation-Indicator",
"value" : "A"
}, {
"operation" : "add",
"name" : "P-Origination-Id",
"value" : "123456-ABCD-999999"
}, {
"operation" : "add",
"name" : "P-Asserted-Identity",
"value" : "\"*Alice\" <tel:+17035550001;verstat=TN-Validation-Passed>"
}, {
"operation" : "add",
"name" : "P-Asserted-Identity",
"value" : "\"*Alice\" <sip:+17035550001;verstat=TN-Validation-Passed@example.com>"
}, {
"operation" : "remove",
"name" : "From",
"value" : "\"alice\" <sip:+15715550000@example.com>;tag=1f4e4f40"
}, {
"operation" : "remove",
"name" : "Identity",
"value" : "eyJhbGciOiJFUzI1NiIsInBwdCI6InNoYWtlbiIsInR5cCI6InBhc3Nwb3J0IiwieDV1IjoiaHR0cDovL2NhLmV4YW1wbGUuY29tL3Rlc3QuZGVyIn0.eyJhdHRlc3QiOiJBIiwiZGVzdCI6eyJ0biI6WyIxNTcxNTU1MDAwMSJdfSwiaWF0IjoxNzMyNTY2NTIxLCJta3kiOlt7ImFsZyI6IlNIQS0xIiwiZGlnIjoiNEFBREI5QjEzRjgyMTgzQjU0MDIxMkRGM0U1RDQ5NkIxOUU1N0NBQiJ9LHsiYWxnIjoiU0hBLTI1NiIsImRpZyI6IjM2M0JBRTEyOTU5NUY1OTcyREY3RTA4NEZFQ0RGMUJDQUQ3QTcwNjRGN0U3NEY3RUE2MDIwNjBFMzc1NENGRjcifV0sIm9yaWciOnsidG4iOiIxNzAzNTU1MDAwMSJ9LCJvcmlnaWQiOiIxMjM0NTYtQUJDRC05OTk5OTkiLCJyY2QiOnsibmFtIjoiQWxpY2UifX0.Sho_dQYWK8Jm2ngfbTMTwcZmzQgSb1mFr4Na-khJ6ByWtqjO9ZN2OoC9Fgni-qfTGcQyDpY7HeaF2Xz5BNzimA;info=<http://ca.example.com/test.der>;alg=ES256;ppt=\"shaken\""
}, {
"operation" : "remove",
"name" : "P-Asserted-Identity",
"value" : "\"Alice\" <tel:+17035550001>"
}, {
"operation" : "remove",
"name" : "P-Asserted-Identity",
"value" : "\"Alice\" <sip:+17035550001@example.com>"
} ]
}
The description of the fields in the response is as below:
Path | Type | Optional | Description |
---|---|---|---|
|
|
|
Verification status |
|
|
|
The URI of next hop |
|
|
|
The policy for processing the SIP message |
|
|
|
A list of SIP headers or RequestLine to be added into or removed from SIP INVITE message |
|
|
|
Either 'add' or 'remove' |
|
|
|
The name of the SIP header or RequestLine to be added or removed |
|
|
|
The value of the SIP header or RequestLine to be added or removed |
Example For Tagging SIP INVITE Message with an Invalid SIP Identity Header
The following is an example for tagging an incoming SIP INVITE message with an invalid SIP Identity header. The response in JSON format instructs the SIP proxy that the "verstat" value of "TN-Validation-Failed" to be appended to SIP From/P-Asserted-Id headers, and CNAM field appended with an "x" prefix in the SIP From header.
$ curl 'https://ca-verify.neustarlab.biz/ccid/verify/v2/identity/proxy/192.168.1.1/5060?apiKey=%3CapiKey7%3E' -i -X POST \
-H 'Content-Type: text/plain' \
-H 'Accept: application/json' \
-d 'INVITE sip:+15715550001@proxy.example.com;transport=UDP SIP/2.0
Via: SIP/2.0/UDP proxy.example.com:39089;branch=z9hG4bK-d8754za
Max-Forwards: 70
Contact: "alice" <sip:alice@proxy.example.com:39089;transport=UDP>
From: "alice" <sip:+15715550000@example.com>;tag=1f4e4f40
To: "bob" <sip:+15715550001@example.com>
Date: Mon, 25 Nov 2024 20:28:41 GMT
Call-ID: YzRlZDFlYzYyM2IwOTdlMzk0MDA3MTRmZmY3OGIzODM.
Identity: eyJhbGciOiJFUzI1NiIsInBwdCI6InNoYWtlbiIsInR5cCI6InBhc3Nwb3J0IiwieDV1IjoiaHR0cDovL2NhLmV4YW1wbGUuY29tL3Rlc3QuZGVyIn0.eyJhdHRlc3QiOiJBIiwiZGVzdCI6eyJ0biI6WyIxNTcxNTU1MDAwMCJdfSwiaWF0IjoxNzMyNTY2NTIxLCJta3kiOlt7ImFsZyI6IlNIQS0xIiwiZGlnIjoiNEFBREI5QjEzRjgyMTgzQjU0MDIxMkRGM0U1RDQ5NkIxOUU1N0NBQiJ9LHsiYWxnIjoiU0hBLTI1NiIsImRpZyI6IjM2M0JBRTEyOTU5NUY1OTcyREY3RTA4NEZFQ0RGMUJDQUQ3QTcwNjRGN0U3NEY3RUE2MDIwNjBFMzc1NENGRjcifV0sIm9yaWciOnsidG4iOiIxNzAzNTU1MDAwMSJ9LCJvcmlnaWQiOiIxMjM0NTYtQUJDRC05OTk5OTkiLCJyY2QiOnsibmFtIjoiQWxpY2UifX0.14Dty5CtEJE_n_bzAMf4kMuVcnfYRqVpRqwC13vforGsTJtXpEJaqSSj_tA8_6Sc50ELhsYH2rIiRpRMuTFRZQ;info=<http://ca.example.com/test.der>;alg=ES256;ppt="shaken"
P-Asserted-Identity: "Alice" <tel:+17035550001>
P-Asserted-Identity: "Alice" <sip:+17035550001@example.com>
CSeq: 2 INVITE
Content-Type: application/sdp
User-Agent: Z 3.3.25608 r25552
Supported: replaces, norefersub, extended-refer, timer
Allow-Events: presence, kpml
Content-Length: 439
v=0
o=Z 0 0 IN IP4 10.31.32.251
s=Z
c=IN IP4 10.31.32.251
t=0 0
m=audio 8000 RTP/AVP 8 0 3 110 98 101
a=fingerprint:SHA-1 4A:AD:B9:B1:3F:82:18:3B:54:02:12:DF:3E:5D:49:6B:19:E5:7C:AB
a=fingerprint:SHA-256 36:3B:AE:12:95:95:F5:97:2D:F7:E0:84:FE:CD:F1:BC:AD:7A:70:64:F7:E7:4F:7E:A6:02:06:0E:37:54:CF:F7
a=rtpmap:110 speex/8000
a=rtpmap:98 iLBC/8000
a=fmtp:98 mode=20
a=rtpmap:101 telephone-event/8000
a=fmtp:101 0-15
a=sendrecv
'
The successful response message is as below:
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 1577
{
"status" : "ok",
"error" : [ {
"error_id" : "IdentityClaimDestMismatch",
"http_status_code" : 400,
"sip_code" : 438,
"reason" : "'dest' value specified in PASSporT claim does not match SIP To header value",
"timestamp" : "Mon, 25 Nov 2024 20:28:41 GMT",
"developer_message" : "TN is global already",
"attributes" : {
"dest" : "{\"global\":true,\"type\":\"TN\",\"value\":\"15715550001\",\"host\":\"example.com\"}",
"dest_expected" : "{\"tn\":[\"15715550000\"]}"
}
} ],
"next_hop" : "udp:192.168.1.1:5060",
"policy" : "{\"stateful\":false,\"via\":false,\"max_forwards\":false,\"route\":false,\"record_route\":false,\"error_action\":[{\"error\":\"default\",\"action\":\"passthru\"}]}",
"header" : [ {
"operation" : "add",
"name" : "From",
"value" : "\"xAlice\" <sip:+15715550000;verstat=TN-Validation-Failed@example.com>;tag=1f4e4f40"
}, {
"operation" : "add",
"name" : "P-Asserted-Identity",
"value" : "\"xAlice\" <tel:+17035550001;verstat=TN-Validation-Failed>"
}, {
"operation" : "add",
"name" : "P-Asserted-Identity",
"value" : "\"xAlice\" <sip:+17035550001;verstat=TN-Validation-Failed@example.com>"
}, {
"operation" : "remove",
"name" : "From",
"value" : "\"alice\" <sip:+15715550000@example.com>;tag=1f4e4f40"
}, {
"operation" : "remove",
"name" : "P-Asserted-Identity",
"value" : "\"Alice\" <tel:+17035550001>"
}, {
"operation" : "remove",
"name" : "P-Asserted-Identity",
"value" : "\"Alice\" <sip:+17035550001@example.com>"
} ]
}
The description of the fields in the response is as below:
Path | Type | Optional | Description |
---|---|---|---|
|
|
|
Verification status |
|
|
|
The URI of next hop |
|
|
|
The policy for processing the SIP message |
|
|
|
A list of SIP headers or RequestLine to be added into or removed from SIP INVITE message |
|
|
|
Either 'add' or 'remove' |
|
|
|
The name of the SIP header or RequestLine to be added or removed |
|
|
|
The value of the SIP header or RequestLine to be added or removed |
|
|
|
A list of errors encountered in verifying SIP Identity headers |
|
|
|
The unique error identifier |
|
|
|
The HTTP response status code |
|
|
|
The SIP response code associated with the error |
|
|
|
The detailed error text |
|
|
|
The timestamp when the error is generated |
|
|
|
The additional developer message, if any |
|
|
|
The name/value pair .attribute map associated with the error |
|
|
|
The attribute name of 'dest_expected' in the name/value pair |
|
|
|
The attribute name of 'dest' in the name/value pair |
Example For Tagging SIP INVITE Message with SIP Call-Info Header
The following is an example for verifying an incoming SIP INVITE message with a SIP Call-Info header. The response in JSON format instructs the SIP proxy that the existing SIP Call-Info header to be removed, and a new SIP Call-Info header to be inserted:
$ curl 'https://ca-verify.neustarlab.biz/ccid/verify/v2/identity/proxy/127.0.0.2/5060?apiKey=%3CapiKey7%3E' -i -X POST \
-H 'Content-Type: text/plain' \
-H 'Accept: application/json' \
-d 'INVITE sip:+15714340001@proxy.example.com;transport=UDP SIP/2.0
Via: SIP/2.0/UDP proxy.example.com:39089;branch=z9hG4bK-d8754za
Max-Forwards: 70
Contact: "alice" <sip:alice@proxy.example.com:39089;transport=UDP>
From: "alice" <sip:+15714340000@example.com>;tag=1f4e4f40
Call-Info: <data:>;purpose=icon;call-reason="travel"
To: "bob" <sip:+15714340001@example.com>
Date: Mon, 25 Nov 2024 20:28:41 GMT
Call-ID: YzRlZDFlYzYyM2IwOTdlMzk0MDA3MTRmZmY3OGIzODM.
Identity: eyJhbGciOiJFUzI1NiIsInR5cCI6InBhc3Nwb3J0IiwieDV1IjoiaHR0cDovL2NhLmV4YW1wbGUuY29tL3Rlc3QuZGVyIn0.eyJkZXN0Ijp7InRuIjpbIjE1NzE0MzQwMDAxIl19LCJpYXQiOjE3MzI1NjY1MjEsIm9yaWciOnsidG4iOiIxNTcxNDM0MDAwMCJ9fQ.7Jy79jr6zVfY0_xT3knOhbovP-upV21DnjZGK-roi8D-YsZwjNALOYndpVeNHJRqNQdimYsOpzEOcjtMEy1Kww;info=<http://ca.example.com/test.der>;alg=ES256
CSeq: 2 INVITE
Content-Type: application/sdp
User-Agent: Z 3.3.25608 r25552
Supported: replaces, norefersub, extended-refer, timer
Allow-Events: presence, kpml
Content-Length: 239
v=0
o=Z 0 0 IN IP4 10.31.32.251
s=Z
c=IN IP4 10.31.32.251
t=0 0
m=audio 8000 RTP/AVP 8 0 3 110 98 101
a=rtpmap:110 speex/8000
a=rtpmap:98 iLBC/8000
a=fmtp:98 mode=20
a=rtpmap:101 telephone-event/8000
a=fmtp:101 0-15
a=sendrecv
'
The successful response message is as below:
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 523
{
"status" : "ok",
"next_hop" : "udp:192.168.1.1:5060",
"policy" : "{\"stateful\":false,\"via\":false,\"max_forwards\":false,\"route\":false,\"record_route\":false,\"error_action\":[{\"error\":\"default\",\"action\":\"passthru\"}]}",
"header" : [ {
"operation" : "add",
"name" : "Call-Info",
"value" : "<https://example.biz/alice.jpg>;purpose=icon;call-reason=\"Advanture\""
}, {
"operation" : "remove",
"name" : "Call-Info",
"value" : "<data:>;purpose=icon;call-reason=\"travel\""
} ]
}
The description of the fields in the response is as below:
Path | Type | Optional | Description |
---|---|---|---|
|
|
|
Verification status |
|
|
|
The URI of next hop |
|
|
|
The policy for processing the SIP message |
|
|
|
A list of SIP headers or RequestLine to be added into or removed from SIP INVITE message |
|
|
|
Either 'add' or 'remove' |
|
|
|
The name of the SIP header or RequestLine to be added or removed |
|
|
|
The value of the SIP header or RequestLine to be added or removed |
Example For Tagging SIP INVITE Message with SIP P-Identity-Bypass Header
The following is an example for tagging an incoming SIP INVITE message with SIP P-Identity-Bypass headers. The response in JSON format instructs the SIP proxy that the "verstat" value of "No-TN-Validation" to be appended to SIP From/P-Asserted-Identity headers, and the SIP P-Identity-Bypass header removed.
$ curl 'https://ca-verify.neustarlab.biz/ccid/verify/v2/identity/proxy/172.20.1.0/5060?apiKey=%3CapiKey11%3E' -i -X POST \
-H 'Content-Type: text/plain' \
-H 'Accept: application/json' \
-d 'INVITE sip:+15714340001@proxy.example.com;transport=UDP SIP/2.0
Via: SIP/2.0/UDP proxy.example.com:39089;branch=z9hG4bK-d8754za
Max-Forwards: 70
P-Identity-Bypass: IDENTITY-BYPASS-SPC0001-ABC123-000
Contact: "alice" <sip:alice@proxy.example.com:39089;transport=UDP>
From: "alice" <sip:+15714340000@example.com>;tag=1f4e4f40
To: "bob" <sip:+15714340001@example.com>
Date: Mon, 25 Nov 2024 20:28:41 GMT
Call-ID: YzRlZDFlYzYyM2IwOTdlMzk0MDA3MTRmZmY3OGIzODM.
CSeq: 2 INVITE
Content-Type: application/sdp
User-Agent: Z 3.3.25608 r25552
Supported: replaces, norefersub, extended-refer, timer
Allow-Events: presence, kpml
Content-Length: 239
v=0
o=Z 0 0 IN IP4 10.31.32.251
s=Z
c=IN IP4 10.31.32.251
t=0 0
m=audio 8000 RTP/AVP 8 0 3 110 98 101
a=rtpmap:110 speex/8000
a=rtpmap:98 iLBC/8000
a=fmtp:98 mode=20
a=rtpmap:101 telephone-event/8000
a=fmtp:101 0-15
a=sendrecv
'
The successful response message is as below:
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 873
{
"status" : "ok",
"error" : [ {
"error_id" : "RequestIdentityHeaderRequired",
"http_status_code" : 403,
"sip_code" : 428,
"reason" : "Identity header value required",
"timestamp" : "Mon, 25 Nov 2024 20:28:41 GMT"
} ],
"next_hop" : "udp:192.168.1.1:5060",
"policy" : "{\"stateful\":false,\"via\":false,\"max_forwards\":false,\"route\":false,\"record_route\":false,\"error_action\":[{\"error\":\"default\",\"action\":\"reject\"}]}",
"header" : [ {
"operation" : "add",
"name" : "From",
"value" : "\"alice\" <sip:+15714340000;verstat=No-TN-Validation@example.com>;tag=1f4e4f40"
}, {
"operation" : "remove",
"name" : "P-Identity-Bypass",
"value" : "IDENTITY-BYPASS-SPC0001-ABC123-000"
}, {
"operation" : "remove",
"name" : "From",
"value" : "\"alice\" <sip:+15714340000@example.com>;tag=1f4e4f40"
} ]
}
The description of the fields in the response is as below:
Path | Type | Optional | Description |
---|---|---|---|
|
|
|
Verification status |
|
|
|
The URI of next hop |
|
|
|
The policy for processing the SIP message |
|
|
|
A list of errors encountered in verifying SIP Identity headers |
|
|
|
The unique error identifier |
|
|
|
The HTTP response status code |
|
|
|
The SIP response code associated with the error |
|
|
|
The detailed error text |
|
|
|
The timestamp when the error is generated |
|
|
|
A list of SIP headers or RequestLine to be added into or removed from SIP INVITE message |
|
|
|
Either 'add' or 'remove' |
|
|
|
The name of the SIP header or RequestLine to be added or removed |
|
|
|
The value of the SIP header or RequestLine to be added or removed |
Example For Tagging SIP INVITE Message with Error Caused by Robocall Call Insight
The following is an example for tagging an incoming SIP INVITE message with a valid SIP
Identity header originated from a telephone number marked with call_treatment
as send_to_vm
in Robocall Call Insight data. The response in JSON format instructs the SIP proxy that the "verstat" value
of "TN-Validation-Passed" to be appended to SIP From/P-Asserted-Identity headers, and CNAM field appended
with an "" prefix in the SIP From header. It also contains the error code of *SipCallTreatmentSentToVm
,
so that the SIP proxy can apply proper policy to handle the error condition:
$ curl 'https://ca-verify.neustarlab.biz/ccid/verify/v2/identity/proxy/192.168.1.0/5060?apiKey=%3CapiKey1%3E' -i -X POST \
-H 'Content-Type: text/plain' \
-H 'Accept: application/json' \
-d 'INVITE sip:+15714340001@proxy.example.com;transport=UDP SIP/2.0
Via: SIP/2.0/UDP proxy.example.com:39089;branch=z9hG4bK-d8754za
Max-Forwards: 70
Contact: "alice" <sip:alice@proxy.example.com:39089;transport=UDP>
From: "alice" <sip:+15714340000@example.com>;tag=1f4e4f40
To: "bob" <sip:+15714340001@example.com>
Date: Mon, 25 Nov 2024 20:28:41 GMT
Call-ID: YzRlZDFlYzYyM2IwOTdlMzk0MDA3MTRmZmY3OGIzODM.
Identity: eyJhbGciOiJFUzI1NiIsInR5cCI6InBhc3Nwb3J0IiwieDV1IjoiaHR0cDovL2NhLmV4YW1wbGUuY29tL3Rlc3QuZGVyIn0.eyJkZXN0Ijp7InRuIjpbIjE1NzE0MzQwMDAxIl19LCJpYXQiOjE3MzI1NjY1MjEsIm9yaWciOnsidG4iOiIxNTcxNDM0MDAwMCJ9fQ.-XSsV8_-PZs-TJ5XAE-5Sc2GZTsSZqHAtV-18XOBFr_JN6jpXr2fDA6UJWeVmI9_MiFkO6-ZWzemxxA2xhpaAA;info=<http://ca.example.com/test.der>;alg=ES256
CSeq: 2 INVITE
Content-Type: application/sdp
User-Agent: Z 3.3.25608 r25552
Supported: replaces, norefersub, extended-refer, timer
Allow-Events: presence, kpml
Content-Length: 239
v=0
o=Z 0 0 IN IP4 10.31.32.251
s=Z
c=IN IP4 10.31.32.251
t=0 0
m=audio 8000 RTP/AVP 8 0 3 110 98 101
a=rtpmap:110 speex/8000
a=rtpmap:98 iLBC/8000
a=fmtp:98 mode=20
a=rtpmap:101 telephone-event/8000
a=fmtp:101 0-15
a=sendrecv
'
The successful response message is as below:
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 789
{
"status" : "ok",
"error" : [ {
"error_id" : "SipCallTreatmentSendToVm",
"http_status_code" : 403,
"sip_code" : 607,
"reason" : "Call to be sent to voice mail - Fraud Score = 100",
"timestamp" : "Mon, 25 Nov 2024 20:28:41 GMT"
} ],
"next_hop" : "udp:192.168.1.1:5060",
"policy" : "{\"stateful\":false,\"via\":false,\"max_forwards\":false,\"route\":false,\"record_route\":false,\"error_action\":[{\"error\":\"438\",\"action\":\"custom\",\"sip_code\":481}]}",
"header" : [ {
"operation" : "add",
"name" : "From",
"value" : "\"*FraudCall\" <sip:+15714340000;verstat=TN-Validation-Passed@example.com>;tag=1f4e4f40"
}, {
"operation" : "remove",
"name" : "From",
"value" : "\"alice\" <sip:+15714340000@example.com>;tag=1f4e4f40"
} ]
}
The description of the fields in the response is as below:
Path | Type | Optional | Description |
---|---|---|---|
|
|
|
Verification status |
|
|
|
The URI of next hop |
|
|
|
The policy for processing the SIP message |
|
|
|
A list of SIP headers or RequestLine to be added into or removed from SIP INVITE message |
|
|
|
Either 'add' or 'remove' |
|
|
|
The name of the SIP header or RequestLine to be added or removed |
|
|
|
The value of the SIP header or RequestLine to be added or removed |
|
|
|
A list of errors encountered in verifying SIP Identity headers |
|
|
|
The unique error identifier |
|
|
|
The HTTP response status code |
|
|
|
The SIP response code associated with the error |
|
|
|
The detailed error text |
|
|
|
The timestamp when the error is generated |
Obtains SIP Proxy Next Hop And Policy Data
This API entry point returns next hop and policy data in JSON Format for SIP Proxies.
API Method |
|
|
API Path |
|
|
Request Path Variable |
Name |
Description |
|
The remote IP address from which the SIP message is originated |
|
|
The remote port from which the SIP message is originated |
|
Required Parameters |
Name |
Description |
|
The API key uniquely identifying the API client |
|
Request Path (example) |
${BASEURL}/identity/proxy/192.168.1.1/5060?apiKey=... |
|
Successful Response |
HTTP Code |
200 OK |
Content-Type |
application/json |
|
Body (example) |
{ "status" : "ok", "next_hop" : "udp:192.168.1.1:5060", "policy" : "policy...", } |
|
Error Response |
HTTP Code |
4xx, 5xx |
Content-Type |
application/json |
|
Body (example) |
{ "status" : "error", "error" : [ { "error_id" : "SipInterfaceNotAuthorized", "http_status_code" : 400, "sip_code" : 400, "reason" : "SIP interface IP address/port not authorized", "timestamp" : "Fri, 24 Aug 2018 03:26:02 GMT", "attributes" : { "address" : "192.168.9.1", "port" : "5060" } } ] } |
A successful response in JSON format includes the "status" attribute with a value of "ok". It also contains an optional "next_hop" attribute for indicating the next hop for routing the SIP messages, and an optional "policy" attribute with an opaque string to be consumed by the SIP proxy for manipulating SIP headers and mapping error conditions.
A failure response in JSON format includes the "status" attribute with a value of "error", and an "error" attribute, containing a list of error conditions that result in the failure.
Example For Obtaining Proxy Next Hop and Policy Data
The following is an example for obtaining SIP proxy next hop and policy data identified by the remote IP address and port values.
$ curl 'https://ca-verify.neustarlab.biz/ccid/verify/v2/identity/proxy/192.168.1.1/5060?apiKey=%3CapiKey1%3E' -i -X GET \
-H 'Accept: application/json'
The successful response message is as below:
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 251
{
"status" : "ok",
"next_hop" : "udp:192.168.1.1:5060",
"policy" : "{\"stateful\":false,\"via\":false,\"max_forwards\":false,\"route\":false,\"record_route\":false,\"error_action\":[{\"error\":\"438\",\"action\":\"custom\",\"sip_code\":481}]}"
}
The description of the fields in the response is as below:
Path | Type | Optional | Description |
---|---|---|---|
|
|
|
Verification status |
|
|
|
The URI of next hop |
|
|
|
The policy for processing the SIP message |
Error Response Example
The following is an example of error responses produced by the CCID VS if there are any errors encountered for obtaining SIP proxy next hop and policy data.
$ curl 'https://ca-verify.neustarlab.biz/ccid/verify/v2/identity/proxy/192.168.9.1/5060?apiKey=%3CapiKey1%3E' -i -X GET \
-H 'Accept: application/json'
The error response message is as below:
HTTP/1.1 400 Bad Request
Content-Type: application/json
Content-Length: 341
{
"status" : "error",
"error" : [ {
"error_id" : "SipInterfaceNotAuthorized",
"http_status_code" : 400,
"sip_code" : 400,
"reason" : "SIP interface IP address/port not authorized",
"timestamp" : "Mon, 25 Nov 2024 20:28:40 GMT",
"attributes" : {
"address" : "192.168.9.1",
"port" : "5060"
}
} ]
}
The description of the fields in the response is as below:
Path | Type | Optional | Description |
---|---|---|---|
|
|
|
Verification status |
|
|
|
A list of errors encountered in verifying SIP Identity headers |
|
|
|
The unique error identifier |
|
|
|
The HTTP response status code |
|
|
|
The SIP response code associated with the error |
|
|
|
The detailed error text |
|
|
|
The name/value pair .attribute map associated with the error |
|
|
|
The remote IP address of SIP message originated |
|
|
|
The remote IP port of SIP message originated |
|
|
|
The timestamp when the error is generated |
Gets CNAM
The CNAM data can be retrieved via a GET API call by specifying the telephone number as a path parameter, or via a POST API call by specifying SIP From header in a JSON message.
Gets CNAM via a GET API Call
This API entry point is to return the CNAM name of a specific telephone number, which is specified as the path variable in the request URL.
For a successful CNAM lookup, a response in JSON format will be returned with the "cnam" attribute; otherwise, the "cnam_error" attribute will be returned if there are any errors encountered in the CNAM lookup.
API Method |
|
|
API Path |
|
|
Required Parameters |
Name |
Description |
|
The API key uniquely identifying the API client |
|
Request Path Variable |
Name |
Description |
|
The numeric telephone number |
|
Request Path (example) |
${BASEURL}/cnam/tn/15715550001 |
|
Successful Response |
HTTP Code |
200 OK |
Content-Type |
application/json |
|
Body (example) |
{ "cnam" : "Alice" } |
|
Error Response |
HTTP Code |
4xx, 5xx |
Content-Type |
application/json |
|
Body (example) |
{ "cnam_error" : { "error_id" : "CnamDataNotFound", "http_status_code" : 400, "sip_code" : 400, "reason" : "CNAM data not found", "timestamp" : "Fri, 11 Aug 2017 14:50:48 GMT" } } |
CNAM Retrieval Example
The following is an example of retrieving the CNAM of a telephone number:
$ curl 'https://ca-verify.neustarlab.biz/ccid/verify/v2/cnam/tn/15715550000?apiKey=%3CapiKey1%3E' -i -X GET \
-H 'Accept: application/json'
The description of the path parameters in the request URL is as below:
Parameter | Type | Description | Constraints |
---|---|---|---|
|
|
The numeric telephone number for CNAM/ECNAM lookup |
Must be a positive integer |
The successful response message is as below:
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 36
{
"cnam" : "Alice In Wonderland"
}
The description of the fields in the response is as below:
Path | Type | Optional | Description |
---|---|---|---|
|
|
|
CNAM data |
Error Response Example
The following is an example of error responses produced by the CCID VS if there are any errors encountered in retrieving the CNAM of a telephone number:
$ curl 'https://ca-verify.neustarlab.biz/ccid/verify/v2/cnam/tn/15715550001?apiKey=%3CapiKey5%3E' -i -X GET \
-H 'Accept: application/json'
The description of the path parameters in the request URL is as below:
Parameter | Type | Description | Constraints |
---|---|---|---|
|
|
The numeric telephone number for CNAM/ECNAM lookup |
Must be a positive integer |
The error response message is as below:
HTTP/1.1 400 Bad Request
Content-Type: application/json
Content-Length: 212
{
"cnam_error" : {
"error_id" : "CnamNotAuthorized",
"http_status_code" : 400,
"sip_code" : 400,
"reason" : "CNAM service not authorized",
"timestamp" : "Mon, 25 Nov 2024 20:28:40 GMT"
}
}
The description of the fields in the response is as below:
Path | Type | Optional | Description |
---|---|---|---|
|
|
|
The error encountered in CNAM lookup |
|
|
|
The unique error identifier |
|
|
|
The HTTP response status code |
|
|
|
The SIP response code associated with the error |
|
|
|
The detailed error text |
|
|
|
The timestamp when the error is generated |
Gets CNAM via a POST API Call
This API entry point is to return the CNAM name of a specific telephone number, which is embedded in a SIP From header or in a SIP P-Asserted-Identity header, as the "from" attribute in the request JSON message.
For a successful CNAM lookup, a response in JSON format will be returned with the "cnam" attribute; otherwise, the "cnam_error" attribute will be returned if there are any errors encountered in the CNAM lookup.
API Method |
|
|
API Path |
|
|
Required Parameters |
Name |
Description |
|
The API key uniquely identifying the API client |
|
Request |
Content-Type |
application/json |
Body (example) |
{ "from" : "\"Alice\" <sip:+15715550001@example.com>", } |
|
Successful Response |
HTTP Code |
200 OK |
Content-Type |
application/json |
|
Body (example) |
{ "cnam" : "Alice" } |
|
Error Response |
HTTP Code |
4xx, 5xx |
Content-Type |
application/json |
|
Body (example) |
{ "cnam_error" : { "error_id" : "CnamDataNotFound", "http_status_code" : 400, "sip_code" : 400, "reason" : "CNAM data not found", "timestamp" : "Fri, 11 Aug 2017 14:50:48 GMT" } } |
CNAM Retrieval Example
The following is an example of retrieving the CNAM of a telephone number:
$ curl 'https://ca-verify.neustarlab.biz/ccid/verify/v2/cnam?apiKey=%3CapiKey1%3E' -i -X POST \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
"from" : "\"alice\" <sip:+15715550000@example.com>"
}'
The description of the field in the request is as below:
Path | Type | Optional | Description | Constraints |
---|---|---|---|---|
|
|
|
'From' header value from SIP INVITE message |
Required |
The successful response message is as below:
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 36
{
"cnam" : "Alice In Wonderland"
}
The description of the fields in the response is as below:
Path | Type | Optional | Description |
---|---|---|---|
|
|
|
CNAM data |
Error Response Example
The following is an example of error responses produced by the CCID VS if there are any errors encountered in retrieving the CNAM of a telephone number:
$ curl 'https://ca-verify.neustarlab.biz/ccid/verify/v2/cnam?apiKey=%3CapiKey1%3E' -i -X POST \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
"from" : "\"alice\" <sip:+15715550000@example.com>"
}'
The description of the field in the request as below:
Path | Type | Optional | Description | Constraints |
---|---|---|---|---|
|
|
|
'From' header value from SIP INVITE message |
Required |
The error response message is as below:
HTTP/1.1 400 Bad Request
Content-Type: application/json
Content-Length: 203
{
"cnam_error" : {
"error_id" : "CnamDataNotFound",
"http_status_code" : 400,
"sip_code" : 400,
"reason" : "CNAM data not found",
"timestamp" : "Mon, 25 Nov 2024 20:28:40 GMT"
}
}
The description of the fields in the response is as below:
Path | Type | Optional | Description |
---|---|---|---|
|
|
|
The error encountered in CNAM lookup |
|
|
|
The unique error identifier |
|
|
|
The HTTP response status code |
|
|
|
The SIP response code associated with the error |
|
|
|
The detailed error text |
|
|
|
The timestamp when the error is generated |
Gets ECNAM
The ECNAM data can be retrieved via a GET API call by specifying the telephone number as a path parameter, or via a POST API call by specifying SIP From header in a JSON message.
Gets ECNAM via a GET API Call
This API entry point is to return the ECNAM name of a specific telephone number, which is specified as the path variable in the request URL.
For a successful ECNAM lookup, a response in JSON format will be returned with the "ecnam" attribute, along with an optional "call_insight" attribute, if any; otherwise, the "ecnam_error" attribute will be returned if there are any errors encountered in the ECNAM lookup.
API Method |
|
|
API Path |
|
|
Required Parameters |
Name |
Description |
|
The API key uniquely identifying the API client |
|
Request Path Variable |
Name |
Description |
|
The numeric telephone number |
|
Request Path (example) |
${BASEURL}/ecnam/tn/15715550001 |
|
Successful Response |
HTTP Code |
200 OK |
Content-Type |
application/json |
|
Body (example) |
{ "ecnam" : { "business_name" : "Neustar, Inc.", ... } } |
|
Error Response |
HTTP Code |
4xx, 5xx |
Content-Type |
application/json |
|
Body (example) |
{ "ecnam_error" : { "error_id" : "EcnamDataNotFound", "http_status_code" : 400, "sip_code" : 400, "reason" : "ECNAM data not found", "timestamp" : "Fri, 11 Aug 2017 14:50:48 GMT" } } |
ECNAM Retrieval Example
The following is an example of retrieving the ECNAM of a telephone number:
$ curl 'https://ca-verify.neustarlab.biz/ccid/verify/v2/ecnam/tn/15715550000?apiKey=%3CapiKey1%3E' -i -X GET \
-H 'Accept: application/json'
The description of the path parameters in the request URL is as below:
Parameter | Type | Description | Constraints |
---|---|---|---|
|
|
The numeric telephone number for CNAM/ECNAM lookup |
Must be a positive integer |
The successful response message is as below:
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 2135
{
"ecnam" : {
"cnam" : "Alice In Wonderland",
"display_template" : "none",
"business_name" : "Disney World",
"department" : "Theme Park",
"line_type" : "Wireline",
"subscriber_type" : "Business",
"business_type" : "Entertainment",
"business_address" : "Walt Disney World Resort",
"locality" : "Orlando, FL",
"city" : "Orlando",
"state" : "FL",
"country" : "US",
"postal_code" : "32830",
"website_url" : "http://movies.disney.com/alice-in-wonderland-1951",
"logo_url" : "https://static-mh.content.disney.io/matterhorn/assets/goc/nav-logo-dark@2x-2b3eb08c507c.png",
"tagline" : "#AliceInWonderLand",
"employee_name" : "Alice",
"first_name" : "Alice",
"last_name" : "Liddell",
"job_title" : "Adventurer",
"headshot_url" : "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcR2Q1GWX6hdmMr2dh10SoTeEKEn4S4toc4V3yAJCrPQHlzWvr_I",
"email" : "alice@disney.com",
"call_purpose" : "Customer Support",
"social_media_info" : {
"Facebook" : "https://www.facebook.com/DisneyAliceInWonderland",
"Twitter" : "https://twitter.com/Disney"
},
"p_asserted_identity" : "\"Alice In Wonderland\" <sip:alice@example.com;tmpl=none;bn=Disney%20World;dept=Theme%20Park;lt=Wireline;st=Business;bt=Entertainment;ba=Walt%20Disney%20World%20Resort;cs=Orlando, FL;city=Orlando;state=FL;ct=US;zip=32830;wb=http://movies.disney.com/alice-in-wonderland-1951;lg=https://static-mh.content.disney.io/matterhorn/assets/goc/nav-logo-dark@2x-2b3eb08c507c.png;tg=#AliceInWonderLand;sm=%7B%22Facebook%22%3A%22https%3A%2F%2Fwww.facebook.com%2FDisneyAliceInWonderland%22%2C%22Twitter%22%3A%22https%3A%2F%2Ftwitter.com%2FDisney%22%7D;nm=Alice;fn=Alice;ln=Liddell;jt=Adventurer;hs=https://encrypted-tbn0.gstatic.com/images?q%3dtbn:ANd9GcR2Q1GWX6hdmMr2dh10SoTeEKEn4S4toc4V3yAJCrPQHlzWvr_I;cp=Customer Support;email=alice@disney.com>"
},
"call_insight" : {
"call_treatment" : "allow",
"fraud_score" : 0,
"category_id" : 0,
"data_model" : "titan",
"category" : "N/A",
"overlay_name" : "[V] ",
"original_calling_name" : "Alice"
}
}
The description of the fields in the response is as below:
Path | Type | Optional | Description |
---|---|---|---|
|
|
|
ECNAM data |
|
|
|
Call Insight object containing Robocall mitigation data |
Error Response Example
The following is an example of error responses produced by the CCID VS if there are any errors encountered in retrieving the ECNAM of a telephone number:
$ curl 'https://ca-verify.neustarlab.biz/ccid/verify/v2/ecnam/tn/15715550001?apiKey=%3CapiKey5%3E' -i -X GET \
-H 'Accept: application/json'
The description of the path parameters in the request URL is as below:
Parameter | Type | Description | Constraints |
---|---|---|---|
|
|
The numeric telephone number for CNAM/ECNAM lookup |
Must be a positive integer |
The error response message is as below:
HTTP/1.1 400 Bad Request
Content-Type: application/json
Content-Length: 215
{
"ecnam_error" : {
"error_id" : "EcnamNotAuthorized",
"http_status_code" : 400,
"sip_code" : 400,
"reason" : "ECNAM service not authorized",
"timestamp" : "Mon, 25 Nov 2024 20:28:40 GMT"
}
}
The description of the fields in the response is as below:
Path | Type | Optional | Description |
---|---|---|---|
|
|
|
The error encountered in ECNAM lookup |
|
|
|
The unique error identifier |
|
|
|
The HTTP response status code |
|
|
|
The SIP response code associated with the error |
|
|
|
The detailed error text |
|
|
|
The timestamp when the error is generated |
Gets ECNAM via a POST API Call
This API entry point is to return the ECNAM name of a specific telephone number, which is embedded in a SIP From header or in a SIP P-Asserted-Identity header, as the "from" attribute in the request JSON message.
For a successful ECNAM lookup, a response in JSON format will be returned with the "ecnam" attribute, along with an optional "call_insight" attribute, if any; otherwise, the "ecnam_error" attribute will be returned if there are any errors encountered in the ECNAM lookup.
API Method |
|
|
API Path |
|
|
Required Parameters |
Name |
Description |
|
The API key uniquely identifying the API client |
|
Request |
Content-Type |
application/json |
Body (example) |
{ "from" : "\"Alice\" <sip:+15715550001@example.com>", } |
|
Successful Response |
HTTP Code |
200 OK |
Content-Type |
application/json |
|
Body (example) |
{ "ecnam" : { "business_name" : "Neustar, Inc.", ... } } |
|
Error Response |
HTTP Code |
4xx, 5xx |
Content-Type |
application/json |
|
Body (example) |
{ "ecnam_error" : { "error_id" : "EcnamDataNotFound", "http_status_code" : 400, "sip_code" : 400, "reason" : "ECNAM data not found", "timestamp" : "Fri, 11 Aug 2017 14:50:48 GMT" } } |
ECNAM Retrieval Example
The following is an example of retrieving the ECNAM of a telephone number:
$ curl 'https://ca-verify.neustarlab.biz/ccid/verify/v2/ecnam?apiKey=%3CapiKey1%3E' -i -X POST \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
"from" : "\"alice\" <sip:+15715550000@example.com>"
}'
The description of the field in the request is as below:
Path | Type | Optional | Description | Constraints |
---|---|---|---|---|
|
|
|
'From' header value from SIP INVITE message |
Required |
The successful response message is as below:
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 2135
{
"ecnam" : {
"cnam" : "Alice In Wonderland",
"display_template" : "none",
"business_name" : "Disney World",
"department" : "Theme Park",
"line_type" : "Wireline",
"subscriber_type" : "Business",
"business_type" : "Entertainment",
"business_address" : "Walt Disney World Resort",
"locality" : "Orlando, FL",
"city" : "Orlando",
"state" : "FL",
"country" : "US",
"postal_code" : "32830",
"website_url" : "http://movies.disney.com/alice-in-wonderland-1951",
"logo_url" : "https://static-mh.content.disney.io/matterhorn/assets/goc/nav-logo-dark@2x-2b3eb08c507c.png",
"tagline" : "#AliceInWonderLand",
"employee_name" : "Alice",
"first_name" : "Alice",
"last_name" : "Liddell",
"job_title" : "Adventurer",
"headshot_url" : "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcR2Q1GWX6hdmMr2dh10SoTeEKEn4S4toc4V3yAJCrPQHlzWvr_I",
"email" : "alice@disney.com",
"call_purpose" : "Customer Support",
"social_media_info" : {
"Facebook" : "https://www.facebook.com/DisneyAliceInWonderland",
"Twitter" : "https://twitter.com/Disney"
},
"p_asserted_identity" : "\"Alice In Wonderland\" <sip:alice@example.com;tmpl=none;bn=Disney%20World;dept=Theme%20Park;lt=Wireline;st=Business;bt=Entertainment;ba=Walt%20Disney%20World%20Resort;cs=Orlando, FL;city=Orlando;state=FL;ct=US;zip=32830;wb=http://movies.disney.com/alice-in-wonderland-1951;lg=https://static-mh.content.disney.io/matterhorn/assets/goc/nav-logo-dark@2x-2b3eb08c507c.png;tg=#AliceInWonderLand;sm=%7B%22Facebook%22%3A%22https%3A%2F%2Fwww.facebook.com%2FDisneyAliceInWonderland%22%2C%22Twitter%22%3A%22https%3A%2F%2Ftwitter.com%2FDisney%22%7D;nm=Alice;fn=Alice;ln=Liddell;jt=Adventurer;hs=https://encrypted-tbn0.gstatic.com/images?q%3dtbn:ANd9GcR2Q1GWX6hdmMr2dh10SoTeEKEn4S4toc4V3yAJCrPQHlzWvr_I;cp=Customer Support;email=alice@disney.com>"
},
"call_insight" : {
"call_treatment" : "allow",
"fraud_score" : 0,
"category_id" : 0,
"data_model" : "titan",
"category" : "N/A",
"overlay_name" : "[V] ",
"original_calling_name" : "Alice"
}
}
The description of the fields in the response is as below:
Path | Type | Optional | Description |
---|---|---|---|
|
|
|
ECNAM data |
|
|
|
Call Insight object containing Robocall mitigation data |
Error Response Example
The following is an example of error responses produced by the CCID VS if there are any errors encountered in retrieving the ECNAM of a telephone number:
$ curl 'https://ca-verify.neustarlab.biz/ccid/verify/v2/ecnam?apiKey=%3CapiKey1%3E' -i -X POST \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
"from" : "\"alice\" <sip:+15715550000@example.com>"
}'
The description of the field in the request as below:
Path | Type | Optional | Description | Constraints |
---|---|---|---|---|
|
|
|
'From' header value from SIP INVITE message |
Required |
The error response message is as below:
HTTP/1.1 400 Bad Request
Content-Type: application/json
Content-Length: 206
{
"ecnam_error" : {
"error_id" : "EcnamDataNotFound",
"http_status_code" : 400,
"sip_code" : 400,
"reason" : "ECNAM data not found",
"timestamp" : "Mon, 25 Nov 2024 20:28:40 GMT"
}
}
The description of the fields in the response is as below:
Path | Type | Optional | Description |
---|---|---|---|
|
|
|
The error encountered in ECNAM lookup |
|
|
|
The unique error identifier |
|
|
|
The HTTP response status code |
|
|
|
The SIP response code associated with the error |
|
|
|
The detailed error text |
|
|
|
The timestamp when the error is generated |
Lists All Potential Errors
This API entry point is to return the list of all potential errors that could be generated, so that an API consumer can process those errors accordingly.
API Method |
|
|
API Path |
|
|
Successful Response |
HTTP Code |
200 OK |
Content-Type |
application/json |
|
Body (example) |
[ { "error_id" : "Ok", "http_status_code" : 200, "sip_code" : 200, "reason" : "OK" }, {. ... }, { "error_id" : "InternalServerError", "http_status_code" : 500, "sip_code" : 500, "reason" : "Internal server error" } ] |
Error List Example
The following is an example of listing all potential errors generated by the CCID VS:
$ curl 'https://ca-verify.neustarlab.biz/ccid/verify/v2/error' -i -X GET \
-H 'Accept: application/json'
The description of the fields in the response is as below:
Path | Type | Optional | Description |
---|---|---|---|
|
|
|
The unique error identifier |
|
|
|
The HTTP response status code |
|
|
|
The SIP response code associated with the error |
|
|
|
The detailed error text |
The successful response message is as below:
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 26530
[ {
"error_id" : "Ok",
"http_status_code" : 200,
"sip_code" : 200,
"reason" : "OK"
}, {
"error_id" : "ApiKeyRequired",
"http_status_code" : 400,
"sip_code" : 400,
"reason" : "API key is required"
}, {
"error_id" : "ApiKeyInvalid",
"http_status_code" : 400,
"sip_code" : 400,
"reason" : "API key is invalid"
}, {
"error_id" : "CnamNotAuthorized",
"http_status_code" : 400,
"sip_code" : 400,
"reason" : "CNAM service not authorized"
}, {
"error_id" : "CnamDataNotFound",
"http_status_code" : 400,
"sip_code" : 400,
"reason" : "CNAM data not found"
}, {
"error_id" : "EcnamNotAuthorized",
"http_status_code" : 400,
"sip_code" : 400,
"reason" : "ECNAM service not authorized"
}, {
"error_id" : "EcnamDataNotFound",
"http_status_code" : 400,
"sip_code" : 400,
"reason" : "ECNAM data not found"
}, {
"error_id" : "TelephoneNumberInvalid",
"http_status_code" : 400,
"sip_code" : 400,
"reason" : "Telephone number for CNAM/ECNAM query is not valid"
}, {
"error_id" : "TelephoneNumberNotFound",
"http_status_code" : 400,
"sip_code" : 400,
"reason" : "Telephone number for CNAM/ECNAM query is not found"
}, {
"error_id" : "StatusParameterValueInvalid",
"http_status_code" : 400,
"sip_code" : 400,
"reason" : "'status' parameter value is not valid"
}, {
"error_id" : "StatusValueInvalidForInput",
"http_status_code" : 400,
"sip_code" : 400,
"reason" : "'status' value is not valid for input"
}, {
"error_id" : "DateParseException",
"http_status_code" : 400,
"sip_code" : 400,
"reason" : "Date is expected to be in RFC 1123 format"
}, {
"error_id" : "MediaTypeException",
"http_status_code" : 400,
"sip_code" : 400,
"reason" : "Content-Type is invalid or not supported"
}, {
"error_id" : "MessageParseException",
"http_status_code" : 400,
"sip_code" : 400,
"reason" : "Error in parsing the request"
}, {
"error_id" : "MethodNotSupportedException",
"http_status_code" : 400,
"sip_code" : 400,
"reason" : "Request method is not supported"
}, {
"error_id" : "VerstatValueInvalid",
"http_status_code" : 400,
"sip_code" : 400,
"reason" : "Verstat value is invalid"
}, {
"error_id" : "VerstatValueRequired",
"http_status_code" : 400,
"sip_code" : 400,
"reason" : "Verstat value is required"
}, {
"error_id" : "InvalidParameterException",
"http_status_code" : 400,
"sip_code" : 400,
"reason" : "Parameter is missing or invalid"
}, {
"error_id" : "RequestIdentityHeaderDivRequired",
"http_status_code" : 403,
"sip_code" : 428,
"reason" : "Identity header with 'ppt' as 'div' required"
}, {
"error_id" : "CertificateValidatorFailure",
"http_status_code" : 500,
"sip_code" : 500,
"reason" : "Certificate validator failed to be created"
}, {
"error_id" : "SipInterfaceCidrInvalid",
"http_status_code" : 500,
"sip_code" : 500,
"reason" : "SIP interface cidr is invalid"
}, {
"error_id" : "SipInterfaceIpAddressInvalid",
"http_status_code" : 400,
"sip_code" : 400,
"reason" : "SIP interface IP address is invalid"
}, {
"error_id" : "SipInterfacePortInvalid",
"http_status_code" : 400,
"sip_code" : 400,
"reason" : "SIP interface port is invalid"
}, {
"error_id" : "SipInterfaceNotAuthorized",
"http_status_code" : 400,
"sip_code" : 400,
"reason" : "SIP interface IP address/port not authorized"
}, {
"error_id" : "SipCallTreatmentDeny",
"http_status_code" : 403,
"sip_code" : 603,
"reason" : "Call to be blocked"
}, {
"error_id" : "SipCallTreatmentSendToVm",
"http_status_code" : 403,
"sip_code" : 607,
"reason" : "Call to be sent to voice mail"
}, {
"error_id" : "AtisVerificationRequestMissing",
"http_status_code" : 400,
"sip_code" : 400,
"reason" : "Missing mandatory parameters in the verification request"
}, {
"error_id" : "AtisVerificationRequestInvalid",
"http_status_code" : 400,
"sip_code" : 400,
"reason" : "Received invalid parameters"
}, {
"error_id" : "ServiceNotAvailableForSipOptions",
"http_status_code" : 503,
"sip_code" : 503,
"reason" : "Service not available when processing a SIP OPTIONS message"
}, {
"error_id" : "ServiceNotAvailableForSipInvite",
"http_status_code" : 503,
"sip_code" : 503,
"reason" : "Service not available when processing a SIP INVITE message"
}, {
"error_id" : "ServiceErrorInResigningIdentity",
"http_status_code" : 503,
"sip_code" : 503,
"reason" : "Service or request error in re-signing identity header"
}, {
"error_id" : "UriUserPartRequired",
"http_status_code" : 400,
"sip_code" : 416,
"reason" : "URI user-part is required"
}, {
"error_id" : "UriParseError",
"http_status_code" : 400,
"sip_code" : 416,
"reason" : "URI parsing failed"
}, {
"error_id" : "UriSchemeInvalid",
"http_status_code" : 400,
"sip_code" : 416,
"reason" : "URI scheme is invalid"
}, {
"error_id" : "UriEncodingInvalid",
"http_status_code" : 400,
"sip_code" : 416,
"reason" : "URI encoding is invalid"
}, {
"error_id" : "CallInfoHeaderInvalid",
"http_status_code" : 400,
"sip_code" : 403,
"reason" : "Call-Info header is invalid"
}, {
"error_id" : "ContentTypeHeaderInvalid",
"http_status_code" : 400,
"sip_code" : 403,
"reason" : "Content-Type header is invalid"
}, {
"error_id" : "ContentNotFound",
"http_status_code" : 400,
"sip_code" : 403,
"reason" : "Content not found in SIP INVITE message"
}, {
"error_id" : "SipInviteMessageInvalid",
"http_status_code" : 400,
"sip_code" : 403,
"reason" : "SIP INVITE message is invalid"
}, {
"error_id" : "SipInviteDateInvalid",
"http_status_code" : 400,
"sip_code" : 403,
"reason" : "SIP INVITE Date header is invalid"
}, {
"error_id" : "CredentialNotFound",
"http_status_code" : 403,
"sip_code" : 437,
"reason" : "Credential not found"
}, {
"error_id" : "CredentialNotYetValid",
"http_status_code" : 403,
"sip_code" : 437,
"reason" : "Credential not yet valid"
}, {
"error_id" : "CredentialExpired",
"http_status_code" : 403,
"sip_code" : 437,
"reason" : "Credential has expired"
}, {
"error_id" : "CredentialNotSupported",
"http_status_code" : 403,
"sip_code" : 437,
"reason" : "Credential type is not supported"
}, {
"error_id" : "CredentialPrivateKeyNotFound",
"http_status_code" : 403,
"sip_code" : 437,
"reason" : "Private key not found"
}, {
"error_id" : "CredentialPrivateKeyNotValid",
"http_status_code" : 403,
"sip_code" : 437,
"reason" : "Private key not valid"
}, {
"error_id" : "CredentialPrivateKeyNotSupported",
"http_status_code" : 403,
"sip_code" : 437,
"reason" : "Private key not supported"
}, {
"error_id" : "CredentialCertificateNotFound",
"http_status_code" : 403,
"sip_code" : 437,
"reason" : "Certificate not found"
}, {
"error_id" : "CredentialKeyStoreError",
"http_status_code" : 403,
"sip_code" : 437,
"reason" : "Error in accessing keystore"
}, {
"error_id" : "CredentialCertificateUrlRequired",
"http_status_code" : 403,
"sip_code" : 437,
"reason" : "Certificate URL not found"
}, {
"error_id" : "CertificateFetchError",
"http_status_code" : 400,
"sip_code" : 436,
"reason" : "Error in fetching the certificate"
}, {
"error_id" : "CertificateConversionError",
"http_status_code" : 400,
"sip_code" : 436,
"reason" : "Error in converting the data to a certificate"
}, {
"error_id" : "CertificateValidationError",
"http_status_code" : 400,
"sip_code" : 437,
"reason" : "Certificate validation failed"
}, {
"error_id" : "CertificateNotFound",
"http_status_code" : 403,
"sip_code" : 438,
"reason" : "Certificate not found"
}, {
"error_id" : "CertificateNotYetValid",
"http_status_code" : 403,
"sip_code" : 438,
"reason" : "Certificate not yet valid"
}, {
"error_id" : "CertificateExpired",
"http_status_code" : 403,
"sip_code" : 437,
"reason" : "Certificate has expired"
}, {
"error_id" : "CertificateNotSupported",
"http_status_code" : 403,
"sip_code" : 437,
"reason" : "Certificate type is not supported"
}, {
"error_id" : "CertificateNotValidForOrig",
"http_status_code" : 403,
"sip_code" : 437,
"reason" : "Certificate is not valid for the originator"
}, {
"error_id" : "CertificateNotValidForDiv",
"http_status_code" : 403,
"sip_code" : 437,
"reason" : "Certificate is not valid for the diverted call"
}, {
"error_id" : "CertificateTnAuthnListFetchError",
"http_status_code" : 400,
"sip_code" : 436,
"reason" : "Error in fetching the TNAuthorizationList data"
}, {
"error_id" : "TrustStoreFetchError",
"http_status_code" : 403,
"sip_code" : 403,
"reason" : "Error in fetching the trust store"
}, {
"error_id" : "CrlFetchError",
"http_status_code" : 403,
"sip_code" : 403,
"reason" : "Error in fetching the CRL"
}, {
"error_id" : "RequestObjectInvalid",
"http_status_code" : 403,
"sip_code" : 403,
"reason" : "Invalid request object supplied"
}, {
"error_id" : "RequestOrigCountryCodeInvalid",
"http_status_code" : 403,
"sip_code" : 403,
"reason" : "Originator country code(s) invalid"
}, {
"error_id" : "RequestDestCountryCodeInvalid",
"http_status_code" : 403,
"sip_code" : 403,
"reason" : "Destination country code invalid"
}, {
"error_id" : "RequestFromHeaderRequired",
"http_status_code" : 403,
"sip_code" : 403,
"reason" : "From header value required"
}, {
"error_id" : "RequestToHeaderRequired",
"http_status_code" : 403,
"sip_code" : 403,
"reason" : "To header value required"
}, {
"error_id" : "RequestIdentityHeaderRequired",
"http_status_code" : 403,
"sip_code" : 428,
"reason" : "Identity header value required"
}, {
"error_id" : "RequestIdentityHeaderInvalid",
"http_status_code" : 403,
"sip_code" : 403,
"reason" : "Identity header value invalid"
}, {
"error_id" : "RequestStaleDate",
"http_status_code" : 403,
"sip_code" : 403,
"reason" : "Stale date value"
}, {
"error_id" : "RequestInvalidDate",
"http_status_code" : 403,
"sip_code" : 403,
"reason" : "Invalid Date value; It is too far apart from the current time"
}, {
"error_id" : "RequestFingerPrintAlgoInvalid",
"http_status_code" : 403,
"sip_code" : 403,
"reason" : "Invalid SDP fingerprint algorithm"
}, {
"error_id" : "RequestFingerPrintDigestInvalid",
"http_status_code" : 403,
"sip_code" : 403,
"reason" : "Invalid DSP fingerprint digest"
}, {
"error_id" : "RequestOrigTnRequired",
"http_status_code" : 403,
"sip_code" : 403,
"reason" : "Originator must be a telephone number"
}, {
"error_id" : "RequestDestTnRequired",
"http_status_code" : 403,
"sip_code" : 403,
"reason" : "Destination must contain a telephone number"
}, {
"error_id" : "RequestDivTnRequired",
"http_status_code" : 403,
"sip_code" : 403,
"reason" : "Diversion header must contain a telephone number"
}, {
"error_id" : "RequestShakenAttestRequired",
"http_status_code" : 403,
"sip_code" : 403,
"reason" : "SHAKEN attest value required"
}, {
"error_id" : "RequestShakenAttestInvalid",
"http_status_code" : 403,
"sip_code" : 403,
"reason" : "SHAKEN attest value invalid"
}, {
"error_id" : "RequestShakenOrigidRequired",
"http_status_code" : 403,
"sip_code" : 403,
"reason" : "SHAKEN origid value required"
}, {
"error_id" : "RequestDiversionHeaderRequired",
"http_status_code" : 403,
"sip_code" : 428,
"reason" : "Diversion header value required"
}, {
"error_id" : "RequestDiversionHeaderInvalid",
"http_status_code" : 403,
"sip_code" : 403,
"reason" : "Diversion header value invalid"
}, {
"error_id" : "RequestResourcePriorityRequired",
"http_status_code" : 403,
"sip_code" : 428,
"reason" : "Resource Priority header value required"
}, {
"error_id" : "RequestResourcePriorityInvalid",
"http_status_code" : 403,
"sip_code" : 403,
"reason" : "Resource Priority header value invalid"
}, {
"error_id" : "RequestPriorityInvalid",
"http_status_code" : 403,
"sip_code" : 403,
"reason" : "Priority header value invalid"
}, {
"error_id" : "RequestRcdJcardInfoInvalid",
"http_status_code" : 403,
"sip_code" : 403,
"reason" : "RCD JCard information invalid"
}, {
"error_id" : "RequestRcdJcardDataRequired",
"http_status_code" : 403,
"sip_code" : 403,
"reason" : "RCD JCard data required"
}, {
"error_id" : "RequestRcdJcardDataInvalid",
"http_status_code" : 403,
"sip_code" : 403,
"reason" : "RCD JCard data invalid"
}, {
"error_id" : "RequestRcdJcardDataUriInvalid",
"http_status_code" : 403,
"sip_code" : 403,
"reason" : "RCD JCard data URI invalid"
}, {
"error_id" : "RequestRcdJcardPropertyUriInvalid",
"http_status_code" : 403,
"sip_code" : 403,
"reason" : "RCD JCard property URI invalid"
}, {
"error_id" : "RequestRcdJcardDataFetchError",
"http_status_code" : 403,
"sip_code" : 403,
"reason" : "RCD JCard data failed to be fetched"
}, {
"error_id" : "RequestRcdApnInvalid",
"http_status_code" : 403,
"sip_code" : 403,
"reason" : "RCD alternate presentation number invalid"
}, {
"error_id" : "RequestRcdDataUriInvalid",
"http_status_code" : 403,
"sip_code" : 403,
"reason" : "RCD data URI invalid"
}, {
"error_id" : "RequestRcdDataFetchError",
"http_status_code" : 403,
"sip_code" : 403,
"reason" : "RCD data failed to be fetched"
}, {
"error_id" : "RequestRcdSignatureAlgoInvalid",
"http_status_code" : 403,
"sip_code" : 403,
"reason" : "RCD integrity signature algorithm invalid"
}, {
"error_id" : "RequestRcdSignatureInvalid",
"http_status_code" : 403,
"sip_code" : 403,
"reason" : "RCD integrity signature invalid"
}, {
"error_id" : "IdentitySignatureAlgoRequired",
"http_status_code" : 400,
"sip_code" : 438,
"reason" : "Identity signature algorithm not specified"
}, {
"error_id" : "IdentitySignatureAlgoMismatch",
"http_status_code" : 400,
"sip_code" : 437,
"reason" : "Identity signature algorithm not matching signing private key type"
}, {
"error_id" : "IdentitySignatureSigningError",
"http_status_code" : 400,
"sip_code" : 438,
"reason" : "Identity signature signing process failed"
}, {
"error_id" : "IdentitySignatureEcdsaDerInvalid",
"http_status_code" : 400,
"sip_code" : 438,
"reason" : "Identity ECDSA signature failed to be converted from DER into JWS format"
}, {
"error_id" : "IdentitySignatureEcdsaJwsInvalid",
"http_status_code" : 400,
"sip_code" : 438,
"reason" : "Identity ECDSA signature failed to be converted from JWS into DER format"
}, {
"error_id" : "IdentitySignatureVerifyError",
"http_status_code" : 400,
"sip_code" : 438,
"reason" : "Identity signature verification process failed"
}, {
"error_id" : "IdentitySignatureVerifyFailed",
"http_status_code" : 400,
"sip_code" : 438,
"reason" : "Identity signature failed to be verified"
}, {
"error_id" : "IdentityCompactPptUnsupported",
"http_status_code" : 400,
"sip_code" : 438,
"reason" : "SIP Identity header in compact form with 'ppt' parameter is not supported"
}, {
"error_id" : "IdentityParameterAlgUnsupported",
"http_status_code" : 400,
"sip_code" : 436,
"reason" : "'alg' parameter value specified is not supported"
}, {
"error_id" : "IdentityParameterPptRequired",
"http_status_code" : 400,
"sip_code" : 438,
"reason" : "'ppt' parameter value is required"
}, {
"error_id" : "IdentityParameterPptUnsupported",
"http_status_code" : 400,
"sip_code" : 436,
"reason" : "'ppt' parameter value specified is not supported"
}, {
"error_id" : "IdentityParameterInfoRequired",
"http_status_code" : 400,
"sip_code" : 438,
"reason" : "'info' parameter value is required"
}, {
"error_id" : "IdentityParameterInfoInvalid",
"http_status_code" : 400,
"sip_code" : 438,
"reason" : "'info' parameter value is not a valid URL"
}, {
"error_id" : "IdentityParameterInfoUnsupported",
"http_status_code" : 400,
"sip_code" : 438,
"reason" : "'info' parameter value is not a URL of supported protocol"
}, {
"error_id" : "IdentityHeaderParseError",
"http_status_code" : 400,
"sip_code" : 438,
"reason" : "Error in parsing PASSporT header"
}, {
"error_id" : "IdentityHeaderEncodingInvalid",
"http_status_code" : 400,
"sip_code" : 438,
"reason" : "PASSporT header Base64 encoding is not valid"
}, {
"error_id" : "IdentityHeaderPayloadInvalid",
"http_status_code" : 400,
"sip_code" : 438,
"reason" : "PASSporT header payload is not valid"
}, {
"error_id" : "IdentityHeaderPayloadMismatch",
"http_status_code" : 400,
"sip_code" : 438,
"reason" : "PASSporT header payload does not match the re-constructed one"
}, {
"error_id" : "IdentityHeaderAlgRequired",
"http_status_code" : 400,
"sip_code" : 438,
"reason" : "'alg' value is required in PASSporT header"
}, {
"error_id" : "IdentityHeaderAlgUnsupported",
"http_status_code" : 400,
"sip_code" : 436,
"reason" : "'alg' value specified in PASSporT header is not supported"
}, {
"error_id" : "IdentityHeaderAlgMismatch",
"http_status_code" : 400,
"sip_code" : 438,
"reason" : "'alg' value specified in PASSporT header does not match the 'alg' parameter"
}, {
"error_id" : "IdentityHeaderPptRequired",
"http_status_code" : 400,
"sip_code" : 438,
"reason" : "'ppt' value is required in PASSporT header"
}, {
"error_id" : "IdentityHeaderPptUnsupported",
"http_status_code" : 400,
"sip_code" : 438,
"reason" : "'ppt' value specified in PASSporT header is not supported"
}, {
"error_id" : "IdentityHeaderPptMismatch",
"http_status_code" : 400,
"sip_code" : 438,
"reason" : "'ppt' value specified in PASSporT header does not match the 'ppt' parameter"
}, {
"error_id" : "IdentityHeaderTypRequired",
"http_status_code" : 400,
"sip_code" : 438,
"reason" : "'typ' value is required in PASSporT header"
}, {
"error_id" : "IdentityHeaderTypUnsupported",
"http_status_code" : 400,
"sip_code" : 438,
"reason" : "'typ' value specified in PASSporT header is not supported"
}, {
"error_id" : "IdentityHeaderX5uRequired",
"http_status_code" : 400,
"sip_code" : 438,
"reason" : "'x5u' value is required in PASSporT header"
}, {
"error_id" : "IdentityHeaderX5uMismatch",
"http_status_code" : 400,
"sip_code" : 438,
"reason" : "'x5u' value specified in PASSporT header does not match the 'info' parameter"
}, {
"error_id" : "IdentityClaimParseError",
"http_status_code" : 400,
"sip_code" : 438,
"reason" : "Error in parsing PASSporT claim"
}, {
"error_id" : "IdentityClaimEncodingInvalid",
"http_status_code" : 400,
"sip_code" : 438,
"reason" : "PASSporT claim Base64 encoding is not valid"
}, {
"error_id" : "IdentityClaimPayloadInvalid",
"http_status_code" : 400,
"sip_code" : 438,
"reason" : "PASSporT claim payload is not valid"
}, {
"error_id" : "IdentityClaimPayloadMismatch",
"http_status_code" : 400,
"sip_code" : 438,
"reason" : "PASSporT claim payload does not match the re-constructed one"
}, {
"error_id" : "IdentityClaimOrigRequired",
"http_status_code" : 400,
"sip_code" : 438,
"reason" : "'orig' value is required in PASSporT claim"
}, {
"error_id" : "IdentityClaimOrigInvalid",
"http_status_code" : 400,
"sip_code" : 438,
"reason" : "'orig' value specified in PASSporT claim is not valid"
}, {
"error_id" : "IdentityClaimOrigMismatch",
"http_status_code" : 400,
"sip_code" : 438,
"reason" : "'orig' value specified in PASSporT claim does not match SIP From/P-Asserted-Identity header values"
}, {
"error_id" : "IdentityClaimDestRequired",
"http_status_code" : 400,
"sip_code" : 438,
"reason" : "'dest' value is required in PASSporT claim"
}, {
"error_id" : "IdentityClaimDestInvalid",
"http_status_code" : 400,
"sip_code" : 438,
"reason" : "'dest' value specified in PASSporT claim is not valid"
}, {
"error_id" : "IdentityClaimDestMismatch",
"http_status_code" : 400,
"sip_code" : 438,
"reason" : "'dest' value specified in PASSporT claim does not match SIP To header value"
}, {
"error_id" : "IdentityClaimIatRequired",
"http_status_code" : 400,
"sip_code" : 438,
"reason" : "'iat' value is required in PASSporT claim"
}, {
"error_id" : "IdentityClaimMkyInvalid",
"http_status_code" : 400,
"sip_code" : 438,
"reason" : "'mky' value specified in PASSporT claim is not valid"
}, {
"error_id" : "IdentityClaimMkyMismatch",
"http_status_code" : 400,
"sip_code" : 438,
"reason" : "'mky' value specified in PASSporT claim does not match SDP a:fingerprint values"
}, {
"error_id" : "IdentityClaimRequiredMissing",
"http_status_code" : 400,
"sip_code" : 438,
"reason" : "Required PASSporT claim field is missing"
}, {
"error_id" : "IdentityClaimValueInvalid",
"http_status_code" : 400,
"sip_code" : 438,
"reason" : "PASSporT claim value is invalid"
}, {
"error_id" : "IdentityClaimStaleDate",
"http_status_code" : 403,
"sip_code" : 403,
"reason" : "Stale date value in PASSporT claim"
}, {
"error_id" : "IdentityClaimInvalidDate",
"http_status_code" : 403,
"sip_code" : 403,
"reason" : "Invalid Date value in PASSporT claim; It is too far apart from the current time"
}, {
"error_id" : "IdentityClaimShakenAttestRequired",
"http_status_code" : 400,
"sip_code" : 438,
"reason" : "'attest' value is required in PASSporT claim"
}, {
"error_id" : "IdentityClaimShakenAttestInvalid",
"http_status_code" : 400,
"sip_code" : 438,
"reason" : "'attest' value is invalid in PASSporT claim"
}, {
"error_id" : "IdentityClaimShakenOrigidRequired",
"http_status_code" : 400,
"sip_code" : 438,
"reason" : "'origid' value is required in PASSporT claim"
}, {
"error_id" : "IdentityClaimDivRequired",
"http_status_code" : 400,
"sip_code" : 438,
"reason" : "'div' value is required in PASSporT claim"
}, {
"error_id" : "IdentityClaimDivInvalid",
"http_status_code" : 400,
"sip_code" : 438,
"reason" : "'div' value is invalid in PASSporT claim"
}, {
"error_id" : "IdentityClaimDivOptInvalid",
"http_status_code" : 400,
"sip_code" : 438,
"reason" : "'opt' value is invalid in PASSporT claim"
}, {
"error_id" : "IdentityClaimOrigTnRequired",
"http_status_code" : 400,
"sip_code" : 438,
"reason" : "'orig' value is required to be a telephone number in PASSporT claim"
}, {
"error_id" : "IdentityClaimDestTnRequired",
"http_status_code" : 400,
"sip_code" : 438,
"reason" : "'dest' value is required to contain a telephone number in PASSporT claim"
}, {
"error_id" : "IdentityClaimDivTnRequired",
"http_status_code" : 400,
"sip_code" : 438,
"reason" : "'div' value is required to be a telephone number in PASSporT claim"
}, {
"error_id" : "IdentityClaimRphRequired",
"http_status_code" : 400,
"sip_code" : 438,
"reason" : "'rph' value is required in PASSporT claim"
}, {
"error_id" : "IdentityClaimRphAuthRequired",
"http_status_code" : 400,
"sip_code" : 438,
"reason" : "'auth' value is required in PASSporT claim"
}, {
"error_id" : "IdentityClaimRphAuthInvalid",
"http_status_code" : 400,
"sip_code" : 438,
"reason" : "'auth' value is invalid in PASSporT claim"
}, {
"error_id" : "IdentityClaimRphAuthNotFound",
"http_status_code" : 400,
"sip_code" : 438,
"reason" : "'auth' value is not found in SIP Resource-Priority headers"
}, {
"error_id" : "IdentityClaimSphInvalid",
"http_status_code" : 400,
"sip_code" : 438,
"reason" : "'sph' value is invalid PASSporT claim"
}, {
"error_id" : "IdentityClaimRcdRequired",
"http_status_code" : 400,
"sip_code" : 438,
"reason" : "'rcd' value is required in RCD PASSport claim"
}, {
"error_id" : "IdentityClaimRcdCrnMismatch",
"http_status_code" : 400,
"sip_code" : 438,
"reason" : "'crn' value does not match the re-constructed one"
}, {
"error_id" : "IdentityClaimRcdIcnMismatch",
"http_status_code" : 400,
"sip_code" : 438,
"reason" : "'icn' value does not match the re-constructed one"
}, {
"error_id" : "IdentityClaimRcdNamRequired",
"http_status_code" : 400,
"sip_code" : 438,
"reason" : "'nam' value is required in RCD PASSport claim"
}, {
"error_id" : "IdentityClaimRcdNamMismatch",
"http_status_code" : 400,
"sip_code" : 438,
"reason" : "'nam' value does not match the re-constructed one"
}, {
"error_id" : "IdentityClaimRcdJcardInfoInvalid",
"http_status_code" : 400,
"sip_code" : 438,
"reason" : "'jcd' and 'jcl' values is mutually exclusive in RCD PASSporT claim"
}, {
"error_id" : "IdentityClaimRcdJclInvalid",
"http_status_code" : 400,
"sip_code" : 438,
"reason" : "'jcl' value is invalid in RCD PASSporT claim"
}, {
"error_id" : "IdentityClaimRcdJclMismatch",
"http_status_code" : 400,
"sip_code" : 438,
"reason" : "'jcl' value does not match the re-constructed one"
}, {
"error_id" : "IdentityClaimRcdSignAlgoInvalid",
"http_status_code" : 400,
"sip_code" : 438,
"reason" : "'rcdi' algorithm is invalid in RCD PASSporT claim"
}, {
"error_id" : "IdentityClaimRcdSignatureInvalid",
"http_status_code" : 400,
"sip_code" : 438,
"reason" : "'rcdi' value is invalid in RCD PASSporT claim"
}, {
"error_id" : "IdentityClaimRcdSignatureMismatch",
"http_status_code" : 400,
"sip_code" : 438,
"reason" : "'rcdi' value does not match the re-constructed one"
}, {
"error_id" : "IdentitySignatureEncodingInvalid",
"http_status_code" : 400,
"sip_code" : 438,
"reason" : "Identity signature Base64 encoding is not valid"
}, {
"error_id" : "IdentitySignaturePayloadInvalid",
"http_status_code" : 400,
"sip_code" : 438,
"reason" : "Identity signature payload is not valid"
}, {
"error_id" : "IdentitySignaturePayloadMismatch",
"http_status_code" : 400,
"sip_code" : 438,
"reason" : "Identity signature payload does not match the re-constructed one"
}, {
"error_id" : "IdentityClaimDivEndNotFound",
"http_status_code" : 400,
"sip_code" : 438,
"reason" : "Identity diversion claim chain does not end with SIP To Header"
}, {
"error_id" : "IdentityClaimDivInfiniteLoop",
"http_status_code" : 400,
"sip_code" : 438,
"reason" : "Identity diversion claim chain contains infinite loops"
}, {
"error_id" : "IdentityClaimDivStartInvalid",
"http_status_code" : 400,
"sip_code" : 438,
"reason" : "Identity diversion claim chain does start with a regular claim"
}, {
"error_id" : "IdentityClaimDivNotUnique",
"http_status_code" : 400,
"sip_code" : 438,
"reason" : "Identity diversion claim chain is not unique"
}, {
"error_id" : "InternalServerError",
"http_status_code" : 500,
"sip_code" : 500,
"reason" : "Internal server error"
} ]
-EOF-