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.

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.

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.

Party signature types

While the document is in draft, each party can only have signature coordinates configured. The visible signature type is chosen by the party at signing time.

Type	Value	Description
Stamp	`stamp`	Renders the DokStamp digital stamp (gov.br-style layout) at the party coordinates.
Image	`image`	Uses an image uploaded by the party as the visible signature at the party coordinates.

Configure coordinates on create or update (draft only)

PATCH /v1/documents/{document_uuid}/parties/{party_uuid}
{
  "signature_coordinates": {
    "x": 30,
    "y": 400,
    "width": 250,
    "height": 52,
    "page": 2
  }
}

signature_type and signature_image_file_uuid are not accepted on this endpoint.
Confirmation only requires all parties to have valid coordinates.

Choose the type when signing

The party sends the type together with the security code on the public sign endpoint:

POST /v1/documents/sign?token={ACCESS_TOKEN}
Content-Type: multipart/form-data

security_token=ABC1234
signature_type=image
signature_image=@signature.png

For stamp signatures, use application/json or multipart/form-data without a file:

POST /v1/documents/sign?token={ACCESS_TOKEN}
Content-Type: application/json

{
  "security_token": "ABC1234",
  "signature_type": "stamp"
}

signature_type is required (stamp or image).
signature_image is required when signature_type is image (PNG, JPEG, or WebP).
signature_image cannot be sent when signature_type is stamp.
The endpoint uploads the image internally; POST /files is not required.

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:

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:

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"

Getting Started

Core Concepts

Authentication

Institutions

Organizations

Courses

Modules

Students

Enrollments

Certificates

Certificate Templates

Files

Guides

Integration Guide

Document Signing Workflow

Document Signing Workflow

Overview

Step-by-step

1 — Create a Document Type

2 — Upload the PDF

3 — Create the Document

4 — Register the Signer

5 — Link the Signer to the Document

6 — Check Signature Status

Party signature types

Configure coordinates on create or update (draft only)

Choose the type when signing

7 — Sign Institutionally

8 — Download the Signed PDF

Batch operations

Resending signature requests

​Document Signing Workflow

​Overview

​Step-by-step

​1 — Create a Document Type

​2 — Upload the PDF

​3 — Create the Document

​4 — Register the Signer

​5 — Link the Signer to the Document

​6 — Check Signature Status

​Party signature types

​Configure coordinates on create or update (draft only)

​Choose the type when signing

​7 — Sign Institutionally

​8 — Download the Signed PDF

​Batch operations

​Resending signature requests

Document Signing Workflow

Overview

Step-by-step

1 — Create a Document Type

2 — Upload the PDF

3 — Create the Document

4 — Register the Signer

5 — Link the Signer to the Document

6 — Check Signature Status

Party signature types

Configure coordinates on create or update (draft only)

Choose the type when signing

7 — Sign Institutionally

8 — Download the Signed PDF

Batch operations

Resending signature requests