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:

  1. A numeric customer id, uniquely assigned by Neustar.

  2. The name of the customer.

  3. The permission for performing CNAM or ECNAM queries

  4. The permission for performing Robocall Call Insight data queries

  5. The permission for obtaining policies from SDPR

  6. The permission for obtaining CNAM/ECNAM/Robocall data via CVT

  7. The API key supplied or generated, or client CIDR value provisioned, for for accessing the CCID VS.

  8. The default SIP Identity header verification requirement.

  9. The default list of originator country codes, for converting non-global telephone numbers into e.164 format.

  10. The default destination country code, for converting non-global telephone numbers into e.164 format.

  11. The certificate cache expiration time, or if the caching should be disabled.

  12. The time-to-live time of trust stores loaded in the memory.

  13. The options to check X.509 Certificate trust chain and revocation status at the time of certificate retrieval.

  14. 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.

  15. 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.

  16. 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.

ccid vs flow

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.

ccid as uml flow
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:

api guide post processing
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:

api guide post processing cvt

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:

api guide certificate cache

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

POST

API Path

${BASEURL}/identity

Required Parameters

Name

Description

apiKey

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

data_provider_name

String

true

ECNAM data provider name, such as neustar, titan, etc.

If specified, must be a valid token identifying the data provider name

data_source

String

true

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

String

true

BPO client name, from cno data set

If specified, must be a valid token identifying BPO client name in CNO data set

bcd_profile_name

String

true

Branded profile client name, from bcd data set

If specified, must be a valid token identifying branded profile name in BCD data set

cnam

String

true

CNAM data, from ecnam, bcd, or cno data set

If specified, must be a non-empty string as the CNAM value

p_asserted_identity

String

true

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

display_template

String

true

ECNAM data display template, from ecnam data set

If specified, must be a valid template as defined in ECNAM data specification

business_name

String

true

Full business name, from ecnam or bcd data set

If specified, must be non-empty string as a valid business name

department

String

true

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

String

true

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

String

true

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

String

true

Business type, from ecnam or bcd data set

If specified, must be a valid token identifying the business type

business_address

String

true

Business address, from ecnam or bcd data set

If specified, must be a valid address identifying the business location

locality

String

true

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

String

true

City, such as 'Sterling', from ecnam or bcd data set

If specified, must be a valid city nameidentifying the business location

state

String

true

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

String

true

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

String

true

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

String

true

Website URL, from ecnam or bcd data set

If specified, must be a URL of the business website

logo_url

String

true

Logo URL, from ecnam or bcd data set

If specified, must be a valid URL of the business logo image

tagline

String

true

Tagline, from ecnam or bcd data set

If specified, must be non-empty string of the tagline of the business

social_media_info

Object

true

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_name

String

true

Employee’s full name, such as John Smith, from ecnam data set

If specified, must be a valid employee full name

first_name

String

true

Employee’s first name, such as John, from ecnam or bcd data set

If specified, must be a valid first name of the employee

last_name

String

true

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

String

true

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_url

String

true

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

String

true

Email address, from ecnam or bcd data set

If specified, must be a valid email address of the employee

call_purpose

Object

true

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

call_reason

Object

true

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

Integer

true

Name score, between 0 and 100, inclusive, from ecnam data set

If specified, must be an integer between 0 and 100 inclusive

comments

String

true

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:

  • There are additional data fields, excluding the data_provider_name, data_source and cnam values

  • There is a valid cnam value with the data_source value as bcd, cno, or bcd+cno

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

String

true

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

fraud_score

Integer

true

Numeric fraud score between 0 and 100

If specified, must be an integer between 0 and 100 inclusive

category_id

Integer

true

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

String

true

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

String

true

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

overlay_name

String

true

Prefix or overlay name for call treatment methods as 'prefix' or 'overlay'

If specified, must be a non-empty string

original_calling_name

String

true

Original calling name supplied or found, if any

If specified, must be a non-empty string

cv_data

Object

true

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

verstat

Object

true

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

ppt

String

true

PASSporT type value, such as shaken, div, etc.

If specified, must be a valid PASSporT type value

attest

String

true

Attestation indicator value in a PASSporT with type as shaken

If specified, must be one of A, B, or C

origid

String

true

Origination id value in a PASSporT with type as shaken

If specified, must be a valid toekn for an origination id

alternate_calling_name

String

true

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

String

false

'From' header value from SIP INVITE message

Required

to

String

false

'To' header value from SIP INVITE message

Required

identity

Array

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: 21

{
  "status" : "ok"
}

The description of the fields in the response is as below:

Path Type Optional Description

status

String

true

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

String

false

'From' header value from SIP INVITE message

Required

to

String

false

'To' header value from SIP INVITE message

Required

diversion

Array

true

A list of 'Diversion' header values from SIP INVITE message

If specified, must be one as specified in RFC5806 Section 4

identity

Array

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: 21

{
  "status" : "ok"
}

The description of the fields in the response is as below:

Path Type Optional Description

status

String

true

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

String

false

'From' header value from SIP INVITE message

Required

to

String

false

'To' header value from SIP INVITE message

Required

resource_priority

Array

true

A list of 'Resource-Priority' header values from SIP INVITE message

If specified, must be one as specified in RFC4412 Section 3.1

priority

String

true

The SIP 'Priority' header value from SIP INVITE message

If specified, must be psap-callback

identity

Array

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: 21

{
  "status" : "ok"
}

The description of the fields in the response is as below:

Path Type Optional Description

status

String

true

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

String

false

'From' header value from SIP INVITE message

Required

to

String

false

'To' header value from SIP INVITE message

Required

caller_name

String

true

The CNAM to be used for constructing RCD PASSporT

If specified, must be not empty or blank

call_info

Array

true

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

caller_logo_uri

String

true

The URI identifying the location of the caller logo/icon image

If specified, must be valid URI

alt_present_number

String

true

The alternate presentation number to be used for constructing RCD PASSporT

If specified, must be a valid URI containing a numeric phone number

jcard

String

true

The JSON string representing a valid JCARD

If specified, must be valid JCARD in JSON format

rcd_issuer

String

true

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

rcd_integrity

Boolean

true

The boolean flag for verifying RCD PASSporT integrity hash

If specified, must be either true or false, with default as false

identity_info

Boolean

true

Boolean flag for returning information related to SIP Identity values verified

If specified, must be true or false

identity

Array

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

status

String

true

Verification status

identity_info

Array

true

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

status

String

false

The verification status of a SIP Identity header

Either "Ok" or an unique error identifier

params

String

false

The parameters in a SIP Identity header

Must be extracted from SIP Identity header

header

Object

false

The decoded PASSporT header object in a SIP Identity header

Must be a valid PASSporT header object

claim

Object

false

The decoded PASSporT claim object in a SIP Identity header

Must be a valid PASSporT claim object

certificate_info

Object

true

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

subject

String

false

The subject of the certificate used in a SIP Identity header

Must contain the subject extracted from an X.509 certificate

issuer

String

false

The issuer of the certificate used in a SIP Identity header

Must contain the issuer extracted from an X.509 certificate

tn_auth_list

Array

true

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

[].spc

String

true

A Service Provider Code in TN Authorization List

Must contain a non-empty string

[].one

String

true

A telephone number in TN Authorization List

Must contain a valid E.164 telephone number

[].range

Object

true

A telephone range in TN Authorization List

Must be a valid A telephone range object

[].range.start

Varies

false

The start telephone number of a telephone range in TN Authorization List

Must contain a valid E.164 telephone number

[].range.count

Varies

false

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

status

String

true

Verification status requirement

If specified, must be 'none', 'partial' or 'all'

from

String

false

'From' header value from SIP INVITE message

Required

to

String

false

'To' header value from SIP INVITE message

Required

identity

Array

false

A list of SIP Identity values to be verified

Required

verstat

Boolean

true

Boolean flag for returning verstat value after SIP Identity values are verified

If specified, must be true or false

identity_info

Boolean

true

Boolean flag for returning information related to SIP Identity values verified

If specified, must be true or false

request_id

String

true

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

status

String

true

Verification status

verstat

String

true

'verstat' value defined by ETSI TS 124 299

identity_info

Array

true

A list of information related to SIP Identity headers verified

request_id

String

true

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

status

String

false

The verification status of a SIP Identity header

Either "Ok" or an unique error identifier

params

String

false

The parameters in a SIP Identity header

Must be extracted from SIP Identity header

header

Object

false

The decoded PASSporT header object in a SIP Identity header

Must be a valid PASSporT header object

claim

Object

false

The decoded PASSporT claim object in a SIP Identity header

Must be a valid PASSporT claim object

certificate_info

Object

true

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

subject

String

false

The subject of the certificate used in a SIP Identity header

Must contain the subject extracted from an X.509 certificate

issuer

String

false

The issuer of the certificate used in a SIP Identity header

Must contain the issuer extracted from an X.509 certificate

tn_auth_list

Array

true

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

[].spc

String

true

A Service Provider Code in TN Authorization List

Must contain a non-empty string

[].one

String

true

A telephone number in TN Authorization List

Must contain a valid E.164 telephone number

[].range

Object

true

A telephone range in TN Authorization List

Must be a valid A telephone range object

[].range.start

Varies

false

The start telephone number of a telephone range in TN Authorization List

Must contain a valid E.164 telephone number

[].range.count

Varies

false

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

status

String

true

Verification status requirement

If specified, must be 'none', 'partial' or 'all'

from

String

false

'From' header value from SIP INVITE message

Required

to

String

false

'To' header value from SIP INVITE message

Required

caller_name

String

true

The CNAM to be used for constructing RCD PASSporT

If specified, must be not empty or blank

call_info

Array

true

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

alt_present_number

String

true

The alternate presentation number to be used for constructing RCD PASSporT

If specified, must be a valid URI containing a numeric phone number

jcard

String

true

The JSON string representing a valid JCARD

If specified, must be valid JCARD in JSON format

rcd_issuer

String

true

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

rcd_integrity

Boolean

true

The boolean flag for verifying RCD PASSporT integrity hash

If specified, must be either true or false, with default as false

identity

Array

false

A list of SIP Identity values to be verified

Required

verstat

Boolean

true

Boolean flag for returning verstat value after SIP Identity values are verified

If specified, must be true or false

identity_info

Boolean

true

Boolean flag for returning information related to SIP Identity values verified

If specified, must be true or false

request_id

String

true

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

status

String

true

Verification status

verstat

String

true

'verstat' value defined by ETSI TS 124 299

identity_info

Array

true

A list of information related to SIP Identity headers verified

request_id

String

true

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

status

String

false

The verification status of a SIP Identity header

Either "Ok" or an unique error identifier

params

String

false

The parameters in a SIP Identity header

Must be extracted from SIP Identity header

header

Object

false

The decoded PASSporT header object in a SIP Identity header

Must be a valid PASSporT header object

claim

Object

false

The decoded PASSporT claim object in a SIP Identity header

Must be a valid PASSporT claim object

certificate_info

Object

true

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

subject

String

false

The subject of the certificate used in a SIP Identity header

Must contain the subject extracted from an X.509 certificate

issuer

String

false

The issuer of the certificate used in a SIP Identity header

Must contain the issuer extracted from an X.509 certificate

tn_auth_list

Array

true

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

[].spc

String

true

A Service Provider Code in TN Authorization List

Must contain a non-empty string

[].one

String

true

A telephone number in TN Authorization List

Must contain a valid E.164 telephone number

[].range

Object

true

A telephone range in TN Authorization List

Must be a valid A telephone range object

[].range.start

Varies

false

The start telephone number of a telephone range in TN Authorization List

Must contain a valid E.164 telephone number

[].range.count

Varies

false

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

status

String

true

Verification status requirement

If specified, must be 'none', 'partial' or 'all'

from

String

false

'From' header value from SIP INVITE message

Required

to

String

false

'To' header value from SIP INVITE message

Required

date

String

true

'Date' header value from SIP INVITE message

If specified, must be in RFC1123 format

identity

Array

false

A list of SIP Identity values to be verified

Required

pai

Array

true

A list of 'P-Asserted-Identity' header values from SIP INVITE message

If specified, must be one as specified in RFC3325 Section 9.1

finger_print

Array

true

A list of SDP 'a=fingerprint' attribute values from SIP INVITE message

If specified, must be one as specified in RFC3325 Section 9.1

finger_print[].algorithm

String

false

Algorithm name of a SDP 'a=fingerprint' attribute from SIP INVITE message

Cannot be null or empty

finger_print[].digest

String

false

Digest value of a SDP 'a=fingerprint' attribute from SIP INVITE message

Cannot be null or empty

orig_cc

Array

true

Default country codes for the originator telephone number

If specified, must be a valid country code

dest_cc

String

true

Default country code for the destination telephone number

If specified, must be a valid country code

cnam

Boolean

true

Boolean flag for performing CNAM lookup

If specified, must be true or false

ecnam

Boolean

true

Boolean flag for performing ECNAM lookup

If specified, must be true or false

robocall

Boolean

true

Boolean flag for returning Robocall Call Insight data

If specified, must be true or false

verstat

Boolean

true

Boolean flag for returning verstat value after SIP Identity values are verified

If specified, must be true or false

identity_info

Boolean

true

Boolean flag for returning information related to SIP Identity values verified

If specified, must be true or false

request_id

String

true

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

status

String

true

Verification status

request_id

String

true

Client supplied request identifier for tracking purpose

verstat

String

true

'verstat' value defined by ETSI TS 124 299

identity_info

Array

true

A list of information related to SIP Identity headers verified

cnam

String

true

CNAM data

ecnam

Object

true

ECNAM data

call_insight

Object

true

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

String

false

'From' header value from SIP INVITE message

Required

to

String

false

'To' header value from SIP INVITE message

Required

identity

Array

false

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

status

String

true

Verification status

resigned_identity

String

false

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

String

false

'From' header value from SIP INVITE message

Required

to

String

false

'To' header value from SIP INVITE message

Required

identity

Array

false

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

status

String

true

Verification status

resigned_identity

String

false

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

String

false

'From' header value from SIP INVITE message

Required

to

String

false

'To' header value from SIP INVITE message

Required

identity

Array

false

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

status

String

true

Verification status

error

Array

true

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

status

String

true

Verification status requirement

If specified, must be 'none', 'partial' or 'all'

from

String

false

'From' header value from SIP INVITE message

Required

to

String

false

'To' header value from SIP INVITE message

Required

date

String

true

'Date' header value from SIP INVITE message

If specified, must be in RFC1123 format

identity

Array

false

A list of SIP Identity values to be verified

Required

cnam

Boolean

true

Boolean flag for performing CNAM lookup

If specified, must be true or false

ecnam

Boolean

true

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

status

String

true

Verification status

error

Array

true

A list of errors encountered in verifying SIP Identity headers

error[].error_id

String

false

The unique error identifier

error[].http_status_code

Number

false

The HTTP response status code

error[].sip_code

Number

false

The SIP response code associated with the error

error[].reason

String

false

The detailed error text

error[].timestamp

String

false

The timestamp when the error is generated

error[].attributes

Object

true

The name/value pair .attribute map associated with the error

error[].attributes.payload

String

true

The attribute name of 'payload' in the name/value pair

error[].attributes.signature

String

true

The attribute name of 'signature' in the name/value pair

cnam_error

Object

true

The error encountered in CNAM lookup

cnam_error.error_id

String

false

The unique error identifier

cnam_error.http_status_code

Number

false

The HTTP response status code

cnam_error.sip_code

Number

false

The SIP response code associated with the error

cnam_error.reason

String

false

The detailed error text

cnam_error.timestamp

String

false

The timestamp when the error is generated

ecnam_error

Object

true

The error encountered in ECNAM lookup

ecnam_error.error_id

String

false

The unique error identifier

ecnam_error.http_status_code

Number

false

The HTTP response status code

ecnam_error.sip_code

Number

false

The SIP response code associated with the error

ecnam_error.reason

String

false

The detailed error text

ecnam_error.timestamp

String

false

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

String

false

'From' header value from SIP INVITE message

Required

to

String

false

'To' header value from SIP INVITE message

Required

diversion

Array

true

A list of 'Diversion' header values from SIP INVITE message

If specified, must be one as specified in RFC5806 Section 4

identity

Array

false

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

status

String

true

Verification status

status

String

true

Verification status

error

Array

true

A list of errors encountered in verifying SIP Identity headers

error[].error_id

String

false

The unique error identifier

error[].http_status_code

Number

false

The HTTP response status code

error[].sip_code

Number

false

The SIP response code associated with the error

error[].reason

String

false

The detailed error text

error[].timestamp

String

false

The timestamp when the error is generated

error[].attributes

Object

true

The name/value pair .attribute map associated with the error

error[].attributes.identity

String

true

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

POST

API Path

${BASEURL}/identity

Required Parameters

Name

Description

apiKey

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

status

String

true

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

apiKey

String

false

The API key for identifying the API client

Cannot be null or empty

status

String

true

Verification status requirement

If specified, must be 'none', 'partial' or 'all'

origcc

String

true

Default country codes for the originator telephone number

If specified, must be a list of valid country codes separated by ',' or white spaces

destcc

String

true

Default country code for the destination telephone number

If specified, must be a valid country code

cnam

String

true

Boolean flag for performing CNAM lookup

If specified, must be 'true' or 'false'

ecnam

String

true

Boolean flag for performing ECNAM lookup

If specified, must be 'true' or 'false'

robocall

String

true

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

status

String

true

Verification status

cnam

String

true

CNAM data

ecnam

Object

true

ECNAM data

call_insight

Object

true

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

status

String

true

Verification status

resigned_identity

String

false

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

status

String

true

Verification status

error

Array

true

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

apiKey

String

false

The API key for identifying the API client

Cannot be null or empty

status

String

true

Verification status requirement

If specified, must be 'none', 'partial' or 'all'

origcc

String

true

Default country codes for the originator telephone number

If specified, must be a list of valid country codes separated by ',' or white spaces

destcc

String

true

Default country code for the destination telephone number

If specified, must be a valid country code

cnam

String

true

Boolean flag for performing CNAM lookup

If specified, must be 'true' or 'false'

ecnam

String

true

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

status

String

true

Verification status

error

Array

true

A list of errors encountered in verifying SIP Identity headers

error[].error_id

String

false

The unique error identifier

error[].http_status_code

Number

false

The HTTP response status code

error[].sip_code

Number

false

The SIP response code associated with the error

error[].reason

String

false

The detailed error text

error[].timestamp

String

false

The timestamp when the error is generated

error[].attributes

Object

true

The name/value pair .attribute map associated with the error

error[].attributes.payload

String

true

The attribute name of 'payload' in the name/value pair

error[].attributes.signature

String

true

The attribute name of 'signature' in the name/value pair

cnam_error

Object

true

The error encountered in CNAM lookup

cnam_error.error_id

String

false

The unique error identifier

cnam_error.http_status_code

Number

false

The HTTP response status code

cnam_error.sip_code

Number

false

The SIP response code associated with the error

cnam_error.reason

String

false

The detailed error text

cnam_error.timestamp

String

false

The timestamp when the error is generated

ecnam_error

Object

true

The error encountered in ECNAM lookup

ecnam_error.error_id

String

false

The unique error identifier

ecnam_error.http_status_code

Number

false

The HTTP response status code

ecnam_error.sip_code

Number

false

The SIP response code associated with the error

ecnam_error.reason

String

false

The detailed error text

ecnam_error.timestamp

String

false

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

POST

API Path

${BASEURL}/identity

Required Parameters

Name

Description

apiKey

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

apiKey

String

false

The API key for identifying the API client

Cannot be null or empty

status

String

true

Verification status requirement

If specified, must be 'none', 'partial' or 'all'

cnamPrefix

String

true

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

apiKey

String

false

The API key for identifying the API client

Cannot be null or empty

status

String

true

Verification status requirement

If specified, must be 'none', 'partial' or 'all'

cnamPrefix

String

true

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

apiKey

String

false

The API key for identifying the API client

Cannot be null or empty

status

String

true

Verification status requirement

If specified, must be 'none', 'partial' or 'all'

origcc

String

true

Default country codes for the originator telephone number

If specified, must be a list of valid country codes separated by ',' or white spaces

destcc

String

true

Default country code for the destination telephone number

If specified, must be a valid country code

cnam

String

true

Boolean flag for performing CNAM lookup

If specified, must be 'true' or 'false'

ecnam

String

true

Boolean flag for performing ECNAM lookup

If specified, must be 'true' or 'false'

robocall

String

true

Boolean flag for returning Robocall Call Insight data

If specified, must be 'true' or 'false'

cvt

String

true

Boolean flag for invoking CVT service for CNAM/ECNAM/Robocall data

If specified, must be 'true' or 'false'

cnamPrefix

String

true

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

String

true

'verstat' value defined by ETSI TS 124 299, for enabling tagging

If specified, must be a valid 'verstat' value

identity

Boolean

true

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

apiKey

String

false

The API key for identifying the API client

Cannot be null or empty

identity

Boolean

true

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

apiKey

String

false

The API key for identifying the API client

Cannot be null or empty

identity

Boolean

true

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

POST

API Path

${BASEURL}/identity/proxy/{addr}/{port}?apiKey=<apiKey>

Request Path Variable

Name

Description

addr

The remote IP address from which the SIP INVITE message is originated

port

The remote port from which the SIP INVITE message is originated

Required Parameters

Name

Description

apiKey

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

status

String

true

Verification status

next_hop

String

true

The URI of next hop

policy

String

true

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

status

String

true

Verification status

next_hop

String

true

The URI of next hop

policy

String

true

The policy for processing the SIP message

header

Array

true

A list of SIP headers or RequestLine to be added into or removed from SIP INVITE message

header[].operation

String

false

Either 'add' or 'remove'

header[].name

String

false

The name of the SIP header or RequestLine to be added or removed

header[].value

String

false

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

status

String

true

Verification status

next_hop

String

true

The URI of next hop

policy

String

true

The policy for processing the SIP message

header

Array

true

A list of SIP headers or RequestLine to be added into or removed from SIP INVITE message

header[].operation

String

false

Either 'add' or 'remove'

header[].name

String

false

The name of the SIP header or RequestLine to be added or removed

header[].value

String

false

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

status

String

true

Verification status

next_hop

String

true

The URI of next hop

policy

String

true

The policy for processing the SIP message

header

Array

true

A list of SIP headers or RequestLine to be added into or removed from SIP INVITE message

header[].operation

String

false

Either 'add' or 'remove'

header[].name

String

false

The name of the SIP header or RequestLine to be added or removed

header[].value

String

false

The value of the SIP header or RequestLine to be added or removed

error

Array

true

A list of errors encountered in verifying SIP Identity headers

error[].error_id

String

false

The unique error identifier

error[].http_status_code

Number

false

The HTTP response status code

error[].sip_code

Number

false

The SIP response code associated with the error

error[].reason

String

false

The detailed error text

error[].timestamp

String

false

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

status

String

true

Verification status

next_hop

String

true

The URI of next hop

policy

String

true

The policy for processing the SIP message

header

Array

true

A list of SIP headers or RequestLine to be added into or removed from SIP INVITE message

header[].operation

String

false

Either 'add' or 'remove'

header[].name

String

false

The name of the SIP header or RequestLine to be added or removed

header[].value

String

false

The value of the SIP header or RequestLine to be added or removed

error

Array

true

A list of errors encountered in verifying SIP Identity headers

error[].error_id

String

false

The unique error identifier

error[].http_status_code

Number

false

The HTTP response status code

error[].sip_code

Number

false

The SIP response code associated with the error

error[].reason

String

false

The detailed error text

error[].timestamp

String

false

The timestamp when the error is generated

error[].developer_message

String

true

The additional developer message, if any

error[].attributes

Object

true

The name/value pair .attribute map associated with the error

error[].attributes.dest_expected

String

true

The attribute name of 'dest_expected' in the name/value pair

error[].attributes.dest

String

true

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

status

String

true

Verification status

next_hop

String

true

The URI of next hop

policy

String

true

The policy for processing the SIP message

header

Array

true

A list of SIP headers or RequestLine to be added into or removed from SIP INVITE message

header[].operation

String

false

Either 'add' or 'remove'

header[].name

String

false

The name of the SIP header or RequestLine to be added or removed

header[].value

String

false

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

status

String

true

Verification status

next_hop

String

true

The URI of next hop

policy

String

true

The policy for processing the SIP message

error

Array

true

A list of errors encountered in verifying SIP Identity headers

error[].error_id

String

false

The unique error identifier

error[].http_status_code

Number

false

The HTTP response status code

error[].sip_code

Number

false

The SIP response code associated with the error

error[].reason

String

false

The detailed error text

error[].timestamp

String

false

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

status

String

true

Verification status

next_hop

String

true

The URI of next hop

policy

String

true

The policy for processing the SIP message

error

Array

true

A list of errors encountered in verifying SIP Identity headers

error[].error_id

String

false

The unique error identifier

error[].http_status_code

Number

false

The HTTP response status code

error[].sip_code

Number

false

The SIP response code associated with the error

error[].reason

String

false

The detailed error text

error[].timestamp

String

false

The timestamp when the error is generated

error[].developer_message

String

true

The additional developer message, if any

error[].attributes

Object

true

The name/value pair .attribute map associated with the error

error[].attributes.dest_expected

String

true

The attribute name of 'dest_expected' in the name/value pair

error[].attributes.dest

String

true

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

status

String

true

Verification status

next_hop

String

true

The URI of next hop

policy

String

true

The policy for processing the SIP message

header

Array

true

A list of SIP headers or RequestLine to be added into or removed from SIP INVITE message

header[].operation

String

false

Either 'add' or 'remove'

header[].name

String

false

The name of the SIP header or RequestLine to be added or removed

header[].value

String

false

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

status

String

true

Verification status

next_hop

String

true

The URI of next hop

policy

String

true

The policy for processing the SIP message

header

Array

true

A list of SIP headers or RequestLine to be added into or removed from SIP INVITE message

header[].operation

String

false

Either 'add' or 'remove'

header[].name

String

false

The name of the SIP header or RequestLine to be added or removed

header[].value

String

false

The value of the SIP header or RequestLine to be added or removed

error

Array

true

A list of errors encountered in verifying SIP Identity headers

error[].error_id

String

false

The unique error identifier

error[].http_status_code

Number

false

The HTTP response status code

error[].sip_code

Number

false

The SIP response code associated with the error

error[].reason

String

false

The detailed error text

error[].timestamp

String

false

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

status

String

true

Verification status

next_hop

String

true

The URI of next hop

policy

String

true

The policy for processing the SIP message

header

Array

true

A list of SIP headers or RequestLine to be added into or removed from SIP INVITE message

header[].operation

String

false

Either 'add' or 'remove'

header[].name

String

false

The name of the SIP header or RequestLine to be added or removed

header[].value

String

false

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

status

String

true

Verification status

next_hop

String

true

The URI of next hop

policy

String

true

The policy for processing the SIP message

header

Array

true

A list of SIP headers or RequestLine to be added into or removed from SIP INVITE message

header[].operation

String

false

Either 'add' or 'remove'

header[].name

String

false

The name of the SIP header or RequestLine to be added or removed

header[].value

String

false

The value of the SIP header or RequestLine to be added or removed

error

Array

true

A list of errors encountered in verifying SIP Identity headers

error[].error_id

String

false

The unique error identifier

error[].http_status_code

Number

false

The HTTP response status code

error[].sip_code

Number

false

The SIP response code associated with the error

error[].reason

String

false

The detailed error text

error[].timestamp

String

false

The timestamp when the error is generated

error[].developer_message

String

true

The additional developer message, if any

error[].attributes

Object

true

The name/value pair .attribute map associated with the error

error[].attributes.dest_expected

String

true

The attribute name of 'dest_expected' in the name/value pair

error[].attributes.dest

String

true

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

status

String

true

Verification status

next_hop

String

true

The URI of next hop

policy

String

true

The policy for processing the SIP message

header

Array

true

A list of SIP headers or RequestLine to be added into or removed from SIP INVITE message

header[].operation

String

false

Either 'add' or 'remove'

header[].name

String

false

The name of the SIP header or RequestLine to be added or removed

header[].value

String

false

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

status

String

true

Verification status

next_hop

String

true

The URI of next hop

policy

String

true

The policy for processing the SIP message

error

Array

true

A list of errors encountered in verifying SIP Identity headers

error[].error_id

String

false

The unique error identifier

error[].http_status_code

Number

false

The HTTP response status code

error[].sip_code

Number

false

The SIP response code associated with the error

error[].reason

String

false

The detailed error text

error[].timestamp

String

false

The timestamp when the error is generated

header

Array

true

A list of SIP headers or RequestLine to be added into or removed from SIP INVITE message

header[].operation

String

false

Either 'add' or 'remove'

header[].name

String

false

The name of the SIP header or RequestLine to be added or removed

header[].value

String

false

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

status

String

true

Verification status

next_hop

String

true

The URI of next hop

policy

String

true

The policy for processing the SIP message

header

Array

true

A list of SIP headers or RequestLine to be added into or removed from SIP INVITE message

header[].operation

String

false

Either 'add' or 'remove'

header[].name

String

false

The name of the SIP header or RequestLine to be added or removed

header[].value

String

false

The value of the SIP header or RequestLine to be added or removed

error

Array

true

A list of errors encountered in verifying SIP Identity headers

error[].error_id

String

false

The unique error identifier

error[].http_status_code

Number

false

The HTTP response status code

error[].sip_code

Number

false

The SIP response code associated with the error

error[].reason

String

false

The detailed error text

error[].timestamp

String

false

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

GET

API Path

${BASEURL}/identity/proxy/{addr}/{port}?apiKey=<apiKey>

Request Path Variable

Name

Description

addr

The remote IP address from which the SIP message is originated

port

The remote port from which the SIP message is originated

Required Parameters

Name

Description

apiKey

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

status

String

true

Verification status

next_hop

String

true

The URI of next hop

policy

String

true

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

status

String

true

Verification status

error

Array

true

A list of errors encountered in verifying SIP Identity headers

error[].error_id

String

false

The unique error identifier

error[].http_status_code

Number

false

The HTTP response status code

error[].sip_code

Number

false

The SIP response code associated with the error

error[].reason

String

false

The detailed error text

error[].attributes

Object

true

The name/value pair .attribute map associated with the error

error[].attributes.address

String

true

The remote IP address of SIP message originated

error[].attributes.port

String

true

The remote IP port of SIP message originated

error[].timestamp

String

false

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

GET

API Path

${BASEURL}/cnam/tn/{digits}

Required Parameters

Name

Description

apiKey

The API key uniquely identifying the API client

Request Path Variable

Name

Description

digits

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

digits

String

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

String

true

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

digits

String

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

cnam_error

Object

true

The error encountered in CNAM lookup

cnam_error.error_id

String

false

The unique error identifier

cnam_error.http_status_code

Number

false

The HTTP response status code

cnam_error.sip_code

Number

false

The SIP response code associated with the error

cnam_error.reason

String

false

The detailed error text

cnam_error.timestamp

String

false

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

POST

API Path

${BASEURL}/cnam

Required Parameters

Name

Description

apiKey

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

String

false

'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

String

true

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

String

false

'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

cnam_error

Object

true

The error encountered in CNAM lookup

cnam_error.error_id

String

false

The unique error identifier

cnam_error.http_status_code

Number

false

The HTTP response status code

cnam_error.sip_code

Number

false

The SIP response code associated with the error

cnam_error.reason

String

false

The detailed error text

cnam_error.timestamp

String

false

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

GET

API Path

${BASEURL}/ecnam/tn/{digits}

Required Parameters

Name

Description

apiKey

The API key uniquely identifying the API client

Request Path Variable

Name

Description

digits

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

digits

String

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

Object

true

ECNAM data

call_insight

Object

true

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

digits

String

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

ecnam_error

Object

true

The error encountered in ECNAM lookup

ecnam_error.error_id

String

false

The unique error identifier

ecnam_error.http_status_code

Number

false

The HTTP response status code

ecnam_error.sip_code

Number

false

The SIP response code associated with the error

ecnam_error.reason

String

false

The detailed error text

ecnam_error.timestamp

String

false

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

POST

API Path

${BASEURL}/ecnam

Required Parameters

Name

Description

apiKey

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

String

false

'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

Object

true

ECNAM data

call_insight

Object

true

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

String

false

'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

ecnam_error

Object

true

The error encountered in ECNAM lookup

ecnam_error.error_id

String

false

The unique error identifier

ecnam_error.http_status_code

Number

false

The HTTP response status code

ecnam_error.sip_code

Number

false

The SIP response code associated with the error

ecnam_error.reason

String

false

The detailed error text

ecnam_error.timestamp

String

false

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

GET

API Path

${BASEURL}/error

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

[].error_id

String

false

The unique error identifier

[].http_status_code

Number

false

The HTTP response status code

[].sip_code

Number

false

The SIP response code associated with the error

[].reason

String

false

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-