Nexmo Verify API

Name: Verify API
Brand: Verify API
Availability: InStock

★ Only Publicly Available OpenAPI DocumentIdentity AuthAuthenticationapiKey6 EndpointsREST

For Agents

Run a 2FA verification flow by sending a PIN to a phone number, validating the user-entered code, and managing the request lifecycle without generating PINs in the application.

Install Jentic One Beta

Connect the Verify API to your agent

Jentic One is a self-hosted execution layer for AI agents. It lets your agent call the Verify API, or any other public or private API you need. You set the rules, the agent never sees your credentials, and every call is logged.

Two steps, two machines. Install the instance in a safe environment, then register your agent from wherever it runs.

Step 1: Jentic One Host machine

# On the machine that will host your Jentic One instance:
curl -fsSL https://raw.githubusercontent.com/jentic/jentic-one/main/tools/install.sh | sh

Step 2: Agent machine

# On the machine where your agent runs (keep this separate from the instance):
curl -fsSL https://raw.githubusercontent.com/jentic/jentic-one/main/tools/install.sh | sh
jentic register       # connects your agent to your Jentic One instance

Jentic One is in public beta. The setup above keeps your agent separate from the instance, which is what you want before using real credentials: an agent running as the same OS user as Jentic One can read its stored keys directly. Just evaluating? A single local install is fine to start. See the secure deployment guide for the tiers.

Capabilities

What an agent can do with Verify API.

Initiate a 2FA verification by sending a PIN to a phone number with SMS-first delivery and voice fallback

Validate a user-entered PIN against an in-flight Verify request and receive a status code on success or failure

Cancel an in-progress verification or trigger the next workflow step via the Verify Control endpoint

GET STARTED

Start building with Verify API

Explore with Jentic

View OpenAPI Document

Jentic publishes the only available OpenAPI specification for Verify API, keeping it validated and agent-ready. The Vonage Verify API runs end-to-end two-factor authentication flows by sending a PIN to a phone number over SMS, falling back to TTS voice if the SMS is not entered, and validating the user-entered code. The 6 endpoints cover request, check, search, control, network unblock, and the PSD2 Strong Customer Authentication variant for payment confirmation. Vonage manages PIN generation, retry workflow, and per-recipient throttling so the application only handles request and check.

Use Cases

Patterns agents use Verify API for, with concrete tasks.

★ User Sign-Up Phone Verification

Confirm that a phone number provided during sign-up belongs to the user before allowing the account to be created. POST /{format} kicks off the verification, Vonage delivers the PIN by SMS and falls back to voice if the user does not enter the code, and POST /check/{format} validates the code returned by the user. The whole workflow runs from two API calls — Vonage handles PIN generation, retries, and timing.

POST /json with number=+15551234567, brand='Acme', and code_length=6 to start the verification, then POST /check/json with the request_id and the code the user entered

Step-Up Authentication for Sensitive Actions

Trigger a one-time PIN challenge before allowing a sensitive action such as changing a password, draining a wallet, or approving a wire. The Verify request returns a request_id that the application stores against the session, and POST /check/{format} confirms the PIN once the user supplies it. POST /control/{format} cancels the request if the user closes the prompt, freeing capacity and avoiding double-billing.

POST /json with the user's phone number, brand, and pin_expiry, then POST /control/json with cmd='cancel' if the session is abandoned before /check is called

PSD2 Payment Confirmation

Run Strong Customer Authentication for online payments under PSD2 by including the payee and amount in the verification prompt. POST /psd2/{format} generates the PIN with the regulated dynamic linking text, Vonage delivers it via SMS or voice, and POST /check/{format} validates the response. Combine with the Search endpoint to record evidence for audit.

POST /psd2/json with number, payee, amount, and currency to deliver an SCA-compliant prompt, then POST /check/json to validate the user's response

AI Agent 2FA Workflow

Through Jentic, an AI agent triggers and completes a verification flow without holding the Vonage api_key or api_secret. The agent searches Jentic with the intent 'verify a phone number with a PIN', loads the POST /{format} schema, and executes with the recipient and brand. The check, control, and search endpoints become subsequent Jentic calls, with credentials resolved from the MAXsystem vault.

Use Jentic search query 'verify a phone number with a PIN' to load POST /{format}, execute with number and brand, then chain POST /check/{format} with the user-entered code

Key Endpoints

6 endpoints — jentic publishes the only available openapi specification for verify api, keeping it validated and agent-ready.

METHOD

PATH

DESCRIPTION

POST

/{format}

Request a verification PIN for a phone number

POST

/check/{format}

Check a user-entered PIN against a request

POST

/control/{format}

Cancel or advance a verification request

GET

/search/{format}

Search the status of a verification request

POST

/psd2/{format}

Run a PSD2 Strong Customer Authentication request

POST

/network-unblock

Request a network unblock for a throttled number

POST

/{format}

Request a verification PIN for a phone number

POST

/check/{format}

Check a user-entered PIN against a request

POST

/control/{format}

Cancel or advance a verification request

GET

/search/{format}

Search the status of a verification request

POST

/psd2/{format}

Run a PSD2 Strong Customer Authentication request

Why Jentic?

Three things that make agents converge on Jentic-routed access.

Credential isolation

Vonage api_key and api_secret are stored encrypted in the Jentic MAXsystem vault. Jentic injects them as request parameters at execution time, so /verify, /check, and /control calls carry valid credentials without exposing the secret to the agent.

Intent-based discovery

Agents search Jentic with the intent 'verify a phone number with a PIN' and Jentic returns POST /{format} alongside the matching /check operation, so a 2FA flow can be assembled from two operations without browsing Vonage docs.

Time to first call

Direct Verify integration: 1-2 days to wire request, check, control, and search plus error handling on workflow events. Through Jentic: under 1 hour to search, load, and execute the request and check operations end-to-end.

FAQs

Specific to using Verify API through Jentic.

Why is there no official OpenAPI spec for Verify API?

Vonage does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Verify API via structured tooling. It is validated against the live API and kept up to date. Get started at https://app.jentic.com/sign-up.

What authentication does the Vonage Verify API use?

Verify is called with the Vonage api_key and api_secret as request parameters on POST /{format}, POST /check/{format}, and POST /control/{format}. Jentic stores both in the MAXsystem vault and injects them at execution time, so agents never see the raw secret.

Can I use Verify for PSD2 Strong Customer Authentication?

Yes. POST /psd2/{format} accepts payee and amount fields in addition to the recipient number, and Vonage formats the prompt to satisfy PSD2 dynamic-linking requirements. Validate the response with POST /check/{format} the same way as a standard verification.

How does Vonage handle SMS-to-voice fallback during a verification?

POST /{format} schedules SMS delivery first, then escalates to a TTS voice call if the user has not entered the PIN within the workflow window. The application only sees the request_id and the eventual /check result — Vonage controls the retry cadence and channel switching.

How do I cancel a verification that the user abandoned?

Call POST /control/{format} with the request_id and cmd='cancel'. This stops further delivery attempts on the workflow, releasing the throttle on the recipient number and ensuring the request is not billed beyond the deliveries already made.

How do I run a Vonage Verify flow through Jentic?

Run pip install jentic, then use the Jentic search query 'verify a phone number with a PIN' to load POST /{format}. Execute with number and brand, store the request_id, and chain POST /check/{format} with the code the user enters. Sign up at https://app.jentic.com/sign-up.

Nexmo Verify API

Connect the Verify API to your agent

Capabilities

Start building with Verify API

Use Cases

Key Endpoints

Why Jentic?

Related APIs

FAQs