API Documentation

Secure phone number validation via SMS using Allcance SMS service

RESTful API with authentication, rate limiting, and comprehensive error handling

API Information
  • Base URL: /api/v1
  • Authentication: API Key required
  • Content-Type: application/json
  • Rate Limit: 3 requests per 5 minutes per phone
Authentication

Include your API key in requests using one of these methods:

  • X-API-Key: your-api-key
  • Authorization: Bearer your-api-key

API Endpoints

POST /api/v1/send

Send SMS verification code to a phone number.

Request Body:
{
  "phone_number": "(41) 99209-6998"
}
Response (Success):
{
  "status": "success",
  "message": "Código de verificação enviado com sucesso",
  "expires_in": 600
}
Response (Error - Invalid Format):
{
  "status": "error",
  "message": "Formato de telefone inválido. Use o formato: (41) 99209-6998"
}
Response (Error - OTP Already Sent):
{
  "status": "error",
  "message": "Código de verificação já enviado. Verifique suas mensagens ou aguarde a expiração.",
  "error_code": "otp_already_sent",
  "expires_in": 598
}
POST /api/v1/resend

Resend the same SMS verification code to a phone number (60-second cooldown).

Request Body:
{
  "phone_number": "(41) 99209-6998"
}
Response (Success):
{
  "status": "success",
  "message": "Código de verificação reenviado com sucesso",
  "expires_in": 420
}
Response (Error):
{
  "status": "error",
  "message": "Aguarde 60 segundos antes de solicitar outro reenvio."
}
POST /api/v1/validate

Verify the SMS code entered by the user.

Request Body:
{
  "phone_number": "(41) 99209-6998",
  "code": "123456"
}
Response (Success):
{
  "status": "success",
  "message": "Telefone verificado com sucesso"
}
Response (Error):
{
  "status": "error",
  "error": "Invalid or expired verification code"
}
GET /api/v1/health

Health check endpoint (no authentication required).

Response:
{
  "status": "success",
  "service": "Velox OTP API",
  "version": "1.0.0",
  "status": "healthy"
}

API Testing Interface

Required for send-verification and verify-code endpoints
Send Verification Code
Verify Code
HTTP Status Codes
Code Description When it occurs
200 OK Request successful
400 Bad Request Invalid request data or format
401 Unauthorized Missing or invalid API key
404 Not Found Endpoint does not exist
405 Method Not Allowed HTTP method not supported
429 Too Many Requests Rate limit exceeded
500 Internal Server Error Server error or SMS service failure