API reference

Recipients

The people on a document: signers, and people who get a copy (cc).

Endpoints · 7

POST Add a recipient
GET List recipients
GET Retrieve a recipient
PATCH Update a recipient
DELETE Remove a recipient
POST Send a reminder now
POST Create an embedded signing session

The object

Field	Type	Description
`id`	string	Unique ID, starting with rcp_.
`object`	string	Always "recipient".
`name, email`	string	Who they are.
`role`	enum	signer or cc.
`signing_order`	integer	With sequential signing, lower numbers sign first. People with the same number sign at the same time.
`locale`	enum	en or fr: the language of their emails and signing page.
`template_role`	string or null	The template role they fill.
`access_code`	boolean	true if they need an access code from you to open the document.
`status`	enum	pending, sent, viewed, signed or declined.
`sent_at, viewed_at, signed_at, declined_at`	timestamp or null	What they did, and when.
`decline_reason`	string or null	Their reason, if they declined.

POST/documents/{id}/recipients

Add a recipient

Drafts only.

Parameter	Type		Description
`name`	string	required	Up to 120 characters.
`email`	string	required	Each address once per document.
`role`	enum	optional	signer (default) or cc.
`signing_order`	integer	optional	1 to 50. Default: after the others.
`locale`	enum	optional	en or fr.
`access_code`	string	optional	A code you give them yourself, 4 to 40 characters. Stored only as a fingerprint.

Request

bash

curl -X POST "https://api.esorasign.com/v1/documents/doc_3y9Pf34qY6Nb3wWD25RQ4F/recipients" \
  -H "Authorization: Bearer $ESORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Maya Chen", "email": "maya.chen@example.com", "locale": "en" }'

Response

json

{
  "id": "rcp_5ZR3qa7yEeeby3abP3E2Zs",
  "object": "recipient",
  "name": "Maya Chen",
  "email": "maya.chen@example.com",
  "role": "signer",
  "signing_order": 1,
  "locale": "en",
  "template_role": null,
  "access_code": false,
  "status": "sent",
  "sent_at": "2026-11-02T14:05:11.000Z",
  "viewed_at": null,
  "signed_at": null,
  "declined_at": null,
  "decline_reason": null
}

GET/documents/{id}/recipients

List recipients

In signing order.

Request

bash

curl "https://api.esorasign.com/v1/documents/doc_3y9Pf34qY6Nb3wWD25RQ4F/recipients" \
  -H "Authorization: Bearer $ESORA_API_KEY"

Response

json

{
  "object": "list",
  "data": [
    {
      "id": "rcp_5ZR3qa7yEeeby3abP3E2Zs",
      "object": "recipient",
      "name": "Maya Chen",
      "email": "maya.chen@example.com",
      "role": "signer",
      "signing_order": 1,
      "locale": "en",
      "template_role": null,
      "access_code": false,
      "status": "sent",
      "sent_at": "2026-11-02T14:05:11.000Z",
      "viewed_at": null,
      "signed_at": null,
      "declined_at": null,
      "decline_reason": null
    }
  ],
  "has_more": false,
  "next_cursor": null
}

GET/documents/{id}/recipients/{recipient_id}

Retrieve a recipient

Request

bash

curl "https://api.esorasign.com/v1/documents/doc_3y9Pf34qY6Nb3wWD25RQ4F/recipients/rcp_5ZR3qa7yEeeby3abP3E2Zs" \
  -H "Authorization: Bearer $ESORA_API_KEY"

Response

json

{
  "id": "rcp_5ZR3qa7yEeeby3abP3E2Zs",
  "object": "recipient",
  "name": "Maya Chen",
  "email": "maya.chen@example.com",
  "role": "signer",
  "signing_order": 1,
  "locale": "en",
  "template_role": null,
  "access_code": false,
  "status": "sent",
  "sent_at": "2026-11-02T14:05:11.000Z",
  "viewed_at": null,
  "signed_at": null,
  "declined_at": null,
  "decline_reason": null
}

PATCH/documents/{id}/recipients/{recipient_id}

Update a recipient

Drafts only. To fix a name or email after sending, use Correct in the app.

Parameter	Type		Description
`name, email, role, signing_order, locale, access_code`		optional	As in Add a recipient.

Request

bash

curl -X PATCH "https://api.esorasign.com/v1/documents/doc_3y9Pf34qY6Nb3wWD25RQ4F/recipients/rcp_5ZR3qa7yEeeby3abP3E2Zs" \
  -H "Authorization: Bearer $ESORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "email": "m.chen@example.com" }'

Response

json

{
  "id": "rcp_5ZR3qa7yEeeby3abP3E2Zs",
  "object": "recipient",
  "name": "Maya Chen",
  "email": "maya.chen@example.com",
  "role": "signer",
  "signing_order": 1,
  "locale": "en",
  "template_role": null,
  "access_code": false,
  "status": "sent",
  "sent_at": "2026-11-02T14:05:11.000Z",
  "viewed_at": null,
  "signed_at": null,
  "declined_at": null,
  "decline_reason": null
}

DELETE/documents/{id}/recipients/{recipient_id}

Remove a recipient

Drafts only. Their fields are removed too.

Request

bash

curl -X DELETE "https://api.esorasign.com/v1/documents/doc_3y9Pf34qY6Nb3wWD25RQ4F/recipients/rcp_5ZR3qa7yEeeby3abP3E2Zs" \
  -H "Authorization: Bearer $ESORA_API_KEY"

Response

json

{ "id": "rcp_5ZR3qa7yEeeby3abP3E2Zs", "object": "recipient", "deleted": true }

POST/documents/{id}/recipients/{recipient_id}/remind

Send a reminder now

Emails a reminder to a signer whose turn it is and who hasn’t signed. At most one email to a person per hour.

Parameter	Type		Description
`Idempotency-Key`	header	required	A unique value for this action, 8 to 200 characters. See Idempotency.

Request

bash

curl -X POST "https://api.esorasign.com/v1/documents/doc_3y9Pf34qY6Nb3wWD25RQ4F/recipients/rcp_5ZR3qa7yEeeby3abP3E2Zs/remind" \
  -H "Authorization: Bearer $ESORA_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'

Response

json

{ "id": "rcp_5ZR3qa7yEeeby3abP3E2Zs", "object": "recipient", "reminded": true }

POST/documents/{id}/recipients/{recipient_id}/signing-sessions

Create an embedded signing session

A one-time URL to show the signing page inside your site, for a signer you have identified yourself. The document must be sent. See Embedded signing.

Parameter	Type		Description
`return_url`	string	optional	HTTPS (or http://localhost while developing). Where the signer goes after signing, with ?event=signing_complete added.

Request

bash

curl -X POST "https://api.esorasign.com/v1/documents/doc_3y9Pf34qY6Nb3wWD25RQ4F/recipients/rcp_5ZR3qa7yEeeby3abP3E2Zs/signing-sessions" \
  -H "Authorization: Bearer $ESORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "return_url": "https://portal.example.com/signed" }'

Response

json

{
  "object": "signing_session",
  "recipient_id": "rcp_5ZR3qa7yEeeby3abP3E2Zs",
  "url": "https://sign.esorasign.com/embed/7Hk2…",
  "expires_at": "2026-11-02T14:12:00.000Z",
  "note": "Open within 5 minutes. The URL works once. Add your site to the workspace embed_origins to show it in a frame."
}