# Signers

> Add and manage document signers

Source: https://docs.korala.ai/guides/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

| Property | Type | Description |
|----------|------|-------------|
| `id` | string | Unique identifier |
| `email` | string | Signer's email address |
| `name` | string | Signer's display name |
| `role` | enum | `signer`, `approver`, or `cc` |
| `signingOrder` | number | Order in signing sequence (1-based) |
| `status` | enum | `pending`, `viewed`, `signed`, `declined` |
| `authMethod` | enum | `email_link`, `wallet_signature`, `sms_otp` |
| `accessToken` | string | Token for signing URL |
| `signedAt` | datetime | When the signer completed signing |

## Adding Signers

    ```typescript
    const signer = await korala.signers.create(documentId, {
      email: 'john@example.com',
      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}`;
    ```
    ```bash
    api_request "POST" "/api/v1/documents/${DOCUMENT_ID}/signers" \
      '{"email":"john@example.com","name":"John Doe"}'
    ```

## Signing Order

For sequential signing, specify the order:

    ```typescript
    // First signer
    await korala.signers.create(documentId, {
      email: 'alice@example.com',
      name: 'Alice Smith',
      signingOrder: 1,
    });

    // Second signer (receives link after Alice signs)
    await korala.signers.create(documentId, {
      email: 'bob@example.com',
      name: 'Bob Jones',
      signingOrder: 2,
    });

    // Third signer
    await korala.signers.create(documentId, {
      email: 'carol@example.com',
      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

| Role | Description |
|------|-------------|
| `signer` | Must complete all assigned fields |
| `approver` | Reviews and approves without signing |
| `cc` | Receives a copy when complete |

```typescript
// Add a CC recipient
await korala.signers.create(documentId, {
  email: 'legal@example.com',
  name: 'Legal Team',
  role: 'cc',
});
```

## Listing Signers

    ```typescript
    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}`);
      }
    }
    ```
    ```bash
    api_request "GET" "/api/v1/documents/${DOCUMENT_ID}/signers"
    ```

## Signer Status Flow

```mermaid
stateDiagram-v2
    [*] --> pending: Created
    pending --> viewed: Opens link
    viewed --> signed: Completes signing
    viewed --> declined: Declines
    pending --> declined: Declines
```

| Status | Description |
|--------|-------------|
| `pending` | Hasn't opened the signing link yet |
| `viewed` | Opened the document but hasn't signed |
| `signed` | Completed all required fields |
| `declined` | Declined to sign |

## Removing Signers

Remove a signer before you send the document:

    ```typescript
    await korala.signers.delete(documentId, signerId);
    ```
    ```bash
    api_request "DELETE" "/api/v1/documents/${DOCUMENT_ID}/signers/${SIGNER_ID}"
    ```

You can remove signers only while the document is in `draft` status.

## 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

    ```typescript
    const signer = await korala.signers.create(documentId, {
      email: 'john@example.com',
      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

```json
{
  "id": "sig_abc123",
  "documentId": "doc_xyz789",
  "email": "john@example.com",
  "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"
}
```