API Reference

Reference for the current ChinqIT Verify API. Base path: https://sms.chinqit.com/api/v2.

Authentication

All requests require an API key in one of these headers:

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

or

Authorization: Bearer your-api-key-here

You create your API keys yourself in the dashboard. Create an account, then open API keys and choose Create API key. A new account can create a key right away and send OTPs; normal messages unlock after its first top-up.

The full API key is shown once, when it is created or regenerated. Store it securely; it cannot be shown again.

In the dashboard, Regenerate key and Deactivate each ask for confirmation first: a regenerated key stops the old one working immediately, and requests with a deactivated key are rejected until you reactivate it. A test send from a key's details panel sends an OTP code by default and is charged to your balance like any other message.

When you create or edit a key, its WhatsApp and Email switches decide whether it may send WhatsApp and email OTPs. Email delivery uses the shared ChinqIT sender; customer-owned sender domains are not yet available and the dashboard marks them as coming soon.

401 Unauthorized (missing key):

{
  "success": false,
  "message": "API key is required. Please provide X-API-Key header or Authorization Bearer token."
}

403 Forbidden (invalid or inactive key):

{
  "success": false,
  "message": "Invalid or inactive API key."
}

401 Unauthorized (expired key):

{
  "success": false,
  "message": "API key expired."
}

403 Forbidden (API key not assigned to a user account):

{
  "success": false,
  "message": "API key is not assigned to a user."
}

403 Forbidden (sender ID expired — SMS send endpoints only):

{
  "success": false,
  "code": "SENDER_ID_EXPIRED",
  "message": "The API key sender ID has expired. Remove it or renew the sender ID before sending SMS."
}

When a sender ID (header) bound to the key expires, the gateway blocks SMS traffic for that key instead of falling back to the default sender. Remove the expired header from the key in the dashboard or renew the header, then retry. WhatsApp sends are not affected.

Base URL

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

Phone number formats

Rules depend on the endpoint and OTP channel.

SMS (POST /api/v2/notify, POST /api/v2/code with channel: "sms", POST /api/v2/check with channel: "sms")

Mauritania numbers only. Accepted inputs are normalized to +222XXXXXXXX:

• Canonical: +222XXXXXXXX (e.g. +22238089336)
• With country code: 222XXXXXXXX
• Local: XXXXXXXX (must start with 2, 3, or 4)

WhatsApp OTP (POST /api/v2/code with channel: "whatsapp")

Uses international E.164 format (e.g. +12133734253). The number must be valid for its country.

Supported countries: Mauritania (MR) and United States (US). Other countries return 400 with:

"WhatsApp OTP supports only Mauritania (MR) and United States (US) phone numbers."

Example US number: +12133734253.

Use the same E.164 number (and channel) when calling POST /api/v2/check.

Invalid formats return 400 Bad Request.

Rate limiting

Throughput (notify, code, check, status GET)

Per API key: 10 requests per second. When exceeded, the API returns 429 with a retryAfter field (seconds) and a Retry-After header.

Standard rate limits do not apply to bulk requests. A key can send 2 broadcasts per minute; see Broadcasts.

OTP sending (POST /api/v2/code only)

Per recipient (phone number or email) per API key.

ChinqIT sets these limits on each API key: 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

When exceeded, the API returns 429 with retryAfter (seconds).

POST /api/v2/notify

Send an SMS message.

Request:

{
  "message": "Hello, this is a test message",
  "phoneNumber": "+22238089336"
}

Response:

{
  "success": true,
  "messageId": "550e8400-e29b-41d4-a716-446655440000",
  "queued": true,
  "cost": 0.10,
  "parts": 1,
  "pricePerMessage": 0.10,
  "encoding": "GSM-7",
  "length": 37
}

cost, parts, pricePerMessage, encoding and length are the expected charge.

Messages are queued and processed asynchronously. Use messageId to track delivery.

Charging: an SMS is charged when it is sent. If your balance is too low, it is not sent or charged, and its status becomes failed.

Errors: 429 if the key reached its monthly limit, 503 if SMS is temporarily unavailable.

Example:

curl -X POST https://sms.chinqit.com/api/v2/notify \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phoneNumber": "+22238089336", "message": "Hello"}'

POST /api/v2/code

Request an OTP (send a verification code via SMS, WhatsApp or email). For email, see Email OTP.

Request:

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

Response:

{
  "success": true,
  "messageId": "550e8400-e29b-41d4-a716-446655440000",
  "expiresIn": 600,
  "cost": 0.10,
  "parts": 1,
  "pricePerMessage": 0.10,
  "encoding": "GSM-7",
  "length": 37
}

cost, parts, pricePerMessage, encoding and length are the expected charge.

• 6-digit code, valid 10 minutes (600 seconds), max 3 verification attempts.

Charging:

• SMS: as for POST /api/v2/notify.
• WhatsApp and email: charged when you send the request. A 402 means your balance is too low.

402 Payment Required — Insufficient balance (WhatsApp and email):

{
  "success": false,
  "message": "Insufficient balance",
  "messageId": "550e8400-e29b-41d4-a716-446655440000"
}

WhatsApp channel (channel: "whatsapp"):

• Your API key must have WhatsApp enabled; otherwise 403 with "WhatsApp access is not enabled for this API key".
• Phone must be valid E.164 for MR or US (see Phone number formats); other countries return 400.
• 503 if WhatsApp delivery is temporarily unavailable.

Example:

curl -X POST https://sms.chinqit.com/api/v2/code \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phoneNumber": "+22238089336", "language": "en"}'

POST /api/v2/check

Verify an OTP code.

Request:

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

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/api/v2/check \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phoneNumber": "+22238089336", "otp": "123456"}'

GET /api/v2/notify/

Get delivery status for a message.

Response:

{
  "success": true,
  "data": {
    "messageId": "550e8400-e29b-41d4-a716-446655440000",
    "status": "sent",
    "billed": true,
    "sent": true,
    "phoneNumber": "+22238089336",
    "type": "message",
    "origin": "internal_alert",
    "alertType": "low_balance",
    "smppMessageId": "abc123",
    "submittedAt": "2024-01-15T10:30:00.000Z",
    "dlrStatus": "DELIVRD",
    "dlrReceivedAt": "2024-01-15T10:30:05.000Z",
    "cost": 0.10,
    "parts": 1,
    "pricePerMessage": 0.10,
    "createdAt": "2024-01-15T10:29:55.000Z",
    "updatedAt": "2024-01-15T10:30:05.000Z"
  }
}

404 if the message is not found or does not belong to your API key.

Example:

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://sms.chinqit.com/api/v2/notify/550e8400-e29b-41d4-a716-446655440000"

Broadcasts

Send to up to 50,000 recipients per batch for single-part messages. Multi-part or max-length messages reduce capacity — the request body is capped at 20 MB (recipients × (encoded message bytes + ~40 bytes) ≤ 20 MB). See the dedicated Broadcasts guide for:

• POST /api/v2/bulk/send (returns 202 Accepted)
• GET /api/v2/bulk/status/:batchId

Error format

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

HTTP status codes:

Billing failures for broadcast batches are documented in the Broadcasts guide.

Deprecation

Legacy unversioned endpoints (/messages/send, /otp/send, etc.) remain available but return dated Deprecation and Sunset headers and a deprecation object in the JSON body. Do not use them for new integrations. See deprecated API section.

See also

• API Usage
• Troubleshooting
• SMS Retriever Guide

API v1 (deprecated): legacy section