Skip to main content
GET
/
api
/
replies
Check Replies
curl --request GET \
  --url https://app.tuco.ai/api/replies \
  --header 'Authorization: Bearer <token>'
{
  "leadId": "<string>",
  "messageId": "<string>",
  "message": "<string>",
  "respondedAtUtc": "<string>",
  "recipientPhone": "<string>",
  "recipientEmail": "<string>",
  "name": "<string>",
  "recentReplies": [
    {
      "messageId": "<string>",
      "message": "<string>",
      "receivedAtUtc": "<string>"
    }
  ],
  "parentMessages": [
    {
      "messageId": "<string>",
      "message": "<string>",
      "sentAtUtc": "<string>",
      "batchId": "<string>",
      "stepIndex": 123
    }
  ]
}
Use this endpoint to check if a specific lead has replied, or to list all leads who replied (optionally scoped to a campaign). Returns the reply text, up to 10 recent replies from the lead, and up to 10 outbound messages you sent them.

​
Authentication

Authorization: Bearer tuco_sk_xxxxxxxxxxxxx

​
Query parameters

​
leadId
string
Replies from this lead only (valid ObjectId; returns 404 if lead not found).
​
campaignId
string
Restrict to leads who replied and are in this campaign.
​
recipientEmail
string
Filter by reply sender email.
​
recipientPhone
string
Filter by reply sender phone (E.164 or normalized).
​
lineId
string
Restrict to replies received on this Tuco line (24-char ObjectId hex). Returns 400 if malformed.
​
dateFrom
string
Inclusive ISO 8601 UTC lower bound on the reply timestamp (e.g. 2026-06-01T00:00:00Z). Returns 400 if unparseable or greater than dateTo.
​
dateTo
string
Inclusive ISO 8601 UTC upper bound on the reply timestamp.
​
page
number
default:"1"
Page number.
​
limit
number
default:"50"
Results per page (max 100).

​
Examples

curl "https://app.tuco.ai/api/replies?recipientPhone=%2B14422646782&limit=10" \
  -H "Authorization: Bearer tuco_sk_xxxxxxxxxxxxx"

​
Success response (200)

{
  "replies": [
    {
      "leadId": "69b2c41d352a78479d2c623b",
      "messageId": "69b340dd6dae1d942ece4d09",
      "message": "Stop",
      "respondedAtUtc": "2026-03-12T22:40:29.174Z",
      "recipientPhone": "+919042956129",
      "recipientEmail": "goforbg@icloud.com",
      "name": "BG Real",
      "recentReplies": [
        {
          "messageId": "69b340dd6dae1d942ece4d09",
          "message": "Stop",
          "receivedAtUtc": "2026-03-12T22:40:29.174Z"
        },
        {
          "messageId": "69b33fdd6dae1d942ece4d08",
          "message": "Thanks for reaching out",
          "receivedAtUtc": "2026-03-12T21:15:00.000Z"
        }
      ],
      "parentMessages": [
        {
          "messageId": "69b344bc6dae1d942ece4d0e",
          "message": "Here's your document.",
          "sentAtUtc": "2026-03-12T22:57:02.892Z",
          "batchId": null,
          "stepIndex": null
        }
      ]
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 50,
  "totalPages": 1
}

​
Reply fields

​
leadId
string
Lead who replied.
​
messageId
string
ID of the most recent reply message.
​
message
string
The reply text (e.g. “Stop”, “Interested!”, “Call me tomorrow”).
​
respondedAtUtc
string
ISO 8601 timestamp of the most recent reply.
​
recipientPhone
string
Lead’s phone number.
​
recipientEmail
string
Lead’s email address.
​
name
string
Lead’s display name.

​
recentReplies (up to 10)

All inbound replies from this lead, newest first. Gives you the full conversation context from their side.
​
recentReplies
array

​
parentMessages (up to 10)

Outbound messages you sent to this lead, newest first. Shows what you said before they replied.
​
parentMessages
array

​
Error responses

StatusWhenBody
400Invalid leadId or campaignId{ "error": "Invalid leadId" } or { "error": "Invalid campaignId" }
400Invalid lineId (not a 24-char ObjectId hex){ "error": "Invalid lineId" }
400dateFrom / dateTo unparseable{ "error": "Invalid dateFrom" } or { "error": "Invalid dateTo" }
400dateFrom > dateTo{ "error": "dateFrom must be <= dateTo" }
401Missing or invalid API key{ "error": "Unauthorized" }
404leadId provided but lead not found{ "error": "Lead not found or access denied" }
404campaignId provided but campaign not found{ "error": "Campaign not found" }
429Rate-limited (120 req/min per workspace){ "error": "Rate limit exceeded" }
500Server error{ "error": "Failed to fetch replies" }