Overview
eKYC Platform
Face Authentication
Vision Score
Behavioral Biometric (BehavioIQ)
SIM Verification
Overview
API Docs
Mule Account Database
eKYC Core
Demo Apps
Download SDKs
Privacy Policy
FAQ

TrustVision API Documentation v1.0.0

SIM Verification API

SIM Verification confirms a customer's ownership of a phone number, and surfaces telco-held information about that SIM for verification purposes. The typical flow is an OTP round trip — send an OTP to the phone number, then verify the code the customer entered — plus a separate call to verify information about the SIM/phone number directly.

Sim verification send OTP

This service allows you to send OTP to a phone number.

1. Request

Method	Path	Content-Type	Auth Required
POST	`/v1/sim_verification_send_otp`	application/json	Yes

Request Body:

JSON

{
    "phone_number": string
}

Where

Name	Type	Required	Description
phone_number	string	Yes	Send OTP to this number.

Authentication mechanism is described in Authentication.

Sample Request

bash

curl -X POST \
https://tv-staging.trustingsocial.com/api/v1/sim_verification_send_otp \
-H 'Authorization: TV <YOUR ACCESS KEY>:<CREATED SIGNATURE>' \
-H 'X-TV-Timestamp: 2019-04-21T18:00:15+07:00' \
-H 'Content-Type: application/json' \
-d \
'
{
   "phone_number": "0909123456"
}
'

2. Response

The response will be a JSON with following format:

javascript

{
    "data": {
        "status": string, // "success" or "failure"
        "phone_number": string,
        "request_id": string // return request id to the client and can use request-id to check logs.
        "telco": string, // vnpt, viettel or mobifone
    },
    "errors": [
            {
                "code": string,
                "message": string,
                "detail": {
                    "field": string, // optional, which parameter is invalid.
                    ... // any other information that can be useful for client
                },
            },
            ... // other errors
        ]
}

In case the request processing has been finished, the HTTP status code will be

200, and the data.status is either "success" or "failure" depending on whether the request has been successfully processed or not.

If the `data.status` is `"failure"`, the `"errors"` field will tell you why it

failed.

error code	description
`failed_to_send_otp`	Failed to send the one-time password (OTP).
`invalid_otp_format`	The provided OTP has an invalid format.
`unsupported_telco`	The telecommunications provider is not supported.

In case of any other errors, the data field will be empty, and the server sends one of the following HTTP status codes with an error code:

HTTP code	error code	description
`401`	`access_denied_exception`	You are not authorized to perform the action.
`400`	`invalid_parameter_exception`	Input parameter violates a constraint.
`400`	`request_time_too_skewed`	The X-TV-Timestamp header is expired, need a newer one.
`408`	`request_timeout_exception`	Request takes too long to process
`429`	`rate_limit_exception`	The number of requests exceeded your throughput limit.
`500`	`internal_server_error`	Some unexpected error occurs while processing the request

Sample Response

JSON

{
    "data": {
        "status": "success",
        "phone_number": "0909123456",
        "request_id": "48ff3909-6402-4cde-a9d4-972b0f72969c",
        "telco": "vnpt"
    }
}

Sim verification verify OTP

This service allows you to verify OTP sent to phone.

1. Request

Method	Path	Content-Type	Auth Required
POST	`/v1/sim_verification_verify_otp`	application/json	Yes

Request Body:

JSON

{
    "phone_number": string,
    "otp": string
}

Where

Name	Type	Required	Description
phone_number	string	Yes	Verify OTP of this number.
otp	string	Yes	OTP sent by telco to phone number.

Authentication mechanism is described in Authentication.

Sample Request

bash

curl -X POST \
https://tv-staging.trustingsocial.com/api/v1/sim_verification_verify_otp \
-H 'Authorization: TV <YOUR ACCESS KEY>:<CREATED SIGNATURE>' \
-H 'X-TV-Timestamp: 2019-04-21T18:00:15+07:00' \
-H 'Content-Type: application/json' \
-d \
'
{
   "phone_number": "0909123456",
   "otp": "123456"
}
'

2. Response

The response will be a JSON with following format:

javascript

{
    "data": {
        "status": string, // "success" or "failure"
        "phone_number": string,
        "request_id": string // return request id to the client and can use request-id to check logs.
    },
    "errors": [
            {
                "code": string,
                "message": string,
                "detail": {
                    "field": string, // optional, which parameter is invalid.
                    ... // any other information that can be useful for client
                },
            },
            ... // other errors
        ]
}

In case the request processing has been finished, the HTTP status code will be

200, and the data.status is either "success" or "failure" depending on whether the request has been successfully processed or not.

If the `data.status` is `"failure"`, the `"errors"` field will tell you why it

failed.

error code	description
`incorrect_otp`	The provided OTP is incorrect.
`otp_expired`	The one-time password (OTP) has expired.
`otp_already_used`	The one-time password (OTP) has already been used.
`failed_to_verify_otp`	Failed to verify the one-time password (OTP).

In case of any other errors, the data field will be empty, and the server sends one of the following HTTP status codes with an error code:

HTTP code	error code	description
`401`	`access_denied_exception`	You are not authorized to perform the action.
`400`	`invalid_parameter_exception`	Input parameter violates a constraint.
`400`	`request_time_too_skewed`	The X-TV-Timestamp header is expired, need a newer one.
`408`	`request_timeout_exception`	Request takes too long to process
`429`	`rate_limit_exception`	The number of requests exceeded your throughput limit.
`500`	`internal_server_error`	Some unexpected error occurs while processing the request

Sample Response

JSON

{
    "data": {
        "status": "success",
        "phone_number": "0909123456",
        "request_id": "48ff3909-6402-4cde-a9d4-972b0f72969c",
    }
}

Sim verification verify information

This service allows you to verify information of sim owner.

1. Request

Method	Path	Content-Type	Auth Required
POST	`/v1/sim_verification_verify_info`	application/json	Yes

Request Body:

JSON

{
    "phone_number": string,
    "fields": [
      {
        "name": "field_name",
        "value": "value of this field"
      },
      ...
    ]
}

Where

Name	Type	Required	Description
phone_number	string	Yes	Verify information of this number.
fields	array	Yes	List field name and value need to check.

Which each field's parameters contains:

Name	Type	Required	Description
`name`	string	Yes	name of field data need to verify.
`value`	string	Yes	value of field need to check same or not.

List supported fields

name	value	description
`is_id`	eg. `079012123456`	id number of CCCD.
`is_name`	eg. `Nguyễn Văn A`	name of CCCD.
`is_dob`	eg. `01/01/1980`	date of birth of sim owner, format `dd/MM/yyyy`
`is_issue_date`	eg. `01/01/2025`	issue date of CCCD, format `dd/MM/yyyy`
`is_port_out`	no required value	is subscriber port out or not
`is_port_in`	no required value	is subscriber port in or not
`is_active_last_90`	no required value	is subscriber active in 90 days or not
`is_subscriber_active`	no required value	is subscriber active or not
`has_usage_last_90`	no required value	is subscriber has usage last 90 days or not
`has_changed_device_last_30`	no required value	is subscriber has change device last 30 days or not
`is_use_cf_service`	no required value	is subscriber use cf service or not
`has_changed_id_last_30`	no required value	is subscriber change ID Number in last 30 days or not
`is_top_20_contact_last_30`	eg. `0909112233`	is `phone_number` in top 20 contact last 30 days

Authentication mechanism is described in Authentication.

Sample Request

bash

curl -X POST \
https://tv-staging.trustingsocial.com/api/v1/sim_verification_verify_info \
-H 'Authorization: TV <YOUR ACCESS KEY>:<CREATED SIGNATURE>' \
-H 'X-TV-Timestamp: 2019-04-21T18:00:15+07:00' \
-H 'Content-Type: application/json' \
-d \
'
{
   "phone_number": "0909123456",
   "fields": [
      {
        "name": "is_id",
        "value": "079012123456",
      },
      {
        "name": "is_name",
        "value": "Nguyễn Văn A",
      }
   ]
}
'

2. Response

The response will be a JSON with following format:

javascript

{
    "data": {
        "status": string, // "success" or "failure"
        "phone_number": string,
        "request_id": string // return request id to the client and can use request-id to check logs.
        "fields": [
          {
            "name": string,  // field name to check
            "value": string, // value of field name to check
            "verdict": string, // "matched|unmatched|no_data" return verdict of value same with sim owner information in telco or not
          }
          ...
        ]
    },
    "errors": [
            {
                "code": string,
                "message": string,
                "detail": {
                    "field": string, // optional, which parameter is invalid.
                    ... // any other information that can be useful for client
                },
            },
            ... // other errors
        ]
}

In case the request processing has been finished, the HTTP status code will be

200, and the data.status is either "success" or "failure" depending on whether the request has been successfully processed or not.

If the `data.status` is `"failure"`, the `"errors"` field will tell you why it

failed.

error code	description
`invalid_phone_number`	The provided phone number is invalid.
`verification_session_expired`	The verification session has expired.
`failed_to_verify_info`	Failed to verify the information.

In case of any other errors, the data field will be empty, and the server sends one of the following HTTP status codes with an error code:

HTTP code	error code	description
`401`	`access_denied_exception`	You are not authorized to perform the action.
`400`	`invalid_parameter_exception`	Input parameter violates a constraint.
`400`	`request_time_too_skewed`	The X-TV-Timestamp header is expired, need a newer one.
`408`	`request_timeout_exception`	Request takes too long to process
`429`	`rate_limit_exception`	The number of requests exceeded your throughput limit.
`500`	`internal_server_error`	Some unexpected error occurs while processing the request

Sample Response

JSON

{
    "data": {
        "status": "success",
        "phone_number": "0909123456",
        "request_id": "48ff3909-6402-4cde-a9d4-972b0f72969c",
         "fields": [
          {
            "name": "is_id",
            "value": "079012123456",
            "verdict": "matched"
          },
          {
            "name": "is_name",
            "value": "Nguyễn Văn A",
            "verdict": "unmatched"
          }
        ]
    }
}

.css-9x8bsw{-webkit-text-decoration:none;text-decoration:none;}.css-9x8bsw:hover{-webkit-text-decoration:underline;text-decoration:underline;}SIM Verification API

SIM Verification API