List recipients

GET https://platform.scribeless.co/api/recipients
X-API-Key: YOUR_API_KEY

Returns a JSON array of recipients accessible to your API key, including their campaign summaries and generated document records. Shipped and delivered recipients are included unless you filter by status. Deleted recipients are excluded by default.

Query parameters

Filters are combined. Results are ordered newest first, with recipient ID as a tie-breaker. The response is an array, without a total count or pagination envelope.

Always supply page and pageSize when listing large collections. Omitting both leaves the result subject to the database response limit; it does not guarantee every recipient. Continue requesting pages until an empty array is returned. If the service truncates a page below the requested size, reduce pageSize before continuing. As with other page-number APIs, concurrent additions or removals can move rows between pages.

Example request

curl --get 'https://platform.scribeless.co/api/recipients' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --data-urlencode 'externalId=order_12345' \
  --data-urlencode 'campaignId=CAMPAIGN_ID' \
  --data-urlencode 'status=pending' \
  --data-urlencode 'page=1' \
  --data-urlencode 'pageSize=200'

No matching recipients returns []. The external ID is stored under variables.externalId in each recipient; it is not a unique Scribeless recipient ID.

List the active cart

Fetch GET /api/carts/active with the same API key. Each item in campaigns contains a nested campaign object. For each campaigns[].campaign.id, list recipients with campaignId=<id>&status=pending&page=1&pageSize=200, then continue through the pages.

This restricts the list to pending recipients in the cart's campaigns. There is no direct cart filter on the recipients endpoint. Invalid recipients require a separate status=invalid request if you want to inspect validation failures.

Recipient status and rendering

status describes the recipient lifecycle, not rendering progress. A one-time recipient can remain pending while its documents render and until payment is completed. Check render_status and generated documents separately to determine whether previews are available. Filtering status=pending alone does not mean a recipient has finished rendering.

Status codes