> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dokstamp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Document Signing Workflow

> How the three-party document signing workflow works — third-party signers and institutional digital certificates.

# Document Signing Workflow

DokStamp supports a **three-party signature workflow**: a document can be signed by external third parties (via email link) and/or signed institutionally using a digital certificate stored in the platform.

***

## Overview

```
Institution                          Third Party (Signer)
     │                                       │
     │  1. Create Document Type              │
     │  2. Upload PDF (/files)               │
     │  3. Create Document                   │
     │  4. Register Signer                   │
     │  5. Link Signer → Document ──────────►│
     │                                       │  6. Signer receives email
     │                                       │  7. Signer clicks link & signs
     │  8. Poll signature status ◄───────────│
     │  9. Sign institutionally (cert)       │
     │ 10. Download signed PDF               │
```

***

## Step-by-step

### 1 — Create a Document Type

Document types define the template for a category of documents, including the indexer fields (metadata fields for classification).

```bash theme={null}
curl -X POST https://api.dokstamp.com/document-types \
  -H "Authorization: Bearer {TOKEN}" \
  -H "X-Tenant: {TENANT}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Service Agreement",
    "signed_by_third": true,
    "multiples_third_signers": false,
    "indexers": [
      { "indexer": "Client Name", "rule": "Outro" },
      { "indexer": "Client CPF",  "rule": "CPF" },
      { "indexer": "Client Email","rule": "E-mail" }
    ]
  }'
```

The `indexers` array defines custom metadata fields for documents of this type. The `rule` field validates the input: `"Outro"` (any text), `"CPF"` (Brazilian tax ID), `"E-mail"` (email address).

***

### 2 — Upload the PDF

```bash theme={null}
curl -X POST https://api.dokstamp.com/files \
  -H "Authorization: Bearer {TOKEN}" \
  -H "X-Tenant: {TENANT}" \
  -H "Accept: application/json" \
  -F "files[]=@contract.pdf"
```

Save the returned `uuid` as `file_uuid`.

***

### 3 — Create the Document

```bash theme={null}
curl -X POST https://api.dokstamp.com/documents \
  -H "Authorization: Bearer {TOKEN}" \
  -H "X-Tenant: {TENANT}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Service Agreement — Acme Corp",
    "document_type_id": 1,
    "module_id": 2,
    "department_id": 3,
    "file_uuid": "{FILE_UUID}",
    "indexers": ["Acme Corp", "123.456.789-00", "contact@acme.com"]
  }'
```

<Warning>
  The `indexers` array values must be in the **same order** as the indexers defined in the Document Type. The API maps them positionally to their configured fields.
</Warning>

***

### 4 — Register the Signer

Signers are third-party individuals who need to sign the document. They are identified by name, email, and CPF (Brazilian tax ID).

```bash theme={null}
curl -X POST https://api.dokstamp.com/signers \
  -H "Authorization: Bearer {TOKEN}" \
  -H "X-Tenant: {TENANT}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Carlos Oliveira",
    "document": "12345678900",
    "email": "carlos@acme.com"
  }'
```

Use `GET /signers?where[user][email]=carlos@acme.com` first to avoid creating duplicate records.

***

### 5 — Link the Signer to the Document

This step both links the signer and **triggers the signature request email** automatically. This endpoint is **public** — no `Authorization` header is required.

```bash theme={null}
curl -X POST https://api.dokstamp.com/documents/{doc_id}/signers/{signer_id}
```

The signer receives an email with a secure link to view and sign the document electronically.

***

### 6 — Check Signature Status

Poll the document detail endpoint to check whether all signatures have been collected:

```bash theme={null}
curl https://api.dokstamp.com/documents/{doc_id}?includes[signatures]=1 \
  -H "Authorization: Bearer {TOKEN}" \
  -H "X-Tenant: {TENANT}" \
  -H "Accept: application/json"
```

The `signatures` array in the response shows the status of each signer:

```json theme={null}
{
  "data": {
    "uuid": "d4e5f6a7-b8c9-0123-defg-234567890123",
    "description": "Service Agreement — Acme Corp",
    "signatures": [
      {
        "user": { "name": "Carlos Oliveira" },
        "signed": true
      }
    ]
  }
}
```

`"signed": true` means the signer has completed their signature. `false` means pending.

***

### 7 — Sign Institutionally

Once third-party signatures are collected, sign the document with the institution's digital certificate:

```bash theme={null}
curl -X POST https://api.dokstamp.com/documents/{doc_id}/sign/{cert_id} \
  -H "Authorization: Bearer {TOKEN}" \
  -H "X-Tenant: {TENANT}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{ "pin": "123456" }'
```

The `cert_id` refers to the institutional digital certificate configured in the platform. The `pin` is the certificate's PIN protection code.

***

### 8 — Download the Signed PDF

```bash theme={null}
curl https://api.dokstamp.com/files/{file_uuid}/download \
  --output signed-contract.pdf
```

This endpoint is **public** — no authentication required. Share the UUID with the signer or store the link in your system.

***

## Batch operations

For high-volume scenarios, batch endpoints are available:

| Endpoint                                  | Purpose                                                            |
| ----------------------------------------- | ------------------------------------------------------------------ |
| `POST /documents/signatures/batch/resend` | Resend signature request emails to multiple signers                |
| `POST /documents/batch/sign/{cert_id}`    | Sign multiple documents at once with the institutional certificate |

***

## Resending signature requests

If a signer did not receive or lost the email:

```bash theme={null}
curl -X POST https://api.dokstamp.com/documents/{doc_id}/signers/{signer_id}/signatures/resend \
  -H "Authorization: Bearer {TOKEN}" \
  -H "X-Tenant: {TENANT}" \
  -H "Accept: application/json"
```