Lines API

Before You Request Lines

The line-request API is for workspaces that already exist in Tuco. That means the normal first step is still:

Sign in to Tuco.
Create or join a workspace.
Buy a base plan for that workspace.
Use your workspace API key to request lines.

If the workspace does not have an active subscription, Tuco returns subscription_required and does not create the request.

What the Lines API Does

Lines are the sending identities you use in Tuco, such as phone numbers and email addresses. Through the API, you can:

Request a new line.
Check whether a request is waiting for payment, provisioning, active, failed, or canceled.
Recover a payment link for a pending request.
Cancel a pending request you no longer want.
List the lines already attached to your workspace.
Update a line’s name or profile photo.

Line Request Flow

The request flow is intentionally simple:

Submit the line details once.
Tuco checks your active plan and current capacity.
If the request is included in your plan, Tuco moves it straight to provisioning.
If the request requires an add-on, Tuco stores the line request as awaiting_payment and returns a hosted invoice link.
After payment succeeds, the request moves to provisioning.

You do not need to resubmit the same line after payment.

What happens if the user does not want to pay?

If a line request is in awaiting_payment, the user can:

pay the invoice and let the same request continue
recover the payment link later
cancel the request entirely

Canceling the pending request releases the payment block and lets the workspace create a different request.

What happens if the user loses the payment link?

Use the line-request management endpoint to recover it. If the invoice is still open, Tuco returns the same hosted invoice link. If billing has already been reconciled, the request may already move to provisioning.

What blocks the next request?

Only awaiting_payment blocks a new line request. A request already in provisioning does not block the next purchase. This lets a workspace continue buying or requesting lines while earlier ones are still being set up.

Plan Behavior

Tuco checks both the workspace plan and the line type you are requesting.

Plan	Phone lines	Email lines
Mini	Not available	First email included, more email lines paid
Starter	First phone included, no extra phone lines	Paid add-ons
Growth	First 2 phone lines included, more phone lines paid	Paid add-ons

Workspace-level overrides can still raise limits for specific customers.

Line Request Statuses

Status	Meaning
`awaiting_payment`	The line request exists, but payment is still required before provisioning can begin
`provisioning`	Tuco accepted the request and provisioning is underway
`active`	The line is ready to use
`failed`	Provisioning did not complete successfully
`canceled`	The request was canceled before completion

Endpoints

Recommended integration pattern

For most API clients, the cleanest pattern is:

Call POST /api/line-requests with the legal name, company name and antiSpamAccepted: true — plus, for a purchased phone line (eSIM), the legal address, simCountry (US or CA), the zipcode to provision on and areaCodeBestEffortAcknowledged: true. The display name is optional and falls back to the legal name. See Create Line Request.

iMessage works globally. P2P SMS fallback from a line’s own number only reaches recipients in the country of that line’s eSIM (simCountry).

If the response is provisioning, store the returned line._id
If the response is awaiting_payment, store the returned line._id and paymentUrl
Poll GET /api/line-requests/{id} until the status changes
If needed, call POST /api/line-requests/{id} with action: "payment_link" or action: "cancel"

Fetch All Lines (API Key)

Endpoint

Method: GET
Path: /api/lines/by-user
Auth: Tuco API key or Clerk token (via authenticateRequest)

Behavior

Returns all lines for the authenticated workspace, including:

current profile details
provisioning and payment state
per-day usage
public health information when available

For request-specific lifecycle management, use the line-request endpoints above. profileImageUrl is the public URL of the line’s profile photo, or null if none is set. It is part of the stable response.

Example

GET /api/lines/by-user
Authorization: Bearer tuco_xxx

Response

{
  "lines": [
    {
      "_id": "667f1f77bcf86cd799439011",
      "workspaceId": "org_123",
      "firstName": "Sales",
      "lastName": "Team 1",
      "profileImageUrl": "https://cdn.example.com/sales.png",
      "phone": "+12025551234",
      "email": "sales+1@example.com",
      "isActive": true,
      "provisioningStatus": "active",
      "paymentStatus": "paid",
      "requestSource": "api",
      "requestedChannelType": "email",
      "requestedLineType": "purchased",
      "paymentLinkUrl": null,
      "stripeInvoiceId": "in_123",
      "dailyNewConversationsLimit": 20,
      "dailyTotalMessagesLimit": 150,
      "usage": {
        "date": "2025-10-14",
        "newMessages": 3,
        "totalMessages": 42
      },
      "healthCheck": {
        "status": "healthy",
        "lastCheckedAt": "2025-10-14T10:00:00Z"
      }
    }
  ]
}

Update a Line’s Name, Photo or Call Recording Notice

Endpoint

Method: PATCH
Path: /api/lines/{id}
Auth: Tuco API key

Send any of firstName, lastName, profileImageUrl (use null to remove the photo), callRecordingDisclosure (true plays a “this call may be recorded” notice when the person you call answers) and callRecordingDisclosureMessage (your own wording, or null for the default). Other fields are rejected. See Update a Line.

PATCH /api/lines/667f1f77bcf86cd799439011
Authorization: Bearer tuco_xxx
Content-Type: application/json

{ "firstName": "Sarah", "lastName": "Lee", "profileImageUrl": "https://cdn.example.com/sarah.png" }

Check Health of a Line

Endpoint

Method: GET
Path: /api/lines/check-availability?id={lineId}
Auth: Clerk (Tuco dashboard or trusted backend using Clerk tokens)

This endpoint performs a fresh health check for a specific line (server ping + iMessage availability) and updates the line’s health status.

Example

GET /api/lines/check-availability?id=667f1f77bcf86cd799439011
Authorization: Bearer <clerk_token>

Response (success)

{
  "success": true,
  "lineId": "667f1f77bcf86cd799439011",
  "status": "healthy",
  "failures": [],
  "checkedAt": "2025-10-14T10:30:00Z",
  "shouldNotify": false,
  "notificationSent": false
}

If the line is not active or lacks the necessary configuration, you receive a 400 with a descriptive error; on auth failure you receive 401.

Overview

Webhooks

Errors and status codes

iMessage Availability

Messages

Voice / Calling

Replies

Do Not Contact

Lines & Leads

Analytics

Goal Bots

API Tools

Agency

Workspace settings

Before You Request Lines

What the Lines API Does

Line Request Flow

What happens if the user does not want to pay?

What happens if the user loses the payment link?

What blocks the next request?

Plan Behavior

Line Request Statuses

Endpoints

Recommended integration pattern

Fetch All Lines (API Key)

Endpoint

Behavior

Example

Response

Update a Line’s Name, Photo or Call Recording Notice

Endpoint

Check Health of a Line

Endpoint

Example

Response (success)

​Before You Request Lines

​What the Lines API Does

​Line Request Flow

​What happens if the user does not want to pay?

​What happens if the user loses the payment link?

​What blocks the next request?

​Plan Behavior

​Line Request Statuses

​Endpoints

​Recommended integration pattern

​Fetch All Lines (API Key)

​Endpoint

​Behavior

​Example

​Response

​Update a Line’s Name, Photo or Call Recording Notice

​Endpoint

​Check Health of a Line

​Endpoint

​Example

​Response (success)

Before You Request Lines

What the Lines API Does

Line Request Flow

What happens if the user does not want to pay?

What happens if the user loses the payment link?

What blocks the next request?

Plan Behavior

Line Request Statuses

Endpoints

Recommended integration pattern

Fetch All Lines (API Key)

Endpoint

Behavior

Example

Response

Update a Line’s Name, Photo or Call Recording Notice

Endpoint

Check Health of a Line

Endpoint

Example

Response (success)