How to Check Campaign Status

📋 Prerequisites

Valid api-token and app-id from your LigueLead account
A campaign_id returned by POST /v1/sms (see How to Send SMS)

🔎 Check Recipients Status

Endpoint: GET /v1/campaigns/{campaign_id}/recipients

Works for both standard SMS and SMS Flash: campaign_type is sms or sms_flash.

Request Example

curl -X GET "https://api.liguelead.com.br/v1/campaigns/2f7b3c40-8f93-4a3b-9b71-6c8b5bf1b5e2/recipients?limit=100" \
  -H "api-token: YOUR_API_TOKEN" \
  -H "app-id: YOUR_APP_ID"

Response Example

{
  "message": "Campaign recipients retrieved successfully.",
  "data": {
    "campaign_id": "2f7b3c40-8f93-4a3b-9b71-6c8b5bf1b5e2",
    "campaign_type": "sms",
    "recipients": [
      {
        "phone": "+5511999999999",
        "status": "delivered",
        "sent_at": "2026-07-29T11:20:03-03:00",
        "updated_at": "2026-07-29T11:20:41-03:00"
      },
      {
        "phone": "+5521888888888",
        "status": "invalid_number",
        "sent_at": "2026-07-29T11:20:03-03:00",
        "updated_at": "2026-07-29T11:20:05-03:00"
      }
    ],
    "pagination": {
      "limit": 100,
      "next_cursor": "KzU1MjE4ODg4ODg4ODg"
    }
  }
}

📋 Query Parameters

Parameter	Type	Required	Description
`limit`	integer	❌	Page size, 1–500. Defaults to `100`
`cursor`	string	❌	Opaque cursor from a previous response. Cannot be combined with `phone`
`phone`	string	❌	Narrows the result to a single recipient. Cannot be combined with `cursor`

📊 Recipient Statuses

Status	Description
`queued`	Accepted by us, not yet handed to a carrier
`in_progress`	Accepted by the carrier, delivery report pending
`delivered`	Reported as delivered
`unreachable`	Number is unreachable or the region is denied
`invalid_number`	Number is invalid, a landline, or does not support SMS
`policy_block`	Blocked by a content filter (spam, fraud or content policy)
`opt_out`	Recipient has unsubscribed from SMS messages
`insufficient_credits`	No credits available at send time; the message was never dispatched
`request_error`	The carrier rejected the request synchronously
`config_error`	Message or account configuration issue
`generic_error`	Unknown carrier or platform error
`unknown_error`	Unclassified error

About the timestamps

Both timestamps are ISO-8601 with the São Paulo offset (-03:00), not UTC — the same
form used by the daily detailed report and by the per-message webhook. The offset is part
of the string, so any ISO-8601 parser resolves it to the exact instant:

2026-07-29T18:45:50-03:00   ==   2026-07-29T21:45:50Z

About `updated_at`

sent_at is when LigueLead processed the message for sending, and it never changes — it is
filled even when the message was not dispatched, as with insufficient_credits. updated_at
is when LigueLead recorded the recipient's latest status — it only moves when a new status
is actually recorded, so a duplicated or out-of-order delivery report leaves it untouched. In
the example above the two are 38 seconds apart: the message was processed at 11:20:03 and
its delivery was recorded at 11:20:41.

The sent_at of this endpoint is the one to rely on for each recipient. The sent_at of the
per-message webhook can be earlier, by up to the duration of the send, for messages that share
the same text.

💡 Note: This endpoint reports the status of each recipient individually and is
therefore finer-grained than the per-message webhook described in
How to Receive Webhooks. Use webhooks to be notified of
deliveries as they happen — SMS webhooks report only delivered —, and use this endpoint to
see every recipient, including the ones that were not delivered.

📄 Pagination

Follow data.pagination.next_cursor until it is no longer present:

# First page
curl -X GET ".../recipients?limit=500" -H "api-token: ..." -H "app-id: ..."

# Next page — pass the cursor back verbatim
curl -X GET ".../recipients?limit=500&cursor=KzU1MjE4ODg4ODg4ODg" \
  -H "api-token: ..." -H "app-id: ..."

Two things to keep in mind:

A page may contain fewer items than limit. That does not mean you reached the
end — only the absence of next_cursor does.
The listing is not a point-in-time snapshot. It never repeats a recipient, but a
recipient whose first status is recorded while you are already paginating may only
show up on a later pass. For a definitive count, paginate again once the campaign has
settled.

Treat next_cursor as opaque: pass it back exactly as received, and do not build or
modify one yourself.

📱 Checking a Single Recipient

Pass phone to look up one recipient directly, in any format:

curl -X GET ".../recipients?phone=11999999999" \
  -H "api-token: YOUR_API_TOKEN" -H "app-id: YOUR_APP_ID"

All of these resolve to the same recipient: 11999999999, (11) 99999-9999,
5511999999999, +5511999999999. For a mobile number, include the ninth digit: a number
sent in the old 8-digit form is stored with the ninth digit restored, and a lookup without
it is not found.

If you use + inside a query string, URL-encode it as %2B (a raw + means "space").
Sending it without the + avoids the issue entirely.

⏱️ Availability and Retention


Right after sending	Recipient records are written as the campaign is processed, which begins a few seconds after `POST /v1/sms` returns. Querying immediately may answer `404` — retry after a few seconds
Retention	Records are kept for 72 hours. After that the campaign answers `404`; use the daily detailed report for historical data

🛠️ Troubleshooting

Status	Cause	What to do
`401`	Missing or invalid `api-token` / `app-id`	Check both headers
`404`	Campaign does not exist, belongs to another account, is older than 72 h, has not started processing yet, or the requested `phone` is not part of it	Confirm the `campaign_id`; if you just sent it, retry in a few seconds
`422`	`campaign_id` is not a UUID, `limit` is outside 1–500, `cursor` is invalid, `phone` is malformed, or `phone` and `cursor` were sent together	Check the parameters against the table above

Recipients that stay `in_progress`

Some routes do not return a delivery report. When that happens the recipient legitimately
remains in_progress and the message may still have been delivered — the carrier simply
never confirmed it. We deliberately do not promote those to a failure status, so what you
read here always matches your detailed report.

A number you sent twice appears once

Recipients are identified by phone number. If the same number appeared more than once in
the same send — including as different formats such as 11999999999 and
(11) 99999-9999 — it is listed once here, with a single status. The send itself is
unaffected.

📞 Support

Documentation: docs.liguelead.com.br
Client Area: areadocliente.liguelead.app.br