Send a draft signing request

POST /api/v1/signing-requests/{id}/send

Needs the send permission.

Permission	send
MCP tool	send_signing_request
Retries	Safe with an Idempotency-Key
Approval	Agent keys, and keys made to need approval, wait for an owner or admin: 202

Request

Path parameters

Name	Type	Required	Description
id	string (uuid)	Yes	—

Headers

Name	Type	Required	Description
Idempotency-Key	string	No	Makes a retried call safe: the same key returns the first result instead of creating or sending again. Matches ^[A-Za-z0-9_-]{8,100}$.

Responses

Status	Meaning
200	Sent.
202	The send waits for a person's approval.
400	The input is invalid.
401	No key, or a key that is unknown, expired or revoked, or whose creator is no longer an owner or admin.
402	The workspace's plan doesn't allow it: no completed requests left this month, more members than sender seats, more signers than the plan allows, a document that must be bought first, or the workspace's saved templates are at its plan's limit.
403	The key lacks the permission, or it is an API key and the workspace isn't on Teams & Platform.
404	Not found in the key's workspace (a key works only in the workspace it was made in; get_workspace says which).
409	The request is in a state that doesn't allow this, or the Idempotency-Key was used for something else.
422	Valid, but it can't go ahead: an address outside the key's recipient domains or one that can't receive email, or a signing role without a recipient.
429	More than 120 calls a minute through this key, more than 2000 from one network address (for IPv6, its /56 block) across all keys, or a limit on sending reached: the key's daily sends, the plan's or a recipient's daily requests, or the workspace's waiting approvals.

Errors share one shape, { "message": "…" }: see Errors and rate limits.

200 body

Field	Type	Description
id	string (uuid)	—
title	string	—
status	draft or sent or completed or declined or voided or expired	—
routing	sequential or parallel	—
message	string or null	—
sender	object or null	—
sender.name	string or null	—
sender.email	string	—
created_at	string (date-time) or null	—
sent_at	string (date-time) or null	—
completed_at	string (date-time) or null	—
expires_at	string (date-time) or null	—
documents	array of objects	—
documents[].id	string (uuid)	—
documents[].document_id	string (uuid)	—
documents[].title	string	—
documents[].completed_copy	boolean	—
recipients	array of objects	—
recipients[].id	string (uuid)	—
recipients[].role	string	—
recipients[].name	string	—
recipients[].email	string	—
recipients[].routing_order	integer	—
recipients[].status	pending or notified or viewed or signed or declined	—
recipients[].signed_at	string (date-time) or null	—
recipients[].declined_at	string (date-time) or null	—
recipients[].delivery	string or null	The latest email delivery status.
approval	object or null	The latest approval, when the request was sent through an agent key or a key that needs approval.
approval.id	string (uuid)	—
approval.kind	signing.send or intake.create	—
approval.status	pending or approved or declined or expired or failed	—
approval.title	string	—
approval.addresses	array of string	—
approval.credential	string or null	—
approval.signing_request_id	string or null	—
approval.intake_request_id	string or null	—
approval.decided_by	string or null	—
approval.decided_at	string (date-time) or null	—
approval.result	string or null	—
approval.expires_at	string (date-time)	—
approval.created_at	string (date-time)	—

Example

{
  "id": "c3e9a7b1-2d4f-4a6c-8e1b-5f7d9a2c4e6b",
  "title": "Mutual NDA — Acme",
  "status": "sent",
  "routing": "sequential",
  "message": "Please review and sign.",
  "sender": {
    "name": "Olga Owner",
    "email": "olga@example.com"
  },
  "created_at": "2026-11-03T16:20:00.000Z",
  "sent_at": "2026-11-03T16:41:12.000Z",
  "completed_at": null,
  "expires_at": "2026-12-03T16:41:12.000Z",
  "documents": [
    {
      "id": "0c2e4a6b-8d1f-4b3c-9e5a-7c9e1b3d5f2a",
      "document_id": "8a1f5c2e-3b4d-4e6f-9a7b-1c2d3e4f5a6b",
      "title": "Mutual NDA — Acme",
      "completed_copy": false
    }
  ],
  "recipients": [
    {
      "id": "b6d8f1a3-5c7e-4d9b-a2f4-6c8e1b3d5f7a",
      "role": "client",
      "name": "Ada Lovelace",
      "email": "ada@example.com",
      "routing_order": 1,
      "status": "notified",
      "signed_at": null,
      "declined_at": null,
      "delivery": "delivered"
    }
  ],
  "approval": {
    "id": "a4c6e8b2-1d3f-4b5a-8c7e-9f1b3d5a7c2e",
    "kind": "signing.send",
    "status": "approved",
    "title": "Mutual NDA — Acme",
    "addresses": [
      "ada@example.com"
    ],
    "credential": "Sales agent",
    "signing_request_id": "c3e9a7b1-2d4f-4a6c-8e1b-5f7d9a2c4e6b",
    "intake_request_id": null,
    "decided_by": "Olga Owner",
    "decided_at": "2026-11-03T16:41:10.000Z",
    "result": null,
    "expires_at": "2026-11-10T16:20:01.000Z",
    "created_at": "2026-11-03T16:20:01.000Z"
  }
}

202 body

The same as 200.

Examples

curl

curl -X POST https://tryjustdocs.com/api/v1/signing-requests/c3e9a7b1-2d4f-4a6c-8e1b-5f7d9a2c4e6b/send \
  -H "Authorization: Bearer $JUSTDOCS_API_KEY" \
  -H "Idempotency-Key: deal-4821-send-signing-request"

Node.js

const response = await fetch("https://tryjustdocs.com/api/v1/signing-requests/c3e9a7b1-2d4f-4a6c-8e1b-5f7d9a2c4e6b/send", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.JUSTDOCS_API_KEY}`,
    "Idempotency-Key": "deal-4821-send-signing-request",
  },
});
if (!response.ok) throw new Error((await response.json()).message);
const result = await response.json();

Python

import os
import requests

response = requests.post(
    "https://tryjustdocs.com/api/v1/signing-requests/c3e9a7b1-2d4f-4a6c-8e1b-5f7d9a2c4e6b/send",
    headers={"Authorization": f"Bearer {os.environ['JUSTDOCS_API_KEY']}", "Idempotency-Key": "deal-4821-send-signing-request"},
    timeout=30,
)
response.raise_for_status()
result = response.json()