API reference.

# order a French mobile line for one month
curl -X POST https://api.nokycphone.com/v1/numbers \
  -H "Authorization: Bearer nkp_live_9f2c8a41d0b7e5…" \
  -H "Idempotency-Key: 7d1e4c22-90aa-4d1f-8b0e-1c2f9a55b311" \
  -H "Content-Type: application/json" \
  -d '{"country":"fr","type":"mobile","period":1,"label":"signups"}'

# 201 Created
{
  "id": "num_8f2c1a94",
  "e164": "+33647189022",
  "country": "fr",
  "type": "mobile",
  "status": "active",
  "label": "signups",
  "auto_renew": true,
  "created_at": "2026-09-21T09:14:02Z",
  "renews_at": "2026-10-21T09:14:02Z",
  "charged": { "monthly": 12.90, "activation": 10.00, "total": 22.90, "currency": "USD" },
  "balance_after": 77.10
}

# read the inbox, newest first — the code is already extracted for you
curl "https://api.nokycphone.com/v1/numbers/num_8f2c1a94/messages?limit=2" \
  -H "Authorization: Bearer nkp_live_9f2c8a41d0b7e5…"

# 200 OK
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "id": "msg_5b1f77c0",
      "direction": "inbound",
      "from": "Telegram",
      "to": "+33647189022",
      "body": "Your login code is 72194. Do not share it.",
      "code": "72194",
      "received_at": "2026-09-21T09:15:41Z"
    },
    {
      "id": "msg_5b1f7411",
      "direction": "inbound",
      "from": "+14155550142",
      "to": "+33647189022",
      "body": "Your verification code: 408-113",
      "code": "408113",
      "received_at": "2026-09-21T09:14:58Z"
    }
  ]
}

Authorization: Bearer nkp_live_9f2c8a41d0b7e5…

curl "https://api.nokycphone.com/v1/messages?limit=50&starting_after=msg_5b1f7411" \
  -H "Authorization: Bearer nkp_live_9f2c8a41d0b7e5…"

{
  "error": {
    "type": "balance_error",
    "code": "insufficient_balance",
    "message": "Your balance is 4.10 USD; this order costs 22.90 USD.",
    "param": null,
    "doc": "https://nokycphone.com/api/#billing"
  }
}

curl https://api.nokycphone.com/v1/countries \
  -H "Authorization: Bearer nkp_live_9f2c8a41d0b7e5…"

# 200 OK
{
  "object": "list",
  "data": [
    {
      "code": "fr",
      "name": "France",
      "dial": "+33",
      "region": "europe",
      "types": ["mobile", "landline"],
      "in_stock": true,
      "price": { "mobile": 12.90, "landline": 10.30, "activation": 10.00, "currency": "USD" },
      "premium_surcharge": 4.90
    }
  ]
}

curl "https://api.nokycphone.com/v1/numbers/available?country=de&type=mobile&premium=true" \
  -H "Authorization: Bearer nkp_live_9f2c8a41d0b7e5…"

# 200 OK
{
  "object": "list",
  "data": [
    { "e164": "+4915735550088", "pattern": "repeating", "surcharge": 4.90 },
    { "e164": "+4915735551234", "pattern": "sequential", "surcharge": 4.90 },
    { "e164": "+4915735557000", "pattern": "round", "surcharge": 4.90 }
  ]
}

# stop auto-renew, mask the caller ID, mute the line at night
curl -X PATCH https://api.nokycphone.com/v1/numbers/num_8f2c1a94 \
  -H "Authorization: Bearer nkp_live_9f2c8a41d0b7e5…" \
  -H "Content-Type: application/json" \
  -d '{"auto_renew":false,"mask_caller_id":true,"quiet_from":"23:00","quiet_to":"07:00"}'

curl "https://api.nokycphone.com/v1/messages?has_code=true&since=2026-09-21T00:00:00Z" \
  -H "Authorization: Bearer nkp_live_9f2c8a41d0b7e5…"

curl -X POST https://api.nokycphone.com/v1/messages \
  -H "Authorization: Bearer nkp_live_9f2c8a41d0b7e5…" \
  -H "Content-Type: application/json" \
  -d '{"from":"num_8f2c1a94","to":"+447700900123","body":"On my way."}'

# 202 Accepted
{
  "id": "msg_9c04ab71",
  "direction": "outbound",
  "status": "queued",
  "segments": 1,
  "charged": 0.08,
  "created_at": "2026-09-21T09:22:10Z"
}

curl https://api.nokycphone.com/v1/voicemails/vm_31d9f0a2 \
  -H "Authorization: Bearer nkp_live_9f2c8a41d0b7e5…"

# 200 OK
{
  "id": "vm_31d9f0a2",
  "number": "num_8f2c1a94",
  "from": "+33612345678",
  "duration": 34,
  "language": "fr",
  "transcript": "Bonjour, c'est le service livraison, votre colis arrive demain entre 9h et 11h.",
  "translation": "Hello, this is the delivery service, your parcel arrives tomorrow between 9 and 11.",
  "summary": "Delivery tomorrow, 09:00–11:00.",
  "audio_url": "https://api.nokycphone.com/v1/voicemails/vm_31d9f0a2/audio",
  "expires_at": "2026-10-21T09:14:02Z",
  "received_at": "2026-09-21T09:31:44Z"
}

# open a one-time deposit address for 50 USD in Monero
curl -X POST https://api.nokycphone.com/v1/topups \
  -H "Authorization: Bearer nkp_live_9f2c8a41d0b7e5…" \
  -H "Content-Type: application/json" \
  -d '{"amount_usd":50,"coin":"XMR"}'

# 201 Created
{
  "id": "top_4a91c7e2",
  "coin": "XMR",
  "address": "46BeWrHpwXm…",
  "amount_crypto": "0.2841",
  "amount_usd": 50.00,
  "rate_locked_until": "2026-09-21T10:05:00Z",
  "status": "waiting",
  "confirmations_required": 10
}

curl -X POST https://api.nokycphone.com/v1/webhooks \
  -H "Authorization: Bearer nkp_live_9f2c8a41d0b7e5…" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.org/hooks/nkp","events":["message.received","call.missed"]}'

# 201 Created
{
  "id": "whk_77c1e0",
  "url": "https://example.org/hooks/nkp",
  "events": ["message.received", "call.missed"],
  "secret": "whsec_2b91f4c7a0d3…",
  "created_at": "2026-09-21T09:40:00Z"
}

POST /hooks/nkp HTTP/1.1
Content-Type: application/json
X-NKP-Event: message.received
X-NKP-Delivery: evt_6f0b28d4
X-NKP-Timestamp: 1789033541
X-NKP-Signature: v1=6b3a1f8e7c0d94aa5e2b…

{
  "event": "message.received",
  "created_at": "2026-09-21T09:45:41Z",
  "data": {
    "id": "msg_5b1f77c0",
    "number": "num_8f2c1a94",
    "e164": "+33647189022",
    "from": "Telegram",
    "body": "Your login code is 72194. Do not share it.",
    "code": "72194",
    "received_at": "2026-09-21T09:45:41Z"
  }
}

import hmac, hashlib, time

def verify(secret, headers, raw_body):
    ts = headers["X-NKP-Timestamp"]
    if abs(time.time() - int(ts)) > 300:
        return False
    sent = headers["X-NKP-Signature"].split("=", 1)[1]
    mine = hmac.new(secret.encode(), f"{ts}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(sent, mine)

const nkp = (path, init = {}) =>
  fetch("https://api.nokycphone.com/v1" + path, {
    ...init,
    headers: { Authorization: `Bearer ${process.env.NKP_KEY}`, "Content-Type": "application/json", ...init.headers },
  }).then(async (r) => {
    const body = await r.json();
    if (!r.ok) throw new Error(body.error.code + ": " + body.error.message);
    return body;
  });

const line = await nkp("/numbers", { method: "POST", body: JSON.stringify({ country: "fr", type: "mobile" }) });
console.log(line.e164);

import os, requests

S = requests.Session()
S.headers["Authorization"] = "Bearer " + os.environ["NKP_KEY"]
BASE = "https://api.nokycphone.com/v1"

def nkp(method, path, **kw):
    r = S.request(method, BASE + path, timeout=15, **kw)
    if not r.ok:
        e = r.json()["error"]
        raise RuntimeError(f"{e['code']}: {e['message']}")
    return r.json()

line = nkp("POST", "/numbers", json={"country": "fr", "type": "mobile"})
print(line["e164"])