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

Phone Number Format (Mauritania)​

All endpoints accept Mauritania phone numbers in the following formats:

  • Canonical format: +222XXXXXXXX (e.g., +22238089336)
  • With country code: 222XXXXXXXX (e.g., 22238089336) - automatically normalized to +222XXXXXXXX
  • Local format: XXXXXXXX (e.g., 38089336) - automatically normalized to +222XXXXXXXX

Rules:

  • The 8-digit local number (XXXXXXXX) must start with 2, 3, or 4
  • The API automatically normalizes all accepted formats to +222XXXXXXXX before storing or sending
  • Phone numbers are stored and used in normalized format (+222XXXXXXXX) for consistency
  • Invalid formats (wrong length, wrong prefix, contains spaces/dashes) will return a 400 Bad Request error

Examples:

  • ✅ +22238089336 → normalized to +22238089336
  • ✅ 22238089336 → normalized to +22238089336
  • ✅ 38089336 → normalized to +22238089336
  • ❌ 12345678 → Error: must start with 2, 3, or 4
  • ❌ +222 27 63 56 42 → Error: spaces not allowed
  • ❌ +1234567890 → Error: not a valid Mauritania number

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": "+22238089336"
}

Parameters:

  • message (required): SMS message content
  • phoneNumber (required): Recipient phone number (Mauritania format). See Phone Number Format above for details.

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

OTP Operations​

Send OTP​

POST /otp/send

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

Request Body:

{
  "phoneNumber": "+22238089336",
  "hash": "ABC123XYZ45",
  "language": "en",
  "channel": "sms"
}

Parameters:

  • phoneNumber (required): Phone number to send OTP to (Mauritania format).
  • hash (optional): 11-character SMS Retriever hash (SMS channel only). When provided, the hash will be appended to the OTP message on a new line. See SMS Retriever Guide.
  • 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

Verify OTP​

POST /otp/verify

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

Request Body:

{
  "phoneNumber": "+22238089336",
  "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
}

Error Responses​

All endpoints return errors in a consistent format:

{
  "success": false,
  "message": "Error description",
  "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)

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!