Signature Endpoints

The Signatures API lets you create electronic signature requests, send them to recipients, track their status, and cancel them when needed.

All requests require a valid API key in the Authorization header. See the Authentication guide for details.

Base URL: https://api.leypal.dev/api/v1

Create Draft Signature

POST /api/v1/signatures

Creates a new signature in draft status. After creating the draft you will upload the document separately and then call the Send Signature endpoint to dispatch the signing request to all recipients.

Request body

Field	Type	Required	Description
`type`	string	Yes	Signature type. One of `advanced`, `fast`, `self_signed`, `in_person`
`originalDocumentName`	string	Yes	Human-readable name of the document (e.g. `"Contract Q1 2024.pdf"`)
`originalDocumentType`	string	Yes	MIME type of the document (e.g. `"application/pdf"`)
`originalDocumentExtension`	string	Yes	File extension without dot (e.g. `"pdf"`, `"docx"`)

Example request

curl -X POST https://api.leypal.dev/api/v1/signatures \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "advanced",
    "originalDocumentName": "Service Agreement.pdf",
    "originalDocumentType": "application/pdf",
    "originalDocumentExtension": "pdf"
  }'

Example response

{
  "id": 1042,
  "type": "advanced",
  "status": "draft",
  "documentStatus": "draft",
  "senderName": "Hugo Gutierrez",
  "subject": "",
  "messageContent": "",
  "originalDocumentName": "Service Agreement.pdf",
  "originalDocumentType": "application/pdf",
  "originalDocumentExtension": "pdf",
  "organizationId": 7,
  "createdByUserId": 3,
  "createdAt": "2024-11-15T09:30:00.000Z",
  "updatedAt": "2024-11-15T09:30:00.000Z"
}

Note: The returned id is the signatureId used in all subsequent endpoints for this signature.

List Signatures

GET /api/v1/signatures

Returns a paginated list of signatures belonging to the authenticated organization.

Query parameters

Parameter	Type	Required	Description
`skip`	number	No	Number of records to skip (default: `0`)
`limit`	number	No	Max records to return per page (default: `20`)
`status`	string	No	Filter by status. One of `draft`, `created`, `scheduled`, `expired`, `partially_signed`, `completed`, `rejected`
`type`	string	No	Filter by type. One of `advanced`, `fast`, `self_signed`, `in_person`
`fileName`	string	No	Filter by document file name (partial match)
`subject`	string	No	Filter by subject line (partial match)
`date`	string	No	Filter by exact sent date (`YYYY-MM-DD`)
`dateFrom`	string	No	Filter sent date from (`YYYY-MM-DD`)
`dateTo`	string	No	Filter sent date to (`YYYY-MM-DD`)
`recipients`	string	No	Comma-separated list of signer emails to filter by
`sortBy`	string	No	Sort field. One of `createdAt`, `dateSent`, `updatedAt`
`sortOrder`	string	No	Sort direction. One of `asc`, `desc`

Example request

curl -X GET "https://api.leypal.dev/api/v1/signatures?status=created&limit=10&skip=0&sortBy=createdAt&sortOrder=desc" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example response

{
  "items": [
    {
      "id": 1042,
      "type": "advanced",
      "status": "created",
      "subject": "Service Agreement — please sign",
      "senderName": "Hugo Gutierrez",
      "dateSent": "2024-11-15T09:35:00.000Z",
      "expiresDate": "2024-12-15T09:35:00.000Z",
      "createdAt": "2024-11-15T09:30:00.000Z",
      "updatedAt": "2024-11-15T09:35:00.000Z",
      "signers": [
        {
          "id": 501,
          "email": "signer@example.com",
          "name": "Jane Doe",
          "status": "pending"
        }
      ]
    }
  ],
  "total": 1,
  "skip": 0,
  "limit": 10
}

Get Signature

GET /api/v1/signatures/{signatureId}

Returns the full details of a single signature, including its current status and all signers.

Path parameters

Parameter	Type	Required	Description
`signatureId`	number	Yes	The numeric ID of the signature

Example request

curl -X GET https://api.leypal.dev/api/v1/signatures/1042 \
  -H "Authorization: Bearer YOUR_API_KEY"

Example response

{
  "id": 1042,
  "type": "advanced",
  "status": "partially_signed",
  "documentStatus": "ready",
  "subject": "Service Agreement — please sign",
  "messageContent": "Hi, please review and sign the attached document.",
  "senderName": "Hugo Gutierrez",
  "dateSent": "2024-11-15T09:35:00.000Z",
  "expiresDate": "2024-12-15T09:35:00.000Z",
  "requireVerification": false,
  "ccOnComplete": ["manager@example.com"],
  "createdAt": "2024-11-15T09:30:00.000Z",
  "updatedAt": "2024-11-16T14:10:00.000Z",
  "signers": [
    {
      "id": 501,
      "email": "signer@example.com",
      "name": "Jane Doe",
      "status": "signed",
      "signedAt": "2024-11-16T14:10:00.000Z"
    },
    {
      "id": 502,
      "email": "second@example.com",
      "name": "John Smith",
      "status": "pending",
      "signedAt": null
    }
  ]
}

Signature status values

Status	Description
`draft`	Created but not yet configured or sent
`created`	Configured and dispatched to signers
`scheduled`	Queued for future dispatch
`expired`	Signing deadline passed without all signers completing
`partially_signed`	At least one signer has signed, others pending
`completed`	All signers have signed
`rejected`	One or more signers rejected the document

Get Signature Status

GET /api/v1/signatures/{signatureId}/status

Returns a lightweight status summary for a signature. Useful for polling without fetching the full object.

Path parameters

Parameter	Type	Required	Description
`signatureId`	number	Yes	The numeric ID of the signature

Example request

curl -X GET https://api.leypal.dev/api/v1/signatures/1042/status \
  -H "Authorization: Bearer YOUR_API_KEY"

Example response

{
  "id": 1042,
  "status": "partially_signed",
  "documentStatus": "ready",
  "signers": [
    { "id": 501, "email": "signer@example.com", "status": "signed" },
    { "id": 502, "email": "second@example.com", "status": "pending" }
  ]
}

Send Signature

POST /api/v1/signatures/{signatureId}/send

Finalizes a draft signature and sends signing invitation emails to all configured signers. This transitions the signature from draft to created status.

Path parameters

Parameter	Type	Required	Description
`signatureId`	number	Yes	The numeric ID of the signature to send

Request body

Field	Type	Required	Description
`signers`	array	Yes	List of signer objects. Each signer must have at minimum an `email` field
`signers[].email`	string	Yes	Signer email address
`signers[].name`	string	No	Signer display name
`signers[].order`	number	No	Signing order (for sequential workflows)
`subject`	string	No	Email subject line sent to signers
`messageContent`	string	No	Body message included in the signing invitation email
`senderName`	string	No	Name shown as sender in signing invitation emails
`expiresDate`	string	No	ISO 8601 expiry date for the signing request
`ccOnComplete`	array	No	List of email addresses to CC when signing is complete
`requireVerification`	boolean	No	Require identity verification before signing (default: `false`)
`categoryId`	number	No	Category ID to associate this signature with

Note: Signer emails within the same signature request must be unique. Duplicate emails will return a 400 validation error.

Example request

curl -X POST https://api.leypal.dev/api/v1/signatures/1042/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "signers": [
      { "email": "signer@example.com", "name": "Jane Doe" },
      { "email": "second@example.com", "name": "John Smith" }
    ],
    "subject": "Service Agreement — please sign",
    "messageContent": "Hi, please review and sign the attached document at your earliest convenience.",
    "senderName": "Hugo Gutierrez",
    "expiresDate": "2024-12-15T09:35:00.000Z",
    "ccOnComplete": ["manager@example.com"],
    "requireVerification": false
  }'

Example response

{
  "id": 1042,
  "type": "advanced",
  "status": "created",
  "subject": "Service Agreement — please sign",
  "messageContent": "Hi, please review and sign the attached document at your earliest convenience.",
  "senderName": "Hugo Gutierrez",
  "dateSent": "2024-11-15T09:35:00.000Z",
  "expiresDate": "2024-12-15T09:35:00.000Z",
  "requireVerification": false,
  "ccOnComplete": ["manager@example.com"],
  "createdAt": "2024-11-15T09:30:00.000Z",
  "updatedAt": "2024-11-15T09:35:00.000Z",
  "signers": [
    { "id": 501, "email": "signer@example.com", "name": "Jane Doe", "status": "pending" },
    { "id": 502, "email": "second@example.com", "name": "John Smith", "status": "pending" }
  ]
}

Cancel Signature

DELETE /api/v1/signatures/{signatureId}

Soft-deletes a signature, preventing any further signing actions. Signing links already sent to recipients will no longer work after cancellation.

Path parameters

Parameter	Type	Required	Description
`signatureId`	number	Yes	The numeric ID of the signature to cancel

Example request

curl -X DELETE https://api.leypal.dev/api/v1/signatures/1042 \
  -H "Authorization: Bearer YOUR_API_KEY"

Example response

Returns 200 OK with the soft-deleted signature object:

{
  "id": 1042,
  "status": "draft",
  "deletedAt": "2024-11-15T10:00:00.000Z"
}

Note: Only signatures your organization owns can be cancelled. Attempting to delete another organization's signature returns 403 Forbidden.

Send Signer Reminder

POST /api/v1/signatures/{signatureId}/signers/{signerId}/notification

Sends a reminder email to a specific signer who has not yet signed.

Path parameters

Parameter	Type	Required	Description
`signatureId`	number	Yes	The numeric ID of the signature
`signerId`	number	Yes	The numeric ID of the signer to remind

Example request

curl -X POST https://api.leypal.dev/api/v1/signatures/1042/signers/502/notification \
  -H "Authorization: Bearer YOUR_API_KEY"

Example response

{
  "message": "Reminder sent to second@example.com"
}

Update Signer Email

PATCH /api/v1/signatures/{signatureId}/signers/{signerId}

Updates the email address of a signer before they have signed. Useful when a recipient's email was entered incorrectly.

Path parameters

Parameter	Type	Required	Description
`signatureId`	number	Yes	The numeric ID of the signature
`signerId`	number	Yes	The numeric ID of the signer to update

Request body

Field	Type	Required	Description
`email`	string	Yes	New email address for the signer

Example request

curl -X PATCH https://api.leypal.dev/api/v1/signatures/1042/signers/502 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "email": "corrected@example.com" }'

Example response

{
  "id": 502,
  "email": "corrected@example.com",
  "name": "John Smith",
  "status": "pending"
}

Signature Endpoints

On this page