Skip to main content
GET
/
api
/
line-requests
/
:id
Get Line Request
curl --request GET \
  --url https://app.tuco.ai/api/line-requests/:id \
  --header 'Authorization: Bearer <token>'
Use this endpoint to poll a specific line request after creation. It is the source of truth for whether the request is still waiting for payment, already provisioning, active, failed, or canceled.

​
When To Use This Endpoint

Call this endpoint any time your integration wants to answer one of these questions:
  • Did the user already pay?
  • Has provisioning started yet?
  • Is the line active?
  • Was the request canceled or did it fail?
This is the simplest endpoint to poll after POST /api/line-requests.

​
Authentication

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

​
Path parameter

​
id
string
Required. The line request id returned by POST /api/line-requests.

​
Example

curl "https://app.tuco.ai/api/line-requests/6a09279daa903300e2530b0f" \
  -H "Authorization: Bearer tuco_xxxxxxxxxxxxx"

​
Success (200 OK)

{
  "success": true,
  "status": "provisioning",
  "paymentStatus": "paid",
  "paymentRequired": false,
  "line": {
    "_id": "6a09279daa903300e2530b0f",
    "firstName": "Support",
    "lastName": "Email 2",
    "channelType": "email",
    "lineType": "purchased",
    "provisioningStatus": "provisioning",
    "paymentStatus": "paid"
  }
}

​
Status behavior

statusMeaning
awaiting_paymentInvoice is still unpaid
provisioningPayment is complete or not required, and Tuco is provisioning the line
activeLine is ready to use
failedProvisioning did not succeed
canceledThe pending request was canceled
When possible, Tuco also reconciles a stuck awaiting_payment request against the latest subscription state while reading this endpoint.

​
Practical meaning of each status

  • awaiting_payment The request exists, but the invoice is still unpaid or billing has not been reconciled yet.
  • provisioning Payment is done or was never needed, and Tuco is now setting the line up.
  • active The line is ready to use in normal message flows.
  • failed Provisioning did not complete. At that point the request needs review or a retry path outside this endpoint.
  • canceled The pending request was intentionally canceled before completion.

​
Typical polling behavior

Most clients poll after:
  1. creating a paid request
  2. showing the hosted invoice to the user
  3. waiting for the request to move from awaiting_payment to provisioning
After that, the same endpoint can still be used until the line becomes active.

​
Error responses

StatusWhenBody
400Invalid line request id{ "error": "Invalid line request id" }
401Missing or invalid API key / session{ "error": "Unauthorized" }
404Request not found in your workspace{ "error": "Line request not found" }