Sign API

Best Practices

Best practices for building reliable, efficient signing workflows with the Skribble Sign API.

API Version Selection

Use Sign API v2 for all production integrations — it is the current stable version.

Sign API v3 is available as a preview and is a great opportunity to test upcoming features early and share feedback with the Skribble team before general availability:

• Draft workflow — build signature requests before inviting signers
• Multi-document support — up to 50 documents per request
• Signer groups and flexible signer management

Signature Request Workflow

In v2, a signature request is created and goes directly to OPEN — signers are notified immediately. Include the document inline in the creation call, either as a URL reference or Base64-encoded content, or reference a previously uploaded document by ID.

Code
OPEN → SIGNED/DECLINED/WITHDRAWN

Option 1 — Document via URL

Code
{
  "title": "Contract Agreement",
  "message": "Please sign this contract.",
  "document": {
    "url": "https://your-app.com/documents/contract.pdf",
    "filename": "contract.pdf"
  },
  "signatures": [
    { "signer_email_address": "alice@example.com" }
  ]
}

Option 2 — Document as Base64

Code
{
  "title": "Contract Agreement",
  "message": "Please sign this contract.",
  "document": {
    "content": "<base64-encoded-pdf>",
    "filename": "contract.pdf"
  },
  "signatures": [
    { "signer_email_address": "alice@example.com" }
  ]
}

Option 3 — Pre-uploaded document by ID

Upload the document first, then reference it by ID:

Code
{
  "content": "<base64-encoded-pdf>",
  "filename": "contract.pdf"
}

Then reference the returned id in the signature request:

Code
{
  "title": "Contract Agreement",
  "document_id": "doc-aaa-111",
  "signatures": [
    { "signer_email_address": "alice@example.com" }
  ]
}

Document Handling

Upload Best Practices

1. Validate before upload: Ensure documents are valid PDFs
2. Use meaningful filenames: They appear in the signing interface
3. Optimize file size: Large files slow down the signing experience
4. Base64 encode properly: Documents must be Base64-encoded

Code
// Upload a document
const response = await api.post('/documents', {
  title: 'Contract.pdf',
  content_type: 'application/pdf',
  content: base64EncodedPdf
});

Supported Attachment Types

• PDF documents
• Microsoft Office formats (Word, Excel, PowerPoint)
• Images (JPEG, PNG)
• Plain text files

Signer Management

Adding Signers

You can add signers in several ways:

1. By Email (Skribble account required):

Code
{
  "signer_email_address": "signer@example.com"
}

2. With Identity Data (no account required):

Code
{
  "signer_identity_data": {
    "email_address": "signer@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "mobile_number": "+41791234567",
    "language": "en"
  }
}

3. With both (no account required, unless existing account present):

Code
{
  "signer_email_address": "signer@example.com",
  "signer_identity_data": {
    "email_address": "signer@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "mobile_number": "+41791234567",
    "language": "en"
  }
}

Signing Sequence

Control the order in which signers are invited by setting sequence on each signature:

• Values start at 1 and must be sequential with no gaps (1, 2, 3…)
• Signers with the same sequence number sign in parallel
• Range: 1–999
• Omit sequence to allow all signers to sign in parallel

Disabling Notifications for SES

For Simple Electronic Signature (SES) quality, you can disable TAN-based notifications for no-account signers by setting notify: false on the signature. Use identity_reference in signer_identity_data to correlate signers with your internal system.

Signer Modification Rules

• In v2, signers are part of the creation call — once the request is OPEN, you cannot add or remove signers
• Once any signer has signed, you cannot modify the request
• Use DELETE /signature-requests/{id} to withdraw an open request and recreate it if changes are needed

Signature Qualities

Choose the appropriate signature quality based on your requirements:

Quality	Description	Use Case
SES	Simple Electronic Signature	Low-risk documents, internal approvals
AES	Advanced Electronic Signature	Standard contracts, agreements
QES	Qualified Electronic Signature	High-value contracts, regulatory requirements
DEMO	Test signature	Development and testing

Legislation Compliance

Legislation	Region	Standard
ZERTES	Switzerland	Swiss Federal Act on Electronic Signatures
EIDAS	European Union	EU Regulation on electronic identification

Customizing the Signing URL

When a signature request is created, each signer receives a signing_url. This URL forwards the signer to a preview page of the PDF document where they can start the signature process as usual.

You can append query parameters to the signing_url to control the signer's experience after completing or declining the signature process.

Parameter	Type	Description
exitURL	string (URL-encoded)	Optional URL to redirect after the signature process finished or declined. Example: https%3A%2F%2Fgoogle.com
errorURL	string (URL-encoded)	Optional URL to redirect in case of an error. Defaults to exitURL. Ignored if exitURL is not set.
declineURL	string (URL-encoded)	Optional URL to redirect when the user declines. Defaults to exitURL. Ignored if exitURL is not set.
hidedownload	boolean	Optional flag to hide and disable the download document option. Example: true
redirectTimeout	integer	Seconds before auto-redirect after signing. Min 0 (instant), max 90. Default: 45.
lang	string	Language for the signing page: en (default), de, fr.

Code
const signingUrlWithParams = `${signer.signing_url}?exitURL=${encodeURIComponent('https://your-app.com/done')}&lang=de&hidedownload=true`;

Reminders

Sending Manual Reminders

Code
POST /signature-requests/{id}/remind

Reminder Limitations

• Rate limit: One reminder per signer per hour
• Only works for signers who haven't completed signing
• Consider using automatic reminders for better UX

Request Ownership

By default, the API user creating a signature request is the owner. To assign ownership to a different business member, set the creator field:

Code
{
  "title": "Contract Agreement",
  "creator": "colleague@company.com",
  "document": { "url": "https://..." },
  "signatures": [...]
}

Deleting and Cleaning Up Data

Deletion Cascades

Deleting cascades to related resources and cleans up orphan leaves:

• DELETE /signature-requests/{id} also deletes the request's documents that are not referenced by another signature request.
• DELETE /documents/{id} also deletes the parent document when no other reference remains.

This means a document can be removed as a side effect of deleting its signature request. If you then try to delete that document directly, the API returns 404 (already gone) or 403 (cascade still in-flight — the document is about to be removed). Neither is an error to worry about.

Bulk Cleanup

When removing many objects at once (e.g. tidying up a test account):

1. Delete signature requests first. Their orphan documents go with them via the cascade above.
2. Then list remaining documents (GET /documents) and delete those — these are the orphans that were never attached to a signature request.
3. Treat 404 and 403 on document deletes as success — 404 means already gone, 403 means the SR cascade is still in-flight (retry after a short delay). Only 401 or 5xx indicate a real problem.

Code
// 1) Delete every signature request (cascades to its orphan documents)
const srs = await api.get('/signature-requests'); // returns the full set
for (const sr of srs) {
  await api.delete(`/signature-requests/${sr.id}`); // 404 ⇒ already gone
}

// 2) Mop up any remaining standalone documents
const docs = await api.get('/documents');
for (const doc of docs) {
  await api.delete(`/documents/${doc.id}`); // 404 ⇒ already gone, 403 ⇒ cascade in-flight (retry)
}

Common Pitfalls

Avoid These Mistakes

1. Caching document_id: The document_id changes with each revision and activity on a Signature Request. Always store only the Signature Request id and fetch the current document_id and status from the API when needed
2. Missing required fields: Ensure all signers and document details are complete in the creation call, since v2 requests go directly to OPEN
3. Ignoring status: Always check status_overall before performing actions
4. Not handling callbacks: Rely on callbacks rather than polling for status updates
5. Hardcoding URLs: Use environment-specific base URLs
6. Wrong type for page in visual signatures: The page field in visual signature positions must be a string (e.g. "page": "0"), not an integer

Status Checking

Always verify the current status before operations:

Code
const request = await api.get(`/signature-requests/${id}`);

if (request.status_overall === 'OPEN') {
  // Waiting for signatures — can send reminders
} else if (request.status_overall === 'SIGNED') {
  // All signers signed — download the signed document
} else if (request.status_overall === 'DECLINED') {
  // A signer declined — handle accordingly
} else if (request.status_overall === 'WITHDRAWN') {
  // Request was withdrawn
}