Nexmo Verify API
Browse all Nexmo APIs★ 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.
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.
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.
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.
1
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 | sh2
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 instanceJentic 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
Search the status and history of a Verify request to surface delivery, attempts, and final outcome
Run PSD2 Strong Customer Authentication flows for payment confirmation with payee and amount included in the prompt
Request a network unblock so a phone number that has been throttled by the carrier can receive Verify traffic again
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
POST
/network-unblock
Request a network unblock for a throttled number
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.
Related APIs
Alternatives and complements available in the Jentic catalogue.
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.
GET STARTED