Phone Verification API

Request temporary phone numbers and retrieve OTP codes for automated verification flows.

Phone verification is backed by TextVerified. Each verification provides a real non-VoIP US mobile number that receives SMS. Designed for AI agents doing browser automation that hit "verify your phone" walls.

Services

List Services

GET /api/verifications/services

Returns available verification services (Google, Facebook, etc.) with their capabilities.

curl https://api.trunx.ai/api/verifications/services \
  -H "Authorization: Bearer tk_live_..."

const res = await fetch("https://api.trunx.ai/api/verifications/services", {
  headers: { "Authorization": "Bearer tk_live_..." },
});
const { services } = await res.json();

import requests

res = requests.get(
    "https://api.trunx.ai/api/verifications/services",
    headers={"Authorization": "Bearer tk_live_..."},
)
services = res.json()["services"]

Response

{
  "services": [
    {
      "serviceName": "google",
      "description": "Google",
      "capability": "Sms"
    },
    {
      "serviceName": "facebook",
      "description": "Facebook",
      "capability": "Sms"
    }
  ]
}

Verifications

Create Verification

POST /api/verifications

Request a temporary phone number for a target service.

Field	Type	Required	Description
`serviceName`	string	Yes	Target service (from list services, e.g. `google`)
`areaCode`	string	No	Preferred US area code

curl -X POST https://api.trunx.ai/api/verifications \
  -H "Authorization: Bearer tk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "serviceName": "google"
  }'

const res = await fetch("https://api.trunx.ai/api/verifications", {
  method: "POST",
  headers: {
    "Authorization": "Bearer tk_live_...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ serviceName: "google" }),
});
const verification = await res.json();
// Use verification.number for the phone verification prompt

res = requests.post(
    "https://api.trunx.ai/api/verifications",
    headers={"Authorization": "Bearer tk_live_..."},
    json={"serviceName": "google"},
)
verification = res.json()
# Use verification["number"] for the phone verification prompt

Response (201)

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "providerVerificationId": "tv_abc123",
  "serviceName": "google",
  "number": "+17755551234",
  "status": "active",
  "cost": "0.5000"
}

Get Verification

GET /api/verifications/{id}

Get verification status, assigned number, and OTP if already received.

{
  "id": "a1b2c3d4-...",
  "serviceName": "google",
  "number": "+17755551234",
  "status": "completed",
  "smsContent": "G-123456 is your Google verification code.",
  "otpCode": "123456",
  "cost": "0.5000",
  "createdAt": "2026-03-18T12:00:00.000Z"
}

Poll for OTP Code

GET /api/verifications/{id}/code

Polls the provider for incoming SMS up to 3 times with 5-second intervals (15 seconds max server-side wait). If no code is received, returns { "status": "pending" } — retry after a few seconds.

curl https://api.trunx.ai/api/verifications/$VERIFICATION_ID/code \
  -H "Authorization: Bearer tk_live_..."

const res = await fetch(`https://api.trunx.ai/api/verifications/${id}/code`, {
  headers: { "Authorization": "Bearer tk_live_..." },
});
const { status, otpCode, smsContent } = await res.json();

if (status === "completed") {
  console.log("OTP:", otpCode);
} else {
  // Retry after a few seconds
}

res = requests.get(
    f"https://api.trunx.ai/api/verifications/{verification_id}/code",
    headers={"Authorization": "Bearer tk_live_..."},
)
data = res.json()

if data["status"] == "completed":
    print("OTP:", data["otpCode"])
else:
    # Retry after a few seconds
    pass

Response (code received)

{
  "status": "completed",
  "otpCode": "123456",
  "smsContent": "G-123456 is your Google verification code."
}

Response (still waiting)

{
  "status": "pending"
}

The OTP is automatically extracted from the SMS using pattern matching (explicit prefixes like "code is 123456", Google-style "G-123456", or standalone digit sequences). The raw smsContent is also returned if you need to parse it yourself.

Cancel Verification

POST /api/verifications/{id}/cancel

Cancel an active verification and release the number.

curl -X POST https://api.trunx.ai/api/verifications/$VERIFICATION_ID/cancel \
  -H "Authorization: Bearer tk_live_..."

Response

{
  "id": "a1b2c3d4-...",
  "status": "cancelled"
}

MCP Tools

Four MCP tools are available for AI agents:

Tool	Description
`verify_list_services`	List available verification services
`verify_get_number`	Request a temp number for a service
`verify_get_code`	Poll for OTP (15s server-side wait)
`verify_cancel`	Cancel and release a verification

See MCP for connection details.

Events

Event	Description
`verification.created`	New verification requested
`verification.code_received`	OTP code extracted from SMS
`verification.cancelled`	Verification cancelled

Billing

Each completed verification (code received) reports a verification.create usage event for metered billing.

Phone Verification API

On this page