Migrating from Number Verification API to Verify Silent Auth

This guide explains how to migrate from a silent authentication flow using the Network Enablement API and Number Verification API to the unified Verify API with Silent Authentication.

The Verify API supports both synchronous and asynchronous implementations of Silent Authentication. This guide follows the asynchronous flow, which is the recommended method for integrating Silent Authentication.

Legacy and New Architecture Comparison

Before you begin the migration, please review the sections below to understand the differences between the legacy and new architectures.

Legacy Architecture: Network Enablement and Number Verification

In the current setup, silent authentication requires coordinating two separate APIs. First, the Network Enablement API is called to check if the user’s network and device context support silent authentication. If supported, the Number Verification API is then used to perform the actual silent mobile identity verification.

This approach has some limitations:

• There's no built-in fallback if silent verification isn’t supported.
• Developers must manually orchestrate both APIs.
• Error and retry logic needs to be implemented on the client side.

New Architecture: Verify with Silent Authentication

The new architecture replaces the two-step approach with a single integration using the Verify API with Silent Authentication. This unified approach reduces complexity, supports fallback channels (like SMS, voice, WhatsApp, or email) when silent verification isn’t possible, and handles webhook callbacks automatically.

Main differences

The table below shows the main differences between the legacy and new approach:

Migration Steps

Follow the steps below to migrate from Network Enablement and Number Verification API to Verify API with Silent Authentication:

Step 1: Update your Application Settings

Step 2: Replace the Legacy Flow with Verify API

Step 3: Update Authentication Method

Step 4: Update the Request Structure

Step 5: Pass the check_url to the Mobile App

Step 6: Handle the action_pending Callback

Step 7: Mobile App Follows Redirects and Receives Code

Step 8: Validate the Verification Code

Step 9: Handle the Summary Callback

Update your Application Settings

In the Vonage Application Dashboard, open your application's settings. Under Capabilities > Network Registry, update the Verify event status callback with the URL where your backend will receive webhook events (e.g., action_pending, completed).

Replace the Legacy Flow with Verify API

Once the mobile app triggers the authentication, your backend must start the authentication flow:

Legacy flow:

1. Call Network Enablement API.
2. If the network is supported, call the Number Verification API for a coverage check.

New flow:

1. Call the Verify API using the silent_auth workflow.
2. If silent verification fails, a fallback channel (e.g., SMS, voice, WhatsApp, or email) is triggered automatically if defined in the workflow (see Update the Request Structure).

Update Authentication Method

The Verify API supports two authentication methods: Basic Authentication and JWT (Bearer Token). Refer to the Verify Authentication Guide for details on when to use each method and how to generate the credentials.

Update the Request Structure

Verify API uses a workflow array to define the sequence of verification channels. Silent Authentication must be the first step in the workflow as shown in the following example:

{
  "brand": "ACME",
  "workflow": [
    {
      "channel": "silent_auth",
      "to": "447700900000",
    },
    {
      "channel": "sms",
      "to": "447700900000"
    }
  ]
}   

Pass the check_url to the Mobile App

After calling the Verify API, you'll receive a synchronous response similar to this example:

{
  "request_id": "c11236f4-00bf-4b89-84ba-88b25df97315",
  "check_url": "https://api.nexmo.com/v2/verify/c11236f4.../silent-auth/redirect"
}   

The response includes the check_url parameter, which is similar to the auth_url used in Number Verification. The mobile app must perform an HTTP

You may also receive the same check_url later in an event callback (see Pass the check_url to the Mobile App), so you can pass it to the app from either source, depending on your implementation.

Handle the action_pending Callback

Shortly after the request, Vonage sends an event callback to your webhook URL defined in Updating your Application Settings.

{
  "request_id": "...",
  "type": "event",
  "channel": "silent_auth",
  "status": "action_pending",
  "action": {
    "type": "check",
    "check_url": "https://eu.api.silent.auth/..."
  }
}   

You can use the check_url from either the initial API response (Update the Request Structure) or this callback to launch silent auth in the app.

Mobile App Follows Redirects and Receives Code

The mobile app performs a GET request to the check_url. It will follow one or more HTTP 302 redirects and finally receive a response:

{
  "request_id": "...",
  "code": "si9sfG"
}   

If successful, this code must be validated in the next step.

Validate the Verification Code

Send a POST request from the mobile app to the Verify API to validate the code:

POST https://api.nexmo.com/v2/verify/{request_id}
Authorization: Bearer {access_token}
Content-Type: application/json  

With the following body:

{
  "code": "si9sfG"
}   

If everything goes well, the response from the backend will be similar to this example:

{
  "request_id": "...",
  "status": "completed"
}   

Handle the Summary Callback

Once verification is complete, Vonage sends a final callback to your webhook:

{
  "request_id": "...",
  "type": "event",
  "channel": "silent_auth",
  "status": "completed"
}   

This confirms the verification flow has finished.

Next steps

• Test your integration in a sandbox environment. Use test numbers and the Developer Dashboard to validate both silent and fallback scenarios.
• Check our Silent Authentication Best Practices Guide.
• Monitor webhook events. Ensure your backend is correctly handling status callbacks (e.g., action_pending, completed, failed).

For more details, refer to the Verify API documentation.