MeiSIM Dealer API

Real T-Mobile numbers, owned and managed in the US by MEISIM USA LLC, a Wyoming company run from Los Angeles.

REST API for authorized dealers to programmatically order eSIMs, top up SIMs, and manage their wallet.

Base URLhttps://api.meisimusa.com
Content typeapplication/json
API versionv1

Quick start

# 1. Get your API key (one-time)
curl -X POST https://api.meisimusa.com/dealer/send-otp \
  -H 'content-type: application/json' \
  -d '{"email":"you@yourcompany.com"}'

# Check email for the 6-digit code, then:
curl -X POST https://api.meisimusa.com/dealer/verify-otp \
  -H 'content-type: application/json' \
  -d '{"email":"you@yourcompany.com","code":"123456"}'
# → returns { "verified": true, "apiKey": "..." }

# 2. Use the API key on every request
curl https://api.meisimusa.com/api/v1/me \
  -H 'x-dealer-key: YOUR_API_KEY'

Public catalogue — no key required

Reading the plan catalogue needs no dealer key and no signup: GET https://api.meisimusa.com/mm/products. It is documented in full on the public page — Catalogue API → (endpoint, filters, response shape and fair-use limits).

Authentication

Everything below this point is the dealer API and does need a key. Two equivalent auth methods. Use either on any endpoint.

Option A — API Key (recommended for backend integration)

Issued via the OTP flow below. Passed in the request header:

x-dealer-key: YOUR_API_KEY

The key does not expire. Treat it like a password, and rotate it whenever you need to (see Rotating your key).

Option B — JWT (for portal/UI integrations)

Issued via the password-login flow. Passed in the standard Bearer header:

Authorization: Bearer YOUR_JWT

JWT expires after 12 hours. Re-login to refresh.

Rotating your key

Sign in to the dealer dashboard, open the API key tab, enter your password and press Rotate API key. You choose when the old key stops working:

The new key is shown once and never emailed. We email you that the key changed. While the old key still works you can end it early from the same tab. Rotation needs a signed-in session and your password, so an API key cannot replace itself. Lost the current key? The email code flow below returns it.

Auth flow — OTP login

POST/dealer/send-otp

Send a 6-digit code to your email.

{ "email": "you@yourcompany.com" }

Response: { "sent": true }. Rate limit: 5 sends per 15 min per IP. Code expires in 5 minutes; max 5 verification attempts.

POST/dealer/verify-otp

Verify the code and receive your API key.

{ "email": "you@yourcompany.com", "code": "123456" }

Response:

{ "verified": true, "apiKey": "dk_..." }

Rate limit: 10 verifications per 15 min per IP.

Auth flow — password login (returns JWT)

POST/dealer/auth/set-password

One-time password setup, for an account that has no password yet. Requires x-dealer-key from the OTP flow. Once the account has a password this answers 409: reset a forgotten password with POST /dealer/auth/forgot { "email": "you@yourcompany.com" }, which emails a link to that address. Every password set or change is emailed to the account.

{
  "email": "you@yourcompany.com",
  "password": "min-8-chars"
}

Response: { "ok": true }.

POST/dealer/auth/login

Email + password → JWT.

{ "email": "you@yourcompany.com", "password": "..." }

Response:

{
  "ok": true,
  "token": "eyJhbGc...",
  "expiresAt": "2026-05-06T12:00:00.000Z",
  "dealer": { "id": "...", "email": "...", "company": "..." }
}

Rate limit: 8 attempts per 15 min per IP.

eSIM endpoints

GET/api/v1/esim/countries

List supported countries. Returns the upstream country catalog.

POST/api/v1/esim/bundles

List bundles for a country/region.

{
  "countryISO":   "JP",            // optional, ISO 3166-1 alpha-2
  "countryName":  "Japan",         // optional, alternative to ISO
  "region":       "Asia",          // optional
  "pageNumber":   1,               // optional, default 1
  "pageSize":     20               // optional, default 20, max 100
}

Response: paginated bundle list with each bundle's name, data allowance, validity, and price.

POST/api/v1/esim/order

Order an eSIM for an end customer.

{
  "bundleName":        "esim_5gb_30days_jp",  // required, from /bundles
  "customerReference": "ORDER-12345",         // optional, your tracking id
  "emailAddress":      "end-customer@x.com",  // optional, where the QR is sent
  "qrToCustomer":      true                    // optional, default false
}

Response: { "Status": "Success", "Iccid": "...", "QrCode": "...", ... } (upstream-format). The order is logged in your dealer history.

POST/api/v1/esim/details

Get activation status and data usage.

{ "iccid": "894900..." }

Returns activation state, data used vs allowance, expiry.

POST/api/v1/esim/revoke

Deactivate an eSIM upstream and update your dealer order history.

{ "iccid": "894900..." }

Rate limit: 10 per minute per dealer.

Top-up endpoints

For recharging existing SIMs (not new eSIMs).

GET/api/v1/topup/networks

List networks eligible for top-up.

POST/api/v1/topup/confirm

Validate a target SIM exists on a network. Use this before recharge to avoid charging a non-existent SIM.

{
  "networkName":     "Vodafone-UK",
  "contactNumber":   "+447700900000",   // either contactNumber
  "simSerialNumber": "894400..."         // OR simSerialNumber
}

POST/api/v1/topup/recharge

Execute a top-up recharge.

{
  "networkName":       "Vodafone-UK",       // required
  "contactNumber":     "+447700900000",     // OR simSerialNumber
  "simSerialNumber":   "894400...",
  "topUpValue":        20,                  // required, currency depends on network
  "bundleValue":       null,                // optional bundle add-on
  "bundleProductCode": null,                // the plan to apply, from topup/confirm BundleList
  "creditOnly":        false                // true = plain credit, no plan
}

topup/confirm returns two lists for a line: BundleList (plans, each with a BundleProductCode) and TopUpList (plain credit amounts).

US Unlimited by the day

A prepaid US unlimited line (talk, text, 5G data, real US number) sold by the day and pushed to the customer's phone over the air; no QR code. Any number of days from 1 to 365, no minimum, at your account's day rate (shown in your dealer portal). The start day counts as day 1; service ends at midnight US Pacific on the last day. One line per order. Your wallet is debited when the order is accepted and refunded if the carrier refuses the activation.

POST/api/v1/daily-lines/order

{
  "customerEmail": "traveler@example.com",
  "customerName": "Ana Lima",
  "days": 10,
  "start_date": "2026-11-02",        // optional: today (US Pacific) when omitted; up to 90 days ahead
  "eid": "89049032...5307",          // the phone's 32-digit eSIM id (or "imei": 15 digits); one is required
  "clientRef": "your-ref-123"        // optional, idempotent: the same ref returns the original order
}

Response 201: order_id, short_id, order_state (scheduled for a later start, activating while the carrier works, fulfilled when the line is on), charged_usd, phone once known, and fd with days, start_date, end_date, ends_at. Poll GET /api/v1/orders or use your order webhook; the number appears when the carrier confirms, usually within minutes.

Extending a running line

Send "extend_order": "<short_id of the earlier order>" with days instead of eid/start_date. The new days start the day after the current last day on the same number; no new activation, no gap. Only a line that is active can be extended; a closed line needs a new order.

GET/api/v1/daily-lines

Your lines: phone, status (activating, active, closed, failed), days, start_date, end_date, ends_at, customer_email, order_id.

Port-in: keep the customer's number

Moves a customer's existing US mobile number onto a new line on T-Mobile or AT&T. API only. Your wallet is charged when the port-in is accepted and refunded if the carrier refuses it. The old line must stay active until the port finishes. Most ports finish within hours; some take 1 to 2 business days.

GET/api/v1/port-in/plans

The plans a number can move onto, each with productId, carrier, name, term, price_usd (your price) and what the device needs. T-Mobile is the monthly unlimited line (fd:month, 1 to 12 months). AT&T plans are p3:2:PLAN.

POST/api/v1/port-in

{
  "productId": "fd:month",            // from /api/v1/port-in/plans
  "number": "3105551234",             // the number to move
  "accountNumber": "123456789",       // account number at the current carrier
  "pin": "1234",                      // transfer PIN from the current carrier
  "accountHolder": { "firstName": "Ana", "lastName": "Lima" },   // name on that account
  "address": { "line1": "100 Main St", "line2": "Apt 4", "city": "Los Angeles", "state": "CA", "zip": "90012" },  // billing address on that account
  "customerEmail": "ana@example.com",
  "eid": "89049032...5307",           // the new phone's 32-digit eSIM id
  "imei": "356789012345678",          // its 15-digit IMEI. T-Mobile: eid or imei. AT&T: both.
  "months": 1,                        // T-Mobile only, 1 to 12
  "clientRef": "your-ref-123"         // optional, idempotent
}

Response 201: order_id, short_id, status (pending, completed, failed, refunded), number, charged_usd, and esim once completed. The PIN is sent to the carrier once and not stored. A refused port (usually a wrong account number or PIN, or a name or ZIP that does not match the old account) needs a new port-in with the corrected details. A second port-in of a number that is still running answers 409.

GET/api/v1/port-in/{orderId}

Where a port-in stands, by short_id or order_id. T-Mobile lines also show line_status and end_date. You also get the Order ready or Activation failed notice you have switched on.

POST/api/v1/port-in/renew

{ "orderId": "MeiDlr-XXXXXXXXXXXX", "months": 1 }

Adds months to a T-Mobile port-in line from your wallet, starting the day after its current end. Renew before the end date: an unpaid line is paused at the end, and after 5 days it is closed and the number is gone. An AT&T line renews with POST /api/v1/lines/renew.

Numbers to move out

Buy US numbers you pick by area code, then move them to your own carrier. Switched on per account: ask us. Your wallet pays for each number when you order it. Each number comes with everything your carrier asks for to move it, and you see each move as it happens. A number not moved within 30 days is released unless you keep it, 30 more days at a time. The same is in your portal, on the Numbers to move out tab.

GET/api/v1/move-out-numbers/available?area_code=443

Up to 30 free numbers in the area code, each with its town. Narrow it with city or state. Also answers your price_usd per number, keep_price_usd, hold_days and max_per_order.

POST/api/v1/move-out-numbers

{
  "numbers": ["+14435550123", "+14435550124"],   // picked from the lookup, up to 20
  "client_ref": "your-ref-123",                   // optional, idempotent
  "webhook_url": "https://example.com/hooks/numbers"   // optional, https
}

Response 201: bought, ready, still_buying, refunded, charged_usd, and numbers, each with its id, number, status and, once ready, move: what your carrier asks for.

"move": {
  "account_number": "4435550123",            // the phone number itself
  "pin": "48201937",                          // made for this number only
  "billing_telephone_number": "4435550123",
  "account_name": "MEISIM USA LLC",
  "authorized_name": "First Last",
  "account_holder": { "first_name": "First", "last_name": "Last" },
  "account_type": "business",
  "service_address": { "line1": "...", "line2": null, "city": "...", "state": "..", "zip": "....." },
  "port_type": "full"
}

Give these to your carrier and ask for a full port. A number someone else bought first is skipped and not charged. With a webhook_url we post every change of every number, signed: X-MeiSIM-Signature is the hex HMAC-SHA256 of the raw body, keyed with the webhook_secret in this answer (shown once). Statuses: buying, ready (yours to move), moving (your carrier asked; we approve it within the hour), approved (it moves on the move date), moved, released (not moved in time), failed (not bought, refunded).

GET/api/v1/move-out-numbers

Your numbers, newest first, without PINs. Filter with ?status=ready.

GET/api/v1/move-out-numbers/{id}

One number (by its id or the number) with its PIN, and port while it moves: status, says, new_carrier, move_date, refused_because, notes from the porting team, and history.

POST/api/v1/move-out-numbers/{id}/keep

Adds 30 days at your keep price. We email you 3 days before a number would be released.

To move a number onto an AT&T line with us: POST /api/v1/port-in with accountNumber = move.account_number, pin = move.pin, accountHolder = move.account_holder and address = move.service_address. Webhook events: move_out.ready, move_out.moving, move_out.approved, move_out.date_changed, move_out.note, move_out.refused, move_out.cancelled, move_out.moved, move_out.released. A webhook body never carries the PIN.

Account & history

GET/api/v1/me

Whoami, with your wallet balance and today's line allowance.

{
  "id": "...",
  "company_name": "...",
  "email": "...",
  "status": "approved",
  "wallet_balance_usd": 245.30,
  "daily_line_limit": null,          // null = no daily limit
  "lines_today": null,
  "lines_remaining_today": null
}

GET/api/v1/orders

Recent orders. Returns up to the last 100, newest first.

[
  {
    "id": "...",
    "order_type": "esim" | "topup",
    "bundle_name": "esim_5gb_30days_jp",
    "customer_reference": "ORDER-12345",
    "email_address": "end-customer@x.com",
    "iccid": "894900...",
    "amount": 6.50,
    "status": "completed",
    "created_at": "2026-05-05T12:34:56Z"
  }
]

Wallet

GET/api/v1/wallet

Your balance, what is coming due against it, and recent transactions. Poll it to warn yourself before the wallet runs low. ?limit= sets how many transactions come back, 0 to 100 (default 20).

{
  "ok": true,
  "balance_usd": 245.30,
  "currency": "USD",
  "runway": { "covered": true, "needed_7d_usd": ..., "renewals_30d": [ ... ], "...": "..." },
  "auto_topup": { "enabled": false, "card": null, "threshold_usd": null, "amount_usd": null, "...": "..." },
  "transactions": [
    { "id": "...", "created_at": "2026-11-04T12:34:56Z", "type": "debit", "amount_usd": -35.00, "balance_after_usd": 245.30, "description": "...", "related_order_id": "..." }
  ]
}
runway fieldMeaning
coveredtrue while balance_usd is at least needed_7d_usd. Alert on false.
needed_7d_usdA week of daily-rate rent plus every renewal that charges itself in the next 30 days.
renewals_30dRenewals due in the next 30 days, grouped by day: { ends_on, lines, usd, auto_renew }. renewals_30d_usd is their total, auto_renew_30d_usd the part that renews by itself.
daily_lines, per_day_usd, days_coveredNumbers on the daily rate, what they cost a day together, and how many days the balance pays for them.
monthly_lines, noteNumbers on a monthly term, and the same outlook in one sentence.

The runway counts the US numbers you rent from us and every line you put on auto-renew with POST /api/v1/lines/auto-renew. A line you renew yourself is not in it, so keep its renewal cost in the wallet too.

POST/api/v1/wallet/topups

Start a USDT top-up. You get our receiving addresses and the exact amount to send; the credit lands in your wallet by itself once the transfer confirms on-chain, usually within a few minutes. There is no fee from us; you pay only the network fee. The credit is from $50 to $10,000 per top-up. Rate limit: 10/min.

POST /api/v1/wallet/topups
{ "amount_usd": 100 }

{
  "ok": true,
  "id": "MeiTopup-ABCDEFGHJKMN",
  "method": "usdt",
  "status": "pending",
  "credit_usd": 100,
  "amount_usdt": 100.374512,          // send exactly this
  "networks": [
    { "network": "TRC20", "name": "USDT on Tron (TRC-20)", "address": "T..." },
    { "network": "ERC20", "name": "USDT on Ethereum (ERC-20)", "address": "0x..." }
  ],
  "expires_at": "2026-11-04T13:34:56.000Z",
  "created_at": "2026-11-04T12:34:56.000Z",
  "payment": null,
  "pay_url": "https://www.meisimusa.com/crypto-pay.html?o=MeiTopup-ABCDEFGHJKMN",
  "note": "Send exactly 100.374512 USDT to one of the addresses by ..."
}

Send amount_usdt exactly, on either network, within the hour. The cents after the credit amount are how we know the transfer is yours, so each top-up has its own amount. pay_url is the same payment page the dealer portal opens, if a person is paying.

GET/api/v1/wallet/topups/{id}

Where a top-up stands. Each read also checks the network for the transfer, so polling this is enough; we also check on our own. Same response as above, plus wallet_balance_usd.

statusMeaning
pendingWaiting for your transfer, inside the hour.
expiredThe hour passed. A transfer of the exact amount that arrives late is still credited for 7 days, and note says until when. To pay now, start a new top-up.
creditingThe transfer is confirmed and the credit is being added. payment has the network and transaction hash.
paidIn your wallet.

The addresses are listed only while a top-up is open. You can read only your own top-ups; any other id answers 404.

GET/dealer/wallet

Wallet balance and recent transactions, in the dealer portal's own format. New integrations can use GET /api/v1/wallet above.

{
  "ok": true,
  "balance": 245.30,
  "markupPct": 15,
  "resendFee": 1.00,
  "company": "...",
  "email": "...",
  "transactions": [
    {
      "id": "...",
      "created_at": "2026-05-05T12:34:56Z",
      "type": "debit" | "topup",
      "amount_usd": -6.50,
      "balance_after_usd": 245.30,
      "description": "...",
      "stripe_session_id": null,
      "related_order_id": "..."
    }
  ]
}

GET/dealer/statement

CSV export. Default range: last 90 days.

GET /dealer/statement?from=2026-04-01&to=2026-05-01

Returns CSV with columns: Date, Type, Amount USD, Balance after USD, Description, Order ID, Stripe session.

POST/dealer/topup

Create Stripe checkout session for wallet top-up.

{ "amountUsd": 100 }

amountUsd must be between $50 and $10,000. Response: { ok, checkoutUrl, netAmt, grossAmt, fee }. Redirect user to checkoutUrl. Rate limit: 5/min.

POST/dealer/topup-intent

Create Stripe PaymentIntent for embedded checkout.

{ "amountUsd": 100 }

Response: { ok, clientSecret, publishableKey, netAmt, grossAmt, fee }. Use Stripe.js with clientSecret. Rate limit: 10/min.

GET/dealer/topup/preview?net=100

Preview Stripe fee. Response: { ok, net, gross, fee }.

Order from your wallet

POST/dealer/order

Alternative to /api/v1/esim/order — debits your wallet at your dealer price.

Moxee plans need imei but no eid. The carrier issues the Moxee eSIM profile from its own pool, so there is no customer EID to bind — send one and it is ignored. The customer's 15-digit device IMEI is required. Every other US prepaid (p3:) carrier still requires both.

Changed 2026-08-10 — breaking. Moxee previously needed neither field, because we activated it onto a SIM from our own stock. Moxee orders sent without an imei now fail with a 400.

{
  "productId":     "p3:att-prepaid-30",      // required
  "customerEmail": "end@x.com",                // required
  "customerName":  "Jane Doe",                 // required
  "quantity":      1,                          // optional, 1–20
  "language":      "en",                       // optional
  "imei":          "359123456789012",          // required for ALL US prepaid, Moxee included
  "eid":           "89001012...",              // required for US prepaid — NOT for Moxee
  "sim_type":      "physical",                 // optional, Moxee only: activate the SIM cards we sent you
  "iccids":        ["8901260812345678901"],    // with sim_type physical: one ICCID per line (= quantity)
  "whatsappNumber":"+13055550123",             // optional — see below
  "address": {                                 // optional — see below
    "first_name":     "Jane",
    "last_name":      "Doe",
    "address_line_1": "123 Main St",
    "city":           "Phoenix",
    "state":          "AZ",
    "zip_code":       "85001",
    "phone":          "+15555550100"
  }
}

Physical SIM cards (Moxee only)

If we have sent you Moxee SIM cards, activate a plan onto a card instead of an eSIM: send "sim_type": "physical" and "iccids", one ICCID per line, so the array length equals quantity. The imei is optional for a card (it goes into whichever handset you choose); given, it must still be 15 digits. No eid.

The order's lines come back with "sim_type": "physical", the number in phone_number, the card's ICCID, and qr_available: false: put the card in the handset and the number is live on it. A card activates once; an ICCID already on a live or pending order is refused with a 409 naming that order. The same works in bulk upload through an iccid column (one card per row, quantity 1).

Carriers your account cannot activate

Some US carriers can be switched off for dealer accounts — across the board or for one account — usually because the carrier's own fraud team has raised something about traffic on those lines. When that applies to you, the carrier's plans do not appear in the catalogue you are served, and /dealer/order (and /dealer/replace/:orderId) answers 403 with "<Carrier> activations are not available on your account." Nothing is charged and no line is created. Refills of lines you already sold on that carrier keep working — only new activations are refused.

2026-08-12 — LinkUp Mobile is blocked for all dealer accounts. AT&T's fraud department flagged LinkUp lines activated through us as SMS spamming. Existing LinkUp lines are unaffected and can still be recharged.

WhatsApp delivery (whatsappNumber)

Optional. When set, your customer also gets the assigned number, the QR and the one-tap install links on WhatsApp, the moment the line goes live. Email is sent either way — this adds a channel, it never replaces one.

The activation address (US p3: plans)

address is optional, and it does two jobs at once: it is registered with the carrier as the line's E911 (emergency services) address, and the carrier picks the number's area code from the ZIP — so a Phoenix ZIP produces a Phoenix number. Omit address entirely and we assign both for you.

If you send any of address_line_1, city, state or zip_code, you must send all four, valid. A partial address can't be used for either job, so the order is rejected with 400 rather than quietly activating on our address (which would give your customer an unexpected area code).

address_line_1Must start with a street number (123 Main St). A PO Box or PMB/mailbox is never a valid E911 address.
city2+ characters
state2-letter code (AZ), not the full state name
zip_code5 digits (ZIP+4 accepted, extra digits ignored)

first_name / last_name / address_line_2 / phone are always optional, and an address carrying only names is fine — it just names the customer.

We do not pre-validate the address against the carrier's E911 database (no carrier exposes one to resellers) — it is checked at activation. If the carrier rejects it, we automatically retry once with our own address so the line still activates; the area code then follows ours, not the one you asked for.

Response:

{
  "ok": true,
  "orderId": "...",
  "shortId": "MM-AB12CD",
  "unitPriceUsd": 25.00,
  "totalUsd": 25.00,
  "newBalance": 220.30,
  "activation": "delivered"        // "delivered" | "pending" | "failed"
}

Returns 402 Payment Required if balance is insufficient.

Branch on activation, not on ok. ok: true means the order was accepted and priced — the carrier can still refuse the activation after that. pending means the carrier has it and hasn't confirmed yet; we deliver automatically when it does.

When activation is "failed" the response also carries a failure object — the carrier's verdict, what it means, and the one thing that changes the outcome on a retry. Show whatToDo to whoever is holding the handset:

{
  "ok": true,
  "shortId": "MeiDlr-5WTVYMEKJUH2",
  "activation": "failed",
  "failure": {
    "reason":   "The device is compatible for esim activation through IMEI2. Please use IMEI2 for esim activation.",
    "meaning":  "The phone is fine — we were given the IMEI for its physical SIM slot, not its eSIM.",
    "whatToDo": "Dial *#06# on the handset. Dual-SIM phones list TWO IMEIs — use the SECOND one (IMEI2), which is the eSIM. Place the order again with that number and it should go through.",
    "refunded": true
  }
}

refunded: true means the charge is already back in your wallet and there is nothing to claim. The one verdict to not retry blindly is a carrier timeout — there we cannot tell whether a line was created, and whatToDo says so.

On a successful order this response carries no eSIM data — take the orderId (or shortId) and call the endpoint below to get the QR / activation code.

GET/dealer/order/:orderId

The order's eSIM: QR, activation code, ICCID and assigned US number. Accepts the UUID or the short id (MeiDlr-…), and is scoped to your own orders. One entry per line, so a quantity: 3 order returns three.

{
  "ok": true,
  "orderId": "…", "shortId": "MeiDlr-3NSXHFD8THR2",
  "productId": "p3:318:698", "state": "fulfilled", "quantity": 1,
  "customer": { "email": "end@x.com", "name": "Jane Doe" },
  // on a failed order only — same shape as POST /dealer/order's `failure`,
  // alongside the raw carrier string in `error`
  // "failure": { "reason": "…", "meaning": "…", "whatToDo": "…" },
  "lines": [{
    "line": 1,
    "status": "delivered",
    "activation_code": "LPA:1$CUST-001-V4-PROD-ATL2.GDSB.NET$EAF6DA2AB…",
    "smdp": "CUST-001-V4-PROD-ATL2.GDSB.NET",
    "matching_id": "EAF6DA2AB…",
    "iccid": "89049032000001000096650386218347",
    "phone_number": "3415128315",
    "qr_png_url": "https://api.meisimusa.com/qr?size=480&text=…",
    "install_ios_url": "https://esimsetup.apple.com/…",
    "install_android_url": "https://esimsetup.android.com/…"
  }]
}

Data balance

GET /dealer/order/:orderId/usage returns the live balance of a travel-data eSIM per line: data_total_mb, data_used_mb, data_left_mb, expires_at, and status: active, not_installed (the QR has not been scanned), expired (installed, but the plan ended) or deleted (removed from the phone). ?line=N narrows a multi-eSIM order. UK lines and US carrier lines answer 409 NO_USAGE_API: those networks expose no usage endpoint; the customer sees usage in the carrier's own app.

About the QR code

The carrier issues an activation string, not a picture. activation_code is the GSMA LPA:1$<smdp>$<matchingId> payload, and a QR code is simply that string encoded. This holds for LinkUp Mobile and every other US carrier. Three ways to deliver it:

  1. render activation_code as a QR yourself;
  2. show qr_png_url — a PNG we render, no auth needed, safe to drop straight into an <img>;
  3. or call GET /dealer/order/:orderId/qr for the PNG bytes over your API key — ?line=N (default 1) and ?size= (64–1024, default 480).

install_ios_url / install_android_url are one-tap install links: on iOS 17.4+ and recent Android, tapping installs the eSIM with no scan at all.

status is one of three, and your next move differs for each:

deliveredwe hold the line. Check qr_available before showing a QR
provisioningthe carrier hasn't issued it yet — poll, don't treat as an error
unavailableorder finished with nothing recorded. Won't change on its own — contact us

Gate your QR rendering on qr_available, not on status. qr_source says where the QR comes from, and it matters:

activation_codewe hold the LPA string. qr_png_url always renders, and the one-tap install links work.
carrierthe carrier holds the profile and serves its QR image (Moxee, LinkUp). qr_png_url fetches it on demand — handle a failed image load, since an older line may have no profile behind it. activation_code and the one-tap links are null; the customer scans the QR.

The QR route answers 409 when there is no QR to give, and 404 only when the line does not exist.

Cancelled or refunded orders return no install data (lines: [], and the QR route answers 410) — their profiles are revoked at the carrier.

POST/dealer/resend-email/:orderId

Resend an eSIM activation email. Charges the resend fee on your account (see resendFee in GET /dealer/wallet).

{ "email": "alternate@x.com" }

Body is optional — omit email to resend to the original address.

POST/dealer/replace/:orderId

Issue a replacement eSIM at the original product's current price. Charged from your wallet. Returns 402 if insufficient balance.

Renewing a US carrier line from your wallet

A US carrier line bought with /dealer/order (a p3: plan) runs for one paid cycle. Renew it from your wallet with the calls below. The top-up endpoints are a different provider and do not reach these lines.

Timing. A refill restarts the cycle from the day it is applied, so renewing early throws paid days away. After the cycle ends the carrier holds the number for a few days (five on Moxee) before it is gone. Auto-renew renews in the last 24 hours of the cycle for that reason.

GET/api/v1/lines/plans?orderId=…

The renewal plans this line can take, priced as your price (an agreed price on your account included). Name the line by orderId, iccid or contactNumber.

{
  "ok": true, "order_id": "MeiDlr-XXXXXXXXXXXX", "contact_number": "6455551234",
  "count": 2,
  "plans": [
    { "product_id": "r3:445:2037", "title": "100 SMS Only (Refill)", "validity": "1 month",
      "is_rtr": false, "your_price_usd": 7.00, "priced_at_usd": null }
  ],
  "auto_renew": { "on": false },
  "expires_at": "2026-11-30T17:04:40.119Z"
}

A plan with is_rtr: true is a range top-up: add &amount=30 to price it at the amount you intend to load.

POST/api/v1/lines/renew

{ "productId": "r3:445:2037", "orderId": "MeiDlr-XXXXXXXXXXXX" }

Charges your wallet at your_price_usd and refills the line at the carrier in the same call. 201-style success carries charged_usd, wallet_balance_usd and carrier_ref. 402 is a short wallet (required, balance, shortfall); 424 is a carrier failure, already refunded (refunded_usd). A range plan also needs amountUsd.

POST/api/v1/lines/auto-renew

{ "productId": "r3:445:2037", "orderId": "MeiDlr-XXXXXXXXXXXX" }        // on
{ "on": false, "orderId": "MeiDlr-XXXXXXXXXXXX" }                      // off

Say it once and the line renews itself: in the last 24 hours of every cycle we charge your wallet at your_price_usd and refill the line, through the same path as /renew. Fixed price plans only; a range plan needs an amount each time, so renew those yourself. The answer carries auto_renew, plan, your_price_usd and expires_at; the plan list above shows the state afterwards.

If the wallet is short on the day, you get one email per run naming the numbers, the line runs to the end of its paid cycle, and we try again on every run while the carrier still holds the number. Top up, or renew now, and it goes through. Auto top-up in the dealer portal keeps the wallet from running dry in the first place.

Real T-Mobile numbers: incoming SMS and voice over SIP

Every endpoint here takes your API key. Numbers are closed per account by default; ask us to open them, and to add voice.

GET/dealer/sms-lines/offer

What you may buy and at what price: first_month_usd, renew_price_usd, term_days, your balance, and voice.available with voice.price_usd, the Voice + SMS price per number per month, when voice is open on your account.

POST/api/v1/sms/order

{ "count": 5, "area_code": "718", "zip_code": "11201", "voice": true, "billing": "monthly", "months": 2, "line_history": "fresh", "auto_renew": true, "customer_reference": "ord-48213" }

Which lines: line_history is required on monthly orders. "fresh" = a number you have never had (new from the carrier, or from our stock if it was never yours): your account's usual minimum applies, and no refund if the carrier blocks it. "any" = a number from our stock, which may be one you returned before. Daily-rate orders are always "any"; a fresh line cannot be bought on the daily rate.

count is required, a whole number of numbers. A body without it, or with a field not listed here, is refused with 400 invalid_input and nothing is charged. A created order answers 201; a repeated customer_reference answers 200 with the first order.

Two ways to pay. billing: "monthly" (the default) pays months up front, 2 months minimum (2 to 12; an account we have allowed single months may send 1, and min_months on the offer says which you are; with no months sent the order is for your minimum): the first month at first_month_usd, every month after at renew_price_usd. Voice numbers are monthly only, 2 months minimum for every account, and a voice number is cancelled when it ends: it is never given out again. billing: "daily" is the daily rate for text-only numbers (daily.price_usd). Every activation is daily.min_days days minimum, paid at purchase; from the day after, each morning we take the next day from your wallet. A new number has a one-time activation fee (daily.activation_fee_usd); a number that is already active in our stock has none, and the response itemises it (days_paid, activation_fee_usd, new_numbers, from_pool). Returning a number early does not refund the days paid. If the wallet is short, the number stops at 22:00 US Eastern that day and is released; we retry at 18:00 US Eastern first.

count is required. area_code (3 digits) or zip_code (5 digits) asks the carrier for a number local to it; it is a request, not a promise. voice: true orders Voice + SMS lines at your Voice + SMS price, and needs voice open on your account. auto_renew: true switches auto-renew on for the numbers as they arrive. Charged to your wallet up front; 402 with shortfall when it is short. The numbers appear in /api/v1/sms/lines within a few minutes.

Your reference, and retries. Send customer_reference (up to 120 characters: letters, digits and . _ - : / #) to tie the order to your own records. It is unique on your account: sending the same reference again orders and charges nothing and answers { "ok": true, "duplicate": true, "order": {...} } with the first order. So if a call times out on your side, repeat it with the same reference, or look the order up. The response carries order_id, and every number in /api/v1/sms/lines carries the order_id and customer_reference of the order that bought it.

What is left, on every order. The 201 answer carries wallet: balance_usd after this order, per_day_usd and days_covered for your daily-rate numbers, renewals_30d_usd for the monthly numbers that end within 30 days, needed_7d_usd (a week of daily rent plus every auto-renew due within the month), covered (the balance meets it) and a plain note. Shown, never enforced: an order is never refused for what later charges will need. Auto top-up is the fix: save a card in the dealer portal (Wallet, Auto top-up), name a floor and a refill, and a charge that finds the wallet short is paid from the card at once instead of stopping the number.

Days up front on the daily rate. With billing: "daily", send days (from daily.min_days to 90) to pay that many days at purchase instead of the minimum. After them the wallet pays day by day as usual; to end a number on its paid date instead, set POST /api/v1/sms/lines/:number/daily-stop.

GET/api/v1/sms/orders/:id

One order, by order_id or by your customer_reference: status (provisioning, partially_fulfilled, fulfilled, closed_refunded, cancelled), ordered, delivered, outstanding, refunded_numbers, refunded_usd, refunded_at, the numbers delivered so far, billing, days_paid, charged_usd, created_at, completed_at. GET /api/v1/sms/orders?limit=50 lists your latest orders the same way.

If the carrier cannot fill an order. When an order has received no new number for 3 hours, it is closed at what it delivered and the missing numbers are refunded to your wallet automatically: their share of the days or months paid and their activation fee. The order then shows closed_refunded with refunded_numbers and refunded_usd, the refund is a line in your wallet history, and you get a notice. The numbers you did receive are unaffected.

{ "ok": true, "ordered": 5, "charged_usd": 80.00, "billing": "monthly", "months": 2, "per_line_usd": 16.00, "term_days": 60, "voice": true,
  "requested": { "area_code": "718", "zip_code": null } }

GET/api/v1/sms/lines?limit=100&offset=0&q=

Your numbers, paged. Each carries number, e164, status, expires_at, auto_renew, renew_price_usd, voice and, on a voice line, sip_status (preparing while the number is being set up, usually within a day, then ready) and sip. A line in trunk mode shows its bridge login (host, port, tls_port, user; one call at a time, caller ID is the number). A line not yet switched shows bridge_required: true: switch it with /sip/mode below. Loop while next_offset is present.

kind says what each line is: sms or voice (a number in our gateway, read over this API) or handset, a T-Mobile Talk & Text line delivered as an eSIM for a phone. A handset line's calls and texts happen on the phone, so /messages returns nothing for it and it has no sip; instead it carries esim_status (preparing for the few minutes until the carrier hands over the code, then ready) and esim with lpa (the activation code), smdp, activation_code, qr_image_url, ios_install_url and android_install_url. One install per code. It renews and auto-renews like any monthly number; the daily rate and the voice plan do not apply to it (409).

POST/api/v1/handset/order

{ "months": 1, "auto_renew": true, "area_code": "310", "zip_code": null, "label": "sales phone 2" }

Orders one T-Mobile Talk & Text line for a phone, when it is switched on for your account (403 otherwise). Paid from your wallet at your price, months (1 to 12) up front; 402 with shortfall when the wallet is short. A field not listed here is refused with 400 and nothing is charged. The 201 answer carries status: ordered (the carrier issues the number within about 20 minutes), preparing (the number is live, the eSIM code follows within minutes) or ready; number when known; order_id; charged_usd; balance_usd. The line then appears in GET /api/v1/sms/lines as kind: "handset" with its esim, and the account email receives the QR. Renew and cancel it with the same calls as any number.

GET/api/v1/sms/sip

Where to send calls: the bridge host (sip.meisimusa.com), port and tls_port, and how many voice numbers you have. Every voice number has its own login at that host, shown on the number in /lines; the password appears once, when you switch the line to trunk mode or rotate it.

Choosing the number a call goes out from. Each number has a login of its own, so the login you send with picks the number. Caller ID is always that line's number; the From header you send is not used.

One login for all your numbers. A dialer or PBX that keeps one SIP login and sets a caller ID per campaign can ask us to switch this on for the account. A call sent with any of your logins then goes out from the voice number of your account that its From names (ten digits, with or without 1 or +1). Any other From is ignored, and the call goes out from the login's own number. Each number still carries one call at a time, and each call is listed under the number it went out from. sip.caller_id_by_from on a number in /lines says whether it is on.

Outbound calls reach US numbers only. These lines cannot call international numbers; a call abroad is refused with 403.

Trunk mode: the bridge for voice-agent platforms

Voice lines work in trunk mode, which is what voice AI platforms that only accept SIP trunks need. Our switch at sip.meisimusa.com keeps the line connected to the carrier, the line gets a login of its own at our switch, your platform or PBX sends outbound calls there with digest authentication on every INVITE (no REGISTER), and every inbound call is forwarded to one SIP address you set. UDP and TCP on 5060, TLS on 5061, SRTP accepted; G.711 and Opus toward your platform. Our calls to your platform come from 45.77.205.201, for platforms that allowlist an address. sip.meisimusa.com is that same address, so where a platform asks for a number instead of a name, give it 45.77.205.201. Send the number you are calling as +1 and ten digits; 1 and ten digits, or ten digits alone, work too.

The rules, enforced on the switch: caller ID is always the line's number (the From you send is not used, unless your account has one login for all its numbers); US numbers only, no Canada, Caribbean or territories, no 900, 976, N11 or 933; one call at a time per line in both directions (486, shown in the call log with that code); 60 minutes per call; a calls-per-minute cap per account; a line whose account is closed or unfunded answers 403. An inbound call that your platform does not answer within 30 seconds fails back to the caller. The caller's number is the caller ID of the forwarded call, the line's number travels in X-MeiSIM-Line and the caller in X-MeiSIM-Caller. Tested end to end with Vapi (the setup guide has the exact steps) and with a self-hosted LiveKit; the presets for the other three platforms are in place and verified with you on first use.

POST/api/v1/sms/lines/:number/sip/mode

{ "mode": "trunk" }          // add "all": true when the answer is 409 SHARED_LOGIN

Switches the line. A new voice line shows sip_mode: "register" and has no login yet: this call is the first step, and it is what gives the line its login. The trunk answer carries sip: host, port (5060), tls_port (5061), user and password. The password is 32 random characters, shown in this answer and never again; we keep only a digest hash. Some older lines share one login with others on your account, and a login can serve only one line in trunk mode: switching one of them answers 409 with code: "SHARED_LOGIN" and siblings, and all: true switches them together (each gets its own bridge login and password, listed in also). Anything of yours still using an old login must be stopped first. Going back to the old register mode is closed (409 with code: "REGISTER_MODE_CLOSED").

POST/api/v1/sms/lines/:number/sip/rotate

A new password for the bridge login, live within a minute, shown once.

GET/api/v1/sms/sip/presets

The forwarding presets: vapi, retell, elevenlabs, livekit, openai and custom, each with its transport, whether it wants SRTP, the parameters it needs (sip_subdomain for LiveKit Cloud, project_id for OpenAI, the credential_id of your SIP trunk for Vapi) and a note on the platform side.

PATCH / DELETE/api/v1/sms/lines/:number/sip/inbound

{ "preset": "livekit", "params": { "sip_subdomain": "abc123xyz" } }
{ "preset": "custom", "uri": "agent@sip.example.com:5061", "transport": "tls", "srtp": true,
  "auth_user": "meisim", "auth_pass": "…", "headers": { "X-Agent": "reception" } }

Where this line's inbound calls go. A preset builds the address from the line's number and the platform's identifiers; custom takes any user@host[:port] (a hostname or an IPv4, no sip: prefix, no parameters). transport is udp, tcp or tls (TLS implies SRTP unless srtp: false); auth_user and auth_pass answer a digest challenge from your platform; up to five X- headers ride on every forwarded INVITE. The answer repeats the forwarding in sip.inbound with auth_pass_set instead of the password. DELETE clears it; with nothing set, inbound calls fail with 480. 409 NOT_TRUNK_MODE when the line is in register mode, 400 INVALID_FORWARDING with the reason otherwise. The line's sip block in GET /api/v1/sms/lines shows mode, the login (never the password) and the forwarding.

GET/api/v1/sms/lines/:number/calls

{ "ok": true, "number": "2125550100", "count": 1, "calls": [
  { "direction": "inbound", "from": "+13105550199", "to": "2125550100",
    "started_at": "2026-11-04T01:36:54.000Z", "answered_at": null, "ended_at": "2026-11-04T01:36:54.000Z",
    "duration_s": 0, "billed_s": 0, "result": "failed", "ok": false, "reason_code": "login_needed",
    "reason": "Your voice platform asked our SIP bridge for a username and password, and this line's call forwarding has none.",
    "fix": "Add your platform's SIP username and password to the line's forwarding (auth_user and auth_pass), or set your platform to accept calls from our bridge at 45.77.205.201.",
    "sip_code": null } ] }

The line's calls, newest first. For every line at once, with filters, totals and a file, use the call log. limit goes up to 200 (50 by default), and before (a date) fetches the next page, given as next_before. result is answered, no_answer, busy, cancelled, refused or failed. When an incoming call fails for a reason you can fix on your side, reason_code names it (login_needed, login_refused, refused, number_unknown, unreachable, media_mismatch, unavailable, no_forwarding or platform_error), and reason and fix say it in plain words. Each trunk-mode line in GET /api/v1/sms/lines also carries its last incoming call in sip.last_inbound_call, or null before the first one. It also carries its last call out in sip.last_outbound_call: at, result, ok and, when the call failed for a reason you can fix, reason_code, reason and fix. It holds no phone numbers. A call refused at the login step is matched to a line by the caller ID it carries, so it may not have come from your system, and note says so. null means no call out on your account yet.

A call out that our bridge refuses at the login step is in the list too, with result refused and its own reason_code: out_login_unknown (the bridge does not know the SIP username your system sent), out_login_password (the password did not match), out_login_missing (your system did not answer the bridge's request for a login) or out_login_refused (the username or the password did not match). reason says what kind of username was sent when that explains it, for example a masked placeholder or the phone number. We never keep or show the username itself.

An answered call also says whether audio was carried and which side ended it. audio is both_ways, far_side_silent (none came from the far side), your_side_silent (none came from your system) or no_audio. ended_by is you, far_side or meisim. Both are null when the record does not hold them: on a call shorter than 2 seconds and on calls before November 6, 2026. meisim means our bridge ended the call itself. A call out that is answered and then receives no audio at all from the far side in the six seconds after the answer is ended by the bridge: its audio is far_side_silent, and your system receives a BYE with Reason: Q.850;cause=41. A call that carried audio in those seconds is never ended this way. This is a count of audio packets, never a recording. It says audio was carried, not what was in it: a far side that answers and says nothing still sends audio. A call out that is turned away before it is answered says so in reason with the SIP code your own system received, for example 480.

When calls into a line start failing for one of those reasons, we email you once, with the reason and the fix. You hear from us again only if calls work and then fail, fail for a different reason, or still fail after you change the forwarding. A failure you have already acted on is not emailed: if you changed the forwarding after the failed call (or made a new login after a refused one), the next call decides. Calls out that are refused at the login step are told the same way, at most once a day for a line. In your dashboard this email is "Voice line call failed" under Notifications, where you can turn it off.

GET/api/v1/sms/calls

GET /api/v1/sms/calls?from=2026-11-05&to=2026-11-05&result=failed&limit=100

{ "ok": true, "from": "2026-11-05T00:00:00.000Z", "to": "2026-11-06T00:00:00.000Z", "number": null, "count": 1,
  "calls": [
    { "id": "5f0c2a6e-3b1d-4c7a-9e21-7d4f0a6b8c11", "line": "2125550100", "direction": "outbound",
      "from": "2125550100", "to": "3105550199",
      "started_at": "2026-11-05T17:45:59.000Z", "answered_at": null, "ended_at": "2026-11-05T17:46:01.000Z",
      "duration_s": 2, "billed_s": 0, "ring_s": null, "result": "failed", "ok": false, "sip_code": 480,
      "reason": "The call was turned away on the carrier side before it rang (SIP 480).",
      "fix": null, "reason_code": null, "audio": null, "ended_by": "far_side", "early_media": false } ],
  "next": "MjAyNi0xMS0wNVQxNzo0NTo1OS4wMDBafDVmMGMyYTZlLTNiMWQtNGM3YS05ZTIxLTdkNGYwYTZiOGMxMQ",
  "summary": { "total": 120, "answered": 96, "no_answer": 2, "busy": 1, "cancelled": 3, "refused": 2, "failed": 16,
    "inbound": 8, "outbound": 112, "talk_seconds": 5410,
    "by_sip_code": { "200": 96, "480": 14, "487": 3, "603": 2 },
    "audio": { "both_ways": 94, "far_side_silent": 1, "your_side_silent": 0, "no_audio": 0 },
    "complete": true } }

The call log of your account: every call on your voice lines for a period, newest first. It is the same log as the Call log window in your dashboard. Use it to analyze your own calling: how many calls connected, how each of the others ended and with which SIP code, how long they rang and how long they lasted.

Filters, all optional: from and to (a day such as 2026-11-05, taken as that whole day in UTC, or a date and time; with neither you get the last 7 days, and one request covers at most 92 days), number (one of your lines), direction (inbound or outbound), result (answered, no_answer, busy, cancelled, refused or failed), sip_code, and other (3 to 15 digits of the other number: the number you called, or the caller). limit is 100 by default and at most 500. When there are more calls, the answer carries next: send it back as next with the same filters to get the following page.

Each call has the fields of a line's call list, and these: id (a reference you can quote to us), line (your number the call was on), ring_s (seconds from the start to the answer) and early_media (whether there was sound before the answer, such as a ringback tone or a recorded announcement; null on calls before November 6, 2026). refused means our bridge stopped the call: a login, a busy line, a limit, or a number this line does not call. failed means the call left our bridge and did not connect; reason says how, with the SIP code.

summary comes with the first page and covers the whole period you asked for, not only the page: the count for each result, calls in and out, the seconds of talk, the count for each SIP code, and for answered calls how many carried audio which way. It reads up to 20,000 calls; complete is false when the period holds more, and a shorter period gives exact totals.

Add format=csv to download the period as a file (up to 20,000 calls, newest first, times in UTC), with the same filters. The response header X-Calls-Complete is false when the period holds more than the file. Files are limited to 6 a minute.

What is never in the log: a recording or any part of what was said, and anything about the networks between our bridge and the other party. The log holds timings, counts and how each call ended, for your own calls only.

Setting up LiveKit (verified)

  1. Switch the line to trunk mode and keep the login and password from the answer.
  2. In LiveKit, create an outbound trunk: address sip.meisimusa.com, transport UDP (or TLS on 5061), numbers +1 and the line, auth_username and auth_password set to the bridge login. Outbound calls then leave with the line's number as caller ID; dial US numbers in +1 form.
  3. Create an inbound trunk for +1 and the line with allowed_addresses containing 45.77.205.201 (or set a username and password on the trunk and give the same pair as auth_user and auth_pass below), and a dispatch rule to the room or agent that should take the call.
  4. Set the line's forwarding: { "preset": "livekit", "params": { "sip_subdomain": "<your project's SIP subdomain>" } } for LiveKit Cloud, or { "preset": "custom", "uri": "+1<line>@<your SIP service host>:<port>" } when you host LiveKit yourself.
  5. Call the line: the SIP participant joins with the caller's number as its identity, and X-MeiSIM-Line says which line rang. Place a call with CreateSIPParticipant on the outbound trunk: it rings the destination within a few seconds.

Setting up Vapi (tested)

  1. Switch the line to trunk mode and keep the login and password from the answer.
  2. In Vapi, create a BYO SIP trunk credential (POST /credential, provider: "byo-sip-trunk") with one gateway: ip 45.77.205.201, port 5060, netmask 32, inboundEnabled and outboundEnabled true, outboundProtocol udp. Give the address, not the name sip.meisimusa.com: Vapi accepts only a numeric address on a gateway that receives calls. Put the bridge login in outboundAuthenticationPlan (authUsername and authPassword) and set outboundLeadingPlusEnabled to true.
  3. Import the number (POST /phone-number, provider: "byo-phone-number") as +1 and the line, with that credential's id as credentialId and your assistant as assistantId.
  4. Set the line's forwarding: { "preset": "vapi", "params": { "credential_id": "<the credential's id>" } }. Calls to the line then go to +1<line>@<credential id>.sip.vapi.ai.
  5. Call the line: your assistant answers, and it sees the caller's number. Place a call with POST /call and the phone number's id: the phone you call shows the line's number.

Every request in full, what we tested and what each failure looks like on Vapi's side are in Connect MeiSIM to Vapi. Use UDP, as shown: that is the setup we tested end to end, and we have not finished testing encrypted calls (TLS with SRTP) with Vapi. After you rotate the line's password, create a new credential in Vapi with the new password and point the number at it.

Retell, ElevenLabs and OpenAI Realtime: pick the preset, give the identifier it asks for, and import the number on the platform in +1 form (Retell: a custom telephony number; ElevenLabs: a SIP trunk phone number, TLS; OpenAI: the project's SIP endpoint and the realtime.call.incoming webhook). We have the presets in place and verify each one with you on first use.

GET/api/v1/sms/messages?number=&since=&limit=

Incoming texts on your numbers. Ask for messages since the last id you saw so nothing falls between two polls.

POST/api/v1/sms/lines/:number/send

{ "to": "2125551234", "message": "See you at 3pm" }
{ "to": "68953",      "message": "HELP" }          // a 5 or 6 digit short code works too

Sends a text from one of your numbers to a 10-digit US number or to a 5 or 6 digit short code. Sending is switched on per account on request, and each number has its own monthly allowance. The same limits apply here as in the console: a send over a limit comes back as 429 with the reason. A number or an account that has no sending answers 403 with code: "SENDING_NOT_ENABLED" and retryable: false: waiting does not change that, so ask us to switch sending on. If the text cannot be handed to the carrier, the answer is 424 with code: "SEND_FAILED" and retryable: true: try again in a minute. A failed attempt still counts against the number's allowance. The answer says status: "accepted": the carrier took the text. There is no delivery receipt on a mobile line, so accepted is the last thing anyone can see; a text that is accepted and never arrives was dropped by a carrier on the way, usually because it looked like a broadcast. One cause is refused before it can happen: the same text to more than three numbers from one line inside an hour answers 429 with code: "SAME_TEXT_FAN_OUT" and retryable: false, because carriers drop that pattern silently and the number can stay filtered afterwards. These lines are for one-to-one conversations: write to each person in their own words. Spam of any kind closes the account.

GET / POST/api/v1/sms/webhook

The account's main webhook: where we push each incoming text as it arrives. { "webhook_url": "https://…" } sets it and { "webhook_url": "" } clears it. The answer carries signing_secret once. Every delivery carries X-MeiSIM-Signature, the hex HMAC-SHA256 of the raw request body under that secret: compare it before trusting the message. The body is JSON with event, number, from, text and received_at. A delivery your server does not accept is tried again (30 seconds, 1 minute, 2 minutes and so on, up to an hour apart, eight tries), and the text stays in /api/v1/sms/messages either way.

GET / POST / DELETE/api/v1/sms/webhooks

More places to push texts, next to the main webhook: one for each workflow, app or system, up to 20 on an account. Each one gets every incoming text, so several workflows can all receive your texts at once. POST { "webhook_url": "https://…", "number": "2125551234" } adds one and answers its id and its own signing_secret, once. number is optional: leave it out for texts to every number of yours. Deliveries are signed and retried the same way as the main webhook, each with its own secret. GET lists them, with when each last succeeded or failed. DELETE /api/v1/sms/webhooks/:id removes one, and an address that answers 410 Gone is removed for you. Our workflow integrations use these, so turning a workflow off removes only its own address.

POST/api/v1/sms/lines/:number/renew

{ "months": 1 }. Extends the number from its current end date, charged to your wallet at renew_price_usd. Renewing early costs no days.

POST/api/v1/sms/renew-all

{ "months": 1 }. Renews every live number on the account, one after the other, and stops at the first the wallet cannot cover: renewed, total, charged_usd, stopped_short, failed[]. Top up and call again for the rest.

POST/api/v1/sms/lines/:number/auto-renew and /api/v1/sms/auto-renew-all

{ "auto_renew": true }. With auto-renew on, the next term is taken from your wallet shortly before the number would stop; if the wallet is short on the day, the number stops and is released.

POST/api/v1/sms/lines/:number/billing

{ "billing": "daily" } moves a monthly number to the daily rate from the day after its paid month ends; nothing is charged until then. { "billing": "monthly", "months": 2 } moves a daily number back to monthly, 2 months minimum, charged now at renew_price_usd per month, starting the day after its last paid day. Renew and auto-renew refuse a daily number (409); switch it first.

POST/api/v1/sms/lines/:number/daily-stop

{ "stop": true } stops the daily charges: the number works through its last paid day (daily_paid_through) and stops at 22:00 US Eastern, then it is released. { "stop": false } resumes before then. Nothing is refunded; every paid day is delivered. Each line carries billing, daily_price_usd, daily_paid_through, daily_stop and daily_unpaid_since.

PATCH/api/v1/sms/lines/:number

{ "allowed_contacts": ["2125551234"] } binds the number to the people it may text: while the list is non-empty, a send to any other destination answers 403 with code: "CONTACT_NOT_ALLOWED", whichever way the send is made. Up to 10 ten-digit US numbers; null or [] clears it. Inbound is not affected: the number still receives from anyone. This is how a platform gives one companion or agent its own line and keeps it one-to-one with the user who pays for it. { "label": "Mia for user 8812" } names the number (60 characters). Only these two fields are writable; an unknown field is refused. The answer carries the number as GET /api/v1/sms/lines shows it, including allowed_contacts.

POST/api/v1/sms/lines/:number/cancel

Not available. Numbers cannot be returned or cancelled: they are prepaid and run for the time paid, and nothing is refunded. This call answers 409 with code: "NO_RETURNS" and tells you what to do instead: on a daily-rate number, stop its charges with /daily-stop and it works through its last paid day; on a monthly number, switch auto-renew off and it ends on its paid-through date.

A monthly number runs the months it was paid for (2 minimum) and then stops unless renewed or on auto-renew. A daily-rate number runs while each morning's charge goes through and stops at 22:00 US Eastern on its last paid day when it does not. Either way, a number that stops goes back to our pool and is no longer yours. Its messages are kept for 48 hours in case you order the same number again (it comes back with them); after that they are erased and the number may be sold to anyone. Nothing is closed at the carrier.

Errors

Every error is one JSON shape. error is the sentence for a person. code is stable, so a program can branch on it. request_id is the same value as the x-request-id response header on every request: quote it to support and we find the call in our logs. retryable says whether trying again can help (a rate limit, a fault on our side) or cannot (a bad request, an empty wallet, nothing to find).

{ "error": "count is required: how many numbers, a whole number from 1 to 100.", "code": "invalid_input", "request_id": "iad1:iad1::k7f2x-1760300000000-9c1d2e3f4a5b", "retryable": false }

Codes: invalid_input (400), unauthorized (401), payment_required (402), forbidden (403), not_found (404), conflict (409), upstream_failed (424), rate_limited (429), server_error (5xx).

StatusMeaning
400Bad request — missing or malformed fields
401Unauthorized — missing or invalid x-dealer-key / JWT
402Payment required — insufficient wallet balance
403Forbidden — account not approved, on hold, or suspended, or the carrier is not available on your account. If the message says your account is on hold, we have a question out to you by email: answer it and we will lift the hold. Nothing on the account is lost while it is held.
404Not found — order, product, or dealer doesn't exist
424Something we depend on failed: a carrier or a payment processor. The sentence says what was not done and what became of your money. retryable says whether trying again can help.
429Rate limit exceeded
500Server error — try again, contact support if persistent

Rate limits (per dealer unless noted)

Endpoint groupLimit
Order operations (/api/v1/esim/order, /api/v1/topup/recharge, /dealer/order)No limit — order as many as your wallet balance covers
Read operations (/api/v1/me, /api/v1/orders, /api/v1/esim/countries, /api/v1/esim/bundles, /api/v1/esim/details, /api/v1/topup/networks, /api/v1/topup/confirm, /api/v1/esim/revoke)600 / min
Wallet top-ups (/dealer/topup, /dealer/topup-intent)5–10 / min
Number orders (/api/v1/sms/order)6 / min
Talk & Text orders (/api/v1/handset/order)3 / min
US line renewals (/api/v1/lines/plans, /api/v1/lines/renew, /api/v1/lines/auto-renew)Read-operation burst; the wallet is the ceiling on renewals
Renew all (/api/v1/sms/renew-all)3 / min
OTP send5 / 15 min per IP
OTP verify10 / 15 min per IP
Password login8 / 15 min per IP

Rate-limit window is sliding; on 429, wait the indicated period and retry.

eSIM Verification — Dealer API

Submit a batch of LPAs (eSIM activation codes) and we'll classify each as one of: available, used, invalid, error, unknown. The check is read-only — LPAs are never consumed by the verification. Batches up to 50,000 rows. Results typically arrive within minutes.

Pricing: a fee per LPA at your account's rate, debited from your dealer wallet at submission time. Rows that return error are refunded automatically — you only pay for successful verdicts. Authentication uses either your bearer JWT (from /dealer/login) or the legacy x-dealer-key header.

POST /dealer/esim-verify — Submit batch

POST https://api.meisimusa.com/dealer/esim-verify
Authorization: Bearer <dealer-jwt>     # OR: x-dealer-key: <your-key>
Content-Type: application/json

{
  "lpas": [
    "LPA:1$T-MOBILE.IDEMIA.IO$AYU36-O48VE-8PWDE-ZRXGS",
    "LPA:1$T-MOBILE.IDEMIA.IO$O0VQX-7MJVW-99Y97-KLSI4",
    "..."
  ],
  "notify_email": "results@yourcompany.com"   // optional
}

Response (200):

{
  "ok":                  true,
  "batch_id":            "<uuid>",
  "total_rows":          2,
  "charged_usd":         2.00,
  "wallet_balance_usd":  148.00
}

Errors:

HTTPCodeMeaning
400No LPAs providedEmpty lpas array
402INSUFFICIENT_FUNDSWallet balance below required total — response.balance and response.required show details
403—Dealer account not active

GET /dealer/esim-verify/:batch_id — Poll batch

GET https://api.meisimusa.com/dealer/esim-verify/<batch-uuid>
Authorization: Bearer <dealer-jwt>

200 OK
{
  "ok": true,
  "batch": {
    "id":            "<uuid>",
    "label":         "Dealer Acme Inc · 100 LPAs",
    "total_rows":    100,
    "started_at":    "2026-05-13T18:00:00Z",
    "completed_at":  null,
    "paid_total_usd": 100.00
  },
  "progress": {
    "total":       100,
    "pending":     40,
    "in_progress": 5,
    "used":        35,
    "available":   18,
    "invalid":     1,
    "error_count": 1,
    "unknown":     0
  }
}

GET /dealer/esim-verify/:batch_id/results.csv — Download CSV

Returns a CSV with columns iccid, lpa, status, reason, checked_at. Safe to call while the batch is still running — pending rows show status=pending.

curl -H "Authorization: Bearer $DEALER_JWT" \
  https://api.meisimusa.com/dealer/esim-verify/<batch-uuid>/results.csv \
  -o results.csv

eSIM Supply — Portal API

Authentication is JWT bearer (not the x-dealer-key header above). POST to /api/portal/v1/auth/login with the credentials we issued you to receive a token. All endpoints in this section share the prefix /api/portal/v1. Reseller portal access is by invitation only — contact support@meisimusa.com.

eSIM Supply sells pre-validated AT&T eSIM stock. Each purchase atomically claims rows from inventory using FOR UPDATE SKIP LOCKED, so two concurrent buyers never collide on the same iccid. Wallet is debited per unit at your tier's price.

Before any purchase, read the eSIM Supply Terms of Service — in particular the rule that removing an eSIM as a troubleshooting step permanently destroys it and disqualifies it from replacement.

POST /services/esim_supply_att/execute — Buy eSIMs

Atomically claims quantity rows from inventory and assigns them to the caller.

POST /api/portal/v1/services/esim_supply_att/execute
Authorization: Bearer <jwt>
Content-Type: application/json

{
  "sku_id":   "<sku-uuid-from-/services/esim_supply_att/skus>",
  "quantity": 10
}

Response (200):

{
  "usage_id":         12345,
  "vendor_order_ref": "INV-12345",
  "cost_usd":         40.00,
  "status":           "succeeded",
  "result": {
    "carrier":          "att",
    "plan_type":        "qr",
    "quantity_ordered": 10,
    "quantity_filled":  10,
    "partial":          false,
    "esims": [
      { "iccid": "8901410...", "lpa": "LPA:1$...", "inventory_id": "...", "assigned_at": "..." },
      ...
    ]
  }
}

If stock is short, quantity_filled < quantity_ordered, partial is true, and the wallet is automatically credited for the shortfall. If stock is zero, the call fails with VENDOR_ERROR and the full debit is refunded.

GET /esim-supply/stock — Stock count

Returns available counts so your UI can hide "Buy 1000" when only 12 are left.

GET /api/portal/v1/esim-supply/stock
Authorization: Bearer <jwt>

200 OK
{ "stats": { "att.qr.available": 12345, "att.qr.sold": 678, "att.qr.burned": 23 } }

GET /esim-supply/my — My eSIMs

Lists eSIMs assigned to the caller, newest first. Paged via limit and offset.

GET /api/portal/v1/esim-supply/my?limit=100&offset=0
Authorization: Bearer <jwt>

200 OK
{
  "esims": [
    {
      "id":                "...",
      "iccid":             "8901410...",
      "lpa":               "LPA:1$...",
      "carrier":           "att",
      "plan_type":         "qr",
      "status":            "sold",
      "assigned_at":       "2026-05-12T10:00:00Z",
      "sold_via_usage_id": 12345
    }
  ],
  "total":  42,
  "limit":  100,
  "offset": 0
}

POST /esim-supply/replace — Request replacement

Submit an iccid you believe is broken. We enqueue a validator check on the matching LPA, respond synchronously with a check_id, and you poll /esim-supply/replace/status/:check_id until decision is not pending.

POST /api/portal/v1/esim-supply/replace
Authorization: Bearer <jwt>
{ "iccid": "8901410..." }

200 OK
{ "ok": true, "decision": "submitted", "check_id": "<uuid>", "message": "..." }
GET /api/portal/v1/esim-supply/replace/status/:check_id
Authorization: Bearer <jwt>

200 OK  (one of)
{ "decision": "pending",          "validator_status": "in_progress" }
{ "decision": "install_again",    "validator_status": "available",  "message": "..." }
{ "decision": "replaced",         "validator_status": "used",       "replacement": { "iccid": "...", "lpa": "...", "inventory_id": "..." } }
{ "decision": "awaiting_restock", "validator_status": "used",       "message": "..." }
{ "decision": "admin_review",     "validator_status": "error",      "message": "..." }

Replacement policy: only validator-confirmed used verdicts auto-replace from current inventory. available means the eSIM is still valid — try installing again. Anything else routes to admin review within 24h.

eSIM Validator — Portal API

Submit a CSV of LPAs and we run each through a real eSIM-capable device on our worker pool. Each row returns one of: available, used, invalid, error, unknown. Median throughput is ~5s per LPA.

Pricing is per-row at the price shown in /services/esim_validate/skus. The wallet is debited up-front for cost_per_row × rows; rows that error out are refunded automatically — you only pay for successful verdicts.

POST /services/esim_validate/execute — Submit batch

POST /api/portal/v1/services/esim_validate/execute
Authorization: Bearer <jwt>
Content-Type: application/json

{
  "sku_id": "<sku-uuid>",
  "label":  "att-batch-may12",
  "csv":    "iccid,lpa\n8901410...,LPA:1$...\n..."
}

Response (200) — batch is queued; status is executing until workers finish.

{
  "usage_id":         54321,
  "vendor_order_ref": "<batch-uuid>",
  "cost_usd":         150.00,
  "status":           "executing",
  "result": {
    "batch_id":   "<batch-uuid>",
    "total_rows": 1000,
    "cost_usd":   150.00,
    "per_row_usd":0.15,
    "message":    "Batch queued. Poll /esim-check/customer/batches/:id for progress."
  }
}

GET /esim-check/customer/batches/:id — Poll batch

GET /api/portal/v1/esim-check/customer/batches/<batch-uuid>
Authorization: Bearer <jwt>

200 OK
{
  "batch": {
    "id":            "<uuid>",
    "label":         "att-batch-may12",
    "total_rows":    1000,
    "started_at":    "...",
    "completed_at":  null,
    "paid_total_usd": 150.00
  },
  "progress": {
    "total":     1000,
    "pending":   400,
    "in_progress": 8,
    "used":      350,
    "available": 230,
    "invalid":   8,
    "error_count": 2,
    "unknown":   2
  }
}

GET /esim-check/customer/batches/:id/results.csv — Download results

Returns a CSV with columns iccid, lpa, status, reason, checked_at. Safe to call while the batch is still running — pending rows show status=pending.

curl -H "Authorization: Bearer $TOKEN" \
  https://api.meisimusa.com/api/portal/v1/esim-check/customer/batches/<batch-uuid>/results.csv \
  -o results.csv

Code samples

n8n, no code

The community node n8n-nodes-meisim wraps this API: a trigger for incoming texts (signed webhook, or polling), and operations for messages, lines, orders and the account. In n8n open Settings, then Community Nodes, and install it by name. Source and a three-node texting agent: github.com/Shauliko/n8n-nodes-meisim.

JavaScript / Node.js

const API = 'https://api.meisimusa.com';
const KEY = process.env.MEISIM_DEALER_KEY;

async function orderEsim(bundleName, customerEmail) {
  const r = await fetch(`${API}/api/v1/esim/order`, {
    method: 'POST',
    headers: {
      'x-dealer-key': KEY,
      'content-type': 'application/json',
    },
    body: JSON.stringify({
      bundleName,
      emailAddress: customerEmail,
      qrToCustomer: true,
    }),
  });
  if (!r.ok) throw new Error(`HTTP ${r.status}: ${await r.text()}`);
  return r.json();
}

Python

import os, requests

API = 'https://api.meisimusa.com'
KEY = os.environ['MEISIM_DEALER_KEY']

def order_esim(bundle_name, customer_email):
    r = requests.post(
        f'{API}/api/v1/esim/order',
        headers={'x-dealer-key': KEY},
        json={
            'bundleName': bundle_name,
            'emailAddress': customer_email,
            'qrToCustomer': True,
        },
        timeout=30,
    )
    r.raise_for_status()
    return r.json()

curl

curl -X POST https://api.meisimusa.com/api/v1/esim/order \
  -H "x-dealer-key: $MEISIM_DEALER_KEY" \
  -H 'content-type: application/json' \
  -d '{"bundleName":"esim_5gb_30days_jp","emailAddress":"end@x.com","qrToCustomer":true}'

For dealer onboarding, account questions, or technical support, contact your account manager directly.
Document version: v1.0 — 2026-05-05