Skip to main content

API Reference

Complete reference documentation for the Chinqit SMS Gateway REST API.

🔐 Authentication​

All API endpoints require authentication using an API key provided by Chinqit.

Authentication Header​

Include your API key in the request header:

X-API-Key: your-api-key-here

Getting an API Key​

API keys are provided by Chinqit. Contact your service administrator to obtain your API key.

Error Responses​

401 Unauthorized - Missing API key:

{
  "success": false,
  "message": "API key is required"
}

403 Forbidden - Invalid API key:

{
  "success": false,
  "message": "Invalid API key"
}

📍 Base URL​

All API requests should be made to:

  • Production: https://sms.chinqit.com

💬 Message Operations​

Send Message​

POST /messages/send

Send an SMS message to a phone number.

Request Headers:

X-API-Key: your-api-key
Content-Type: application/json

Request Body:

{
  "message": "Hello, this is a test message",
  "phoneNumber": "+1234567890",
  "hash": "ABC123XYZ45"
}

Parameters:

  • message (required): SMS message content
  • phoneNumber (required): Recipient phone number (with country code, e.g., +1234567890)
  • hash (optional): 11-character SMS Retriever hash for automatic SMS consumption. When provided, the hash will be appended to the message. See SMS Retriever Guide for implementation details in Flutter, React Native, and Kotlin.

Response:

{
  "success": true,
  "messageId": "550e8400-e29b-41d4-a716-446655440000",
  "queued": true
}

Important Notes:

  • Messages are queued and processed asynchronously
  • The API returns immediately after queuing (non-blocking)
  • Use the messageId to track your message

Example:

curl -X POST https://sms.chinqit.com/messages/send \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{
    "message": "Hello from SMS Gateway!",
    "phoneNumber": "+1234567890"
  }'

JavaScript Example:

const response = await fetch("https://sms.chinqit.com/messages/send", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": "your-api-key",
  },
  body: JSON.stringify({
    message: "Hello from SMS Gateway!",
    phoneNumber: "+1234567890",
  }),
});

const data = await response.json();
console.log("Message ID:", data.messageId);

Python Example:

import requests

url = "https://sms.chinqit.com/messages/send"
headers = {
    "Content-Type": "application/json",
    "X-API-Key": "your-api-key"
}
data = {
    "message": "Hello from SMS Gateway!",
    "phoneNumber": "+1234567890"
}

response = requests.post(url, json=data, headers=headers)
result = response.json()
print(f"Message ID: {result['messageId']}")

🔐 OTP Operations​

Send OTP​

POST /otp/send

Send a one-time password (OTP) code via SMS or WhatsApp.

Request Headers:

X-API-Key: your-api-key
Content-Type: application/json

Request Body:

{
  "phoneNumber": "+1234567890",
  "language": "en",
  "channel": "sms"
}

Parameters:

  • phoneNumber (required): Phone number to send OTP to (E.164 format, e.g., +1234567890)
  • language (optional): Language for OTP message. Options: fr (default), en, ar
  • channel (optional): Communication channel. Options: sms (default), whatsapp

Response:

{
  "success": true,
  "messageId": "550e8400-e29b-41d4-a716-446655440000",
  "expiresIn": 600
}

OTP Details:

  • 6-digit numeric code
  • Valid for 10 minutes (600 seconds)
  • Maximum 3 verification attempts
  • Can be sent via SMS or WhatsApp

SMS Channel Example:

curl -X POST https://sms.chinqit.com/otp/send \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{
    "phoneNumber": "+1234567890",
    "language": "en",
    "channel": "sms"
  }'

WhatsApp Channel Example:

curl -X POST https://sms.chinqit.com/otp/send \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{
    "phoneNumber": "+1234567890",
    "language": "en",
    "channel": "whatsapp"
  }'

JavaScript Example:

// Send OTP via SMS
const smsResponse = await fetch("https://sms.chinqit.com/otp/send", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": "your-api-key",
  },
  body: JSON.stringify({
    phoneNumber: "+1234567890",
    language: "en",
    channel: "sms",
  }),
});

// Send OTP via WhatsApp
const whatsappResponse = await fetch("https://sms.chinqit.com/otp/send", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": "your-api-key",
  },
  body: JSON.stringify({
    phoneNumber: "+1234567890",
    language: "en",
    channel: "whatsapp",
  }),
});

const data = await whatsappResponse.json();
console.log("OTP expires in:", data.expiresIn, "seconds");

Python Example:

import requests

# Send OTP via SMS
sms_response = requests.post(
    "https://sms.chinqit.com/otp/send",
    headers={
        "Content-Type": "application/json",
        "X-API-Key": "your-api-key"
    },
    json={
        "phoneNumber": "+1234567890",
        "language": "en",
        "channel": "sms"
    }
)

# Send OTP via WhatsApp
whatsapp_response = requests.post(
    "https://sms.chinqit.com/otp/send",
    headers={
        "Content-Type": "application/json",
        "X-API-Key": "your-api-key"
    },
    json={
        "phoneNumber": "+1234567890",
        "language": "en",
        "channel": "whatsapp"
    }
)

data = whatsapp_response.json()
print(f"OTP expires in: {data['expiresIn']} seconds")

Verify OTP​

POST /otp/verify

Verify an OTP code that was sent to a phone number.

Request Headers:

X-API-Key: your-api-key
Content-Type: application/json

Request Body:

{
  "phoneNumber": "+1234567890",
  "otp": "123456",
  "channel": "sms"
}

Parameters:

  • phoneNumber (required): Phone number the OTP was sent to
  • otp (required): 6-digit OTP code to verify
  • channel (optional): Communication channel used. Options: sms (default), whatsapp

Response (Success):

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

Response (Invalid):

{
  "success": false,
  "message": "Invalid OTP",
  "retriesLeft": 2
}

Example:

curl -X POST https://sms.chinqit.com/otp/verify \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{
    "phoneNumber": "+1234567890",
    "otp": "123456",
    "channel": "sms"
  }'

JavaScript Example:

const response = await fetch("https://sms.chinqit.com/otp/verify", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": "your-api-key",
  },
  body: JSON.stringify({
    phoneNumber: "+1234567890",
    otp: "123456",
    channel: "sms",
  }),
});

const data = await response.json();
if (data.verified) {
  console.log("OTP verified successfully");
} else {
  console.log("Invalid OTP. Retries left:", data.retriesLeft);
}

Python Example:

import requests

url = "https://sms.chinqit.com/otp/verify"
headers = {
    "Content-Type": "application/json",
    "X-API-Key": "your-api-key"
}
data = {
    "phoneNumber": "+1234567890",
    "otp": "123456",
    "channel": "sms"
}

response = requests.post(url, json=data, headers=headers)
result = response.json()
if result.get("verified"):
    print("OTP verified successfully")
else:
    print(f"Invalid OTP. Retries left: {result.get('retriesLeft', 0)}")

⚠️ Error Responses​

All endpoints return errors in a consistent format:

{
  "success": false,
  "message": "Error description",
  "errors": [] // Optional: Validation errors
}

HTTP Status Codes​

  • 200 OK: Successful request
  • 400 Bad Request: Invalid request data or validation error
  • 401 Unauthorized: Missing API key
  • 403 Forbidden: Invalid API key
  • 404 Not Found: Resource not found
  • 429 Too Many Requests: Rate limit exceeded
  • 500 Internal Server Error: Server error
  • 502 Bad Gateway: Provider error (for WhatsApp channel)

Common Error Scenarios​

Validation Error (400):

{
  "success": false,
  "message": "Validation failed",
  "errors": [
    {
      "path": ["message"],
      "message": "String must contain at least 1 character(s)"
    }
  ]
}

Rate Limit Exceeded (429):

{
  "success": false,
  "message": "Rate limit exceeded. Please try again later."
}

WhatsApp Provider Error (502):

{
  "success": false,
  "message": "WhatsApp OTP send failed",
  "error": "Error details from WhatsApp API"
}

📊 Rate Limiting​

OTP Sending​

Per phone number per API key:

  • 3 requests per minute
  • 10 requests per hour
  • 20 requests per day

Rate limits are automatically enforced. If exceeded, you will receive a 429 status code.

💡 Best Practices​

API Key Security​

  • Never commit API keys to version control
  • Use environment variables or secure secret management
  • Rotate keys periodically
  • Use HTTPS for all API requests

Error Handling​

  • Always check the success field in responses
  • Handle all HTTP status codes appropriately
  • Implement retry logic for transient errors (429, 500, 502)
  • Log errors for debugging

Message Sending​

  • Store messageId for tracking purposes
  • Handle errors gracefully
  • Implement proper timeout handling

OTP Best Practices​

  • Always verify OTPs server-side
  • Don't expose OTP codes in logs
  • Handle rate limits gracefully
  • Use appropriate channel (SMS or WhatsApp) based on user preference

📚 Additional Resources​

Need help? Check the Troubleshooting Guide for common issues!