API Reference

Complete API reference for K-OTP service endpoints, parameters, and responses.

Base URL

Production: https://api.k-otp.dev/v1
Sandbox: https://api-sandbox.k-otp.dev/v1

Authentication

All API requests must include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Send OTP

Send an OTP via SMS, email, or voice call.

Endpoint

POST /send

Request Body

{
  "to": "+1234567890",
  "method": "sms",
  "type": "verification",
  "template": "default",
  "ttl": 300,
  "length": 6,
  "metadata": {
    "user_id": "user_123",
    "action": "login"
  }
}

Parameters

Parameter	Type	Required	Description
`to`	string	Yes	Phone number (E.164) or email address
`method`	string	Yes	Delivery method: `sms`, `email`, `voice`
`type`	string	Yes	OTP type: `verification`, `two_factor`, `password_reset`, `transaction`
`template`	string	No	Template name (default: "default")
`ttl`	integer	No	Time to live in seconds (default: 300, max: 900)
`length`	integer	No	OTP length (default: 6, min: 4, max: 8)
`metadata`	object	No	Custom metadata (max 1KB)

Response

{
  "id": "otp_1234567890abcdef",
  "to": "+1234567890",
  "method": "sms",
  "type": "verification",
  "status": "sent",
  "created_at": "2024-01-15T10:30:00Z",
  "expires_at": "2024-01-15T10:35:00Z",
  "cost": {
    "amount": 0.05,
    "currency": "USD"
  }
}

Verify OTP

Verify an OTP code entered by the user.

Endpoint

POST /verify

Request Body

{
  "id": "otp_1234567890abcdef",
  "code": "123456"
}

Parameters

Parameter	Type	Required	Description
`id`	string	Yes	OTP ID from send response
`code`	string	Yes	OTP code entered by user

Response

{
  "valid": true,
  "id": "otp_1234567890abcdef",
  "verified_at": "2024-01-15T10:32:00Z",
  "attempts": 1,
  "metadata": {
    "user_id": "user_123",
    "action": "login"
  }
}

Check Status

Check the delivery status of an OTP.

Endpoint

GET /status/{id}

Parameters

Parameter	Type	Required	Description
`id`	string	Yes	OTP ID from send response

Response

{
  "id": "otp_1234567890abcdef",
  "status": "delivered",
  "to": "+1234567890",
  "method": "sms",
  "created_at": "2024-01-15T10:30:00Z",
  "delivered_at": "2024-01-15T10:30:15Z",
  "attempts": 0,
  "verified": false,
  "carrier": "Verizon",
  "country": "US"
}

List OTPs

Get a list of OTPs with filtering options.

Endpoint

GET /otps

Query Parameters

Parameter	Type	Description
`limit`	integer	Number of results (max: 100, default: 20)
`offset`	integer	Pagination offset (default: 0)
`method`	string	Filter by delivery method
`status`	string	Filter by status
`from`	string	Start date (ISO 8601)
`to`	string	End date (ISO 8601)

Response

{
  "data": [
    {
      "id": "otp_1234567890abcdef",
      "to": "+1234567890",
      "method": "sms",
      "status": "delivered",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "limit": 20,
    "offset": 0,
    "total": 150,
    "has_more": true
  }
}

Status Codes

Status	Description
`pending`	OTP is being processed
`sent`	OTP has been sent to carrier/provider
`delivered`	OTP was successfully delivered
`failed`	OTP delivery failed
`expired`	OTP has expired
`verified`	OTP has been successfully verified

Error Responses

All errors follow this format:

{
  "error": {
    "code": "INVALID_PHONE",
    "message": "The phone number format is invalid",
    "details": {
      "field": "to",
      "value": "123456"
    }
  }
}

Common Error Codes

Code	HTTP Status	Description
`INVALID_API_KEY`	401	API key is missing or invalid
`INSUFFICIENT_CREDITS`	402	Account has insufficient credits
`RATE_LIMITED`	429	Rate limit exceeded
`INVALID_PHONE`	400	Phone number format is invalid
`INVALID_EMAIL`	400	Email address format is invalid
`OTP_NOT_FOUND`	404	OTP ID not found
`OTP_EXPIRED`	400	OTP has expired
`INVALID_CODE`	400	OTP code is incorrect
`MAX_ATTEMPTS`	400	Maximum verification attempts reached

Rate Limits

Send OTP: 10 requests per minute per phone/email
Verify OTP: 5 attempts per OTP
API Calls: 1000 requests per minute per API key

Rate limit headers are included in all responses:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1642248600

Webhooks

Configure webhooks to receive real-time notifications about OTP events. See Webhooks for details.

SDKs and Libraries

JavaScript/Node.js: npm install @k-otp/sdk
Python: pip install k-otp
PHP: composer require k-otp/sdk
Go: go get github.com/k-otp/go-sdk
Java: Maven/Gradle available

API Reference

On this page