Subscriber Tenure [Developer Preview]

Subscriber Tenure allows for verification that a network subscriber has been a customer of the mobile operator for a specified minimum length of time so as to establish a level of trust for the associated network subscription identifier.

It is designed for businesses and service providers that need to verify user identities online — particularly those in financial services, fintech, e-commerce, or telecommunications — who want to reduce fraud and improve decision-making confidence.

Amongst the most common use cases where Subscriber Tenure can bring benefit, there are:

• Strengthen Identity Verification and Onboarding: Businesses can use Subscriber Tenure to assess the reliability of a user’s mobile identity during onboarding or KYC verification. A long phone number tenure increases confidence that the user’s identity is genuine, complementing other checks such as document verification or subscriber match. This helps reduce onboarding fraud and improves trust in digital identity validation.
• Improve Authentication Confidence: The API supports mobile phone authenticators such as Number Verification or One-Time Password (OTP) SMS by adding a trust factor based on phone number tenure. When a number has been active for a long period, it can be prioritized or weighted more heavily in risk scoring models, while recently activated numbers may trigger step-up authentication.
• Enhance Fraud Detection and Risk Scoring: Fraud prevention systems can use tenure data to identify newly activated or short-lived phone numbers that may indicate synthetic identities or high-risk activity. This enables early detection of potential fraud before it affects transactions, account changes, or other sensitive operations.
• Support Financial Services Risk Assessment: Banks and financial institutions can integrate tenure checks into their lending and payment workflows. By evaluating how long a user has maintained their phone number, they gain an additional indicator of credibility and stability, helping to reduce the likelihood of identity fraud or false applications.

Prerequisites

To use Identity Insights, you must ensure your account is configured correctly; see the Getting Started guide for more information on:

• Creating your account,
• Creating a Vonage application for use with the Identity Insights API,
• The different environments available and how to configure your account to use them,
• And how to use the Dashboard Getting Started UI to use the API without writing any code.

This guide will explain how to use the Subscriber Tenure Insight programmatically using cURL.

Making an API Call

Authentication for the Identity Insights API is done via JWTs, a compact and self-contained JSON token. To generate a JWT, you can use our online generator, or alternatively use the Vonage CLI. You will need your application ID and private key to generate the JWT. Once you have your JWT, you can send a request to the API.

This example shows a cURL request for the Subscriber Tenure insight, to check if the subscriber associated with the given phone number has kept association with the same carrier for the whole period monitored; the start of the monitored period is defined by the date parameter:

curl -X POST https://api-eu.vonage.com/identity-insights/v1/requests  \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "14040000000",
    "purpose": "FraudPreventionAndDetection",
    "insights": {
        	"subscriber_tenure": {
          "date": "2023-07-03"
          }
        }
    }'

The API will then fetch the tenure information associated with the particular mobile phone number and validate it against the date provided in the request:

{
    "request_id": "f41087de-b9fc-4081-ab85-9d6475a19706",
    "insights": {
        "subscriber_tenure": {
            "is_tenure_met": true,
            "contract_type": "PREPAID",
            "status": {
                "code": "OK",
                "message": "Success"
            }
        }
    }
}

Here, the status object indicates the status of the information returned for the specified phone number:

If status.code in the response is OK, you may also see the fields described in the table below. If a field is marked as 'Yes' in the 'Mandatory' column, it will always be returned when the status is OK. If a field is marked as 'No', it may or may not be returned.

Further Reading

• Read more about the Identity Insights API in the API Reference.
• If you have any questions, you can reach out to us on the Vonage Community Slack.