Documents

A document represents a PDF and its signers. It moves through three states: PENDING (created, not yet sent), SENT (out for signature), and COMPLETED (all signers have signed).

Create a document

POST /api/v1/documents

Uploads a PDF and creates a document in PENDING state. Send the request as multipart/form-data.

Request fields

Field	Type	Required	Description
file	file	Yes	The PDF to be signed. Must be application/pdf and at most 10MB.
name	string	No	A label for the document. Defaults to the file name.

curl -X POST https://signyu.com/api/v1/documents \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -F "file=@/path/to/agreement.pdf" \
  -F "name=Service Agreement"

Response

Returns 201 Created.

{
  "documentId": "b6b1f0e2-1c9a-4a1e-9b1a-2f3d4e5a6b7c",
  "name": "Service Agreement",
  "status": "PENDING"
}

Add signers

POST /api/v1/documents/{documentId}/signers

Adds one or more signers. Only allowed while the document is PENDING. Signers sign in the order they are added, and a document can have at most 6 signers.

Request body

Field	Type	Required	Description
signers	array	Yes	A non-empty array of signer objects.
signers[].name	string	Yes	The signer's full name.
signers[].phone	string	Yes	Digits only, at least 10 characters.
signers[].email	string	Yes	A valid email address. The signing link is emailed here.

curl -X POST https://signyu.com/api/v1/documents/{documentId}/signers \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "signers": [{ "name": "Asha Rao", "phone": "9876543210", "email": "asha@example.com" }] }'

Response

Returns 201 Created with the created signers and their assigned signing order.

{
  "signers": [
    { "signerId": "s_1", "name": "Asha Rao", "email": "asha@example.com", "signingOrder": 1 }
  ]
}

Send for signature

POST /api/v1/documents/{documentId}/send

Deducts one credit per signer, marks the document SENT, emails a signing link to each signer, and returns those links. Requires at least one signer. The request has no body.

curl -X POST https://signyu.com/api/v1/documents/{documentId}/send \
  -H "Authorization: Bearer sk_live_your_api_key"

Response

{
  "documentId": "b6b1f0e2-1c9a-4a1e-9b1a-2f3d4e5a6b7c",
  "status": "SENT",
  "creditsRemaining": 48,
  "signers": [
    {
      "signerId": "s_1",
      "name": "Asha Rao",
      "email": "asha@example.com",
      "signingOrder": 1,
      "signUrl": "https://signyu.com/sign?did=b6b1f0e2-1c9a-4a1e-9b1a-2f3d4e5a6b7c&sid=s_1"
    }
  ]
}

If you do not have enough credits, the request returns 402 insufficient_credits and nothing is sent.

Retrieve a document

GET /api/v1/documents/{documentId}

Returns the document, each signer's progress, and a downloadUrl for the signed PDF once the document is COMPLETED. The download URL is a temporary, presigned link. Each signer's signUrl is null until the document is sent, and is populated once the status is SENT.

curl https://signyu.com/api/v1/documents/{documentId} \
  -H "Authorization: Bearer sk_live_your_api_key"

Response

{
  "documentId": "b6b1f0e2-1c9a-4a1e-9b1a-2f3d4e5a6b7c",
  "name": "Service Agreement",
  "status": "COMPLETED",
  "createdAt": "2026-07-17T06:30:00.000Z",
  "updatedAt": "2026-07-17T07:15:00.000Z",
  "downloadUrl": "https://s3.ap-south-1.amazonaws.com/...",
  "signers": [
    {
      "signerId": "s_1",
      "name": "Asha Rao",
      "email": "asha@example.com",
      "phone": "9876543210",
      "signingOrder": 1,
      "openedAt": "2026-07-17T07:00:00.000Z",
      "signedAt": "2026-07-17T07:05:00.000Z",
      "hasSigned": true,
      "signUrl": "https://signyu.com/sign?did=b6b1f0e2-1c9a-4a1e-9b1a-2f3d4e5a6b7c&sid=s_1"
    }
  ]
}

List documents

GET /api/v1/documents

Returns your documents, most recent first, with a summary of signer progress.

Query parameters

Parameter	Type	Default	Description
limit	number	20	Number of documents to return (1 to 100).
offset	number	0	Number of documents to skip.

curl "https://signyu.com/api/v1/documents?limit=20&offset=0" \
  -H "Authorization: Bearer sk_live_your_api_key"

Response

{
  "documents": [
    {
      "documentId": "b6b1f0e2-1c9a-4a1e-9b1a-2f3d4e5a6b7c",
      "name": "Service Agreement",
      "status": "SENT",
      "createdAt": "2026-07-17T06:30:00.000Z",
      "signers": { "total": 2, "signed": 1 }
    }
  ],
  "limit": 20,
  "offset": 0
}