Skip to main content
POST
Create Line Request
The Try it panel runs against production (https://app.tuco.ai) with the key you paste into it. There is no sandbox — a request from this page creates a real line request, and can start a real payment.
Use this endpoint after the workspace already has an active Tuco subscription. If the request is included in the current plan, Tuco starts provisioning immediately. If the request requires an add-on, Tuco returns a hosted invoice link.

​
What This Endpoint Decides

You send the line details once, and Tuco decides what should happen next. The response will always fall into one of these buckets:
  • provisioning Tuco accepted the request immediately and has started setting up the line.
  • awaiting_payment Tuco saved the request, but it needs payment before provisioning can begin.
  • subscription_required The workspace needs an active base plan before it can request lines.
  • forbidden_line_type The current plan does not allow that request, or the plan reached a hard cap with no paid expansion path.

​
Authentication

Pass your workspace API key as a Bearer token, or use a Clerk session token.

​
Request body

Every order must carry the legal name, the company name and an explicit anti-spam acceptance. A purchased phone line (an eSIM) must also carry the full legal address, the eSIM country, the ZIP / postal code to provision on, and the area-code acknowledgement. A request missing any of them is rejected with 400 and no line is created.

​
Who the line belongs to

​
string
required
Required. First name of the person authorised to make this payment on behalf of the company. Agency ordering for a client? Use your client’s name. Business owner? Use your own name. Marketing or ops? Use your name or the business owner’s. Only the SIM card provider sees it — never your leads (they see the display name).
​
string
required
Required. Last name of the same authorised person (see legalFirstName).
​
string
Optional. Display first name — set on the Mac and shown to conversation participants on iMessage. If omitted, Tuco uses legalFirstName. firstName is accepted as an alias.
​
string
Optional. Display last name — set on the Mac and shown to conversation participants on iMessage. If omitted, Tuco uses legalLastName. lastName is accepted as an alias.
​
string
required
Required for every line. The company’s legal name — an LLC, Inc, sole proprietorship or any registered business, anywhere in the world, e.g. "Acme, LLC" or "Acme, Inc.". legalName is accepted as an alias.
​
string
Optional. Business contact number for the company (not the line’s own number).
​
boolean
required
Required for every line. Must be the boolean true, confirming the workspace accepts Tuco’s anti-spam and messaging rules. Any other value — including "true" as a string — is treated as not accepted.Those rules include: every lead sees Delete / Delete and Report Spam / Mark as Known on every message until they save you; no old leads who’ve forgotten you, no high-pressure tactics, nobody who opted in more than a month ago; and when re-engaging older leads, a different message per lead with a 3–5 minute gap. See What your leads see.

​
What kind of line

​
string
required
Supported values: "phone" or "email". Defaults to "phone".
​
string
Optional. Supported values: "purchased" or "byon". Defaults to "purchased" when omitted.Send "byon" (bring your own number) only if you are porting a number you already own. Leave it out to have Tuco provision a new number on an eSIM.
​
string
Required for email lines, and for phone lines you are porting (lineType: "byon"). Leave it out for a purchased phone line.
​
string
Not required unless you are porting a number you already own (lineType: "byon"), in which case send it in E.164 form, e.g. "+14155550123".For a purchased phone line — the normal case — omit this field entirely. Tuco assigns the number and reports it back once provisioning completes.
Do not send a placeholder such as "pending", "none" or "" to satisfy the field. Whatever you send is stored as the line’s number, so a placeholder makes the line look like it already has one. Omitting the field is what marks the number as not yet assigned.

​
eSIM fields (purchased phone lines)

Required when channelType is "phone" and lineType is "purchased" (or omitted). Ignored for email lines and ported numbers.
​
string
required
Country the eSIM is for: "US" or "CA". eSIMs are self-serve for the US and Canada only — for the UK, Australia or any other country, contact support@tuco.ai. Any other value is rejected with 400.
iMessage works globally — a US or Canadian line can iMessage recipients in any country. P2P SMS fallback (a green bubble sent from this same number when the recipient isn’t on iMessage) only reaches recipients in the eSIM’s country: a US eSIM falls back to SMS for US numbers only, a CA eSIM for Canadian numbers only.
​
string
required
Street of the legal service address — it can be anywhere in the world. Carriers need a real address to activate the eSIM. The number itself is provisioned on zipcode (US or Canada).
​
string
Optional. Apt / suite / unit.
​
string
required
City of the legal service address.
​
string
required
State (US) or province (Canada) of the legal service address, e.g. "CA" or "ON".
​
string
required
ZIP (US) or postal code (Canada) of the legal service address. Not format-checked.
​
string
required
ZIP / postal code to provision the number on. The eSIM number is requested on this ZIP — not on an area code. It can be different from legalZipcode. Not format-checked.
​
boolean
required
Must be the boolean true. Confirms you understand the area code is best effort: Tuco does not guarantee an area code — the eSIM is provisioned on the zipcode you provide, not an area code, and the legal address and that ZIP can be different.
​
string
Optional. Leave it out (the default) to accept any area code that matches zipcode. Send it only if you’d like a specific area code, as 3 digits (e.g. "212"). Best effort — NOT guaranteed. We try for it, but the number is provisioned on zipcode and you may get a different area code. It never delays the order. Anything that isn’t a 3-digit US / Canada area code returns 400.
An area code is never guaranteed, whether or not you send preferredAreaCode. Don’t promise a specific area code to anyone before the line is live.

​
Calling add-ons (optional, phone lines)

Every phone line includes 500 outgoing minutes/month with recording, unlimited incoming, and $3 per extra 100 minutes. These per-line add-ons are optional — see Calling add-ons.
​
string[]
Any of "facetime_audio" (FaceTime Audio add-on — $100/mo per line) and `"caller_id_registration"` (Registered caller ID add-on — $50 setup + $50/mo per line + $0.075 per call). Charged right after the line is created, to the card on file: the setup fee plus today’s prorated share of the monthly, then monthly. Add-ons can’t be removed after purchase — contact support@tuco.ai. Add-ons already bought with your plan at checkout attach to new lines automatically, with no second charge.
​
boolean
Required (true) whenever callingAddons is non-empty — your explicit agreement to those charges. Non-refundable. Without it the request is rejected with 400 and nothing is created.
The response then includes a callingAddons array — one result per add-on, with status pending_setup (charged to the card on file; we’re setting it up) or, only when the card is declined or the bank requires authentication (3-D Secure), awaiting_payment plus a paymentUrl for the customer to confirm the payment. All of a line’s add-ons are charged together: one invoice, so every awaiting_payment result carries the same paymentUrl, and one confirmation starts them all. The link lapses after about 23 hours if unpaid; the add-ons then go back to none.

​
Other

​
string
Optional. Forwarding destination for inbound calls on phone lines. One line = one forwarding number.
​
string
Optional. Avatar shown in Tuco.
Review everything and be sure. Ordering is free — the name and photo you send here don’t count. After the line is created, its display name and photo can change at most 3 times per line per month — each change needs a person on our side to update the Mac. A 4th change in the same month returns 400 (LINE_INFO_UPDATE_LIMIT); contact support@tuco.ai. Use reviewOnly below to check everything first.
​
boolean
Optional. Send true to review the order without creating it. Tuco runs exactly the same validation as a real order and returns 200 with a review object — the display name and photo your leads will see, the legal name, company, eSIM country, legal address, provisioning ZIP, forwarding number, calling add-ons with their charges, and a recipientPreviewUrl showing Apple’s “Maybe: (your name)” screens. Nothing is created or charged. Change anything and review again, then send the same body without reviewOnly to order. Missing or invalid fields return 400 with missingFields, as on a real order.
​
string
Optional. You can also send this as the Idempotency-Key header. Reusing the same key returns the original response instead of creating a duplicate request.

​
Required field rules

Every request needs legalFirstName, legalLastName, companyName and antiSpamAccepted: true. On top of that: displayFirstName / displayLastName are always optional — each falls back to the legal name. Extra fields are tolerated, so an unexpected field will not fail the request — but a value you send is a value Tuco stores. Leave out the fields your request type does not use rather than filling them with placeholders.

​
Default behavior for phone lines

If channelType is phone and lineType is omitted, Tuco treats the request as:
That means the eSIM fields are required unless you explicitly send lineType: "byon".

​
Example: included line (eSIM)

​
Success: provisioning (201 Created)

recipientPreviewUrl is returned on every order: a hosted preview of exactly what a lead sees from this line — Apple’s “Maybe: Jane from Acme” header with Delete, Delete and Report Spam and Mark as Known on every message until they save your contact. Show it to whoever writes your messages. See What your leads see. line.firstName / line.lastName are the display name — what the Mac shows participants.

​
Example: paid add-on line

No display name is sent, so the line shows Sam Support.

​
Success: awaiting payment (201 Created)

​
Example: review before ordering (reviewOnly)

Send the same body with "reviewOnly": true:
Open recipientPreviewUrl to see exactly what your leads will see. Wrong name or photo? Change displayName* / profileImageUrl and review again.

​
Example: rejected — missing compliance fields (400)

​
What To Do After You Create A Request

If the response is provisioning:
  • keep the returned line._id
  • poll GET /api/line-requests/{id} for status updates
If the response is awaiting_payment:
  • keep the returned line._id
  • show the paymentUrl to the user
  • after payment, poll GET /api/line-requests/{id} until it changes to provisioning
You should not submit the same line details again after payment. The original request is the one that continues.

​
One Request At A Time

Tuco blocks a new request only when the workspace already has a line request in awaiting_payment. This prevents:
  • duplicate unpaid requests
  • accidental double purchases
  • race conditions from retries
Lines already in provisioning do not block the next request.

​
Error responses

​
Notes

  • Payment is always attached to the exact saved line request. The caller does not need to resubmit the payload after paying.
  • The API uses the authenticated workspace. You cannot request lines for an arbitrary workspace id in the body.
  • Retry safety is built in through idempotency support and workspace-level request locking.