API v1 Endpoints

Complete reference documentation for the ChinqIT Verify REST API.

Authentication

All API endpoints require authentication using an API key provided by ChinqIT Verify.

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 Verify. 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

:::caution Deprecated All endpoints on this page are deprecated but still work. Responses include a Deprecation: true header and a deprecation object in the JSON body. Use the current API: API Reference. :::

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 (v1 – Deprecated)

Send Message

POST /messages/send (Deprecated – use POST /api/v2/notify)

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 (v1 – Deprecated)

Send OTP

Note: The v1 OTP route is frozen. It does not support email OTP. Use POST /api/v2/code with channel: "email" and email.

POST /otp/send (Deprecated – use POST /api/v2/code)

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

Note: The v1 OTP route is frozen. It does not support email OTP. Use POST /api/v2/check with channel: "email" and email.

POST /otp/verify (Deprecated – use POST /api/v2/check)

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
}

Status Operations (v1 – Deprecated)

Get Message Status

GET /message/:messageId/status (Deprecated – use GET /api/v2/notify/

)

Retrieve delivery status for a message owned by your API key.

Response: Same data object as GET /api/v2/notify/

Update Message Status

POST /update-message-status (Deprecated – no v2 replacement)

:::warning Do not use for new integrations There is no v2 equivalent. Delivery status is updated automatically by ChinqIT Verify. This endpoint exists only for legacy clients. :::

Request Body:

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

Response:

{
  "success": true,
  "message": "Message status updated successfully",
  "data": {
    "messageId": "550e8400-e29b-41d4-a716-446655440000",
    "sent": true,
    "updatedAt": "2024-01-15T10:30:00.000Z"
  }
}

Deprecation Response Format

All legacy endpoints return:

Header: Deprecation: true
Body field: deprecation with message and useInstead

Example (POST /messages/send):

{
  "success": true,
  "messageId": "550e8400-e29b-41d4-a716-446655440000",
  "queued": true,
  "deprecation": {
    "message": "This endpoint is deprecated. Use POST /api/v2/notify instead.",
    "useInstead": "POST /api/v2/notify"
  }
}

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.

You set these limits on each API key in the dashboard: per minute, per hour and per day. If you leave them empty, the maximum applies:

60 requests per minute
1,000 requests per hour
5,000 requests per day

If a limit is exceeded, the API returns HTTP 429 with a retryAfter value when applicable.

During the free trial: 429 TRIAL_LIMIT means "Free trial limit reached. Top up to send more." and 403 TRIAL_PAUSED means "Free trial sending is paused. Top up to continue."

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

API Reference – current API (use this for new integrations)
API Usage Guide – code samples (v1 deprecated)
Troubleshooting Guide – common issues and solutions

Need help? Check the Troubleshooting Guide for common issues!

On this page