Verify API

The Verify API provides a simple way to implement two-factor authentication (2FA) and phone number verification. Send SMS codes and verify them with just two API calls.

How It Works

The verification flow consists of two steps:

Send: Generate and send a verification code to a phone number
Check: Verify the code entered by the user

Send Verification Code

Endpoint

POST https://www.telephony.io/api/verify/send

Parameters

Parameter	Type	Description
`phone_number`	string	Phone number to verify (E.164 format: `+61412345678`)
`brand`	string	Optional. Your app name to include in SMS (default: "Telephony.io")
`channel`	string	Optional. Delivery method: `sms` or `voice` (default: `sms`)
`code_length`	number	Optional. Length of verification code: 4-10 digits (default: 6)
`locale`	string	Optional. Language for message: `en`, `es`, `fr` (default: `en`)

Example Request

curl -X POST https://www.telephony.io/api/verify/send \
  -H "Authorization: Bearer sk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+61412345678",
    "brand": "MyApp",
    "channel": "sms",
    "code_length": 6
  }'

Example with JavaScript

const sendVerification = async (phoneNumber) => {
  const response = await fetch('https://www.telephony.io/api/verify/send', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer sk_live_abc123...',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      phone_number: phoneNumber,
      brand: 'MyApp',
      channel: 'sms'
    })
  });

  return await response.json();
};

Response

{
  "success": true,
  "verification_id": "verify_k8h3j9f2d7s6",
  "phone_number": "+61412345678",
  "channel": "sms",
  "status": "pending",
  "expires_at": "2024-12-10T00:50:00Z",
  "creditsUsed": 0.05
}

Check Verification Code

Endpoint

POST https://www.telephony.io/api/verify/check

Parameters

Parameter	Type	Description
`phone_number`	string	Phone number being verified (same as send request)
`code`	string	Verification code entered by user

Example Request

curl -X POST https://www.telephony.io/api/verify/check \
  -H "Authorization: Bearer sk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+61412345678",
    "code": "123456"
  }'

Example with JavaScript

const checkVerification = async (phoneNumber, code) => {
  const response = await fetch('https://www.telephony.io/api/verify/check', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer sk_live_abc123...',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      phone_number: phoneNumber,
      code: code
    })
  });

  const result = await response.json();
  
  if (result.status === 'approved') {
    // Verification successful - log user in
    console.log('Phone verified successfully');
  } else {
    // Verification failed
    console.log('Invalid code');
  }
  
  return result;
};

Success Response

{
  "success": true,
  "status": "approved",
  "phone_number": "+61412345678",
  "verified_at": "2024-12-10T00:45:32Z"
}

Failed Verification

{
  "success": false,
  "status": "failed",
  "error": {
    "code": "invalid_code",
    "message": "The verification code is incorrect"
  }
}

Code Expiration & Limits

Validity: Verification codes expire after 10 minutes
Attempts: Maximum 5 verification attempts per code
Rate Limiting: Maximum 3 send requests per phone number per hour
Reuse: Once a code is verified, it cannot be reused

💡 Best Practice

Store the verification_id returned from the send request for audit logging and webhook correlation. This helps track verification attempts and troubleshoot issues.

SMS Message Format

The SMS sent to users follows this format:

Your MyApp verification code is: 123456

This code expires in 10 minutes.

Error Responses

Invalid Phone Number

{
  "error": {
    "code": "invalid_phone_number",
    "message": "Phone number must be in E.164 format"
  }
}

Rate Limit Exceeded

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many verification attempts. Try again in 45 minutes."
  }
}

Pricing

SMS Verification: AU$0.05 per message
Voice Verification: AU$0.10 per call
International SMS: Variable rates by destination

Only successful send requests are charged. Failed sends (invalid numbers, blocked carriers) are not charged to your account.

Security Considerations

Always verify codes on your backend, never in client-side code
Implement rate limiting on your endpoints to prevent abuse
Log verification attempts for security auditing
Consider implementing CAPTCHA before sending verification codes
Monitor for unusual patterns (same number, multiple failed attempts)