Signers

Signers are the people who need to sign a document. Each signer gets a unique access token to view and sign the document.

Signer Properties

Adding Signers

const signer = await korala.signers.create(documentId, {
  email: '[email protected]',
  name: 'John Doe',
});
 
console.log(`Signer ID: ${signer.id}`);
console.log(`Access Token: ${signer.accessToken}`);
 
// Build signing URL
const signingUrl = `https://korala.ai/sign/${signer.accessToken}`;

api_request "POST" "/api/v1/documents/${DOCUMENT_ID}/signers" \
  '{"email":"[email protected]","name":"John Doe"}'

Signing Order

For sequential signing, specify the order:

// First signer
await korala.signers.create(documentId, {
  email: '[email protected]',
  name: 'Alice Smith',
  signingOrder: 1,
});
 
// Second signer (receives link after Alice signs)
await korala.signers.create(documentId, {
  email: '[email protected]',
  name: 'Bob Jones',
  signingOrder: 2,
});
 
// Third signer
await korala.signers.create(documentId, {
  email: '[email protected]',
  name: 'Carol White',
  signingOrder: 3,
});

Signer Roles

// Add a CC recipient
await korala.signers.create(documentId, {
  email: '[email protected]',
  name: 'Legal Team',
  role: 'cc',
});

Listing Signers

const signers = await korala.signers.list(documentId);
 
for (const signer of signers) {
  console.log(`${signer.name}: ${signer.status}`);
  if (signer.signedAt) {
    console.log(`  Signed at: ${signer.signedAt}`);
  }
}

api_request "GET" "/api/v1/documents/${DOCUMENT_ID}/signers"

Signer Status Flow

Removing Signers

Remove a signer before you send the document:

await korala.signers.delete(documentId, signerId);

api_request "DELETE" "/api/v1/documents/${DOCUMENT_ID}/signers/${SIGNER_ID}"

Removing a signer removes their fields too. A signer ID that is not on the document answers 404, including one you already removed, so a retried delete after a timeout can return 404 for a removal that succeeded. The same holds for DELETE /documents/{id}/fields/{fieldId}.

Changing a Signer

Rename a signer or change when they sign, before you send the document. The email address cannot change: a different address is a different signer, so remove this one and add the other.

await korala.signers.update(documentId, signerId, { signingOrder: 2 });

api_request "PATCH" "/api/v1/documents/${DOCUMENT_ID}/signers/${SIGNER_ID}" \
  '{"signingOrder": 2}'

Signers with the same signingOrder sign at the same time; a higher order waits for every lower one. Orders run from 1 to 1000.

Signing URLs

Build each signer’s signing URL from their unique access token:

https://korala.ai/sign/{accessToken}

You can:

• Let Korala send - Korala emails signing links to signers
• Send your own - Use the access token to build and send your own links

The access token is the signer’s only credential: anyone holding the link can open the document and sign as that signer. Treat it like a password. Send it only to the signer, and keep it out of logs and analytics. Korala looks it up by its hash and keeps it encrypted.

How long a link opens

A signing link opens for as long as its document is out for signature, and for 90 days after the document is finished (completed, voided or expired), so the signer can download their copy. After that the link closes: GET /signing/{token}, its /preview and its /downloads answer 410 Gone with "reason": "signing_link_closed", and the signing page sends the signer to Korala to get their copy by email verification instead.

Your own copy is not affected: download it through the documents API at any time.

const signer = await korala.signers.create(documentId, {
  email: '[email protected]',
  name: 'John Doe',
});
 
// Option 1: Let Korala send emails
await korala.documents.send(documentId);
 
// Option 2: Build your own signing URL
const signingUrl = `https://sign.your-domain.com/sign/${signer.accessToken}`;
// Send via your own email system

Response Format

{
  "id": "sig_abc123",
  "documentId": "doc_xyz789",
  "email": "[email protected]",
  "name": "John Doe",
  "role": "signer",
  "signingOrder": 1,
  "status": "pending",
  "authMethod": "email_link",
  "accessToken": "tok_secret123",
  "signedAt": null,
  "createdAt": "2024-01-14T09:00:00Z",
  "updatedAt": "2024-01-14T09:00:00Z"
}