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

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>

2. Send a code (your server)

POST /verify/send

{ "to": "+13055550142", "consent_token": "ct_…", "channel": "sms", "lang": "es" }

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_…" }

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" }

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 }

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 }

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