On this page

Building with an AI coding agent? Point it at /api.md (this page as Markdown) or /llms.txt, or add NOTIFY as an MCP server. To try the routes in your browser, use the interactive docs.

NOTIFY API reference

NOTIFY is a developer-first API for application-triggered SMS in Georgia. It is deliberately limited to transactional messages the recipient is expecting: today, verification, sign-in, and password-reset codes, each from a built-in template in Georgian or English. NOTIFY can also make the code, send it and check what the user types: see Verifications.

Private beta. Get a test key instantly with POST /v1/test-keys — no account needed. For a live key, sign in with GitHub or Google at n0t1fy.dev/login and create one on the dashboard. There is no billing API, campaign API, or sender-management API.

Start here

Environment Base URL Use
Production beta https://api.n0t1fy.dev Use with a key from POST /v1/test-keys or from your dashboard.
Local development http://127.0.0.1:8000 Start the service with the built-in fake provider.

Interactive documentation is available at <base URL>/docs, and the machine-readable OpenAPI document is at <base URL>/openapi.json.

Quick start examples: github.com/n0t1fy/examples has small Node, Python, and curl programs that send a code with a test key and poll it until it settles, with no SDK, and a phone verification form to copy: the page and its two server routes.

All public routes use JSON and are versioned under /v1. Health endpoints are documented separately below.

Integration contract for developers and coding agents

Before writing an integration, follow these rules:

  1. Use only the five public routes documented below: POST /v1/test-keys, POST /v1/messages, GET /v1/messages/{id}, POST /v1/verifications and POST /v1/verifications/{id}/check. An agent can also call the same five operations as tools of the MCP server. Live keys and credits are managed by a human on the dashboard; sender configuration, provider webhooks, and balance management are operator functions. None of them is an API route.
  2. Use an sk_test_… key first. If you have none, POST /v1/test-keys returns one instantly. Test keys always use the fake provider and never send a real SMS or spend credits.
  3. For each logical send, generate and persist one Idempotency-Key. Reuse that exact key only when retrying that same request: the same recipient, template, variables, and locale.
  4. Treat submitted as provider acceptance, not handset delivery. When the workflow needs a final outcome, poll GET /v1/messages/{id} while the status is queued or submitted, and stop at any other status or at your own time limit (see When to stop polling).
  5. If a create call returns a message with unknown, do not automatically send it again: the provider may have received the first request. Preserve the message ID and reconcile before any manual retry.
  6. Never expect a message response to echo its text or full recipient number. Store the information your application needs before calling the API.
  7. To verify a phone number, let NOTIFY make and check the code (Verifications). Let the user in only when a check answers 200 with status approved; treat every other answer, a timeout and a network error as not approved. Branch on error.code, never on the HTTP status alone.

How to read a send result

An HTTP 2xx means the message record exists, not that the SMS arrived. Always read status in the body:

HTTP status in the body What it means What to do
201 submitted The provider accepted it. It is not yet confirmed on the phone. Store the id. Poll if you need the final outcome.
201 failed The provider refused it. Nothing will be delivered. Read error; fix the cause before a new send.
201 unknown It may or may not have been sent. Do not retry automatically.
200 any A replay: this exact request was already processed. Use the original message; no second SMS was sent.
503 — (provider_unavailable) Nothing was sent. Safe to retry with the same Idempotency-Key.
no answer, or another 5xx — It may or may not have been sent. Retry the same request with the same Idempotency-Key; never send a new code automatically.
other 4xx — Nothing was sent. Read error.message: it says what to change.

NOTIFY does not call your application when a status changes: there are no webhooks to customers yet. To learn the final outcome, poll GET /v1/messages/{id}: start after about 2 seconds and double the wait each time, up to 30 seconds between reads. Test messages usually settle within about 30 seconds; a live delivery confirmation usually arrives within seconds but can take minutes.

When to stop polling

Authentication and key modes

Send every message request with:

Authorization: Bearer sk_test_…

Keys are project-scoped. A key can access only the messages created by its own project.

Key prefix Delivery behavior
sk_test_ Uses the built-in fake provider. No SMS is sent.
sk_live_ Uses the configured live delivery provider. Only use for consented, transactional recipient-expected messages.

Treat a key as a password. Do not put it in browser code, source control, logs, issue trackers, or agent prompts that may be retained. A key is shown only once, when it is created; if one is exposed, revoke it on your dashboard and create another.

Quickstart: create and retrieve a test message

Replace YOUR_TEST_API_KEY with an sk_test_… key, from POST /v1/test-keys or from your dashboard. The idempotency value shown here is an example; generate a new unique value for each logical message.

curl -X POST https://api.n0t1fy.dev/v1/messages \
  -H 'Authorization: Bearer YOUR_TEST_API_KEY' \
  -H 'Idempotency-Key: 2a4370b5-26a4-4485-b9bf-8113a053b8bc' \
  -H 'Content-Type: application/json' \
  --data '{
    "to": "+995591234567",
    "template": "verification_code",
    "variables": { "code": "482913" }
  }'

A newly created message returns 201 Created:

{
  "id": "msg_01J…",
  "object": "message",
  "to": "+9955••••••67",
  "status": "submitted",
  "segments": 1,
  "error": null,
  "created_at": "2026-09-04T09:15:30Z",
  "updated_at": "2026-09-04T09:15:31Z"
}

Use the returned ID to retrieve the same project’s message:

curl https://api.n0t1fy.dev/v1/messages/msg_01J… \
  -H 'Authorization: Bearer YOUR_TEST_API_KEY'

With a normal fake-provider recipient, the message usually becomes delivered within about 30 seconds: the simulated confirmation is ready after about five seconds, and the service applies it on its next periodic status check. Poll with a growing wait and a time limit (see How to read a send result); do not code against a fixed number of seconds.

Get a test key

POST /v1/test-keys

Issues a test API key immediately. No authentication, no account, and no browser step — this exists so an AI coding agent can start on its own.

curl -X POST https://api.n0t1fy.dev/v1/test-keys
{
  "api_key": "sk_test_8PIL8xQvWtNOG1mFjJeBz29uo5ODR8Pc",
  "project_id": "proj_01J…",
  "mode": "test",
  "claim_url": "https://n0t1fy.dev/claim/…",
  "expires_at": "2026-10-16T09:15:30Z",
  "next_steps": "Send with: POST /v1/messages, header 'Authorization: Bearer <api_key>' …"
}

The key is shown once and uses the built-in fake provider: it never delivers a real SMS and never spends credits, so the magic recipients below are the whole behaviour. Requests are limited in two ways. On 429 rate_limited (too many from your address this minute), wait a minute before trying again. On 429 daily_limit_reached (today's instant test keys are used up, either your address's daily share or everyone's daily allowance), do not retry before the reset time named in the message, midnight UTC; keep using a key you already have, and a human can still sign in and create a test key on the dashboard meanwhile.

A human can take over your test project: they open claim_url in a browser, sign in with GitHub or Google, and confirm. Anyone who opens it, signs in and confirms becomes the owner: give it only to the person who will own the project, and do not paste it into shared logs or tickets. The project, your key and the messages you sent with it then belong to their account, and your key can still read those messages. Your key stays a test key: it keeps working, and it still never sends a real SMS. To send real messages, the human creates an sk_live_ key on the dashboard and your code switches to it. A claim by someone with no account yet gives their new account its free credits; a claim into an account they already have adds none, and ends a verification code still pending in your project (a check of it then answers verification_closed: start a new one). The link works once, and stops working after 30 days (expires_at) if nobody uses it; the key itself is not affected. Messages of a project nobody claims are deleted 30 days after they were sent.

MCP server

AI coding agents that speak the Model Context Protocol (Claude Code, Codex, Cursor and others) can use NOTIFY as a tool. The server is hosted, so there is nothing to install.

The tools do what the five routes on this page do, with the same checks, limits, credits and error codes. send_message returns {"replayed": …, "message": …}, where message is the message object and replayed: true matches a 200 replay; get_message returns the message object. start_verification returns {"replayed": …, "verification": …} with the verification object; check_verification returns the verification only when it is approved, and every other outcome is a tool error. A tool error carries the same code, message and request_id as the API's error format. Creating and revoking live keys is not a tool: a human does that on the dashboard.

The tools are for trying NOTIFY and checking messages while you build. Your application's own code calls the HTTP API, with the key from its configuration.

Without a key. Add the server with no header. The agent calls create_test_key and passes the sk_test_ key it gets as the api_key argument of the other tools. Test keys never send a real SMS.

claude mcp add --transport http notify https://api.n0t1fy.dev/mcp

Then ask your agent to get a NOTIFY test key and send a test code to +995512345670. Add --scope user to claude mcp add to have NOTIFY in every project.

With a key. Put the key in the connection's header. This is the only way to use a live key: an sk_live_ key passed as a tool argument is refused, because tool arguments are kept in the conversation. With a live key in the header, send_message and start_verification send real SMS and spend credits, so most developers only need a test key here.

Claude Code reads a project's .mcp.json and fills ${NOTIFY_API_KEY} from the environment, so the key stays out of the file:

{
  "mcpServers": {
    "notify": {
      "type": "http",
      "url": "https://api.n0t1fy.dev/mcp",
      "headers": { "Authorization": "Bearer ${NOTIFY_API_KEY}" }
    }
  }
}

A server in a project's .mcp.json waits for approval: run claude once and approve it.

Codex, in ~/.codex/config.toml, without a key:

[mcp_servers.notify]
url = "https://api.n0t1fy.dev/mcp"

or from a terminal: codex mcp add notify --url https://api.n0t1fy.dev/mcp. With a key, name the environment variable that holds it:

[mcp_servers.notify]
url = "https://api.n0t1fy.dev/mcp"
bearer_token_env_var = "NOTIFY_API_KEY"

or codex mcp add notify --url https://api.n0t1fy.dev/mcp --bearer-token-env-var NOTIFY_API_KEY. Codex refuses to start the server when that variable is unset or empty, so use the setting without a key until the variable holds one.

Any other client that supports Streamable HTTP and a custom header works with the same URL and header.

Credits and limits

Live sends spend credits; test sends never do. One credit is one SMS segment — the segments field of the message — and a live send reserves its credits before it reaches the provider:

Four per-minute limits apply to every key, test keys included, and nothing is sent, spent or issued when one is used up. The answer is 429 rate_limited, whose message names the limit that tripped and when the minute ends (also in the Retry-After header and retry_at; see Error format):

A retry with the same Idempotency-Key and body is never refused by these limits: it is answered with the original message. The per-number cap on verifications (5 an hour and 10 in a rolling 24 hours, 429 too_many_verifications) is described under Start a verification, and the 30 team alerts an hour to one number under Team alerts.

We also watch for unusual traffic: a sudden rise in a project's or a key's live sends compared with its usual rate, repeated requests with invalid keys, the per-minute limits hit again and again, verification codes that look guessed (many wrong codes, or verifications ended by five wrong codes), and a live key's team alerts refused again and again for numbers not on the team. These alert the operator, who contacts the project's owner where there is one; they block nothing by themselves.

Prices

For the human who pays (prices in GEL, VAT included):

Every template renders to one segment in Georgian and in English, so one credit is one SMS. There is no API for billing; the dashboard explains how to pay.

Create a message

POST /v1/messages

Creates, records, and attempts to submit one transactional message.

Required headers

Header Value
Authorization Bearer <API_KEY>
Idempotency-Key A non-empty value of 200 characters or fewer, unique per logical send.
Content-Type application/json

Request body

{
  "to": "+995591234567",
  "template": "verification_code",
  "variables": { "code": "482913" },
  "locale": "ka"
}
Field Required Rules
to Yes A Georgian mobile number in the exact E.164 form +9955 followed by eight digits. Do not omit +, add spaces, or send another country’s number.
template Yes One of the template ids below. Message text is never free-form. A team template goes only to a number confirmed on the project's team (Team alerts).
variables Yes An object with exactly the template's variables, every value a JSON string ("0451", not 451, so leading zeros survive).
locale No ka (Georgian, the default) or en.

No other fields are accepted — in particular there is no text field.

Templates

Every message is rendered from a built-in template, and messages are sent under the shared sender name NOTIFY (unless the team has approved a sender of its own for your project). This is what keeps a shared sender trustworthy: nobody can send arbitrary text under it.

template Goes to Variables en ka Segments (en / ka)
verification_code any number code Your verification code is {code}. Do not share it with anyone. თქვენი დამადასტურებელი კოდია {code}. არავის გაუზიაროთ. 1 / 1
login_code any number code Your sign-in code is {code}. If you did not request it, ignore this message. შესვლის კოდი: {code}. თუ არ მოგითხოვიათ, გამოტოვეთ ეს შეტყობინება. 1 / 1
password_reset_code any number code, minutes Your password reset code is {code}. It expires in {minutes} minutes. პაროლის აღდგენის კოდი: {code}. მოქმედებს {minutes} წუთი. 1 / 1
service_down your team only service Alert: {service} is down. გაფრთხილება: {service} არ მუშაობს. 1 / 1
service_up your team only service Resolved: {service} is up again. აღდგა: {service} ისევ მუშაობს. 1 / 1
incident_opened your team only incident Urgent: incident {incident} needs attention. სასწრაფო: ინციდენტი {incident} ყურადღებას საჭიროებს. 1 / 1
support_ticket_urgent your team only ticket Urgent: support ticket {ticket} is waiting for a reply. სასწრაფო: მხარდაჭერის მოთხოვნა {ticket} პასუხს ელოდება. 1 / 1
job_failed your team only job Failed: scheduled job {job} did not finish. შეცდომა: დაგეგმილი ამოცანა {job} ვერ დასრულდა. 1 / 1
agent_alert your team only agent, count {agent}: {count} new updates. Check your app. ("1 new update" for a count of 1) {agent}: {count} ახალი განახლება. შეამოწმეთ აპლიკაცია. 1 / 1

Every template, its blanks and an example request are also on /templates, a page built from the list the API itself uses.

Variable rules:

A refused template or variable returns 400 with invalid_template or invalid_variables and a message naming exactly what to change. Credits are charged per segment of the rendered text, and the response reports segments.

No other fields are accepted. In particular, from is not a public request field: the sender is NOTIFY unless the team has approved another for your project, and a caller can never choose it.

Success responses

HTTP status Meaning
201 Created This is a new message submission attempt. The returned object can have submitted, failed, or unknown status depending on the provider outcome.
200 OK The same idempotency key and identical request were already processed. The response is the original message, not a second send.

Message object

{
  "id": "msg_01J…",
  "object": "message",
  "to": "+9955••••••67",
  "status": "submitted",
  "segments": 1,
  "error": null,
  "created_at": "2026-09-04T09:15:30Z",
  "updated_at": "2026-09-04T09:15:31Z"
}
Field Description
id Opaque message identifier. Store this to retrieve the status later.
object Always message.
to Masked recipient: country code and first digit plus the final two digits. The full number is never returned.
status One of the normalized statuses in Message status.
segments How many SMS segments the message occupies — the unit the provider bills. null only for messages created before segment counting existed.
error null or a safe { "code", "message" } object. Provider internals are not exposed.
created_at ISO 8601 UTC time when the record was created.
updated_at ISO 8601 UTC time of the latest recorded update.

The API never returns message text, an unmasked recipient, a provider message ID, or raw provider status.

A definitive provider rejection

A provider can reject a message after the request has passed API validation. That is still a successfully created API resource, so the response is 201 Created with an honest message state—not an HTTP transport failure:

{
  "id": "msg_01J…",
  "object": "message",
  "to": "+9955••••••01",
  "status": "failed",
  "segments": 1,
  "error": {
    "code": "provider_rejected",
    "message": "The delivery provider rejected the message."
  },
  "created_at": "2026-09-04T09:15:30Z",
  "updated_at": "2026-09-04T09:15:31Z"
}

Team alerts

The team templates (service_down, service_up, incident_opened, support_ticket_urgent, job_failed, agent_alert) text your own team when something needs a human: a service is down, an incident or ticket is urgent, a scheduled job failed, your AI agent has updates. They go only to numbers confirmed on your project's team, so they can never reach a stranger.

Adding a number is done on the dashboard, by the project's signed-in owner: never through the API or MCP, so a stolen key cannot add anyone.

  1. Open the dashboard's team page, type the number and, optionally, a name for the person ("Giorgi, on call"), and pick the language of the code SMS.
  2. NOTIFY texts the number a code: "NOTIFY team alerts: code 482913. Share it only if you agreed to receive them." It costs 1 credit and shows in your message log. Tell the person the code comes from you: the SMS cannot name you, because NOTIFY's messages never carry words of its customers.
  3. The person reads the code to you, and you type it in beside the number within 10 minutes (5 tries). The number is then confirmed.

A team holds at most 10 numbers, confirmed or waiting. At most one code a minute and five an hour go to one number, and 20 a day per project. A number still waiting a day later is removed.

The service and job names a live key may use are a list you keep on the same page, up to 20 names: the API picks one and never writes its own. A name not on the list answers 400 invalid_variables; add it on the team page first.

Sending is the usual POST /v1/messages:

curl https://api.n0t1fy.dev/v1/messages \
  -H "Authorization: Bearer $NOTIFY_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"to": "+995591234567", "template": "service_down", "variables": {"service": "payments-api"}, "locale": "en"}'
Key to Answer
live a number confirmed on the key's project's team 201, sent and charged
live any other number: waiting for its code, not on the team, another project's, or a test number 403 recipient_not_on_team, nothing sent or charged
test a test number, +995512345670 to +995512345679 201, simulated
test any other number, a confirmed number of the project included 403 recipient_not_on_team

Leaving a team. A person who no longer wants a project's alerts writes to contact@n0t1fy.dev, and we remove the number. There is no way to reply STOP by SMS.

Retrieve a message

GET /v1/messages/{message_id}

Returns the current normalized representation of a message when it belongs to the authenticated project.

Required header

Authorization: Bearer <API_KEY>

200 OK returns the same Message object shape used by creation. A message that does not exist or belongs to another project returns 404 message_not_found; this prevents cross-project message enumeration.

The dashboard's message log (/dashboard/messages, behind the sign-in) lists the project's messages and verifications with the same fields and the same masked numbers, plus the key that sent each one, test or live, and each message's template and language, and finds one by its id.

Message status

Status Meaning Recommended application behavior
queued The message record exists and is waiting for a submission attempt. Read again shortly. This is normally brief: if NOTIFY could not record the provider's answer, the message becomes unknown (with internal_error) after about five minutes.
submitted The delivery provider accepted the submission. Handset delivery is not yet confirmed. Record the ID and poll when a final result matters.
delivered A reliable provider confirmation says the message reached delivery. Terminal success.
undeliverable A reliable provider terminal result says the SMS could not be delivered. Terminal non-delivery; inspect error.
failed The service or provider definitively rejected or failed the submission. Inspect error and correct the cause before a new logical send.
unknown The provider did not return a definitive submission result, or NOTIFY could not record it; the SMS may or may not have been sent. Do not automatically retry. Avoiding duplicate SMS takes priority.

Only delivered and undeliverable claim a reliable final delivery outcome. submitted is intentionally not a delivery claim.

Verifications

NOTIFY makes a random six-digit code, sends it by SMS with one of the code templates, and checks the code the user types. The code is never shown to your application, never logged and never stored: NOTIFY keeps only a keyed hash of it (an HMAC), and only until the verification ends, or at most about an hour after the code expires (an hourly task erases the hash of an expired code). A code works for 10 minutes and 5 checks, once. A new start for the same number replaces the previous code, so only the newest one works.

Two routes:

  1. POST /v1/verifications sends a code to a number and answers with a verification id.
  2. POST /v1/verifications/{id}/check checks the code the user typed, for the number it was sent to.

Let the user in only when a check answers 200 with status approved; treat every other answer, a timeout and a network error as not approved. Every other answer of a check is an error (4xx or 5xx), so an application that only asks "did the request succeed?" can never let a wrong code through. Branch on error.code, never on the HTTP status alone.

Start a verification

POST /v1/verifications, with the same Authorization and Idempotency-Key headers as creating a message.

{ "to": "+995591234567", "template": "verification_code", "locale": "ka" }
Field Required Rules
to Yes The number to verify: +9955 followed by eight digits. With a test key, only the test numbers.
template No verification_code (the default), login_code or password_reset_code. NOTIFY fills in the code, and minutes with 10.
locale No ka (Georgian, the default) or en.

No other fields are accepted: there is no code or variables field, because NOTIFY makes the code.

HTTP What it means What to do
201, status: "pending" The code was sent (read message.status: submitted, or unknown if the SMS may or may not have arrived). Store the id, and show the code entry field at once: do not wait for delivered.
201, status: "failed" The provider refused the SMS; error says why. Nothing will arrive. Show a general error and log the id; offer to try again.
201, status: "canceled" Rare: a newer start for the same number (a double click, say), or a claim of the project, ended this code while this start was in flight. A replayed start can even show approved. Act only on a check's 200: a start's own status never lets anyone in. Offer a new code.
200 A replay: this Idempotency-Key and body were already processed, and no second SMS was sent. Use the verification as it is now. It may say approved by then: that is not a check result.
400 Invalid body, number or template; or test_number_required: a test key with a number that is not a test number. Fix the request.
402 insufficient_credits: a live key's project has no credit left. Nothing was sent. The owner adds credits.
409 idempotency_key_reused: the same key with a different body. Use a new key.
429 too_many_verifications: this number had 5 verifications in the last hour, or 10 in the last 24 hours, from your project; the message says when the next is allowed. rate_limited, daily_limit_reached: as for messages. Nothing was sent. Wait, and tell the user when they can ask again.
503 provider_unavailable: nothing was sent; retry with the same Idempotency-Key. verifications_disabled: switched off by the operator.

A start costs one credit with a live key, like the SMS it sends. The per-number limits count every verification whose SMS went out, however it ended; one whose SMS was never sent (refused, or the provider unreachable) does not count. They are per project: one project's verifications never limit another's.

Check a code

POST /v1/verifications/{id}/check, with the Authorization header.

{ "to": "+995591234567", "code": "482913" }

to is required on purpose: it is the number your application is about to mark as verified, and NOTIFY confirms the code was sent to exactly that number. code is the six digits the user typed, as a JSON string; surrounding spaces are trimmed.

Answer HTTP When What to do
approved (the verification object) 200 The right code, for the same number, within 10 minutes, with attempts left, never used before Let the user in, or mark the number verified
incorrect_code 422 A wrong code; attempts remain (the message says how many) "Wrong code, try again"
too_many_attempts 422 A wrong code that was the fifth, or any check after the fifth Offer a new code
recipient_mismatch 422 to is not the number the code was sent to. It costs an attempt, and the code is not compared A bug or an attack: show a general error and log the request_id
verification_expired 410 More than 10 minutes after the start Offer a new code
verification_closed 409 Already approved, replaced by a newer code, or its SMS was never sent Offer a new code
verification_not_found 404 Unknown id, or another project's A bug
invalid_request 400 A malformed body, or a code that is not six digits written as a string. No attempt is spent Fix the request
invalid_recipient 400 to is not +9955 and eight digits. No attempt is spent Fix the request
rate_limited 429 More than 120 checks a minute in your project Wait a moment
verifications_disabled 503 Switched off by the operator Nobody is let in until it is back
unauthorized, invalid_api_key, project_suspended 401, 403 As for every route
internal_error 500 Anything unexpected Not approved

A check is not idempotent, and an Idempotency-Key sent with it is ignored. If a check's answer is lost, the attempt may have approved the code, which then cannot be used again: ask the user for a new code. Do not retry a check by yourself: every check spends an attempt, and five close the verification.

The verification object

{
  "id": "ver_01J8XW7K2N9P4Q6R8S0T2V4W6X",
  "object": "verification",
  "to": "+9955••••••67",
  "status": "pending",
  "template": "verification_code",
  "locale": "ka",
  "attempts_remaining": 5,
  "expires_at": "2026-10-20T09:25:30Z",
  "approved_at": null,
  "error": null,
  "message": { "id": "msg_01J…", "object": "message", "to": "+9955••••••67", "status": "submitted", "segments": 1, "error": null, "created_at": "2026-10-20T09:15:30Z", "updated_at": "2026-10-20T09:15:31Z" },
  "created_at": "2026-10-20T09:15:30Z",
  "updated_at": "2026-10-20T09:15:31Z"
}
Field Description
status pending until a check approves it or it ends: approved, failed (five wrong attempts, or its SMS was never sent), expired or canceled (replaced by a newer code, or ended by a claim). Only pending changes; a pending verification past expires_at is shown as expired.
attempts_remaining Checks left: 5 at the start, one fewer for each wrong code, and 0 once the verification is no longer pending (approved, expired, canceled, or ended by wrong codes).
expires_at 10 minutes after the start request.
error null, or { "code", "message" }: too_many_attempts, replaced, project_claimed, or the error of the SMS when it was never sent (provider_rejected, provider_unavailable, …).
message The message object of the SMS that carried the code. Read its delivery with GET /v1/messages/{message.id} and the usual polling rules.

No answer ever holds the code, its hash, the full number or provider internals. There is no route that reads a verification later, apart from a replay of its start within 24 hours: decide on the check's own answer.

Test keys and test numbers

With a test key, a verification can only go to the test numbers +995512345670 to +995512345679, and their code is always 000000. Nothing is sent and nothing is charged. A test key with any other number gets 400 test_number_required, so a test key left in production lets no real number in; the test numbers still pass with 000000: never deploy a test key. A live key never gets the fixed code, test numbers included.

A test key checks only verifications a test key started, and a live key only those a live key started: a check with a key of the other mode answers 404 verification_not_found, whatever the verification's state, and spends nothing. The same code starts and checks with one key, so nothing is lost; what it closes is a test key, which cannot start a verification to a real number, guessing against a project's live codes.

Everything else behaves as with a live key, so you can try every branch: 123456 gives incorrect_code, five wrong codes give too_many_attempts, a second 000000 gives verification_closed, another test number in to gives recipient_mismatch. The SMS of +995512345671 to +995512345674 follows the test-mode scenarios. The per-minute limit of 5 sends a minute per number applies to the test numbers too: spread test starts over the ten numbers, or wait a minute. Test keys are not held to the per-number limits.

curl -X POST https://api.n0t1fy.dev/v1/verifications \
  -H 'Authorization: Bearer YOUR_TEST_API_KEY' \
  -H 'Idempotency-Key: 7f6c1f0e-2a59-4c55-8b43-5c2a1e0c9d11' \
  -H 'Content-Type: application/json' \
  --data '{ "to": "+995512345670" }'
curl -X POST https://api.n0t1fy.dev/v1/verifications/ver_01J…/check \
  -H 'Authorization: Bearer YOUR_TEST_API_KEY' \
  -H 'Content-Type: application/json' \
  --data '{ "to": "+995512345670", "code": "000000" }'

The first answers 201 with status: "pending"; the second 200 with status: "approved", and the same check again 409 verification_closed.

What a verification cannot do

NOTIFY tells you whether the code typed matches the code it sent to that number; your application decides whom to let in and what else to require. An SMS code shows that someone could read an SMS sent to the number: it does not protect against a SIM swap, a stolen or shared phone, or a user who hands the code to someone else. Limit how often a user, an account and an address may ask for codes in your own application as well: the per-number limits above stop a flood of SMS to one person, not someone guessing across many accounts.

Handling limits in your sign-in form

The limits are meant to be met by an abuser, not seen by a user. A few rules keep the form calm when one trips:

An example form, in Node with no packages, is in the examples repository: verify-form. It keeps the key on the server and the number in the session, keeps its own limits, waits before a new code with a countdown on its button, and gives the user one sentence per case, in English or Georgian; the way out (a support link, another way to sign in) is yours to add.

Suggested wording for the user, to adapt to your product's voice:

When English Georgian
A code was sent We sent a code to your phone. Enter it below. კოდი თქვენს ტელეფონზე გავაგზავნეთ. შეიყვანეთ ქვემოთ.
incorrect_code That code is not right. Check it and try again. კოდი არასწორია. გადაამოწმეთ და სცადეთ თავიდან.
verification_expired, verification_closed, too_many_attempts That code no longer works. Ask for a new one. ეს კოდი აღარ მუშაობს. მოითხოვეთ ახალი.
too_many_verifications Too many codes were requested for this number. You can ask for a new one in {minutes} minutes. ამ ნომერზე ძალიან ბევრი კოდი იქნა მოთხოვნილი. ახლის მოთხოვნას {minutes} წუთში შეძლებთ.
Anything else (a 5xx, a timeout) Something went wrong on our side. Try again in a moment, or contact support. ჩვენს მხარეს შეცდომა მოხდა. სცადეთ ცოტა ხანში, ან დაგვიკავშირდით.

Checking codes

Let NOTIFY do it: Verifications make, send and check the code, with the expiry, the attempt limit and the single use built in. This guide is for applications that make their own codes and send them with POST /v1/messages.

With POST /v1/messages, NOTIFY only delivers the code: your application creates, stores and checks it, in four parts.

  1. Create the code with a cryptographically secure generator: crypto.randomInt in Node, the secrets module in Python, never Math.random or Python's random. Six digits is usual; the templates accept 4 to 8.
  2. Store only a hash of it. Use an HMAC, a hash keyed with a secret only your server knows: a six-digit code has a million possible values, so a plain hash of it is easy to reverse. Keep the hash with the user it belongs to, the number it was sent to, what it is for (sign-in, verification or password reset), when it expires (about ten minutes; with password_reset_code, pass the same number as minutes), and a count of wrong attempts. A new code replaces the previous one for the same user and purpose.
  3. Limit how often you send. Every live SMS costs a credit, and a form that sends a code on request can be abused to send hundreds. Allow, for example, one code per phone number per minute and five per hour, and limit requests per user and per IP address as well. NOTIFY's own per-minute limits stop a runaway loop, but they allow far more codes than a person needs.
  4. Check what the user types. Compute the HMAC of the typed code and compare it with the stored one in constant time: crypto.timingSafeEqual in Node, hmac.compare_digest in Python. Reject a code that has expired, was made for another purpose, or is checked for a phone number other than the number it was sent to. After five wrong attempts, say, discard the code, so the user has to ask for a new one. On success, delete the code at once, so it works only once, and treat as verified only the number it was sent to.

Show the code entry field as soon as the send returns 201 (or 200, when a retry with the same Idempotency-Key gets the original message) with queued, submitted, unknown or delivered: the SMS often arrives before its delivery confirmation does, so do not wait for delivered. Use the status to explain a problem instead. After undeliverable, or failed with invalid_recipient, ask the user to check the number. Any other failed code (provider_rejected, sender_not_allowed, invalid_message, internal_error) is a problem on your side or NOTIFY's, not the user's: show a general error and log the message id and its error. Offer a "send a new code" button, which counts against the limits in step 3. Never send a new code automatically after unknown.

Idempotency and retry safety

The idempotency key belongs to a project and a key mode, and is compared with the exact to, template, variables, and locale request values. Test and live keys never share idempotency: a live send that reuses a key from a test rehearsal is a new live send, never a replay of the test message.

Situation HTTP result What to do
A network failure leaves your client unsure whether it received the response Unknown to the client Retry the same request with the same key. If the service processed it, it returns the original message with 200.
Same key, same recipient, template, and variables 200 Use the original message; do not create another send.
Same key, different recipient, template, or variables 409 idempotency_key_reused Generate a new key for the new logical message.
503 provider_unavailable 503 The service verified that the provider did not take the request (it was unreachable or answered that it was busy). It is safe to retry the same request.
A 201 message whose status is unknown 201 Do not retry automatically: submission may have occurred.

A retry with the same key and the identical request is answered with the original message even when a per-minute limit is used up, and it does not count against those limits: only a new send can get 429 rate_limited.

Idempotency records are currently retained for 24 hours. Treat that as a safety window, not permission to reuse one key for a later business event.

Error format

Every API error uses this envelope and includes a request ID:

{
  "error": {
    "code": "invalid_recipient",
    "message": "The recipient must be a Georgian mobile number in E.164 format: +9955XXXXXXXX.",
    "request_id": "req_01J…"
  }
}

The same ID is returned in the X-Request-Id response header. Provide it when asking for support; it is safe to share, unlike an API key, message body, or full phone number.

Every 429 (rate_limited, too_many_verifications, daily_limit_reached) also says when its limit frees, twice: a Retry-After header with the whole seconds to wait (rounded up, at least 1), and a retry_at field inside error with the same moment in ISO 8601 UTC, Z suffix. Do not retry before it; a sign-in form can count down to it (see Handling limits in your sign-in form). No other error has either.

{
  "error": {
    "code": "too_many_verifications",
    "message": "This number has had 5 verifications from this project in the last hour, the most it may. Do not start another before 2026-10-16T13:00:01Z. Nothing was sent or charged.",
    "request_id": "req_01J…",
    "retry_at": "2026-10-16T13:00:01Z"
  }
}
HTTP Code Meaning and next step
400 invalid_request The JSON body or a request value is invalid, unexpected, or malformed. Correct the supplied request.
400 invalid_recipient Send only the documented +9955XXXXXXXX Georgian mobile format.
400 invalid_template The template id is unknown. The message lists the valid ids.
400 invalid_variables A variable is missing, unexpected, not a string, the wrong shape, or looks like a link or phone number. The message names the variable and gives a valid example.
400 invalid_message The rendered text is empty or too long. The built-in templates never are.
400 idempotency_key_required Add a unique Idempotency-Key header.
400 test_number_required A test key can start a verification only to +995512345670 to +995512345679. Use one of them, or a live key.
401 unauthorized Supply Authorization: Bearer <API_KEY>.
401 invalid_api_key The key is malformed, unknown, or revoked. Obtain a valid current key.
402 insufficient_credits A live key's project has too few credits for this message, or its subscription has ended and the credits left expired; nothing was sent. The project owner adds credits or renews (the dashboard explains how). Test keys keep working.
403 project_suspended The project cannot send at present. Contact the operator.
403 recipient_not_on_team A team template (team alerts) went to a number not confirmed on this project's team, or, with a test key, to a number other than the test numbers. Nothing was sent or charged. Ask the project's owner to add and confirm the number on the dashboard's team page; never retry it as it is.
404 message_not_found The ID is absent or is owned by a different project. Do not retry with another project’s key.
404 verification_not_found The verification ID is absent or is owned by a different project.
409 idempotency_key_reused Use a new key for a changed recipient, template, or variables.
409 verification_closed The verification was already approved, replaced by a newer code, or its SMS was never sent. Do not let the user in; offer a new code.
410 verification_expired The code is more than 10 minutes old. Offer a new code.
422 incorrect_code The code is wrong; the message says how many attempts are left. Ask the user again; do not retry by yourself.
422 too_many_attempts Five wrong attempts: the code no longer works. Offer a new code.
422 recipient_mismatch The check named another number than the one the code was sent to. The attempt is spent.
429 rate_limited A per-minute limit is used up, or the 30 team alerts an hour to one number; the message names it. Nothing was sent. Wait until retry_at, then retry with the same logical-send idempotency key.
429 too_many_verifications This number had 5 verifications in the last hour, or 10 in the last 24 hours, from your project. Nothing was sent; the message and retry_at say when the next is allowed.
429 daily_limit_reached A daily limit is used up: the free tier's segments (nothing was sent; a subscription removes the limit), or today's instant test keys from POST /v1/test-keys (your address's share, or everyone's). Do not retry before retry_at, the reset time named in the message (midnight UTC).
503 provider_unavailable The provider was unreachable or busy and nothing was sent; retrying is safe.
503 verifications_disabled The operator switched verifications off: no code is started or checked, so nobody is let in. Sending messages still works.
500 internal_error An unexpected service error occurred. For a send, retry it cautiously with the same key and provide the request ID if it continues. For a check, it is never an approval, and a check is never retried: ask the user for a new code.

Some provider outcomes appear inside a 201 Message object’s error field rather than this HTTP error envelope. Possible safe codes include provider_rejected, sender_not_allowed, invalid_message, invalid_recipient, and internal_error.

Test-mode scenarios

Use these recipient values with an sk_test_… key to verify how your integration handles outcomes. They are simulator controls only; no SMS is sent.

Recipient Initial API result Later result / safe action
+995512345671 201 message with failed / provider_rejected Definitive simulated provider rejection.
+995512345672 503 provider_unavailable The request is retry-safe.
+995512345673 201 message with unknown / provider_unavailable Simulated ambiguous result; do not automatically retry.
+995512345674 201 message with submitted Becomes undeliverable within about 30 seconds.
Any other valid Georgian mobile number 201 message with submitted Becomes delivered within about 30 seconds.

Both later outcomes take the same path and the same time: about five seconds of simulated delay, then the service's next periodic status check. A test message that is still submitted after 10 seconds is not stuck; one still submitted after two minutes is unusual (see When to stop polling).

A team template with a test key goes to the test numbers +995512345670 to +995512345679 only; its simulated outcomes are those above.

For verifications, a test key uses the test numbers +995512345670 to +995512345679, whose code is always 000000 (Test keys and test numbers). A start to +995512345671 answers 201 with a failed verification; to +995512345672, 503 provider_unavailable (retry with the same key); to +995512345673, a pending verification whose SMS is unknown, and 000000 still works.

Until 15 October 2026 the test numbers were +995 500 000 000 to +995 500 000 009 (written with spaces here, so that nothing copies them). Part of that block turned out to be allocated to an operator, so they are ordinary numbers now: a test key's message to one of them is accepted like any other (no simulated outcome), and a test key's verification to one of them gets 400 test_number_required.

Health endpoints

These endpoints do not require an API key and return no secret configuration.

People can follow uptime and incidents on the status page, status.n0t1fy.dev, which is hosted separately and stays up when the service is down.

Route 200 response Failure behavior
GET /healthz { "status": "alive" } Process liveness only.
GET /readyz { "status": "ready", "database": "ok" } Returns 503 with { "status": "not_ready", "database": "unreachable" } when the database cannot be reached.

Local development

The repository can bootstrap a complete fake-provider environment, including a new test key:

python3 -m venv .venv
.venv/bin/pip install -e ".[dev]"
.venv/bin/python scripts/bootstrap_dev.py
.venv/bin/uvicorn app.main:create_app --factory --reload

The bootstrap script creates a local .env, runs migrations, creates a demo project, and prints a test key. It defaults to the fake provider. Under the fake provider no SMS arrives, so a team number's code cannot reach anyone and no number can be confirmed locally: build team alerts with a test key and the test numbers. Never enable the live provider or the opt-in end-to-end test unless you are authorized to send a controlled message to a consenting recipient.

Scope and data handling

This API does not support marketing campaigns, bulk sends, contact lists, scheduled messaging, inbound SMS, two-way conversations, customer-facing webhooks, arbitrary sender selection, billing, or multi-provider routing. A team is not a contact list: it is at most ten numbers, each confirmed by the person with a code, and it receives only the fixed team alerts.

The service stores message text encrypted at rest and normally purges it after its configured retention period. The text of an SMS that carries a code NOTIFY made (a verification's, or a team number's) is never stored at all, and the code itself never is: only its HMAC, until the verification ends and at most about an hour after the code expires. A verification record (the number, the outcome, the attempts) is deleted after 30 days. Public API responses and normal logs redact the sensitive parts of phone numbers and never expose message text, codes or API secrets. Applications should apply the same standard: avoid logging the full request body or authorization header.

An SMS code does not protect against a SIM swap or a stolen phone: your application decides whom to let in (see What a verification cannot do).