API reference · v1

Reach12 API reference

Send SMS and email through Reach12 with a key of your own. Base URL:

https://api.reach12.com/v1

Version 1 covers SMS (Israeli mobiles, through InforU, under your own sender name), email (one recipient per request, from an address on a domain we verified for you) and calls placed by our AI voice agent in Hebrew (on accounts we enable for calls). There is no WhatsApp yet; GET /policy/contact-window answers the hours question for a call you place yourself.

Nothing is open by default. We create your account, set what it may send, and mint your keys. There is no self-service signup yet: ask for early access.

Keys

KeyDoes
sd_live_...Sends for real.
sd_test_...Runs the whole path (validation, caps, opt-outs, hours) and records the message, but never reaches a carrier. Test messages, opt-outs and caps live in a sandbox of their own, apart from live.

A key is shown once, when it is minted. We keep only its hash, so a lost key cannot be recovered: tell us, and we revoke it and mint a new one.

Send it as a header, either spelling:

X-Api-Key: sd_live_...
    Authorization: Bearer sd_live_...

Every answer carries X-SendOS-Mode: live|test, so a test key pasted into production is noticed at the first response.

Conventions

Send an SMS

POST /sms

Field
toAn Israeli mobile: +9725XXXXXXXX or 05XXXXXXXX.
textUp to 670 characters (ten Hebrew segments).
categorytransactional, service (default) or marketing.
kindOptional label for your own log, e.g. appointment.reminder. A message whose kind is otp or starts with otp. is sent but logged without its text: a code kept in a log is a code anyone who reads the log can use.
idempotencyKeyOptional (or the header).

A marketing SMS must open with the word פרסומת (Israeli Communications Law, section 30A), and goes out only 09:00 to 20:00 Israel time, Friday and a holiday eve until 14:00, never on Shabbat or a holiday. Outside those hours it is refused with the next allowed moment.

curl https://api.reach12.com/v1/sms \
      -H "X-Api-Key: $REACH12_KEY" \
      -H "Idempotency-Key: reminder-4812" \
      -H "Content-Type: application/json" \
      -d '{"to":"0501234567","text":"תזכורת: התור שלך מחר ב-10:00","kind":"appointment.reminder"}'
{ "id": "cm1...", "channel": "sms", "status": "sent", "to": "+972501234567", "mode": "live" }

Send an email

POST /email

Field
toOne address.
subjectOne line, up to 200 characters.
html, textAt least one.
replyToOptional.
category, kind, idempotencyKeyAs for SMS.

The sender is always the address we set up for your account; attachments are not supported in v1.

curl https://api.reach12.com/v1/email \
      -H "X-Api-Key: $REACH12_KEY" \
      -H "Content-Type: application/json" \
      -d '{"to":"dana@example.co.il","subject":"הקבלה שלך","text":"תודה!","category":"transactional"}'

Your message log

GET /messages?channel=sms|email&before=<ISO date>&limit=1..100

Newest first, only your own (a test key sees only test messages). Page with nextBefore.

curl "https://api.reach12.com/v1/messages?channel=sms&limit=20" -H "X-Api-Key: $REACH12_KEY"
{ "data": [ { "id": "cm1...", "channel": "sms", "to": "+972501234567", "text": "...", "status": "sent", "error": null, "createdAt": "..." } ], "hasMore": false, "nextBefore": null }

status is sent, failed (then error is vendor_failed) or blocked.

Your account

GET /account

Who the key belongs to, what the account may send, its daily caps, and how much of today's cap is used. today counts exactly what the caps count: an SMS the carrier accepted or refused (a blocked one never reached a carrier) and every email attempt, in Israel's day. A test key sees its own sandbox's day.

curl https://api.reach12.com/v1/account -H "X-Api-Key: $REACH12_KEY"
{
      "id": "acme-clinic",
      "name": "Acme Clinic",
      "status": "active",
      "mode": "live",
      "key": { "name": "Production server", "prefix": "sd_live_7Hq2" },
      "channels": {
        "sms": { "enabled": true, "sender": "AcmeClinic" },
        "email": { "enabled": true, "from": "Acme Clinic <hello@acmeclinic.com>" }
      },
      "caps": { "sms": 500, "email": 1000 },
      "today": {
        "date": "2026-11-10",
        "resetsAt": "2026-11-10T22:00:00.000Z",
        "sms": { "used": 42, "cap": 500, "remaining": 458 },
        "email": { "used": 7, "cap": 1000, "remaining": 993 }
      },
      "pricing": { "currency": "ILS", "monthlyFee": 25000, "perSms": 8, "perEmail": 1, "perCallMinute": 30 }
    }

pricing is null until we set your prices with you. Every amount is in minor units: agorot for ILS, cents for USD.

Usage and what you owe

GET /usage?month=YYYY-MM

One month, by channel and status, with a series by day. month defaults to the current month; months are Israel time, so a message sent at 00:30 on the 1st in Israel belongs to that month. A month that has not begun is refused with invalid_month. For the current month, complete is false and daily stops at today.

calls counts the month's calls by how they ended (a call still ringing is in no bucket yet), with callbacks (people who called back and the agent answered), seconds, the exact time on the line of the answered ones, minutes, the same calls as billed (each rounded up to the minute), and outcomes, how the answered calls ended (the outcome values under Calls, each counted, zero where none).

When the account is priced, amountDue is the monthly fee plus every message the carrier accepted (sent) and every call minute. A failed or blocked message is never billed, and neither is anything sent with a test key: for a test key billable is false and amountDue is null.

curl "https://api.reach12.com/v1/usage?month=2026-11" -H "X-Api-Key: $REACH12_KEY"
{
      "month": "2026-11",
      "mode": "live",
      "timezone": "Asia/Jerusalem",
      "from": "2026-10-31T22:00:00.000Z",
      "to": "2026-11-30T22:00:00.000Z",
      "complete": false,
      "sms": { "sent": 1200, "failed": 30, "blocked": 9 },
      "email": { "sent": 450, "failed": 4 },
      "calls": {
        "completed": 38, "no_answer": 9, "busy": 2, "failed": 0, "canceled": 0, "simulated": 0, "callbacks": 4, "minutes": 71, "seconds": 3874,
        "outcomes": { "completed": 27, "callback_later": 5, "callback_requested": 2, "not_interested": 3, "do_not_call": 1, "wrong_person": 0, "voicemail": 0, "other": 0 }
      },
      "daily": [ { "date": "2026-11-01", "sms": { "sent": 40, "failed": 1, "blocked": 0 }, "email": { "sent": 12, "failed": 0 }, "calls": { "completed": 2, "no_answer": 1, "busy": 0, "failed": 0, "canceled": 0, "simulated": 0, "callbacks": 0, "minutes": 4, "seconds": 187 } } ],
      "billable": true,
      "amountDue": {
        "currency": "ILS",
        "lines": [
          { "item": "monthly_fee", "quantity": 1, "unitAmount": 25000, "amount": 25000 },
          { "item": "sms", "quantity": 1200, "unitAmount": 8, "amount": 9600 },
          { "item": "email", "quantity": 450, "unitAmount": 1, "amount": 450 },
          { "item": "call_minutes", "quantity": 71, "unitAmount": 30, "amount": 2130 }
        ],
        "total": 37180
      }
    }

The lines always add up to total. The amount for the current month is what it comes to so far.

Your dashboard

Your voice agent's calls are also at dash.reach12.com: paste a key to see the month at a glance (calls, answer rate, talk time, how answered calls ended), every call with its summary, answers and transcript, and your do-not-call list. The key stays in that browser tab only and is sent to nothing but this API.

Opt-outs

One list per account, per channel (all, sms, email, call, whatsapp; all holds every channel). An address is a phone number or an email.

# who asked not to be contacted
    curl "https://api.reach12.com/v1/opt-outs?channel=sms" -H "X-Api-Key: $REACH12_KEY"
    
    # someone replied STOP
    curl https://api.reach12.com/v1/opt-outs -H "X-Api-Key: $REACH12_KEY" -H "Content-Type: application/json" \
      -d '{"address":"0501234567","channel":"sms","reason":"replied STOP"}'
    
    # they asked to be let back in ("all" lifts every channel)
    curl -X DELETE https://api.reach12.com/v1/opt-outs -H "X-Api-Key: $REACH12_KEY" -H "Content-Type: application/json" \
      -d '{"address":"0501234567","channel":"sms"}'

May I contact someone now?

GET /policy/contact-window?kind=call|message

{ "kind": "call", "allowed": false, "nextWindow": "2026-11-15T08:00:00.000Z" }

Calls: 10:00 to 19:30 (Friday and a holiday eve until 13:00). Messages: 09:00 to 20:00 (until 14:00). Never on Shabbat or a holiday. Israel time.

Calls

POST /calls asks our voice agent to call someone now. It says it is an AI in its first sentence, on every call, and nothing you send can change that. There is no queue, no retry and no schedule: a call is placed because a request asked for it, or it is refused.

Field
toAn Israeli number, mobile or landline: +972... or 0....
purposeRequired, up to 300 characters, in Hebrew. The agent says it right after introducing itself, so write it as speech, in the voice's gender or neutrally: אני מתקשרת לאשר את התור שלך מחר ב-10:00.
businessThe name the agent calls on behalf of. Defaults to your account's name.
factsUp to 8 short sentences the agent may state. It states nothing else and never invents.
questionsUp to 5 questions it asks, in order, one at a time. The answers come back on the call.
calleeNameOptional: who you are calling. The agent greets them by first name and shares nothing if someone else answers.
calleeGenderOptional, female or male. Hebrew says "you" differently to each, and a name does not tell; without it the agent phrases around it until the callee's own words make it clear.
agentNameOptional name for the agent.
voicefemale (default) or male.
voicemailOptional message to leave on voicemail; without it the agent hangs up.
announceRecordingtrue (default): the opener says the call is recorded.
categorytransactional or service (default). There are no marketing calls.
kind, idempotencyKeyAs for SMS.

A call is refused outside the call hours (10:00 to 19:30 Israel time, Friday and a holiday eve until 13:00, never on Shabbat or a holiday), to a number on your opt-out list for call or all (whatever the category), past your daily call limit, or when every line is busy (429 lines_busy, try again in a minute). A test key runs every one of these checks and rings nobody: the call is recorded with status simulated.

The opener is ours around your purpose: שלום דנה, כאן העוזרת ה-AI של מרפאת אקמה. אני מתקשרת לאשר את התור שלך מחר ב-10:00. השיחה מוקלטת. יש לך דקה? If the person asks not to be called again, the agent says it will not happen again and adds them to your opt-out list for call, so it doesn't.

curl https://api.reach12.com/v1/calls \
      -H "X-Api-Key: $REACH12_KEY" \
      -H "Idempotency-Key: confirm-4812" \
      -H "Content-Type: application/json" \
      -d '{"to":"0501234567","calleeName":"דנה לוי","purpose":"אני מתקשרת לאשר את התור שלך מחר ב-10:00","facts":["התור אצל ד\"ר כהן, קומה 2"],"questions":["השעה מתאימה לך?"]}'
{ "id": "cm2...", "to": "+972501234567", "status": "ringing", "category": "service", "outcome": null, "mode": "live" }

GET /calls/:id follows it: status is ringing, in_progress, completed, no_answer, busy, failed, canceled or simulated; once it is over, durationSec, outcome (completed, callback_later, callback_requested, not_interested, do_not_call, wrong_person, other), a short summary in Hebrew, answers (one per question, null where it was not answered) and the transcript. The summary follows the call by a few seconds. GET /calls?before=<ISO date>&limit=1..100 lists your calls, newest first, without transcripts; page with nextBefore. Narrow it with status (one or more, comma-separated: ?status=no_answer,busy), outcome (?outcome=not_interested), scenario (?scenario=confirm-appointment) and direction (below).

A call placed from a scenario carries scenario, and each of its answers carries the question's type and a value when the type allows one: "yes" or "no" for a yes/no question, exactly one of the options for a choice, the agreed time in a few words for a time. answer keeps the words either way, and a value nobody gave is null.

recording is true when the call has one. GET /calls/:id/recording returns it as audio (audio/mpeg, two channels: the agent and the person). It is never cached on the way.

Callbacks. When someone calls back the number our agent called them from, within 7 days, the agent answers for you. It says it is your AI assistant and that we called this number earlier. If your call went unanswered and it is the person you called, it finishes your call's purpose and asks your questions. Otherwise it answers from your facts, or takes a message for you. It never shares anything about your call with someone who is not the person you called. The callback is a call on your account with direction: "inbound" and parentId naming your call, with its own outcome, summary, answers and transcript (GET /calls?direction=inbound lists them). It is not a call you placed: it does not count against your daily limit, and it is not in the statuses /usage counts. It is counted in calls.callbacks, and its minutes are billed like any other. A call runs at most 4 minutes.

Your agent and its scenarios

Set your agent once, and a call becomes three fields. The settings are your account's, shared by your live and test keys.

GET /agent and PATCH /agent (send only what changes):

Field
businessThe name the agent says. Defaults to your account's name.
aboutOne or two sentences about your business, up to 300 characters.
factsUp to 8 sentences it may state on every call.
agentNameOptional name for the agent.
voicefemale (default) or male.
announceRecordingtrue (default): the opener says the call is recorded.
handoffPhoneA person at your business, for when a caller asks for one.

A scenario is a kind of call: a purpose with {variables}, the questions it asks, and the facts it may state. GET /scenarios, POST /scenarios, GET, PATCH and DELETE /scenarios/:key.

curl https://api.reach12.com/v1/scenarios -H "X-Api-Key: $REACH12_KEY" -H "Content-Type: application/json" \
      -d '{"key":"confirm-appointment","name":"אישור תור","purpose":"אני מתקשרת לאשר את התור שלך {time}",
           "variables":[{"key":"time","label":"מועד","example":"מחר ב-10:00"}],
           "questions":[{"text":"המועד מתאים?","type":"yes_no"},{"text":"איך תגיעו?","type":"choice","options":["ברכב","בתחבורה ציבורית"]}],
           "category":"transactional"}'
Field
key2 to 40 lowercase letters, digits and dashes. It is the name a call uses, and it does not change.
nameWhat you call it.
purposeRequired: what the agent says after introducing itself, with {variables}.
variablesUp to 10 { key, label, example, required }. Every {variable} a text uses must be here.
questionsUp to 5 { text, type, options }: type is yes_no, choice (2 to 6 options), time or text.
factsUp to 8 sentences for this kind of call, added to your agent's.
voicemailWhat to leave on voicemail; without it the agent hangs up.
categorytransactional or service (default).

Then a call names the scenario and fills its variables:

curl https://api.reach12.com/v1/calls -H "X-Api-Key: $REACH12_KEY" -H "Content-Type: application/json" \
      -d '{"to":"0501234567","scenario":"confirm-appointment","vars":{"time":"מחר ב-10:00"},"calleeName":"דנה לוי"}'

A call that names a scenario takes to, scenario, vars, calleeName, calleeGender, kind and idempotencyKey; sending anything the scenario decides (a purpose, questions, voice...) is refused with scenario_conflict. A required variable that is missing is missing_var, and a scenario you do not have is unknown_scenario. The call keeps the brief it was placed with: editing or deleting the scenario later changes nothing about calls already placed. A call without a scenario takes what it leaves out from your agent: the business, the voice, the recording notice, and your agent's facts ahead of its own.

POST /scenarios/preview { scenario, vars } returns what the agent would open with and ask, filled in: scenario is the key of a saved one, or a draft checked as if it were being saved. A variable you do not send reads as its example. Nothing is dialed.

GET /scenarios/:key/results?month=YYYY-MM counts what a scenario's calls answered that month, question by question: how many were asked and answered, and for a yes/no or a choice, how many gave each value.

{ "scenario": "confirm-appointment", "month": "2026-11", "calls": 48, "reached": 39,
      "questions": [ { "text": "המועד מתאים?", "type": "yes_no", "asked": 39, "answered": 37, "counts": { "yes": 31, "no": 6 } } ] }

POST /scenarios/simulate { scenario, vars, messages } is the same agent in text: messages are the turns after its opener, alternating caller and agent, starting and ending with the caller's. It answers { reply, ended, outcome } from the same instructions a call gets. Nothing is dialed or stored, a test key may use it, and it is limited to 300 turns a day.

Tasks

What a call leaves your business to do: call someone back, send something, reschedule, handle a complaint. A task exists only when something said on the call makes it one, and it keeps the words it came from (quote). A time the person named is kept as said; a time we chose is marked dueApprox and never falls at night. Two tasks come from how a call ended rather than from its words: someone who asked for a person, or to be called later, always leaves a callback (source: "outcome"), and so does a callback nobody could answer (source: "missed_callback").

GET /tasks?status=open|done|all&callId= lists them (open ones soonest first) with how many are open. PATCH /tasks/:id { "status": "done" } ticks one off, and "open" undoes it.

{ "data": [ { "id": "cm...", "callId": "cm...", "to": "+972501234567", "kind": "reschedule", "title": "לתאם לדנה מועד אחר",
      "quote": "מחר לא מתאים לי, אפשר ביום חמישי בבוקר?", "dueAt": "2026-11-12T08:00:00.000Z", "dueApprox": true, "status": "open", "source": "call" } ], "open": 3 }

Refusals

HTTPcodeMeans
400invalid_request, invalid_phone, missing_text, text_too_long, invalid_category, invalid_kind, marketing_label_required, invalid_email, missing_subject, invalid_subject, missing_body, body_too_large, invalid_reply_to, attachments_not_supported, invalid_address, invalid_idempotency_key, invalid_monthThe request itself.
400missing_purpose, invalid_purpose, invalid_business, invalid_agentName, invalid_calleeName, invalid_calleeGender, invalid_voicemail, invalid_facts, invalid_questions, invalid_voice, marketing_calls_not_supportedA call request.
400denies_aiSomething in a call request says the agent is a person. It is an AI and says so.
401unauthorizedNo valid key. The same answer for every reason, on purpose.
403channel_not_enabledThis account may not send on that channel yet.
404not_foundNo such endpoint.
409opted_outThe recipient asked not to be contacted on this channel.
409idempotency_in_progressA request with this key is still being processed.
422outside_hoursA marketing message, or any call, outside the hours; nextWindow says when.
422idempotency_mismatchThis key was used with a different request.
429rate_limitedToo many requests (per key), or too many failed keys from your address.
429daily_cap_reachedThe account's daily cap for the channel; resetsAt is midnight in Israel.
429lines_busyEvery line is on a call; Retry-After says when to try again.
502vendor_failedThe carrier refused the message, or the call could not be placed; it is in your log (or your calls) with status failed.
503unavailableThe channel or the API is not available right now.

Ready for a key?

We onboard early-access accounts one by one and set up your sender name and domain with you.

Get early access