Documentation

API reference

Everything you need to integrate: authentication, endpoints, payloads, webhooks and error codes.

Quickstart

cURL

curl -X POST https://api.blacksms.in/api/v1/sms/send \
  -H "Authorization: Bearer $BLACKSMS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to":"919876543210","sender_id":"BLKSMS","message":"Hello"}'

Endpoints

Method	Path	Purpose
POST	/api/v1/sms/send	Queue a single SMS
POST	/api/v1/otp/send	Generate and send a one-time passcode
POST	/api/v1/otp/verify	Verify a submitted code
POST	/api/v1/otp/resend	Resend the pending code for a number
POST	/api/public/dlr	Provider delivery-report receiver

Request fields

SMS body

{
  "to": "919876543210",         // required, E.164 without +
  "sender_id": "BLKSMS",        // required, approved sender
  "message": "Hello",           // required unless template_id is used
  "message_type": "transactional", // transactional | otp | promotional
  "project_id": "uuid",         // optional
  "template_id": "uuid",        // optional, renders with variables
  "variables": { "name": "Asha" }
}

OTP body

{
  "phone": "919876543210",   // required
  "sender_id": "BLKSMS",     // required
  "purpose": "login",        // optional label
  "code_length": 6,          // 4-8, default 6
  "expiry_seconds": 300,     // 60-3600, default 300
  "max_attempts": 5,         // 1-10, default 5
  "template": "{{code}} is your code"
}

Error codes

Every failure returns the same shape with a stable code.

HTTP	Code	Meaning
401	UNAUTHORIZED	Missing or invalid API key.
401	KEY_REVOKED	This API key has been revoked.
401	KEY_EXPIRED	This API key has expired.
403	FORBIDDEN	You do not have access to this resource.
403	ACCOUNT_SUSPENDED	This account is suspended.
422	VALIDATION_ERROR	One or more fields are invalid.
422	INVALID_PHONE	The destination phone number is invalid.
422	INVALID_SENDER	The sender ID is not approved for this account.
422	MESSAGE_TOO_LONG	The message exceeds the maximum allowed length.
402	INSUFFICIENT_BALANCE	Insufficient wallet balance.
402	WALLET_FROZEN	This wallet is frozen. Contact support.
429	RATE_LIMITED	Rate limit exceeded. Slow down and retry.
409	DUPLICATE_REQUEST	An identical message was sent moments ago.
403	DESTINATION_BLOCKED	This destination is blocked.
503	NO_ROUTE	No active route is available for this destination.
404	OTP_NOT_FOUND	No pending OTP found for this number.
410	OTP_EXPIRED	This OTP has expired.
422	OTP_INVALID	The OTP code is incorrect.
429	OTP_MAX_ATTEMPTS	Too many incorrect attempts. Request a new code.
429	OTP_COOLDOWN	Please wait before requesting another code.
404	NOT_FOUND	Resource not found.
405	METHOD_NOT_ALLOWED	HTTP method not allowed on this endpoint.
502	PROVIDER_ERROR	The upstream SMS provider rejected the request.
500	INTERNAL_ERROR	Something went wrong. Try again.