SMSID API Reference

Quickstart

Authentication

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

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

X-Api-Key: YOUR_API_KEY

Send SMS

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

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());

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

Message 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

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());

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

Send OTP

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());

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

Verify OTP

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());

{
  "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" }
}