Paperjoy API overview

The Paperjoy API is a JSON over HTTPS API for creating and tracking handwritten postcards. New to it? Start with the Quickstart.

Base URL

https://paperjoy.co/api

Send an API key as a bearer token on every request:

Authorization: Bearer pj_live_...

A pj_test_ key runs every request in test mode; a pj_live_ key runs it in live mode. Paths and bodies are identical in both.

Method	Path	Does
`GET`	`/api/user`	Your account and credit balance.
`POST`	`/api/postcards`	Create a postcard.
`POST`	`/api/postcards/preview`	Render the card as a PNG.
`GET`	`/api/postcards`	List your postcards, newest first, one page at a time.
`GET`	`/api/postcards/{id}`	Retrieve one postcard.
`GET`	`/api/signatures`	List your custom signatures.
`GET`	`/api/signatures/{id}`	Retrieve one signature.
`DELETE`	`/api/signatures/{id}`	Delete a signature.

Each endpoint has its own page with the full schema under Endpoints in the sidebar.

Headers. Send Accept: application/json on every request and Content-Type: application/json with a body. The preview endpoint returns image/png.
Envelope. Successful JSON responses wrap the result in data.
IDs. IDs are opaque strings with a prefix: pc_ for postcards, sig_ for signatures, user_ for users. Store them as strings.
Timestamps. ISO 8601 with a UTC offset, such as 2026-10-17T14:31:48+00:00. Fields that haven’t happened yet are null.
Idempotency. POST /api/postcards requires an Idempotency-Key header. See Retry safely.
Errors. A JSON body with message, plus errors for validation failures. See Errors and rate limits.
Compatibility. We may add fields and status values. Ignore fields you don’t use and handle unknown statuses gracefully.