Number Recycling [Developer Preview]

Phone numbers are not permanently tied to a person. When a subscriber cancels a mobile contract for a specific phone number without porting it to another carrier, the mobile operator will eventually reclaim the number and make it available again. This process is known as number recycling.

Number Recycling has two main triggering events:

• Deactivation: The number is removed from its current subscriber and is no longer assigned to anyone. After deactivation, the number is moved to “quarantine”.
• Reassignment: A deactivated number is given to a completely different subscriber.

Once a number is deactivated, operators don't immediately reassign it. They hold it in a temporary "quarantine" window before it can be reused. This helps prevent a new subscriber from accidentally receiving calls or messages meant for the previous owner.

How long this period lasts varies. It can be defined by local regulation or by the operator's own policies. In the United States, for example, the Federal Communications Commission (FCC) requires operators to wait at least 45 days before reassigning a deactivated number.

The Number Recycling API lets you verify whether a phone number has changed ownership since a date you specify. You provide:

• A phone number to check.
• A reference date — typically the date you last confirmed this number belonged to your user (for example, their account registration date).

The API responds with a is_number_recycled field as true when the phone number has been deactivated (it is no longer assigned to any subscriber) or reassigned to a different subscriber after the specified date. It will return false when no change in ownership has been detected after the specified date.

This also covers the quarantine window: if the number was deactivated but not yet reassigned during the timeframe you queried, the response is still true, since the number is no longer with the former subscriber.

These are some of the most common use cases where Number recycling can bring benefit:

Strengthen Identity Verification and Onboarding: When a new customer attempts to sign up with a recycled number, the system can query the API to verify a change in ownership since account creation; if confirmed, it automatically triggers a "clean-slate" workflow that de-links the MSISDN from the previous owner's obsolete profile. This eliminates manual support tickets, prevents identity overlap, and ensures the new user can register without friction or rejection.

Preventive Account Takeover defense: The use of the Number Recycling API serves as a pre-authentication step for high-risk events like password resets or 2FA enrollment. By validating ownership continuity since a specific reference date (e.g., the last successful login), the platform can programmatically block SMS-based recovery attempts if the number has been recycled, closing the security gap where bad actors exploit reissued SIMs to hijack dormant accounts, moving from reactive fraud detection to proactive prevention.

Communications privacy and compliance: Integrating Number Recycling into automated notification systems ensures that sensitive or regulated communications—such as banking alerts or medical reminders—are never delivered to a recycled number's new owner. By performing a real-time ownership check before dispatch, the product ensures better adherence to privacy laws like GDPR and TCPA, and significantly lowers the risk of accidental data leaks.

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 Number Recycling 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 Number recycling insight to check if a subscriber associated with the give phone number is over age 18; this is defined by the age_threshold parameter, which can be set to anywhere between 0 and 120 years:

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": {
            "number_recycling": {
            "date": "2025-10-31"
            },
        }
    }'

The API will then fetch the number recycling information associated with the particular mobile phone number and validate if the latest change of ownership date was in the period queried in the request:

{
    "request_id": "f41087de-b9fc-4081-ab85-9d6475a19706",
    "insights": {
        "number_recycling": {
            "is_number_recycled": true,
            "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.