---
title: Phone Insights Score
slug: us-apis/phone-insights-score
description: Get valuable information on the Trust Score API, a powerful tool assessing phone number trustworthiness. Learn how to interpret the Trust Score, available response versions, and required parameters. Discover fields and data fields used in requests and res
docTags:
createdAt: 2023-01-31T12:44:28.000Z
---
## Introduction
The **Phone Insights Score API** provides a comprehensive risk assessment of a user based solely on their phone number. It aggregates data from carrier records, porting history, SIM activity, and deactivation events to generate a trust score that reflects the reliability and authenticity of the user’s phone identity.
This API is a powerful tool for fraud prevention, risk profiling, and enhancing decision-making during user onboarding or transaction verification. A higher score indicates higher trustworthiness and lower risk associated with the phone number.
### Key Benefits
- Real-time phone-based risk scoring for fraud detection.
- Enhanced onboarding decisions using trusted telecom data.
- Reduced manual checks with automated risk signals.
- Seamless integration into KYC and fraud prevention workflows.
### Common Use Cases
1. Fintech & Lending Risk Assessment
- Evaluate risk of identity fraud before approving loans or credit using phone-based risk indicators.
2. E-commerce Transaction Verification
- Use phone trust score to flag high-risk users or transactions during checkout.
3. Fraud Prevention in Digital Wallets
- Detect fraud or recently ported numbers before allowing sensitive actions like money transfers or password resets.
4. Customer Onboarding in Telecom & Utilities
- Assess user legitimacy based on deactivation patterns and SIM activity before issuing services.
5. Authentication & Login Flows
- Use score as an additional risk signal to trigger step-up authentication or challenge mechanisms.
6. Ride-Sharing, Gig, or Rental Platforms
- Quickly assess the trust level of new users or drivers/renters through phone number intelligence.
### Sample cURL
::::Tabs
:::Tab{title="Production"}
```curl
curl --location 'https://api.signzy.us/api/v3/us-kyc/phone-insights-score' \
--header 'Authorization: ' \
--header 'Content-Type: application/json' \
--data '{
"consentStatus": "",
"phoneNumber": "XXXXXXXXXX",
"countryCode": "US",
"consentOptinType": "Whitelist",
"consentOptinMethod": "TCO",
"consentOptinDuration": "ONE",
"consentOptinId": "XXXXXX",
"consentOptinTimestamp": "2019-09-18T00:13:37.667Z",
“consentOptinUrl” : “www.example.com” // optional field
}'
```
:::
:::Tab{title="Pre-Production"}
```curl
curl --location 'https://api-preproduction.signzy.us/api/v3/us-kyc/phone-insights-score' \
--header 'Authorization: ' \
--header 'Content-Type: application/json' \
--data '{
"consentStatus": "optedIn",
"phoneNumber": "XXXXXXXXXX",
"countryCode": "US",
"consentOptinType": "Whitelist",
"consentOptinMethod": "TCO",
"consentOptinDuration": "ONE",
"consentOptinId": "XXXXXX",
"consentOptinTimestamp": "2019-09-18T00:13:37.667Z",
“consentOptinUrl” : “www.example.com”. // optional field
}'
```
:::
::::
### Request Body Parameters
| **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. |
| phoneNumber | string | true | The phone number being queried.
Formats Accepted :-
1XXXXXXXXXX
+1XXXXXXXXXX |
| countryCode | string | true | The country code associated with the phone number.
Only US should be passed here.
We also have Canada (CA) in the roadmap. |
| consentOptinType | string | true | The type of opt-in.
Value should be "whitelist" here. |
| consentOptinMethod | string | true | The method used to collect consent:
• TCO – online T\&C’s
• MA – mobile app
• TCP – paper T\&C’s
• IVR – via IVR
• SMS – text
• OTHER
|
| consentOptinDuration | string | true | Indicates if consent is for single use or ongoing:
• ONE – single use
• ONG – ongoing
|
| consentOptinId | string | true | A unique identifier for tracking the consumer’s opt-in. |
| consentOptinTimestamp | string | true | Date/time when consent was obtained (ISO-8601 UTC format)
Example Format - \{2025-03-18T00:13:37.667Z} |
| consentOptinUrl | string | false | URL where the consumer provided consent (one-time) or URL of T\&C/Privacy Policy (ongoing). |
### Sample Response
:::CodeblockTabs
Response
```json
{
"result": {
"requestId": "F4C0D35B-1A8E-437C-A140-922121B2CE7C",
"description": "SUCCESS",
"response": {
"phoneNumber": "XXXXXXXXX",
"lineType": "wireless",
"carrier": {
"name": "XXX",
"originalName": "XXXX XXX XXX",
"ocn": "XXXX"
},
"deactInfo": {
"lastDeactType": "",
"lastDeactDate": "",
"lastCarrierName": ""
},
"portingInfo": {
"ported": "false",
"tenure": {
"minDays": "",
"maxDays": ""
},
"lastCarrier": {
"name": "",
"originalName": ""
}
},
"countryCode": "US",
"score": 1000
}
},
"reason": "Request Successful",
"code": "S001"
}
```
:::
### Response Body Parameters
| **Key** | **Type** | **Description** |
| ------------------------------------ | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| requestId | string | The requestId from the request, reflected back for tracking purposes. |
| description | string | A text string that defines the cause of the status code.
It can be SUCCESS or
PARTIAL\_SUCCESS |
| **response** | object | The response object containing trust score details. |
| phoneNumber | string | The phone number associated with the subscriber. |
| lineType | string | Line type associated with the phone number.
Possible values are:
wireless, landline, non-fixed voip, fixed voip |
| carrier.name | string | Standardized short name of the carrier (e.g., ATT, VZW) |
| carrier.originalName | string | Full carrier name from the previous API |
| carrier.ocn | string | Operating Company Number – unique identifier for telecom carriers |
| deactInfo.lastDeactType | string | Indicates whether the number was deactivated
or swapped. Mobile phones only
Possible values:
DEACT – Deactivated
SWAP – Swapped
Mobile phones only
|
| deactInfo.lastDeactDate | string | The date that the phone number was last
deactivated.
Mobile phones only |
| deactInfo.lastCarrierName | string | The name of the previous carrier.
Mobile phones only
|
| portingInfo.ported | string (true / false) | Indicates whether the phone number has been
ported from another carrier.
All phone types
Possible values: true, false |
| portingInfo.tenure.minDays | string | The minimum number of days since the number
has been ported.
All phone types, All carriers |
| portingInfo.tenure.maxDays | string | The maximum number of days since the number
has been ported.
All phone types, All carriers |
| portingInfo.lastCarrier.name | string | Standardized name of the last carrier before porting |
| portingInfo.lastCarrier.originalName | string | Full name of the last carrier before porting |
| countryCode | string | Country code of the phone number (e.g., US) |
| score | integer | Trust score metric (e.g., 1000 is highest trust level)
It ranges between 0 to 1000. |
### Sample Error
:::CodeblockTabs
E601 Internal Server Error
```json
{
"result": {},
"reason": "Internal Server Error",
"status": "failure",
"code": "E601"
}
```
E001 Invalid regex
```json
{
"result": {},
"status": "failure",
"reason": "Bad Request: \"consentStatus\" must be one of [optedIn, optedOut, notCollected, unknown]",
"code": "E001"
}
-----
{
"result": {},
"reason": "Bad Request: \"phoneNumber\" must start with +1 or 1 and be followed by exactly 10 digits.",
"code": "E001"
}
-----
{
"result": {},
"status": "failure",
"reason": "Bad Request: \"countryCode\" must be one of [US, CA]",
"code": "E001"
}
-----
{
"result": {},
"reason": "Bad Request: \"consentOptinType\" is not valid.",
"code": "E001"
}
```
E001 Empty Required field
```json
{
"result": {},
"status": "failure",
"reason": "Bad Request: \"phoneNumber\" is not allowed to be empty",
"code": "E001"
}
```
E401 Upstream Failure
```json
{
"result": {},
"reason": "Upstream error",
"status": "failure",
"code": "E401"
}
```
E001 Invalid Phone number
```curl
// regex passed but phone number is invalid
{
"result": {},
"reason": "Bad Request: \"phoneNumber\" entered is invalid",
"code": "E001"
}
```
:::
### Error Response Parameters
| **Parameter** | **Description** |
| ------------- | ---------------------- |
| result | Empty result object |
| reason | Reason for error |
| status | Status of the api |
| code | Error code from Signzy |
### Error Codes
| HTTP Status Code | Error Code | Description |
| ---------------- | ---------- | --------------------- |
| 400 | E001 | Bad Request |
| 401 | E1001 | Unauthorized Access |
| 403 | E201 | Forbidden |
| 409 | E401 | Upstream error |
| 429 | E501 | Rate Limit Exceeded |
| 500 | E601 | Internal Server Error |
| 503 | E701 | Service Unavailable |
| 504 | E801 | Timeout |
### Success Codes
| HTTP Status Code | Success Code | Description |
| ---------------- | ------------ | ------------------- |
| 200 | S001 | Request Successful. |
:::hint{type="info"}
### 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 [help@signzy.com](#). 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!
:::