Documentation

Learn how to integrate Valid's SMS verification API into your application.

Introduction

Valid provides a simple, secure API for sending SMS verification codes to your users. Our API handles code generation, SMS delivery, and verification - so you can focus on building your application.

Authentication

All API requests require authentication using an API key. Include your API key in the X-API-Key header with every request.

X-API-Key: vld_your_api_key_here

You can create and manage API keys from your dashboard.

Quickstart

Get started with SMS verification in just two API calls:

Step 1: Send a verification code

curl -X POST http://localhost:3000/api/v1/verification \
  -H "X-API-Key: vld_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+14155551234"
  }'

{
  "success": true,
  "data": {
    "verification_id": "550e8400-e29b-41d4-a716-446655440000",
    "phone_number": "+14155551234",
    "status": "pending",
    "expires_at": "2025-01-16T10:05:00Z",
    "created_at": "2025-01-16T10:00:00Z"
  }
}

Step 2: Verify the code

curl -X POST http://localhost:3000/api/v1/verification/check \
  -H "X-API-Key: vld_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "verification_id": "550e8400-e29b-41d4-a716-446655440000",
    "code": "123456"
  }'

{
  "success": true,
  "data": {
    "verification_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "verified",
    "verified_at": "2025-01-16T10:02:30Z"
  }
}

API Reference

Send Verification

Send a verification code to a phone number via SMS.

Request Body

Response

Check Code

Verify a code submitted by the user.

Request Body

* Either verification_id or phone_number is required.

Success Response

{
  "success": true,
  "data": {
    "verification_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "verified",
    "verified_at": "2025-01-16T10:02:30Z"
  }
}

Invalid Code Response

{
  "success": false,
  "error": {
    "code": "INVALID_CODE",
    "message": "The verification code is incorrect",
    "attempts_remaining": 2
  }
}

Get Verification Status

Retrieve the current status of a verification.

{
  "success": true,
  "data": {
    "verification_id": "550e8400-e29b-41d4-a716-446655440000",
    "phone_number": "+14155551234",
    "status": "delivered",
    "delivery_status": "delivered",
    "attempts": 0,
    "max_attempts": 3,
    "expires_at": "2025-01-16T10:05:00Z",
    "created_at": "2025-01-16T10:00:00Z"
  }
}

Cancel Verification

Cancel an active verification request.

{
  "success": true,
  "data": {
    "verification_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "cancelled"
  }
}

Delivery Status Webhook

Receive real-time delivery status updates via webhooks.

Configure your webhook URL in your SMS provider dashboard to receive delivery notifications.

Webhook Payload

{
  "message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "to": "14155551234",
  "from": "Valid",
  "timestamp": "2025-01-16T10:00:01Z",
  "status": "delivered",
  "error": null
}

Status Values

Error Handling

The API uses standard HTTP status codes and returns consistent error responses.

Error Response Format

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": []  // Optional validation errors
  }
}

Error Codes

Rate Limits

Rate limits protect the API from abuse and ensure fair usage for all customers.

Rate limit headers are included in all responses:

RateLimit-Limit: 60
RateLimit-Remaining: 59
RateLimit-Reset: 1705402800

Best Practices

Security

• Never expose your API key in client-side code
• Always validate phone numbers before sending verification requests
• Implement your own rate limiting on top of ours for additional protection
• Use HTTPS for all API requests

User Experience

• Show a countdown timer for code expiration
• Display remaining attempts after an incorrect code
• Allow users to request a new code (respecting rate limits)
• Pre-format phone number input fields for E.164 format

Error Handling

• Handle all error codes gracefully with user-friendly messages
• Implement exponential backoff for rate limit errors
• Log verification failures for fraud detection