Skip to main content

​
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). 
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

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

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"]
  }'
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.

​
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). 
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.
This step both links the signer and triggers the signature request email automatically. This endpoint is public — no Authorization header is required. 
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: 
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: 
{
  "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: 
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

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:
EndpointPurpose
POST /documents/signatures/batch/resendResend 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: 
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"