Recipients

Fetch recipient

Get a Scribeless recipient by ID.

Fetch a recipient when your integration needs to check recipient status, confirm stored recipient data, or find the generated document paths for a rendered recipient.

GET https://platform.scribeless.co/api/recipients/{recipientId}

Headers

X-API-Key: YOUR_API_KEY

Path parameters

Parameter	Type	Description
`recipientId`	string	Scribeless recipient ID.

Example request

curl --request GET 'https://platform.scribeless.co/api/recipients/RECIPIENT_ID' \
  --header 'X-API-Key: YOUR_API_KEY'

Response

Successful requests return the recipient, its campaign summary, and any generated document records.

{
  "id": "RECIPIENT_ID",
  "first_name": "Ada",
  "last_name": "Lovelace",
  "company": "Example Co",
  "address1": "1 Example Street",
  "city": "London",
  "state": "London",
  "postal_code": "SW1A 1AA",
  "country": "GB",
  "region": "UK",
  "status": "pending",
  "is_rendered": true,
  "campaign_id": "CAMPAIGN_ID",
  "variables": {
    "externalId": "order_12345",
    "offerCode": "SPRING-25"
  },
  "campaign": {
    "id": "CAMPAIGN_ID",
    "name": "API postcard campaign",
    "status": "pending",
    "product": {
      "id": "PRODUCT_ID",
      "name": "A6 postcard"
    },
    "template": {
      "id": "TEMPLATE_ID",
      "name": "Postcard template",
      "status": "active"
    },
    "delivery_method": "directMail",
    "include_envelope": false
  },
  "documents": [
    {
      "id": "DOCUMENT_ID",
      "format": "pdf",
      "src": "teams/TEAM_ID/campaigns/CAMPAIGN_ID/recipients/RECIPIENT_ID/postcard.pdf",
      "document": {
        "type": "postcard"
      }
    },
    {
      "id": "PREVIEW_ID",
      "format": "preview",
      "src": "teams/TEAM_ID/campaigns/CAMPAIGN_ID/recipients/RECIPIENT_ID/postcard-1.png",
      "document": {
        "type": "postcard"
      }
    }
  ]
}

Notes

The response only includes recipients your API key can access.
documents contains storage paths and document metadata. Preview entries have format: "preview" and can be downloaded with GET /api/recipients/{recipientId}/preview.
is_rendered indicates whether Scribeless has generated recipient documents.
Treat any non-2xx response as failed and inspect the response body for the error message.

Status codes

Status	Meaning
`200`	Recipient found.
`401`	Missing, malformed, invalid, or unauthorized API key.
`404`	Recipient not found.
`500`	Recipient could not be fetched. Retry or contact support if it persists.

Create recipients

Create one or more recipients for a Scribeless campaign.

Fetch recipient preview

Download a rendered PNG preview for a Scribeless recipient.