Trust Score
Trust Score API (“Trust Score”) is a real-time indicator of a phone number’s trustworthiness. It accurately measures the real-time risk of authenticating a consumer using a specific phone number.
Trust Score achieves this by analyzing and scoring daily life cycle change events, along with leveraging carrier signals and core telecom infrastructure signals, enabling us to manage the tenure identity behind the phone number.
Most consumers have had their phone number for many years. Customer verification increasingly relies on “something you have” authentication using phones and phone numbers, an integral aspect of a consumer’s daily life. In an increasingly digital economy, accelerated by COVID-19, an amplified focus on fraud prevention is essential for many of our customers. Trust Score provides banks, financial institutions, insurance companies, retail companies, and other customers with a tool that can be applied to multiple use cases where knowing the fraud risk of a transaction is critical.
Trust Score establishes the Reputation portion of PRO model of identity verification:
Possession–Confirm possession of the phone with “something-you-have” authentication Reputation–Screen for risk to ensure the phone being used to authenticate is not compromised or used by a bad actor. Ownership–Verifying the phone number associated with the rightful owner or actual consumer.
To make a Trust Score call, the phone number is the only piece of information required. Our proprietary algorithm then consumes carrier signals and uses our managed identity intelligence to generate a Trust Score for the phone number, a numerical value ranging from 0 to 1,000 (the higher the number, the more trustworthy). In addition to the score itself, reason codes are returned in the API response, signifying the factors that affected the score.
Depending on the parameter passed in the API and the end-user mobile consent obtained, some of the attributes used to calculate the Trust Score can be returned as well, representing more specific data and fields. The reason codes and line attributes can be interpreted independently of the Trust Score, should you want to establish further rules for risk tolerance.
There are several inputs and variables that affect the Trust Score of a phone number, some that increase the score and some that decrease it. Although specifics cannot be shared for security purposes, below are some general guidelines that may be shared that indicate how the Trust Score may be affected:
Increase score:
- Found long tenure with
- SIM
- Device
- Phone number
- Signzy managing identity
- Carrier
- Clients inquiring on the phone
Decrease score:
- Inactive status (cannot place phone calls or send and receive texts)
- Recent changes to the SIM or device
- Many changes in a short amount of time to SIM, device, port, phone number
- Higher risk line types (e.g., VoIPs not connected to a physical location)
- No data was supplied from the carrier/telecom
The method used to calculate Trust Score is a point-based deduction. The process evaluates all of the heuristic-based business rules in the model, and for those that meet their conditions, several points are either deducted or added, starting with the perfect score of 1,000.
The number of points deducted or added depends on the components’ criteria being met. The final score can range between 0–1,000, with the highest level of trust being 1,000 and the lowest level of trust being 0. More information on applying these levels of trust can be found in the Trust Score Interpretation section below.
For example, if a given phone number meets two rules, one deducting 150 points and another deducting 100 points, the resulting score will be 750 (1,000 – 150 – 100=750).
Signzy generally recommends the following integer thresholds for mobile line-type numbers when using Trust Score:
- 0-300: Low Trust
- 301-629: Medium Trust
- 630-1000: High Trust
The application of the Trust Score API allows for a degree of customization to best suit your organization’s needs, with two different request and response versions that can control the amount of information returned from the API call. There are also three ways you can analyze a Trust Score: using only the Trust Score integer, the integer and the returned reason codes, or the integer plus the reason codes plus the carrier’s phone line attributes.
The response body contains the Trust Score integer, the reason codes and the carrier’s phone line attributes as a standard response. Additionally, if you pass the details field as true, additional phone line attributes and change events values are returned, potentially including:
- carrier status
- velocity (or the number of changes within the last 90 days) for:
- phone number
- port
- SIM
- device
- tenure (or length of time seen, shown by MinDate and MaxDate) for:
- SIM
- Our Subscriber records
- phone number
- carrier
- device
For all these attributes, standard response will store null value for these fields but when details is set to true and consent status is provided then the values will be shown for the above attributes in response.
Note, as mentioned in the Consumer Consent section above, all phone line attributes listed above are only available from the carrier when consent is obtained from your consumer.
minimumDate & maximumDate Tenure
In order to protect consumer's data and keep from sharing exact dates for tenure calculations, the minimumDate and maximumDate fields indicate ranges of time that the most recent date of activation or change could have occurred in. The minimumDate is the most recent date/time of that range, and the maximumDate is the earliest date/time. See the Minimum/Maximum Logic section for more details.
You must first login before sending the request. The authorization header in the request must include the access token obtained from the login API call.
Key | Type | Mandatory | Description |
|---|---|---|---|
consentStatus | string | true | The consent status of the phone number. Possible values are: optedIn - The end user has provided consent for the collection of their personal data. optedOut - The end user has refused to allow collection of their personal data. notCollected - No attempt has been made to obtain consent from the end user. unknown - The status of consent collection is unknown. Note: This value must be optedIn in order to access MNO data. |
phoneNumber | string | true | The phone number being queried. (without leading plus sign & country code) |
details | String | false | Specifies whether to include additional details in the response. Input is "true" or "false" |
countryCode | string | true | The country code associated with the phone number. "US" or "CA" |
Key | Type | Description |
|---|---|---|
status | integer | The status of the request. A response of 0 indicates success. Any non-0 response is an error indication. |
description | string | A text string that defines the cause of the status code. |
response | object | The response object containing trust score details. |
transactionId | string | Unique transaction identifier used to identify the results of the request. |
payfoneAlias | string | A persistent ID that uniquely identifies a telephone subscriber. |
phoneNumber | string | The phone number associated with the subscriber. |
lineType | string | Line type associated with the phone number. Possible values are: Mobile, Landline, FixedVoIP, NonFixedVoIP. |
carrier | string | The carrier related to the phone number. |
countryCode | string | The country code associated with the phone number. |
statusIndex | string | A bitmapped value that represents networkStatus, accountType, accountRole, and customerType. |
isBaselined | boolean | An indicator to communicate whether Signzy has ever transacted with the input phone number before the current transaction. |
trustScore | number | An integer value ranging from 0–1000 that denotes the real-time trustworthiness of a phone number. |
reasonCodes | string[] | An array of indicators providing additional context about the transaction. |
carrierStatus | string | Carrier status associated with the phone number. Values include: Active Suspended Disconnected Unknown null Value is returned only if consentStatus=optedIn, details=true, else it will be null in standard response. |
phoneNumberVelocity | integer | The number of times the subscriber has changed their phone number. Value is returned only if consentStatus=optedIn, details=true & if phoneNumber is changed, else it will be null in standard response. |
portVelocity | integer | The number of times the subscriber has changed their carrier within the last 90 days. Value is returned only if consentStatus=optedIn, details=true & if carrier is changed, else it will be null in standard response. |
simVelocity | integer | The number of times the mobile subscriber has changed their SIM within the last 90 days. Value is returned only if consentStatus=optedIn, details=true & if SIM is changed, else it will be null in standard response. |
deviceVelocity | integer | The number of times the mobile subscriber has changed their device within the last 90 days. Value is returned only if consentStatus=optedIn, details=true & if device is changed, else it will be null in standard response. |
payfoneTenure | object | The amount of time Signzy has been able to track the subscriber. Defined with a minimum and maximum date. Only returns if details=true |
minimumDate | date-time | Payfone Tenure Object Attribute |
carrierTenure | object | The amount of time Signzy has been able to track the carrier associated with the subscriber. Defined with a minimum and maximum date. Only returns if consentStatus=optedIn, details=true |
minimumDate | date-time | Carrier Tenure Object Attribute |
maximumDate | date-time | Carrier Tenure Object Attribute |
phoneNumberTenure | object | The amount of time Signzy has been able to track the phone number associated with the subscriber. Defined with a minimum and maximum date. Only returns if details=true |
minimumDate | date-time | Phone Number Tenure Object Attribute |
simTenure | object | The amount of time Signzy has been able to track the SIM association with the subscriber. Defined with a minimum and maximum date. Only returns if consentStatus=optedIn, details=true |
minimumDate | date-time | Sim Tenure Object Attribute |
maximumDate | date-time | Sim Tenure Object Attribute |
deviceTenure | object | The amount of time Signzy has been able to track the device association with the subscriber. Defined with a minimum and maximum date. Only returns if consentStatus=optedIn, details=true |
minimumDate | date-time | Device Tenure Object Attribute |
maximumDate | date-time | Device Tenure Object Attribute |
portedDate | | The date associated with a port of the phone number. Defined with a minimum and maximum date. Only returns if details=true |
minimumDate | date-time | Ported Date Object Attribute |
maximumDate | date-time | Ported Date Object Attribute |
The table below shows which attributes return for optedIn versus the attributes returned for optedOut, notCollected, and unknown. Note again that the details field must be set as true to see these detailed attributes.
optedIn | optedOut, notCollected, Unknown |
|---|---|
countryCode | countryCode |
carrierStatus | |
phoneNumberVelocity | phoneNumberVelocity |
portVelocity | portVelocity |
simVelocity | |
deviceVelocity | |
payfoneTenure | payfoneTenure |
phoneNumberTenure | phoneNumberTenure |
carrierTenure | |
simTenure | |
deviceTenure | |
portedDate | portedDate |
Response parameters can be null based on the data availability from the API sources.
Reason Code | Description | Additional Details |
|---|---|---|
CU | Carrier call was unsuccessful | Returned when change data was/is not available, which includes: - We do not support subscriber management for a carrier, which is needed for change events. - We do not receive IMSI, or IMEI changes from a carrier (e.g., US cellular). - We did not get a response from the carrier during the transaction (timeout, for example). |
D2 | The phone number was recently deactivated. | A disconnect event has been detected in the last 2 days. |
DR | The device date returned was not obtained real-time; there could be a more recent device change. | Returned for a phone number if the MNO is a carrier that does not provide IMEI change events in real-time but we can derive an IMEI change. (e.g., Sprint) This can be used to determine that a device change occurred since the last time it was checked, but the date is ambiguous and could have happened at any point between the max date and the min date. |
DV | High device change velocity | This may indicate a higher risk of authenticating the consumer, especially during customer onboarding. |
FF | Call forwarding is not enabled on the consumer’s phone. | The call forwarding check and mobile consent must be enabled on your account, and consentStatus passed optedIn, for this reason code to be returned. |
FO | Call forwarding is enabled on the consumer’s phone. | The call forwarding check and mobile consent must be enabled on your account, and consentStatus passed optedIn, for this reason code to be returned. |
HV | High velocity of change events associated with phone | This may indicate a higher risk of authenticating the consumer, especially during customer onboarding. |
I5 | Indicates zero Instant Link transactions in the last 90 days for the phone number being queried. | This reason code only returns if enabled for you, and a higher level of IL transaction within the period could indicate a higher risk factor. |
I6 | Indicates 1–3 Instant Link transactions in the last 90 days for the phone number being queried. | This reason code only returns if enabled for you, and a higher level of IL transaction within the period could indicate a higher risk factor. |
I7 | Indicates 4–7 Instant Link transactions in the last 90 days for the phone number being queried. | This reason code only returns if enabled for you, and a higher level of IL transaction within the period could indicate a higher risk factor. |
I8 | Indicates 8–15 Instant Link transactions in the last 90 days for the phone number being queried. | This reason code only returns if enabled for you, and a higher level of IL transaction within the period could indicate a higher risk factor. |
I9 | Indicates more than 15 Instant Link transactions in the last 90 days for the phone number being queried. | This reason code only returns if enabled for you, and a higher level of IL transaction within the period could indicate a higher risk factor. |
LP | Low tenure device | This may indicate a higher risk due to low tenure. Normal circumstances may be a device upgrade if the reason code LT is not present. |
LS | Low Tenure SIM | This may indicate higher risk due to low tenure on SIM. Pair this with your high-risk events to mitigate the phone takeover at the carrier. |
LT | Low tenure mobile identity | This may indicate a higher risk of identity theft or synthetic ID fraud, especially at account opening or customer onboarding. |
ND | Phone number network status information is not available. | While this may mean no data is available, this may not necessarily be indicative of risk. |
NM | Not a mobile line type | It may not indicate risk but is intended to filter mobiles from non-mobile line types. |
NP | Non-personal line | It could signify a business or government phone line |
PN | Mobile phone number is not active. | The phone number provided is either suspended or deactivated; it cannot place or receive voice calls or SMS text messages transmitted over a cell tower. |
PT | Phone number is currently in a ported state. | The phone number has been ported outside of the carrier that owns the phone number. This reason code will continue to fire while the phone is in the ported state. Use the ported date field to determine if the port was recent (rather than just relying on the return of this reason code) to manage the risk of carrier takeover via a port attack. |
RL | Phone number is associated with a high-risk line type (Non-Fixed VoIP or Prepaid MVNO). | This may indicate higher fraud risk. |
RN | Phone number is at low risk for fraud as a mobile line listed on the Override Services Registry (OSR). | It may indicate lower risk. For mobile line-type phone numbers, carriers must authenticate their subscriber to add their number to the OSR. Only the owning carrier can add their mobile phone numbers to the OSR. |
RR | Phone number is at a higher risk for fraud as a non-mobile line listed on the Override Services Registry (OSR). | The phone is at risk of SMS-forwarding vulnerability but is not necessarily always at high risk for fraud. Phone numbers that are on the OSR are vulnerable to SMS message hijacking. For non-mobile line type phone numbers, adding a number to the OSR is not restricted to the owning carrier. Other carriers, including non-major carriers more susceptible to fraud, can add these phones to the OSR. |
SA | Sub-account line | Multiple phone lines are associated with one account, typically on family plans. It may not be indicative of risk. |
SR | The SIM date returned was not obtained real-time; there could be a more recent SIM change. | Returned for a phone number if the MNO is a carrier that does not provide IMSI change events in real-time but we can derive an IMSI change. This can be used to know that a SIM change occurred since the last time it was checked, but the date is ambiguous and could have happened between the max date and the min date. |
UC | Insufficient data to calculate trustScore | When no data is returned, this negatively affects the Trust Score but may not indicate risk. |
To avoid sending specific dates for phone attribute change events (i.e., to show SIM tenure, device tenure, etc.), we return general time ranges of minimum-maximum dates that the most recent change event for the attribute falls under concerning the current date.
Change Event Time Range | Minimum Date Field (most recent time possible) | Maximum Date Field (longest time possible) |
|---|---|---|
Unknown or blank | No date returned | No date returned |
<=24 hours ago | Current date with time of 23:59:59 | Current date with time of 00:00:00 |
> 24 hours and <=48 hours ago | Current date minus 1 day & time of 23:59:59 | Current date minus 2 days & time of 00:00:00 |
> 48 hours and <=7 days ago | Current date minus 2 days & time of 23:59:59 | Current date minus 7 days & time of 00:00:00 |
> 7 days and <=30 days ago | Current date minus 7 days & time of 23:59:59 | Current date minus 30 days & time of 00:00:00 |
> 30 days and <=90 days ago | Current date minus 30 days & time of 23:59:59 | Current date minus 90 days & time of 00:00:00 |
> 90 days and <=365 days ago | Current date minus 90 days time of 23:59:59” | Current date minus 365 days & time of 00:00:00 |
> 365 days ago | Current date minus 365 days & time of 23:59:59 | No date returned |
Parameter | Description |
|---|---|
error | This parameter contains the error. |
error.name | the name of the error |
error.message | the error message |
error.status | status of the api |
error.reason | Reason for error |
error.type | Type of the error |
error.statusCode | Request Status code from Signzy |
Getting help
Please feel free to contact us if you have any questions, require clarification, or have ideas for how to make the documents or any of our services better.
You can reach out to us at [email protected]. We strive to provide prompt and reliable assistance, ensuring your queries are addressed effectively.
We value your feedback and are committed to making your experience smooth and enjoyable. Our team is dedicated to assisting you with any needs you may have. Thank you for choosing our services. We look forward to helping you!