API Documentation

Create and manage electronic signature documents programmatically with the ItaSign REST API

Get Started Free View Endpoints

Perché le Nostre API?

API RESTful

Endpoint REST semplici e prevedibili con metodi HTTP standard

Documentazione Completa

Documentazione API interattiva con esempi di codice live

SDK Multipli

SDK ufficiali per Python, Node.js, PHP e .NET

Supporto Webhook

Notifiche in tempo reale per eventi sui documenti

Nessun Limite

Chiamate API illimitate per tutti i clienti

Gratis per Sviluppo

Testa con firme SES/AdES gratuite prima di andare in produzione

Guida Rapida

Create an API Key

Go to your Organization Settings and create a new API key with 'documents:create' and 'documents:read' permissions

Upload Your PDF

Convert your PDF to base64 or upload it to storage first

Create & Send Document

Use POST /api/v1/documents with your PDF and signers. Set send: true to send immediately, or send: false to save as draft

Monitor Status

Poll the /api/v1/documents/{id}/status endpoint to track signing progress

API Endpoints

Browse all available API endpoints

Base URL:https://itasign.com

Authentication

All API requests require authentication using an API key. Include your API key in the request headers:

X-API-Key: your_api_key_here

# or

Authorization: Bearer your_api_key_here

Generate API keys from your organization settings page.

Documenti

POST/api/v1/documents

Create a document with auto-signature (no predefined signature fields). Signers draw their signature when they open the document.

API Key required

Parameters

titlestring (required) - Document title

filestring (required) - Base64 encoded PDF or storage path

file_typestring (optional) - "base64" (default) or "storage_path"

signersarray (required) - Array of signer objects (at least one)

signers[].namestring (required) - Signer full name

signers[].emailstring (optional) - Email address for notifications

signers[].signing_ordernumber (optional) - Order of signing

sendboolean (optional) - true to send immediately, false for draft (default)

messagestring (optional) - Custom message for signers

signature_levelstring (optional) - "ses" (default), "ades", "ades_t"

verification_modestring (optional) - "standard", "email_otp", "sms_otp", "in_person"

external_referencestring (optional) - Your external reference ID

redirect_urlstring (optional) - URL to redirect after signing

Example

// Create and send immediately
{
  "title": "Service Agreement",
  "file": "JVBERi0xLjQK...", // base64 PDF
  "signers": [
    {
      "name": "Mario Rossi",
      "email": "[email protected]"
    }
  ],
  "send": true,
  "message": "Please sign this agreement."
}

// Response:
{
  "success": true,
  "document": {
    "id": "abc-123",
    "title": "Service Agreement",
    "status": "pending"
  },
  "signers": [{
    "id": "signer-1",
    "name": "Mario Rossi",
    "email": "[email protected]",
    "signing_url": "https://itasign.com/sign/xyz789"
  }]
}

POST/api/v1/documents/{id}/send

Send a draft document for signing. Notifies all signers via email.

API Key required

Parameters

idstring (required) - Document ID

Example

Response:
{
  "success": true,
  "document": {
    "id": "abc-123",
    "status": "pending"
  },
  "notified_count": 2
}

POST/api/v1/documents/from-template

Create a new document from a template with pre-filled data

API Key required

Parameters

template_slugstring (required) - Template slug identifier

titlestring (optional) - Document title

external_referencestring (optional) - Your external reference ID

signersarray (required) - Array of signer objects. Each signer requires at least ONE identifier, but multiple identifiers are RECOMMENDED

signers[].rolestring (required) - Role name from template

signers[].namestring (required) - Signer full name

signers[].emailstring (optional) - Email address (recommended for notifications)

signers[].phone_numberstring (optional) - Phone number (requires country_code)

signers[].country_codestring (optional) - ISO country code (e.g., +39, +1)

signers[].unique_identifierstring (optional) - Tax code, DB ID, or other identifier

signers[].identifier_typestring (optional) - Type of unique identifier (e.g., tax_code, db_id)

dataobject (optional) - Key-value pairs for field substitution

redirect_urlstring (optional) - URL to redirect after signing

Example

{
  "template_slug": "privacy-consent",
  "title": "Privacy Consent - Mario Rossi",
  "external_reference": "patient-123",
  "signers": [
    {
      "role": "patient",
      "name": "Mario Rossi",
      "email": "[email protected]",
      "phone_number": "3401234567",
      "country_code": "+39",
      "unique_identifier": "RSSMRA80A01H501U",
      "identifier_type": "tax_code"
    },
    {
      "role": "witness",
      "name": "Luigi Bianchi",
      "phone_number": "3331234567",
      "country_code": "+39"
    },
    {
      "role": "guardian",
      "name": "Anna Verdi",
      "email": "[email protected]",
      "unique_identifier": "VRDNNA85M45F205K",
      "identifier_type": "tax_code"
    }
  ],
  "data": {
    "firstName": "Mario",
    "lastName": "Rossi",
    "address": "Via Roma 1, Milano"
  },
  "redirect_url": "https://yourapp.com/success"
}

GET/api/v1/documents/{id}/status

Get document status and signer progress

API Key required

Parameters

idstring (required) - Document ID

Example

Response:
{
  "success": true,
  "documentId": "abc-123",
  "status": "partially_signed",
  "signerStatuses": [
    {
      "id": "signer-1",
      "name": "Mario Rossi",
      "email": "[email protected]",
      "phone_number": "3401234567",
      "country_code": "+39",
      "unique_identifier": "RSSMRA80A01H501U",
      "identifier_type": "tax_code",
      "status": "signed",
      "signingOrder": 1,
      "signedTime": "2025-12-26T10:00:00Z"
    },
    {
      "id": "signer-2",
      "name": "Luigi Bianchi",
      "phone_number": "3331234567",
      "country_code": "+39",
      "status": "viewed",
      "signingOrder": 2
    },
    {
      "id": "signer-3",
      "name": "Anna Verdi",
      "email": "[email protected]",
      "unique_identifier": "VRDNNA85M45F205K",
      "identifier_type": "tax_code",
      "status": "pending",
      "signingOrder": 3
    }
  ],
  "createdAt": "2025-12-26T09:00:00Z",
  "expiresAt": "2025-12-27T09:00:00Z"
}

POST/api/v1/documents/{id}/void

Void/cancel a document to prevent further signing

API Key required (documents:create permission)

Parameters

idstring (required) - Document ID

reasonstring (optional) - Reason for voiding

Example

Request:
{
  "reason": "Document no longer needed"
}

Response:
{
  "success": true,
  "document": {
    "id": "abc-123",
    "status": "voided",
    "voided_at": "2025-12-26T12:00:00Z"
  }
}

GET/api/v1/documents/{id}/download

Download signed document in PAdES (PDF) or CAdES (P7M) format. Only available for completed documents.

API Key required (documents:download permission)

Parameters

idstring (required) - Document ID

formatstring (optional) - "pades" (default) returns PDF, "cades" returns P7M

Example

# Download as PAdES (PDF)
curl -H "X-API-Key: itasign_xxx" \
  "https://itasign.com/api/v1/documents/abc-123/download" \
  -o document.pdf

# Download as CAdES (P7M)
curl -H "X-API-Key: itasign_xxx" \
  "https://itasign.com/api/v1/documents/abc-123/download?format=cades" \
  -o document.pdf.p7m

# Response Headers (PAdES):
Content-Type: application/pdf
Content-Disposition: attachment; filename="Document Title.pdf"

# Response Headers (CAdES):
Content-Type: application/x-pkcs7-mime
Content-Disposition: attachment; filename="Document Title.pdf.p7m"

Templates

GET/api/v1/templates

List all active templates in your organization

API Key required

Example

Response:
{
  "success": true,
  "templates": [
    {
      "id": "template-1",
      "name": "Privacy Consent",
      "slug": "privacy-consent",
      "description": "Patient privacy consent form",
      "is_active": true,
      "created_at": "2025-12-01T10:00:00Z"
    }
  ]
}

GET/api/v1/templates/{slug}

Get template details by slug

API Key required

Parameters

slugstring (required) - Template slug identifier

Example

Response:
{
  "success": true,
  "template": {
    "id": "template-1",
    "name": "Privacy Consent",
    "slug": "privacy-consent",
    "description": "Patient privacy consent form",
    "signers": [
      {
        "role_name": "patient",
        "signing_order": 1
      },
      {
        "role_name": "organization",
        "signing_order": 2
      }
    ],
    "fields": [
      {
        "field_type": "text",
        "label": "First Name",
        "default_value": "{{firstName}}",
        "is_required": true
      }
    ]
  }
}

Reference

Common values and enumerations

Document Status Values

draftDocument created but not sent for signing

pendingSent and waiting for first signature

partially_signedAt least one signer has signed

completedAll signers have signed

declinedA signer declined to sign

expiredDocument expired before completion

voidedDocument cancelled by creator

Signer Status Values

pendingCreated but not yet notified

notifiedEmail sent to signer

viewedSigner opened the signing link

signedSigner completed signing

declinedSigner refused to sign

Field Types

signatureSignature capture field

initialInitial/paraph capture field

textText input field

dateDate input field

Signer Identifiers

Each signer must have at least one identifier, but providing multiple identifiers is strongly recommended:

emailEmail address for notification and identification

phone_number + country_codePhone number with ISO country code (e.g., +39, +1)

unique_identifierTax code, DB ID, national ID, or other unique identifier

Best Practice:

Provide all available identifiers (email + phone + unique_identifier) for each signer. This enables multiple contact methods, better tracking, and fallback options if one method fails.

Note: If providing phone_number, country_code is required. If providing country_code, phone_number is required.

Template Placeholders

Use placeholders in template field default values to substitute with data from your API request:

# Template field default_value:
"{{firstName}} {{lastName}}"

# API request data:
{"firstName": "Mario", "lastName": "Rossi"}

# Result:
"Mario Rossi"

Tipi di Firma

Scegli il livello di firma giusto per la tua integrazione

SES

Firma Elettronica Semplice

Free unlimited signatures

AdES

Firma Elettronica Avanzata

Free with cryptographic certificates

AdES-T

AdES with Timestamp

€0.25/doc - Long-term validity

QES

Firma Elettronica Qualificata

€0.35/doc - Maximum legal value

Hai Bisogno di Aiuto?

Consulta la nostra documentazione o contatta il nostro team di supporto.

Contatta il Supporto Comunità e Supporto