STIR/SHAKEN API

The STIR/SHAKEN API (STI-AS) is a web service that signs a call and returns its STIR/SHAKEN attestation level and identity token. Use the result for call routing and verification.

This API requires an API key. Find your key on the Organization settings page of the Smart Carrier dashboard. If you cannot find it, contact support@smartcarrier.io.

To review past requests, see the STIR/SHAKEN log.

Web service information

Field	Value
Endpoint	`https://api.smartcarrier.io/v2/sti-as?`
Method	`GET`
Parameters	`ToNumber`, `FromNumber`
Header	`x-api-key` (get your API key)
Example	`https://api.smartcarrier.io/v2/sti-as?ToNumber=12025550143&FromNumber=8005550199`

Request parameters

Parameter	Type	Description
`ToNumber`	string	The destination telephone number for the call.
`FromNumber`	string	The originating telephone number (calling party or ANI).

Sample response

{
  "RequestGuid": "11111111-2222-3333-4444-555555555555",
  "AccountGuid": "12345678-1234-1234-1234-123456789012",
  "APIKey": "YOUR_API_KEY",
  "FromNumber": "18005550199",
  "ToNumber": "12025550143",
  "Prefix": "",
  "LERG_ToNumber": {
    "RequestGuid": "66666666-7777-8888-9999-000000000000",
    "RoutingNumber": "12025550000",
    "NPA": "202",
    "NXX": "555",
    "Block": "1",
    "USState": "DC",
    "Company": "EXAMPLE TELECOM, INC.",
    "OCN": "1234",
    "RateCenter": "EXAMPLE",
    "CLLI": "EXMPLDCXX01",
    "Assigned_Date": null,
    "PrefixType": "CLEC",
    "SwitchName": "",
    "SwitchType": "",
    "LATA": "999",
    "Country": "US",
    "TollFree": false,
    "IsValid": true,
    "RequestedAt": "2025-01-01T12:00:01.0000000Z",
    "ElapsedMilliseconds": 0
  },
  "NationalDNCStatus": "0",
  "AttestationLevel": "B",
  "STI_Token": "",
  "Identity": "<header>.<payload>.<signature>;info=<https://certificates.smartcarrier.io/CERTIFICATE_ID.cer>;alg=ES256;ppt=shaken",
  "RequestingIP": "203.0.113.10",
  "ProcessingTime": 574,
  "ApplicationVersion": "18",
  "DateTimeRequested": "2025-01-01T12:00:00.0000000Z"
}

The sample shortens Identity. A real response holds the full signed token in each of the three parts.

What do these values mean?

Field	Description
`RequestGuid`	A unique identifier assigned to this request.
`AccountGuid`	The account associated with this request.
`APIKey`	The API key used for the request.
`FromNumber`	The originating telephone number (calling party or ANI).
`ToNumber`	The destination telephone number.
`Prefix`	The prefix (trunk) associated with the request. Empty when none applies.
`LERG_ToNumber`	The Local Exchange Routing Guide record for the destination number. It has the same fields as the LERG object in the Enhanced Insights API.
`NationalDNCStatus`	The National Do Not Call status for the destination number. `0` means the number was not flagged.
`AttestationLevel`	The attestation level assigned to the call. `A`: Full attestation. `B`: Partial attestation. `C`: Gateway attestation.
`STI_Token`	The identity token as a standalone value. Empty when the token is returned in `Identity`.
`Identity`	The complete SIP `Identity` header value: the signed token (PASSporT), then the `info`, `alg`, and `ppt` parameters. Place it in the SIP `Identity` header as is.
`RequestingIP`	The IP which initiated the request.
`ProcessingTime`	Total time to complete the request, in milliseconds.
`ApplicationVersion`	The version of the service that handled the request.
`DateTimeRequested`	When the request was received (UTC).

Inside the identity token

The token in Identity has three parts, separated by periods: header, payload, and signature. The header and payload are Base64URL-encoded JSON.

Decoded header:

{
  "alg": "ES256",
  "typ": "passport",
  "ppt": "shaken",
  "x5u": "https://certificates.smartcarrier.io/CERTIFICATE_ID.cer"
}

Decoded payload:

{
  "attest": "B",
  "dest": { "tn": ["12025550143"] },
  "iat": 1735732800,
  "orig": { "tn": "18005550199" },
  "origid": "12345678-1234-1234-1234-123456789012"
}

Field	Description
`x5u`	The URL of the public certificate that verifies the signature.
`attest`	The attestation level (`A`, `B`, or `C`).
`dest.tn`	The destination telephone number.
`orig.tn`	The originating telephone number.
`iat`	When the token was issued, in seconds since 1970-01-01 (UTC).
`origid`	An identifier for the originator of the call. It matches your `AccountGuid`.