Skip to main content

​
Before You Request Lines

The line-request API is for workspaces that already exist in Tuco. That means the normal first step is still:
  1. Sign in to Tuco.
  2. Create or join a workspace.
  3. Buy a base plan for that workspace.
  4. 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.

​
Line Request Flow

The request flow is intentionally simple:
  1. Submit the line details once.
  2. Tuco checks your active plan and current capacity.
  3. If the request is included in your plan, Tuco moves it straight to provisioning.
  4. If the request requires an add-on, Tuco stores the line request as awaiting_payment and returns a hosted invoice link.
  5. 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. 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.
PlanPhone linesEmail lines
MiniNot availableFirst email included, more email lines paid
StarterFirst phone included, no extra phone linesPaid add-ons
GrowthFirst 2 phone lines included, more phone lines paidPaid add-ons
Workspace-level overrides can still raise limits for specific customers.

​
Line Request Statuses

StatusMeaning
awaiting_paymentThe line request exists, but payment is still required before provisioning can begin
provisioningTuco accepted the request and provisioning is underway
activeThe line is ready to use
failedProvisioning did not complete successfully
canceledThe request was canceled before completion

​
Endpoints

For most API clients, the cleanest pattern is:
  1. Call POST /api/line-requests
  2. If the response is provisioning, store the returned line._id
  3. If the response is awaiting_payment, store the returned line._id and paymentUrl
  4. Poll GET /api/line-requests/:id until the status changes
  5. 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.

​
Example

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

​
Response

{
  "lines": [
    {
      "_id": "667f1f77bcf86cd799439011",
      "workspaceId": "org_123",
      "firstName": "Sales",
      "lastName": "Team 1",
      "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"
      }
    }
  ]
}

​
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.