Skip to Content
GuidesSigners

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

PropertyTypeDescription
idstringUnique identifier
emailstringSigner’s email address
namestringSigner’s display name
roleenumsigner, approver, or cc
signingOrdernumberOrder in signing sequence (1-based)
statusenumpending, viewed, signed, declined
authMethodenumemail_link, wallet_signature, sms_otp
accessTokenstringToken for signing URL
signedAtdatetimeWhen the signer completed signing

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}`;

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,
});

Signers with the same signingOrder can sign in parallel. Leave signingOrder unset (or set to 1) for parallel signing.

Signer Roles

RoleDescription
signerMust complete all assigned fields
approverReviews and approves without signing
ccReceives a copy when complete
// 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}`);
  }
}

Signer Status Flow

StatusDescription
pendingHasn’t opened the signing link yet
viewedOpened the document but hasn’t signed
signedCompleted all required fields
declinedDeclined to sign

Removing Signers

Remove a signer before the document is sent:

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

Signers can only be removed from documents in draft status.

Signing URLs

Each signer has a unique access token used to build their signing URL:

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

You can:

  • Send automatically - Korala sends email notifications
  • Send manually - Use the access token to build and send your own links
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"
}
Last updated on
DocumentsFields