TX
Get Key

TextCom API Documentation

Integrate SMS sending, OTP generation, and verification into your applications with our RESTful API. Built for developers who value simplicity and reliability.

Get Started Back to Home

Base URL

https://api.textcomsms.com/api

Authentication

All API requests require authentication using Laravel Sanctum bearer tokens. Generate your API key from your dashboard.

Getting Your API Key

  1. 1 Sign in to your TextCom account
  2. 2 Navigate to API Keys in your dashboard
  3. 3 Click Generate New Key and copy your token

Using Your API Key

Include your API token in the Authorization header of every request: 

Authorization: Bearer YOUR_API_TOKEN

⚠️ Security Best Practices

  • • Never commit API keys to version control
  • • Store keys in environment variables or secure vaults
  • • Rotate keys regularly and revoke unused keys
  • • Use different keys for development and production

SMS API

Send instant or scheduled SMS messages to single or multiple recipients using your approved sender IDs.

POST /api/sms/send

Request Body

Field Type Required Description
text string Yes Message content (1-10,000 characters)
type integer Yes 0 for instant, 1 for scheduled
sender string Yes Sender ID name (must be approved and belong to you)
destinations array Yes Array of phone numbers (max 20 characters each)
schedule string Conditional Required if type is 1. Format: YYYY-MM-DD HH:MM:SS
callback.url string No Webhook URL for delivery status updates (max 500 chars)
callback.accept string No Content-Type header for callback (default: application/json)

Example Request

Instant SMS
curl -X POST https://api.textcomsms.com/api/sms/send \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Hello from TextCom!",
    "type": 0,
    "sender": "TextCom",
    "destinations": ["0533637042", "0244123456"],
    "callback": {
      "url": "https://example.com/sms-callback",
      "accept": "application/json"
    }
  }'
Scheduled SMS
curl -X POST https://api.textcomsms.com/api/sms/send \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Reminder: Your appointment is tomorrow.",
    "type": 1,
    "sender": "TextCom",
    "destinations": ["0533637042"],
    "schedule": "2025-11-25 14:30:00"
  }'

Success Response (201 Created)

{
  "handshake": {
    "id": 0,
    "label": "HSHK_OK"
  },
  "data": {
    "batch": "550e8400-e29b-41d4-a716-446655440000",
    "category": "sms",
    "delivery": false,
    "destinations": [
      {
        "to": "233533637042",
        "id": "660e8400-e29b-41d4-a716-446655440001",
        "status": {
          "label": "SMS_SUBMITTED"
        }
      }
    ]
  }
}

Error Response (422/500)

{
  "handshake": {
    "id": 1,
    "label": "HSHK_ERROR"
  },
  "error": "The selected sender ID is not approved or does not belong to you."
}

Check SMS Status

GET /api/sms/status?batch={batch_id}
or
GET /api/sms/status?destination={destination_id}

Query Parameters

Parameter Type Required Description
batch string Conditional Batch ID (UUID) returned from the send endpoint. Required if destination is not provided.
destination string Conditional Destination ID (UUID) from the destinations array in the send response. Required if batch is not provided.

Note:

You must provide either batch or destination parameter, but not both.

Example Request

Check by Batch ID
curl -X GET "https://api.textcomsms.com/api/sms/status?batch=550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
Check by Destination ID
curl -X GET "https://api.textcomsms.com/api/sms/status?destination=660e8400-e29b-41d4-a716-446655440001" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Success Response (200 OK)

{
  "handshake": {
    "id": 0,
    "label": "HSHK_OK"
  },
  "data": {
    "batch": "550e8400-e29b-41d4-a716-446655440000",
    "category": "sms",
    "delivery": false,
    "destinations": [
      {
        "to": "233533637042",
        "id": "660e8400-e29b-41d4-a716-446655440001",
        "status": {
          "label": "SMS_SUBMITTED"
        }
      }
    ]
  }
}

Response Fields:

  • handshake.id — Status code (0 = success, 1 = error)
  • handshake.label — Status label (HSHK_OK, HSHK_ERROR)
  • data.batch — Batch ID (UUID)
  • data.category — Message category (usually "sms")
  • data.delivery — Boolean indicating if any message is delivered
  • data.destinations — Array of destination objects with status
  • destinations[].to — Phone number
  • destinations[].id — Destination ID (UUID)
  • destinations[].status.label — Status label (SMS_PENDING, SMS_PROCESSING, SMS_SUBMITTED, SMS_DELIVERED, SMS_FAILED)

Error Response (404/422)

{
  "handshake": {
    "id": 1,
    "label": "HSHK_ERROR"
  },
  "error": "Batch not found."
}

Possible error messages:

  • Either batch or destination parameter is required. — No query parameter provided
  • Batch not found. — Batch ID doesn't exist or doesn't belong to you
  • Destination not found. — Destination ID doesn't exist or doesn't belong to you

Status Labels

Status Label Description
SMS_PENDING Message is queued and waiting to be processed
SMS_PROCESSING Message is currently being sent to the provider
SMS_SUBMITTED Message has been successfully submitted to the provider
SMS_DELIVERED Message has been delivered to the recipient
SMS_FAILED Message failed to send or was rejected

OTP API

Generate and verify one-time passwords for phone number verification, two-factor authentication, and secure transactions.

Generate OTP

POST /api/otp/generate

Request Body

Field Type Required Description
number string Yes Phone number (max 13 characters)
sender_id string Yes Sender ID name (must be approved)
length integer Yes OTP code length (6-15 characters)
type string Yes numeric or alphanumeric
medium string Yes sms or voice
expiry integer Yes Expiry time in minutes (1-10)
message string Yes Message template with %otp_code% and %expiry% placeholders (max 1000 chars)

Example Request

curl -X POST https://api.textcomsms.com/api/otp/generate \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "number": "0533637042",
    "sender_id": "TextCom",
    "length": 6,
    "type": "numeric",
    "medium": "sms",
    "expiry": 5,
    "message": "Your verification code is %otp_code%. Valid for %expiry% minutes."
  }'

Success Response (200 OK) 

{
  "code": "success",
  "message": "OTP generated and queued for sending",
  "data": {
    "otp_id": "550e8400-e29b-41d4-a716-446655440000",
    "expires_at": "2025-11-22T15:30:00+00:00"
  }
}

Important Notes

  • • When a new OTP is generated for a phone number, all previous active and unexpired OTPs for that number are automatically deactivated
  • • Rate limiting: Maximum 5 OTP generation requests per phone number per minute
  • • The OTP code is sent via SMS using the specified sender ID
  • • Use %otp_code% and %expiry% placeholders in your message template

Verify OTP

POST /api/otp/verify

Request Body

Field Type Required Description
number string Yes Phone number (max 13 characters)
code string Yes OTP code to verify (6-15 characters)

Example Request

curl -X POST https://api.textcomsms.com/api/otp/verify \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "number": "0533637042",
    "code": "123456"
  }'

Success Response (200 OK) 

{
  "code": "success",
  "message": "OTP verified successfully"
}

Error Response (422 Unprocessable Entity)

{
  "code": "error",
  "message": "Invalid code",
  "attempts": 3
}

Possible error messages:

  • OTP not found or expired — No active OTP found or it has expired
  • Max verification attempts exceeded — Maximum 5 attempts reached
  • Invalid code — The provided code is incorrect
  • Invalid phone number format — Phone number format is invalid

Verification Behavior

  • • Verification is always performed against the latest OTP record for the phone number
  • • Maximum 5 verification attempts per OTP
  • • Once verified successfully, the OTP is marked as used and cannot be reused
  • • Expired or inactive OTPs cannot be verified

Rate Limits & Best Practices

Rate Limits

  • • OTP Generation: 5 requests per phone number per minute
  • • OTP Verification: 5 attempts per OTP
  • • SMS Sending: Based on your account tier and wallet balance

Best Practices

  • ✓ Always validate phone numbers before sending
  • ✓ Handle errors gracefully and implement retry logic
  • ✓ Store OTP IDs for tracking and debugging
  • ✓ Use webhooks for async delivery status updates

Need Help?

Our support team is here to help you integrate TextCom into your application.

Contact Support Get API Key