Trust Score

9 min

Introduction

The "Get Trust Score" API allows you to obtain the trust score for a given phone number, based on the provided consent status. This trust score can be used by your application to make informed decisions, such as whether to proceed with prefilling data or not. By integrating this API into your system, you can enhance your risk assessment processes and ensure compliance with KYC requirements.

How to call the API

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.

API Input Guidelines

To make a successful request to the "Get Trust Score" API, utilize the following request data structure:

Sample cURL

Pre-Production

curl --location 'https://api-preproduction.signzy.app/api/v3/us-kyc/trust-score' \
--header 'Content-Type: application/json' \
--header 'Authorization: <Auth Token>' \
--data '{
  "requestId": "646214d929c23b4d42352a60",
  "consentStatus": "optedIn",
  "phoneNumber": "2001001686",
  "details": "true"
}'

Input Parameters

Key	Type	Mandatory	Description
requestId	string	true	The unique ID of the request.
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	A phoneNumber or payfoneAlias is required in the request, not both.	The phone number to check for trust.
payfoneAlias	string	A phoneNumber or payfoneAlias is required in the request, not both.	A persistent ID that uniquely identifies a telephone subscriber.
details	String	false	Specifies whether to include additional details in the response. Input is "true" or "false"
subscriptionCustomerId	string	false	A unique identifier for our customer's subscribers for Identity Manager.

Response Parameter

Key	Type	Description
requestId	string	The requestId from the request, reflected back for tracking purposes.
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 Only returns if consentStatus=optedIn, details=true
phoneNumberVelocity	integer	The number of times the subscriber has changed their phone number. Only returns if details=true
portVelocity	integer	The number of times the subscriber has changed their carrier within the last 90 days. Only returns if details=true
simVelocity	integer	The number of times the mobile subscriber has changed their device within the last 90 days. Only returns if consentStatus=optedIn, details=true
deviceVelocity	integer	The number of times the mobile subscriber has changed their device within the last 90 days. Only returns if consentStatus=optedIn, details=true
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
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
maximumDate	date-time	Carrier Tenure Object
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
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
maximumDate	date-time	Sim Tenure Object
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
maximumDate	date-time	Device Tenure Object
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
maximumDate	date-time	Ported Date Object

Sample Response

{
    "result": {
        "requestId": "646214d929c23b4d42352a60",
        "status": 0,
        "description": "Success.",
        "response": {
            "transactionId": "12225155409",
            "payfoneAlias": "FBE3C38C4VKRKKXD2EE57673DBEB1BA090MEK1KQZ3T9P8F8EDD8A266860A68A7562DE5FB1D4C17F1F6G34B5868E80AF64727A78421D8B8805086FEBE",
            "phoneNumber": "19177253169",
            "lineType": "Mobile",
            "carrier": "T-Mobile USA",
            "countryCode": "US",
            "statusIndex": "51",
            "isBaselined": true,
            "trustScore": 555,
            "reasonCodes": [
                "CU",
                "PT",
                "DR",
                "SR"
            ],
            "carrierStatus": "UNKNOWN",
            "phoneNumberVelocity": 0,
            "portVelocity": 1,
            "simVelocity": 0,
            "deviceVelocity": 0,
            "payfoneTenure": {
                "minimumDate": "2022-05-18T23:59:59.000Z"
            },
            "carrierTenure": {
                "minimumDate": "2023-05-18T23:59:59.000Z",
                "maximumDate": "2023-05-18T00:00:00.000Z"
            },
            "phoneNumberTenure": {
                "minimumDate": "2022-05-18T23:59:59.000Z"
            },
            "simTenure": {
                "minimumDate": "2023-05-18T23:59:59.000Z",
                "maximumDate": "2023-05-18T00:00:00.000Z"
            },
            "deviceTenure": {
                "minimumDate": "2023-05-18T23:59:59.000Z",
                "maximumDate": "2023-05-18T00:00:00.000Z"
            },
            "portedDate": {
                "minimumDate": "2023-05-18T16:33:00.000Z",
                "maximumDate": "2023-05-18T16:33:00.000Z"
            }
        }
    }
}

Sample Error

{
    "error": {
        "name": "error",
        "message": "..message..",
        "status": 400,
        "reason": "BadRequest",
        "type": "OK",
        "statusCode": 200
    }
}

Response Parameter

PARAMETER NAME	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].