Get Verification Status

Endpoint

GET /v1/verify/{verification_id}

Headers

Header	Required	Description
Authorization	yes	Bearer token: `Bearer tvx_sk_live_...`
X-Tenant-ID	yes	Your tenant ID: `acc_...`

Path parameters

Parameter	Type	Required	Description
verification_id	string	yes	The verification ID from the start response

Response

Success (200 OK)

{
  "data": {
    "verification_id": "ver_abc123",
    "to": "+919876543210",
    "channel": "sms",
    "status": "pending",
    "attempts": 1,
    "max_attempts": 5,
    "created_at": "2026-04-09T10:00:00Z",
    "expires_at": "2026-04-09T10:10:00Z"
  }
}

Response fields

Field	Type	Description
verification_id	string	Unique identifier for this verification
to	string	The phone number or email address
channel	string	Delivery channel: `sms`, `voice`, `whatsapp`, or `email`
status	string	Current status: `pending`, `approved`, `expired`, or `failed`
attempts	integer	Number of check attempts made so far
max_attempts	integer	Maximum allowed attempts (always 5)
created_at	string	ISO 8601 timestamp when verification was created
expires_at	string	ISO 8601 timestamp when code expires

Status values

Status	Description
`pending`	Awaiting verification check - user has not yet submitted the correct code
`approved`	Code successfully verified - verification complete
`expired`	10-minute time limit exceeded - verification can no longer be checked
`failed`	Maximum check attempts exceeded (5 wrong codes) - verification can no longer be checked

Examples

Get verification status

curl -X GET https://api.tryvox.io/v1/verify/ver_abc123 \
  -H "Authorization: Bearer tvx_sk_live_..." \
  -H "X-Tenant-ID: acc_123"

Pending verification (no attempts yet)

{
  "data": {
    "verification_id": "ver_abc123",
    "to": "+919876543210",
    "channel": "sms",
    "status": "pending",
    "attempts": 0,
    "max_attempts": 5,
    "created_at": "2026-04-09T10:00:00Z",
    "expires_at": "2026-04-09T10:10:00Z"
  }
}

Pending with failed attempts

{
  "data": {
    "verification_id": "ver_abc123",
    "to": "+919876543210",
    "channel": "sms",
    "status": "pending",
    "attempts": 3,
    "max_attempts": 5,
    "created_at": "2026-04-09T10:00:00Z",
    "expires_at": "2026-04-09T10:10:00Z"
  }
}

Approved verification

{
  "data": {
    "verification_id": "ver_abc123",
    "to": "+919876543210",
    "channel": "sms",
    "status": "approved",
    "attempts": 2,
    "max_attempts": 5,
    "created_at": "2026-04-09T10:00:00Z",
    "expires_at": "2026-04-09T10:10:00Z"
  }
}

Failed verification (max attempts)

{
  "data": {
    "verification_id": "ver_abc123",
    "to": "+919876543210",
    "channel": "sms",
    "status": "failed",
    "attempts": 5,
    "max_attempts": 5,
    "created_at": "2026-04-09T10:00:00Z",
    "expires_at": "2026-04-09T10:10:00Z"
  }
}

Expired verification

{
  "data": {
    "verification_id": "ver_abc123",
    "to": "+919876543210",
    "channel": "voice",
    "status": "expired",
    "attempts": 1,
    "max_attempts": 5,
    "created_at": "2026-04-09T10:00:00Z",
    "expires_at": "2026-04-09T10:10:00Z"
  }
}

Errors

NOT_FOUND (404)

The verification ID does not exist.

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Verification not found"
  }
}

Use cases

Display remaining attempts

Show users how many attempts they have left before the verification fails:

const response = await fetch(
  `https://api.tryvox.io/v1/verify/${verificationId}`,
  {
    headers: {
      "Authorization": "Bearer tvx_sk_live_...",
      "X-Tenant-ID": "acc_123"
    }
  }
);

const { data } = await response.json();
const remainingAttempts = data.max_attempts - data.attempts;

console.log(`You have ${remainingAttempts} attempts remaining`);

Check expiration time

Calculate time remaining before code expires:

const { data } = await response.json();
const expiresAt = new Date(data.expires_at);
const now = new Date();
const timeRemaining = Math.floor((expiresAt - now) / 1000); // seconds

if (timeRemaining > 0) {
  console.log(`Code expires in ${timeRemaining} seconds`);
} else {
  console.log("Code has expired");
}

Poll for verification status

Monitor verification status in real-time (e.g., when user verifies on another device):

async function pollVerificationStatus(verificationId) {
  const pollInterval = setInterval(async () => {
    const response = await fetch(
      `https://api.tryvox.io/v1/verify/${verificationId}`,
      {
        headers: {
          "Authorization": "Bearer tvx_sk_live_...",
          "X-Tenant-ID": "acc_123"
        }
      }
    );

    const { data } = await response.json();

    if (data.status === "approved") {
      clearInterval(pollInterval);
      console.log("Verification approved!");
    } else if (data.status === "failed" || data.status === "expired") {
      clearInterval(pollInterval);
      console.log(`Verification ${data.status}`);
    }
  }, 2000); // Poll every 2 seconds
}

Show attempt warnings

Alert users when they're running out of attempts:

const { data } = await response.json();

if (data.attempts === 4 && data.status === "pending") {
  alert("Warning: This is your last attempt!");
} else if (data.status === "failed") {
  alert("Too many incorrect attempts. Please request a new code.");
}

Best practices

Don't poll too frequently: Poll at 2-3 second intervals maximum to avoid rate limits
Show time remaining: Display a countdown timer based on expires_at
Display attempt counter: Show "X of 5 attempts remaining" to users
Handle all statuses: Check for pending, approved, failed, and expired states
Stop polling on terminal states: Stop checking status once verification is approved, failed, or expired
Graceful degradation: Don't rely solely on polling - always allow manual code entry
Cache status: Don't fetch status on every keystroke - fetch on page load and after check attempts

Verification timeline

0:00 - Verification created (status: pending)
0:30 - User enters wrong code (attempts: 1, status: pending)
1:00 - User enters wrong code (attempts: 2, status: pending)
1:30 - User enters correct code (attempts: 3, status: approved)

OR

0:00 - Verification created (status: pending)
2:00 - User enters wrong code (attempts: 1, status: pending)
...
8:00 - User enters wrong code (attempts: 5, status: failed)

OR

0:00 - Verification created (status: pending)
10:00 - Time expires (status: expired)

Get Verification Status

On this page