Create a Signature Request

Creating a signature request involves 4 simple steps:

Create signature draft — specify basic document data
Upload document — upload the file using a presigned URL
Wait for processing — Leypal processes the document asynchronously
Send signature — configure signers and fields, then dispatch

Step 1: Create Signature Draft

Create a new signature that returns a signatureId and a presigned URL for uploading your document.

The originalDocumentType must be the MIME type of the document. Only the following types are accepted:

File Type	MIME Type
PDF	`application/pdf`
Word (.docx)	`application/vnd.openxmlformats-officedocument.wordprocessingml.document`
Word (.doc)	`application/msword`
JPG	`image/jpeg`
PNG	`image/png`

curl --location 'https://api.leypal.com/api/v1/signatures' \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: sk_abc123xyz...' \
  --data '{
    "type": "advanced",
    "originalDocumentName": "Service Agreement.docx",
    "originalDocumentType": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
    "originalDocumentExtension": "docx"
  }'

Response:

{
  "signatureId": 46,
  "uploadUrl": "https://example-bucket.s3.us-east-1.amazonaws.com/original/org_2/document.docx?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=..."
}

Save the signatureId (in this case 46) — you'll need it in the following steps.

Step 2: Upload Document

Use the presigned URL returned in Step 1 to upload your document via a PUT request.

curl --location --request PUT 'https://example-bucket.s3.us-east-1.amazonaws.com/original/org_2/document.docx?X-Amz-Algorithm=...' \
  --header 'Content-Type: application/octet-stream' \
  --data-binary '@/path/to/file/Service Agreement.docx'

Once uploaded, the document automatically begins processing.

Step 3: Wait for Document Processing

Leypal processes the document asynchronously. Poll the status using the signatureId until documentStatus is "ready".

curl --location 'https://api.leypal.com/api/v1/signatures/46' \
  --header 'X-Api-Key: sk_abc123xyz...'

Example response:

{
  "signatureId": 46,
  "status": "draft",
  "documentStatus": "ready",
  "type": "advanced",
  "originalDocumentName": "Service Agreement.docx",
  "createdAt": "2026-03-30T12:00:00Z",
  "updatedAt": "2026-03-30T12:05:00Z"
}

Possible document statuses:

Status	Description
`draft`	Created, no document uploaded yet
`uploaded`	Document uploaded, processing starting
`processing`	Leypal is processing the document
`ready`	Document ready — you can proceed to send
`error`	An error occurred processing the document

Only when documentStatus is "ready" can you proceed to the next step.

Step 4: Send Signature with Configuration

Once the document is ready, configure the signers, their signature fields, and send the request.

curl --location 'https://api.leypal.com/api/v1/signatures/46/send' \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: sk_abc123xyz...' \
  --data '{
    "senderName": "Your Company",
    "subject": "Signature Request: Service Agreement",
    "messageContent": "Please review and sign the attached document.",
    "signers": [
      {
        "name": "John Doe",
        "email": "john.doe@example.com",
        "fields": [
          {
            "name": "signature",
            "type": "sign",
            "page": 1,
            "left": 0.1,
            "top": 0.8,
            "width": 0.3,
            "height": 0.1,
            "required": true
          }
        ]
      }
    ]
  }'

Response:

{
  "signatureId": 46,
  "status": "created",
  "documentStatus": "ready",
  "type": "advanced",
  "subject": "Signature Request: Service Agreement",
  "senderName": "Your Company",
  "dateSent": "2026-03-30T12:10:00Z",
  "signers": [
    {
      "id": 501,
      "email": "john.doe@example.com",
      "name": "John Doe",
      "status": "PENDING"
    }
  ]
}

The signature is now in "created" status and signers have received invitation emails.

Next Steps

Signature API Reference — Complete endpoint documentation
Configure Webhooks — Get notified when signers complete
API Overview — Learn about authentication and limits

Create a Signature Request

Create a Signature Request

Step 1: Create Signature Draft

Step 2: Upload Document

Step 3: Wait for Document Processing

Step 4: Send Signature with Configuration

Next Steps

On this page