Developers

SMSID API Reference

Connect your app to SMSID in minutes. Send SMS and one-time passwords, check balance and delivery status — all over a simple JSON REST API.

Quickstart

Get your API key. Sign in and open Dashboard → API Credentials to generate your secret key.

Add the header. Send your key on every request as X-Api-Key.

Send your first message to the /sms/send endpoint (see below). You'll get back a message_id you can track with /sms/status.

Authentication

Every request must include your secret API key in the X-Api-Key header over HTTPS.

Base URL

https://smsid.co.uk/api/v1

Auth header

X-Api-Key: YOUR_API_KEY

Signed requests (HMAC)

If you have generated an API Secret (recommended for production), every request must be signed. Add an X-Api-Sign header containing the hex HMAC-SHA256 of the exact raw JSON request body, keyed with your API secret. Requests with a missing or invalid signature are rejected with 401.

Header	Value
X-Api-Key	Your API key.
X-Api-Sign	hex( HMAC-SHA256( raw_body, api_secret ) )

Sign and send

SECRET="YOUR_API_SECRET"
BODY='{"to":"+447700900123","sender_id":"SMSID","message":"Hello"}'
SIGN=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$SECRET" | sed 's/^.* //')

curl -X POST https://smsid.co.uk/api/v1/sms/send \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "X-Api-Sign: $SIGN" \
  -H "Content-Type: application/json" \
  -d "$BODY"

<?php
$body = json_encode(["to" => "+447700900123", "sender_id" => "SMSID", "message" => "Hello"]);
$sign = hash_hmac("sha256", $body, "YOUR_API_SECRET");   // hex digest

$ch = curl_init("https://smsid.co.uk/api/v1/sms/send");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => ["X-Api-Key: YOUR_API_KEY", "X-Api-Sign: $sign", "Content-Type: application/json"],
    CURLOPT_POSTFIELDS     => $body,   // sign and send the SAME body
]);
echo curl_exec($ch);

import hmac, hashlib, json, requests

secret = "YOUR_API_SECRET"
body = json.dumps({"to": "+447700900123", "sender_id": "SMSID", "message": "Hello"})
sign = hmac.new(secret.encode(), body.encode(), hashlib.sha256).hexdigest()

requests.post(
    "https://smsid.co.uk/api/v1/sms/send",
    headers={"X-Api-Key": "YOUR_API_KEY", "X-Api-Sign": sign, "Content-Type": "application/json"},
    data=body,   # send the exact signed body (do NOT use json=)
)

import crypto from "crypto";

const secret = "YOUR_API_SECRET";
const body = JSON.stringify({ to: "+447700900123", sender_id: "SMSID", message: "Hello" });
const sign = crypto.createHmac("sha256", secret).update(body).digest("hex");

await fetch("https://smsid.co.uk/api/v1/sms/send", {
  method: "POST",
  headers: { "X-Api-Key": "YOUR_API_KEY", "X-Api-Sign": sign, "Content-Type": "application/json" },
  body,
});

Sign the exact bytes you transmit. If you re-serialize the JSON differently (key order, spacing) the signature will not match. No secret set? Requests are accepted with the API key alone.

Send SMS

POST/sms/send

Send a text message to one recipient. The cost is deducted from your prepaid balance.

Field	Type	Description
to required	string	Recipient in international format, e.g. +447700900123
message required	string	Message text (up to 1600 chars; long messages split into segments).
sender_id optional	string	Approved Sender ID (2–11 chars). Defaults to your account sender.

Request

curl -X POST https://smsid.co.uk/api/v1/sms/send \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to": "+447700900123", "sender_id": "SMSID", "message": "Hello from SMSID"}'

<?php
$ch = curl_init("https://smsid.co.uk/api/v1/sms/send");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => [
        "X-Api-Key: YOUR_API_KEY",
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "to"        => "+447700900123",
        "sender_id" => "SMSID",
        "message"   => "Hello from SMSID",
    ]),
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

import requests

resp = requests.post(
    "https://smsid.co.uk/api/v1/sms/send",
    headers={"X-Api-Key": "YOUR_API_KEY"},
    json={
        "to": "+447700900123",
        "sender_id": "SMSID",
        "message": "Hello from SMSID",
    },
)
print(resp.json())

const res = await fetch("https://smsid.co.uk/api/v1/sms/send", {
  method: "POST",
  headers: {
    "X-Api-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    to: "+447700900123",
    sender_id: "SMSID",
    message: "Hello from SMSID",
  }),
});
console.log(await res.json());

Response

{
  "meta": { "code": 200, "text": "OK" },
  "data": {
    "status": "success",
    "message_id": "Dcshuhod0PMAAAFQ...",
    "cost": "0.0400",
    "remaining_balance": "95.6000"
  }
}

Message Status

POST/sms/status

Check the delivery status of a sent message using its message_id.

curl -X POST https://smsid.co.uk/api/v1/sms/status \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message_id": "Dcshuhod0PMAAAFQ..."}'

<?php
$ch = curl_init("https://smsid.co.uk/api/v1/sms/status");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => ["X-Api-Key: YOUR_API_KEY", "Content-Type: application/json"],
    CURLOPT_POSTFIELDS     => json_encode(["message_id" => "Dcshuhod0PMAAAFQ..."]),
]);
echo curl_exec($ch);

import requests

resp = requests.post(
    "https://smsid.co.uk/api/v1/sms/status",
    headers={"X-Api-Key": "YOUR_API_KEY"},
    json={"message_id": "Dcshuhod0PMAAAFQ..."},
)
print(resp.json())

const res = await fetch("https://smsid.co.uk/api/v1/sms/status", {
  method: "POST",
  headers: { "X-Api-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ message_id: "Dcshuhod0PMAAAFQ..." }),
});
console.log(await res.json());

Statuses: queued, sent, delivered, failed.

Check Balance

GET/balance

Return your current prepaid credit balance.

curl https://smsid.co.uk/api/v1/balance \
  -H "X-Api-Key: YOUR_API_KEY"

<?php
$ch = curl_init("https://smsid.co.uk/api/v1/balance");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ["X-Api-Key: YOUR_API_KEY"],
]);
echo curl_exec($ch);

import requests

resp = requests.get("https://smsid.co.uk/api/v1/balance", headers={"X-Api-Key": "YOUR_API_KEY"})
print(resp.json())

const res = await fetch("https://smsid.co.uk/api/v1/balance", {
  headers: { "X-Api-Key": "YOUR_API_KEY" },
});
console.log(await res.json());

Response

{
  "meta": { "code": 200, "text": "OK" },
  "data": { "balance": "95.6000" }
}

Send OTP

POST/otp/send

Generate and send a one-time passcode. SMSID stores and validates the code for you.

curl -X POST https://smsid.co.uk/api/v1/otp/send \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to": "+447700900123"}'

<?php
$ch = curl_init("https://smsid.co.uk/api/v1/otp/send");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => ["X-Api-Key: YOUR_API_KEY", "Content-Type: application/json"],
    CURLOPT_POSTFIELDS     => json_encode(["to" => "+447700900123"]),
]);
echo curl_exec($ch);

import requests

resp = requests.post(
    "https://smsid.co.uk/api/v1/otp/send",
    headers={"X-Api-Key": "YOUR_API_KEY"},
    json={"to": "+447700900123"},
)
print(resp.json())

const res = await fetch("https://smsid.co.uk/api/v1/otp/send", {
  method: "POST",
  headers: { "X-Api-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ to: "+447700900123" }),
});
console.log(await res.json());

Response

{
  "meta": { "code": 200, "text": "OK" },
  "data": { "status": "sent", "to": "+447700900123" }
}

Verify OTP

POST/otp/verify

Check the code entered by your user. Returns verified=true on success.

curl -X POST https://smsid.co.uk/api/v1/otp/verify \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to": "+447700900123", "code": "123456"}'

<?php
$ch = curl_init("https://smsid.co.uk/api/v1/otp/verify");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => ["X-Api-Key: YOUR_API_KEY", "Content-Type: application/json"],
    CURLOPT_POSTFIELDS     => json_encode(["to" => "+447700900123", "code" => "123456"]),
]);
echo curl_exec($ch);

import requests

resp = requests.post(
    "https://smsid.co.uk/api/v1/otp/verify",
    headers={"X-Api-Key": "YOUR_API_KEY"},
    json={"to": "+447700900123", "code": "123456"},
)
print(resp.json())

const res = await fetch("https://smsid.co.uk/api/v1/otp/verify", {
  method: "POST",
  headers: { "X-Api-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ to: "+447700900123", code: "123456" }),
});
console.log(await res.json());

Response

{
  "meta": { "code": 200, "text": "OK" },
  "data": { "status": "verified", "verified": true }
}

Errors & limits

Errors return a non-200 HTTP status with a descriptive message in the meta object. The API is rate limited to 120 requests per minute per key.

{
  "meta": { "code": 400, "text": "Insufficient balance" }
}

HTTP	Meaning
401	Missing or invalid API key.
400	Validation error, unapproved sender, or insufficient balance.
422	OTP verification failed (wrong or expired code).
429	Rate limit exceeded — slow down and retry.