Skip to main content
GET
Get Line Request
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.
Any line id in your workspace works here, not only ids returned by POST /api/line-requests. A line created in the dashboard resolves the same way — you get its current provisioningStatus and the full line object.The write actions in POST /api/line-requests/{id} are different: cancel and payment_link act only on API-created requests awaiting payment, and return 404 Line request not found for anything else.

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.

Path parameter

string
required
The line request id returned by POST /api/line-requests — it is the line._id value in that response.A line request is not a separate record: it is the line itself. The request id and the line id are therefore the same value, which is why any line id from GET /api/lines/by-user also resolves here. A 404 means the id is not a line in your workspace; a malformed id returns 400 Invalid line request id.

Example

Success (200 OK)


Status behavior

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