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:
- Use only the five public routes documented below:
POST /v1/test-keys,POST /v1/messages,GET /v1/messages/{id},POST /v1/verificationsandPOST /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. - Use an
sk_test_…key first. If you have none,POST /v1/test-keysreturns one instantly. Test keys always use the fake provider and never send a real SMS or spend credits. - 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. - Treat
submittedas provider acceptance, not handset delivery. When the workflow needs a final outcome, pollGET /v1/messages/{id}while the status isqueuedorsubmitted, and stop at any other status or at your own time limit (see When to stop polling). - 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. - Never expect a message response to echo its text or full recipient number. Store the information your application needs before calling the API.
- To verify a phone number, let NOTIFY make and check the code (Verifications). Let the user in only when a check answers
200with statusapproved; treat every other answer, a timeout and a network error as not approved. Branch onerror.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
- Keep polling only while
statusisqueuedorsubmitted. No other status ever changes:delivered,undeliverableandfailedare final, andunknownstaysunknown. - Always set a time limit. Pick one that suits the flow: for a sign-in or verification code, a few minutes is plenty, since the code is useless after that anyway. For a test message, two minutes is generous.
- When the limit passes, stop and record the message as unconfirmed. It is not a failure. Do not send it again; read it later if you need to know.
- NOTIFY stops checking a message with the provider 24 hours after it was created; a late report from the provider can still settle it.
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.
- URL:
https://api.n0t1fy.dev/mcp(Streamable HTTP, hosted) - Authentication: optional, the header
Authorization: Bearer sk_… - Tools:
create_test_key,send_message,get_message,start_verification,check_verification
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:
- Too few credits:
402 insufficient_credits, and nothing is sent. The project owner adds credits; the dashboard explains how. - A free-tier project may send 20 segments a day. Past that:
429 daily_limit_reacheduntil midnight UTC, and nothing is sent. A subscription removes the limit. - A subscriber's credits last until the end of the month they belong to. When a
month ends without the next one paid for, the credits left expire and live
sends get
402 insufficient_creditsuntil the subscription is renewed. - A definitive provider rejection, or a
503 provider_unavailable, is refunded. A message that endsunknownstays charged, because it may have been sent. - A started verification spends one credit, like the one SMS it sends; checking a code is free. So does the code SMS that confirms a team number; a team alert spends one, like any message.
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):
- 5 sends a minute to one number from a project (messages and verification starts together);
- 60 sends a minute per project;
- 120 verification checks a minute per project (test and live keys counted apart, so a test key at its limit never refuses a live key's checks);
- 3 instant test keys a minute per address from
POST /v1/test-keys, which also has a daily share per address (see Get a test key).
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):
- Free trial: test keys cost nothing. A new account gets 100 free live credits, up to 20 segments a day, while the overall free allowance lasts. Free credits never expire; any left when you subscribe carry into your first paid month and expire with it.
- Subscription: 20 GEL a month, with 1,000 credits for each month. Extra packs of 1,000 credits cost 5 GEL each and join the current month. A month runs from the day the payment arrives; credits left at its end expire, packs included. Nothing renews by itself: each month is paid by bank transfer.
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:
code: 4 to 8 digits (0–9only).minutes: a whole number from 1 to 999, without leading zeros.incident,ticket: 1 to 8 digits.count: a whole number from 1 to 99, without leading zeros.agent:your_agent("Your agent", "თქვენი აგენტი") orai_assistant("AI assistant", "AI ასისტენტი"); NOTIFY prints the name.service,job: a name on your project's list, kept on the dashboard's team page (with a live key; with a test key, any name that follows these rules): 1 to 24 Latin letters, digits and hyphens, starting with a letter or a digit, with at most 4 digits in all, matched exactly.- Any value that looks like a link (
http,www,://), a web address (example.ge), or a phone number (nine or more digits) is refused, whatever the variable.
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.
- 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.
- 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.
- 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 |
- Test keys work alone. An agent with a test key builds and tests a team-alert integration with the test numbers and no human; any service or job name that follows the rules is accepted, because nothing is sent. A live key meets two refusals a test key does not: a number not confirmed on the team, and a name not on the list.
recipient_not_on_teamreads the same for every refused number, and the operator hears when a live key keeps meeting it. Ask the project's owner to add and confirm the number; never retry it as it is.- At most 30 team alerts an hour go to one number from a project (an alert the provider refused does not count); past it,
429 rate_limitedwithretry_at. The usual 5 a minute to one number applies too. - A removed number is refused from that moment; a replay of an alert sent before still answers
200with the original message, and sends nothing.
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:
POST /v1/verificationssends a code to a number and answers with a verificationid.POST /v1/verifications/{id}/checkchecks 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:
- Show a "send the code again" button only after a cooldown of your own, about a minute per number (the guide suggests one a minute and five an hour). A user who resends at once meets
too_many_verificationsafter five codes, and every code costs a credit. - On
429 too_many_verifications, show a countdown toretry_at("You can ask for a new code in 12 minutes") and disable the resend button until then. The message names the same moment and theRetry-Afterheader has the seconds; see Error format. Do not start another verification by yourself before it. - Never show a raw error code or message to the user.
error.codeis for your code to branch on; the user gets one sentence in their language (below).incorrect_codeasks for the code again;verification_expired,verification_closedandtoo_many_attemptsoffer a new code;too_many_verificationsshows the countdown. - Offer a way out: a link to support, or another way to sign in (email, a password, a call from your team) for a user whose phone receives no SMS or who met the limit.
- Keep the code field visible as soon as the start answers
201(or200), without waiting fordelivered: a code usually arrives within seconds.
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.
- Create the code with a cryptographically secure generator:
crypto.randomIntin Node, thesecretsmodule in Python, neverMath.randomor Python'srandom. Six digits is usual; the templates accept 4 to 8. - 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 asminutes), and a count of wrong attempts. A new code replaces the previous one for the same user and purpose. - 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.
- Check what the user types. Compute the HMAC of the typed code and compare it with the stored one in constant time:
crypto.timingSafeEqualin Node,hmac.compare_digestin 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).