Get Line Request
curl --request GET \
--url https://app.tuco.ai/api/line-requests/{id} \
--header 'Authorization: Bearer <token>'import requests
url = "https://app.tuco.ai/api/line-requests/{id}"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://app.tuco.ai/api/line-requests/{id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://app.tuco.ai/api/line-requests/{id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://app.tuco.ai/api/line-requests/{id}"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://app.tuco.ai/api/line-requests/{id}")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://app.tuco.ai/api/line-requests/{id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_bodyLines & Leads
Get Line Request
Fetch the current status of a line request. REST endpoint in the Tuco AI iMessage API — bearer-token auth, JSON request/response, full schema and code examples.
GET
/
api
/
line-requests
/
{id}
Get Line Request
curl --request GET \
--url https://app.tuco.ai/api/line-requests/{id} \
--header 'Authorization: Bearer <token>'import requests
url = "https://app.tuco.ai/api/line-requests/{id}"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://app.tuco.ai/api/line-requests/{id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://app.tuco.ai/api/line-requests/{id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://app.tuco.ai/api/line-requests/{id}"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://app.tuco.ai/api/line-requests/{id}")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://app.tuco.ai/api/line-requests/{id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_bodyUse 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?
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
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
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
status | Meaning |
|---|---|
awaiting_payment | Invoice is still unpaid |
provisioning | Payment is complete or not required, and Tuco is provisioning the line |
active | Line is ready to use |
failed | Provisioning did not succeed |
canceled | The pending request was canceled |
awaiting_payment request against the latest subscription state while reading this endpoint.
Practical meaning of each status
awaiting_paymentThe request exists, but the invoice is still unpaid or billing has not been reconciled yet.provisioningPayment is done or was never needed, and Tuco is now setting the line up.activeThe line is ready to use in normal message flows.failedProvisioning did not complete. At that point the request needs review or a retry path outside this endpoint.canceledThe pending request was intentionally canceled before completion.
Typical polling behavior
Most clients poll after:- creating a paid request
- showing the hosted invoice to the user
- waiting for the request to move from
awaiting_paymenttoprovisioning
active.
Error responses
| Status | When | Body |
|---|---|---|
400 | Invalid line request id | { "error": "Invalid line request id" } |
401 | Missing or invalid API key / session | { "error": "Unauthorized" } |
404 | Request not found in your workspace | { "error": "Line request not found" } |