Send OTP codes with HelloMe

The complete reference of every route, with a playground to try it with your key: hello-me.net/developers/api.

• Create your workspace in HelloMe: Support → new workspace. You own it.
• In its settings, create a server key with the “read” and “write” scopes. It is shown once: copy it into your server's configuration.
• Top up your HelloMe credit: send the amount by mobile money (Flooz, T-Money, MTN MoMo, Orange Money…) and give the transfer reference to our team from the Credit screen. The balance shows in FCFA and in dollars.
• Send your first code.

curl -X POST https://api.hello-me.net/api/v1/otp/send \
  -H "x-hellome-key: hm_sk_your_server_key" \
  -H "content-type: application/json" \
  -d '{"phone": "+228 90 12 34 56"}'

{
  "data": {
    "id": "66f1c0a2b3c4d5e6f7a8b9c0",
    "phone": "+22890123456",
    "country": "TG",
    "status": "sent",
    "channel": "whatsapp",
    "channelAsked": "whatsapp",
    "fellBack": false,
    "delivery": "pending",
    "length": 6,
    "attempts": 0,
    "attemptsLeft": 5,
    "expiresAt": "2026-10-05T10:05:00.000Z",
    "verifiedAt": null,
    "reference": null,
    "test": false,
    "cost": { "usd": 0.03, "xof": 18 },
    "createdAt": "2026-10-05T10:00:00.000Z"
  }
}

Not a company? From your HelloMe account, Settings → OTP codes (API) gives you a personal key and a mobile money top-up of your HelloMe credit: the same API, paid from your own credit.

Keep the “id” next to the session you are protecting: it is what you send back to verify. The code itself is never shown to you, and we do not keep it either — only its hash.

Every call carries your server key in the “x-hellome-key” header (or “Authorization: Bearer …”). The key belongs to one workspace: it sees only its requests, its credit, its settings. Sending, verifying, canceling and changing settings need the “write” scope; reading requests and usage works with “read”.

The key must never sit in a web page, a mobile app or a code repository. If it leaks, revoke it from the workspace settings and create another: it stops working at once, everywhere.

POST /otp/send. The body is a phone number and, if you want, a few choices.

A refused code is never charged. A code that left is, whether it traveled by WhatsApp, by SMS, or both.

POST /otp/verify with the request id and the typed code. Without an id, give the number: the latest pending code for that number is checked.

curl -X POST https://api.hello-me.net/api/v1/otp/verify \
  -H "x-hellome-key: hm_sk_your_server_key" \
  -H "content-type: application/json" \
  -d '{"id": "66f1c0a2b3c4d5e6f7a8b9c0", "code": "482913"}'

The answer is the request, with a “result” field that says what to do. Only one result lets the person in.

Let the person in only on “approved”. A “200” means nothing more than “we answered”.

When you ask for “whatsapp” (the default), the code leaves by WhatsApp and we watch its delivery. After about twenty seconds, if it is not marked delivered — number without WhatsApp, phone off, message refused — the same code leaves by SMS. The person can type whichever they read first: both messages carry the same code.

• If WhatsApp refuses the message on the spot, the SMS leaves without waiting.
• If the fallback SMS is itself refused, the request stays as it is: the WhatsApp message may still arrive.
• The fallback is never charged on top: one code, one price.
• With “channel: sms”, none of this: the SMS leaves at once.

Prices are in dollars and the same whatever the channel — WhatsApp or SMS, a code costs the same. The price of a code depends on the destination country: an SMS to one country does not cost what it costs to another. GET /otp/prices gives the price per country; a country not listed is charged the default price (defaultSendUsd) when sent, then adjusted within a minute, once the cost is known — “cost” on the request gives the final price. More generally, a code whose real cost exceeds what was charged (a dearer carrier than expected, a WhatsApp-then-SMS fallback) is raised to the country’s real price within a minute; never lowered. Sending needs a balance of at least two codes: the price, plus a reserve for that adjustment — otherwise 402 insufficient_credit. A verification has one price everywhere. The price charged is the one in force when the code is sent, and comes back in “cost” on the request.

{
  "data": {
    "defaultSendUsd": 0.03,
    "verifyUsd": 0.005,
    "usdRate": 600,
    "rows": [
      { "country": "TG", "sendUsd": 0.52, "sendXof": 312 },
      { "country": "CI", "sendUsd": 0.30, "sendXof": 180 }
    ]
  }
}

Your HelloMe credit is kept in FCFA, the currency of your mobile money top-up; every line of your statement also carries its dollar price, and GET /otp/usage gives the balance in both. The rate applied is the one shown in “prices.usdRate”.

{
  "data": {
    "today":  { "requested": 412, "sent": 410, "approved": 371, "failed": 2,
                "byWhatsApp": 352, "bySms": 58, "fellBack": 41,
                "verifications": 455, "spentXof": 8745, "spentUsd": 14.575 },
    "month":  { "...": "the same counters since the 1st" },
    "balance": { "xof": 112500, "usd": 187.5 },
    "prices":  { "sendUsd": 0.03, "verifyUsd": 0.005, "sendXof": 18, "verifyXof": 3, "usdRate": 600 },
    "limits":  { "perPhonePer10Min": 3, "perPhonePerDay": 8, "hourlyCap": 500, "dailyCap": 5000 },
    "paused":  null
  }
}

When the balance no longer covers a code, the send answers 402 and nothing leaves. Two simultaneous sends may take the balance very slightly below zero; the next one is refused. Watch “balance” and warn yourself a few days ahead.

The danger with OTP codes is traffic that is not people: a script requesting codes toward numbers that pay the sender on every SMS received. It empties your credit in a night. These ceilings are there so that it stops by itself.

• Restrict countries to those where you have customers: it is the measure that stops the most fraud for the least effort.
• Put your own limit in front of your send endpoint: per session, per IP address, and a delay before “send again”.
• Do not reveal whether a number has an account with you: answer the same for an unknown number.
• An automatic pause lifts itself after an hour; our team can lift it sooner if your traffic has an explanation.

In your settings, up to ten numbers can have a fixed code. A send toward one of them creates a normal request but sends nothing and costs nothing; verification accepts the fixed code. It is what you need for automated tests, and to let an app-store reviewer log in without a phone of their own.

curl -X PATCH https://api.hello-me.net/api/v1/otp/settings \
  -H "x-hellome-key: hm_sk_your_server_key" \
  -H "content-type: application/json" \
  -d '{"testNumbers": [{"phone": "+22890000099", "code": "424242"}]}'

Test requests appear in the list with “test: true” and count neither in usage nor in ceilings.

Requests are kept ninety days, long enough for any dispute, then erased. Your credit statement stays.

GET and PATCH /otp/settings. Only the fields you send change.

The answer also recalls our own limits (“limits”, including textMaxChars and customTextAllowed for your sentence) and any pause in progress (“paused”).

• Use “reference” with the session id: a button pressed twice or a dropped connection does not send a second code — and does not cost you one.
• Verify by “id” rather than by number when you can: it is unambiguous when the person asked for two codes.
• Never write the code to your logs, nor what the person typed.
• Show “expiresAt” to the person, and offer “send again” only after thirty seconds: the SMS fallback needs those seconds.
• Treat 402 as an operations alert, not a user error: warn your team, show “try again in a moment”.
• Our per-number limits are yours too: a screen that lets someone ask for ten codes in a minute will be refused from the fourth.

The full description of every call, with its schemas, is in the interactive API documentation, section “OTP for Companies”.