Nexmo Verify API

Name: Verify API
Brand: Verify API
Availability: InStock

★ Only Publicly Available OpenAPI DocumentIdentity AuthAuthenticationapiKey6 EndpointsREST

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

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.

Use for: I need to verify a user's phone number with a PIN code, Send a 2FA challenge for a high-value account login, Check whether the code a user typed matches the Verify request, Cancel a Verify request that the user abandoned

Not supported: Does not store user identities, manage sessions, or send arbitrary SMS content - use for phone-channel 2FA, OTP delivery, and PSD2 SCA prompts only.

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 your Jentic One instance.

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

Your Vonage api_key and api_secret are stored once, encrypted, by your own Jentic One instance and injected as request parameters at execution time. They never enter the agent's prompt, logs, or context.

Intent-based discovery

Agents search Jentic by intent such as 'verify a phone number with a PIN' and Jentic returns the POST /{format} operation alongside the matching check operation with their input schemas so the agent assembles the 2FA flow without browsing the reference docs.

Time to first call

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 with Jentic One, the self-hosted execution layer.

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 your Jentic One instance 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. Run it through Jentic One, the self-hosted execution layer.

Can I limit what my agent is allowed to do with the Vonage Verify API?

Yes. Jentic One is self-hosted by you, so your own rules decide which Verify operations and credentials the agent can use. You can allow only starting a verification with POST /{format} and validating the code with POST /check/{format}, while keeping the control, search, PSD2, and network-unblock operations out of the agent's allowed set. Because the target phone number travels in the request body rather than the URL path, you scope access at the operation level, and your api_key and api_secret stay in your instance and are injected at execution time.

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