Noir SMS API

Quickstart

1. Get a keyLog in, open Dashboard → API and click Generate API key. Copy it: it is shown only once.
2. Add fundsThe API spends your normal balance. Top up by card or USDC / SOL in the dashboard.
3. Buy, read, doneBuy a number, put it in the app you are verifying, poll for the code (or use a webhook), then finish or cancel.

curl -X POST https://noirsms.com/api/v1/numbers \
  -H "Authorization: Bearer nsk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"service": "wa", "country": "us", "max_price": 1.50}'

Authentication

Every request needs your API key, either as a bearer token or in the X-API-Key header. Keys start with nsk_live_. One key per account; regenerating it in the dashboard disables the old one at once. Never put the key in a browser or mobile app: call the API from your server.

Authorization: Bearer nsk_live_YOUR_KEY
# or
X-API-Key: nsk_live_YOUR_KEY

Base URL: https://noirsms.com/api/v1. All bodies are JSON, all prices are in US dollars, all times are ISO 8601 in UTC.

Machine-readable spec: /api/openapi.json (OpenAPI 3.1). Import it into Postman or Insomnia, or generate a client in your language.

How a purchase works

• waiting: the number is yours for 20 minutes (expires_at). Enter it in the app and wait for the SMS.
• received: at least one SMS arrived; the code is in sms[].code and the full text in sms[].text. You can ask for another SMS on the same number with /resend while it is open.
• canceled: you canceled it (allowed from cancelable_at, 2 minutes after buying) and the price went back to your balance.
• expired: no SMS in 20 minutes; the price went back to your balance automatically.

The price is calculated on our side at the moment of purchase; send max_price to refuse the purchase if the current price is higher than you expect.

Webhooks

Set an HTTPS URL on the API page of your dashboard and we POST sms.received as soon as we detect an SMS on a number you bought through the API (we retry once after 3 seconds if your server fails). Respond with any 2xx status.

{
  "type": "sms.received",
  "created_at": "2026-10-14T07:06:03Z",
  "data": {
    "number_id": "6026e15f-088d-45b5-bf22-70ed0b417afa",
    "phone": "12025550147", "service": "wa", "country": "us",
    "status": "received", "expires_at": "2026-10-14T07:25:10Z",
    "sms": { "code": "482915", "text": "Your WhatsApp code: 482-915", "received_at": "2026-10-14T07:06:02Z" }
  }
}

Every webhook carries X-NoirSMS-Signature: t=<unix time>,v1=<signature>, where the signature is the hex HMAC-SHA256 of "<t>.<raw body>" with your webhook secret (shown in the dashboard). Check it, and reject timestamps older than 5 minutes.

import crypto from 'node:crypto';

function verify(rawBody, header, secret) {
  const { t, v1 } = Object.fromEntries(header.split(',').map((p) => p.split('=')));
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
  const expected = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}

import hmac, hashlib, time

def verify(raw_body: bytes, header: str, secret: str) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    if abs(time.time() - int(parts["t"])) > 300:
        return False
    expected = hmac.new(secret.encode(), f"{parts['t']}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts["v1"])

Errors

Errors use the HTTP status code and a JSON body with a stable code you can switch on:

{ "error": { "code": "insufficient_balance", "message": "Insufficient balance. You need $0.73.", "needed": 0.73 } }

Limits & rules

• 120 requests per minute per key. Poll a number every 3 to 5 seconds, not faster.
• Each number is for one verification and stays reserved for 20 minutes. SMS only: no calls, no outgoing messages.
• Prices follow supply and demand and can change during the day; always read them from /services or use max_price.
• Use the API only for your own legitimate accounts or, as a reseller, for customers who follow the same Acceptable Use Policy. Bulk or automated account creation, spam, ban evasion and bypassing bank, fintech or identity (KYC) checks are prohibited and lead to account closure.

High volume

Buying numbers every day for your platform, panel or bot? Open a ticket in the Support area of your dashboard with your approximate monthly volume, the services and countries you use and what your platform does. We review each request and can offer special conditions for medium and high volume.

Ask for volume conditions