linevak API (v0.4, 2026-09-30)
Base URL https://api.linevak.com. Every error is { ok:false, error } with error from a
fixed list; no response ever names the phone provider.
Keys
- Secret key
lvk_live_…: server only.Authorization: Bearer lvk_live_…. - Public key
lvk_pub_…: safe in a web page; only shows the consent box. - Sign in at linevak.com/start with your email (a one-click link, no password), create an app, and get both keys. The secret key is shown once; "New secret key" replaces it.
1. The consent box (in the person's browser)
<script src="https://linevak.com/consent.js" data-key="lvk_pub_…"
data-guard="#send" data-show-when="#phone" defer></script>
<div data-linevak-consent></div>
- Shows linevak's wording with the app's name, English or Spanish (
data-lang="auto|en|es"), never pre-ticked. data-guard: that button stays disabled until the box is ticked.data-show-when: the box appears only when that field holds a phone number (emails skip it).- On tick: a hidden
<input name="linevak_consent_token">is filled, alinevak:consentevent fires, andwindow.linevak.getConsentToken()resolves to the token (refreshed if old). - Your page's Content-Security-Policy must allow
script-src https://linevak.comandconnect-src https://api.linevak.com.
2. Send a code (your server)
POST /verify/send
{ "to": "+13055550142", "consent_token": "ct_…", "channel": "sms", "lang": "es" }
channel:sms(default),whatsapp, orcall(the code read aloud twice).consent_tokenis required the first time a number signs in to your app; after that the stored record covers it.- 200
{ "ok": true, "id": "…", "channel": "sms", "expires_in": 600 } - A text or WhatsApp code to a landline answers 400
{ "ok": false, "error": "landline_use_call", "suggest": "call", "message": "…" }and nothing is sent or counted. Send the same request again with"channel": "call". If linevak can't tell what kind of number it is, the code goes out as asked.
3. Check a code (your server)
POST /verify/check { "to": "+13055550142", "code": "481220" } → 200 { "ok": true }
4. Export consent records
GET /consents?cursor= → { records: [{ app, to (masked), at, version, wording, lang, ip, ua, recorded_at }], cursor }
5. Texts, calls and WhatsApp under your own name (Lane 2)
In the dashboard, Text under your own name asks a few plain questions (legal name, the name
customers know, EIN, address, contact, what you'll send, languages) and links an app. linevak
writes your texting policy at linevak.com/b/<your-name>/sms, reviews it, buys your own
toll-free number and files the carrier approval with linevak as the platform. You see the status
in the dashboard and in brand.status webhooks.
Consent for these messages uses the same box with data-purpose="brand":
<script src="https://linevak.com/consent.js" data-key="lvk_pub_…" data-purpose="brand" defer></script>
POST /messages/send
{ "to": "+13055550142", "text": "your order #1042 is ready for pickup.", "channel": "sms", "lang": "es", "consent_token": "ct_…" }
channel:sms(once approved),call(your number calls and reads the text; works as soon as the number is assigned), orwhatsappwith"template": "<approved name>", "params": [...]once your WhatsApp Business account is connected.- linevak adds your name in front and the STOP line; STOP to your number stops only your messages.
- Replies people send to your number arrive as
message.receivedwebhooks. - Forward calls: set a phone in the dashboard and calls to your number ring it.
- Caller name: once approved, calls from your number show your name (up to 15 letters, as carriers list it), which helps keep phones from marking them as spam.
6. Webhooks
Set a URL per app in the dashboard. Every event is a POST:
{ "type": "message.delivered", "created": "2026-09-24T15:04:05Z", "app": "colmado-rosa-1a2b3c", "data": { "id": "…", "to": "••••••••0142", "status": "delivered" } }
Types: message.delivered, message.failed, recipient.opted_out, recipient.opted_in,
message.received (Lane 2 replies, with the full from number and text), brand.status, number.assigned.
Check the signature: linevak-signature: v1=<hex> is HMAC-SHA256 of "<linevak-timestamp>.<raw body>"
with your webhook secret (whsec_…, shown once when you save the URL). Reject timestamps older
than 5 minutes.
7. Plans
A send is one code, one message or one call. Free: 100 a month. Paid plans are billed through
Unyplex; the dashboard shows the upgrade buttons once billing is live. Over the allowance,
sends answer quota_exceeded (HTTP 402).
Every paid plan includes one toll-free number under your own name. Once a paid plan's brand is
ready, linevak buys the number and files the carrier approval by itself; on the free plan
POST /brands/:id/ready answers "filing": "needs_payment". If a plan ends, sending from that
number stops at once (plan_required, HTTP 402) and the number is kept for 30 days; pay again
within those days and nothing changes. A local number for calls (forwarded to your phone, shown
with your business name) is $3 a month: POST /lines { area_code, label, forward_to } returns a
checkout_url; the number is bought when that payment lands.
8. Look up a number (your server)
POST /lookup { "to": "+13055550142" }
{ "ok": true, "to": "+13055550142", "line_type": "mobile", "can_text": true, "can_call": true, "carrier": "T-Mobile USA" }
line_type:mobile,landline,voiporunknown. Landlines can be called, not texted.- Use it before you offer "text me" or "call me". It doesn't count as a send.
- Answers are remembered for 30 days. Limits: 60 a minute per app, 10 an hour per number.
- 503
not_readywhen the lookup can't answer right now; try again or just send the code (/verify/sendchecks landlines by itself).
9. Bring your number
In the dashboard, Bring your number moves a US or Canadian number you already have into linevak, so customers keep calling and texting the number they know. You enter the number, your current phone company, the account number and PIN from your bill, the name on the account and the service address, add a recent bill (PDF, JPG or PNG, up to 4 MB), and sign by typing your name. linevak checks it, files the transfer with the carriers and shows each step: received → sent to your current company → transfer date set → done. If the current company asks for a correction, you fix it and sign again. Your account number and PIN are stored encrypted; the dashboard only ever shows their last digits. Keep your current service until the transfer date.
10. Platforms: one business per customer
For a platform that runs many businesses (each with its own number), linevak flags your app as a platform. Its secret key then creates businesses with no dashboard:
POST /platform/businesses { "external_id": "biz_42", "name": "Taller Luis", "webhook_url": "https://…", "brand": { …same fields as the dashboard form… }, "submit": true }
- Each
external_idbecomes one app with its ownsecret_keyandwebhook_secret, shown once (201). The sameexternal_idagain answers 200 with the same app and no secrets. - Sends and numbers count on your platform's plan.
submit: truefiles the brand while your plan covers another number; otherwisefilingsaysneeds_payment(withcheckout_url) orlimit_reached. GET /platform/businesses/:external_idshows the brand's status and number. The business's app getsnumber.assignedandbrand.statuswebhooks.brandfields (what the carriers check):legal_name,brand_name(≤ 30, on every text),entity_type(PRIVATE_PROFIT·SOLE_PROPRIETOR·NON_PROFIT),ein(9 digits; not for a sole proprietor),address{ line1, city, state (2 letters), zip },website(strongly advised: carriers send a brand back without one),contact{ first, last, email, phone },use_cases(any oforders,delivery,appointments,account,documents,marketing),langs(["es","en"]), optionalwhat{ en, es }andvolume. A missing field answers 400 with its name (e.g.ein_required); on the first call the app'ssecret_keyandwebhook_secretstill come back insidebusiness, and the sameexternal_idlater fills the brand in.- Webhook payloads (envelope
{ type, created, app, data }, signed as in §6):number.assigned→data: { brand, number }(full E.164) — the number is bought, but texts wait for the carriers;brand.status→data: { brand, status, reason, number }(number masked). Texting from the business's own number works oncebrand.statussaysapproved; until then/messages/sendanswers 503not_ready. - Any refusal after the business was made in that call (a bad brand,
submitwith no brand, a takenbusiness_key) still returns the new app'ssecret_keyandwebhook_secretinsidebusiness, since they are shown only once. - Every platform holds up to 25 toll-free numbers and 25 local lines across its businesses, unless linevak sets another limit for it.
Past it, filing says
limit_reachedand a new line answers 402line_limit_reached. DELETE /platform/businesses/:external_id/numbergives a business's toll-free number back: sending stops now and the number is released after 30 days. Safe to repeat (a business with no number left answers 200).POSTon the same path takes it back during those days.
11. Agents: a key from a passvak sign-in
An agent holding a passvak access token made for linevak (resource=https://api.linevak.com) trades it for
an app key on that person's linevak account: POST /agent/keys { "token": "pvt_…", "app_name": "My agent" } →
201 with secret_key (shown once). The key counts on the person's plan like any other app (Free: 100 a
month); over the allowance it answers 402, never a surprise bill. A token made for another product is refused (401).
12. Send to a list
POST /messages/broadcast { "to": ["+13055550142", …], "text": "We open at noon tomorrow.", "lang": "es", "kind": "update" } →
202 { broadcast: { id, status, total, sent, failed, waiting, skipped } }. One text to each number, from your brand's
own number, with your name and the STOP wording. Only numbers with a recorded tick for your brand get it; the rest are skipped and
counted (no_consent, opted_out, invalid, duplicate, unsupported_country). Add "dry": true to see those counts
without sending. Up to 1,000 numbers per send and 3 sends an hour; "kind": "offer" needs the marketing use case and is limited
to 4 a month. The whole list must fit in this month's allowance or nothing is sent (402 quota_exceeded). Texts go out at about 60 a
minute; GET /messages/broadcast/:id shows progress and your webhook gets broadcast.done. It is not a group chat: each person
gets their own text and their replies come to you one by one.
13. Opt-outs: one list per business
linevak keeps each business's opt-out list, so your product doesn't keep its own copy. When a person says stop on your side (a web form, the owner, an agent), tell linevak:
POST /platform/optouts { "external_id": "biz_42", "phone": "+13055550142", "source": "web", "lang": "es" } →
200 { ok, phone, opted_out: true, at }
GET /platform/optouts?external_id=biz_42&phone=%2B13055550142 → 200 { ok, phone, opted_out, at }
- Use the business's own secret key (then
external_idis optional and must be its own), or your platform's key withexternal_id. One business never reads or changes another's list. sourceisweb,owneroragent. A repeat answers the same, with the firstat.- The business's webhook gets
recipient.opted_out{ to, brand?, source, via: "api" }, once, the same event as a texted STOP. - From then on every send to that number from that business answers 409
opted_out. A START from that phone undoes it. - Texted in, the whole message counts as a stop when it is STOP, STOPALL, UNSUBSCRIBE, CANCEL, END, QUIT, OPTOUT or OPT OUT (any case, spaces or a hyphen inside), or Spanish ALTO, PARAR or BAJA. A sentence that only mentions one of them is a reply.
Errors
| error | HTTP | Show your user |
|---|---|---|
invalid_phone |
400 | That doesn't look like a mobile number. |
unsupported_country |
400 | We can't send codes to that country yet. Use email. |
invalid_channel |
400 | (your bug) channel must be sms, whatsapp or call |
consent_required |
400 | Tick the box to get a code. |
opted_out |
409 | This number replied STOP. Use email, or text START to linevak. |
too_many_requests |
429 | Wait a moment before asking for another code. (retry_after seconds) |
wrong_code |
400 | That code isn't right. (tries_left) |
expired |
400 | That code expired. Ask for a new one. |
too_many_attempts |
400 | Too many tries. Ask for a new code. |
invalid_code |
400 | Codes are 6 digits. |
landline_use_call |
400 | That's a landline, so we'll call you with the code instead. (suggest: "call") |
quota_exceeded |
402 | (your plan's monthly allowance is used up) |
no_brand |
400 | (your bug) this app isn't linked to a business name |
text_too_long |
400 | (your bug) 600 characters max |
not_ready |
503 | Codes by this channel aren't available right now. Use email. |
send_failed |
502 | The code didn't go through. Try again or use email. |
Rules linevak enforces
- Destinations: +1 only (US, Canada, Puerto Rico, Dominican Republic); fraud-prone Caribbean ranges refused.
- One code per number per app every 30 seconds, five an hour. Codes last 10 minutes, five tries.
- STOP (or OPT OUT, PARAR, ALTO, BAJA, CANCEL…, as the whole message) to linevak stops texts, calls and WhatsApp from every app.
- Every text starts with
linevak:and ends with the opt-out line. - The codes number only sends codes. Free text (
POST /send-sms, trusted hub only) goes out from the alerts number.