---
title: "Integration Guide"
description: "Signer Integration Guide: API key authentication and the integration options for your application to use Signer, as a reference for each use case."
canonical: "https://docs.lacunasoftware.com/en-us/articles/signer/integration-guide"
locale: "en"
product: "Signer"
last_updated: "2026-10-22"
---

# Integration Guide

Signer is a web portal of documents that enables digital and electronic signatures as well as the creation of complex document flows. This guide presents the integration options so that your application can make the most of Signer's potential.

> **Tip: New here?**
>
> If this is your first integration, start with [Getting started](https://docs.lacunasoftware.com/en-us/articles/signer/get-started), which takes you from zero to your first signed document in about 15 minutes. This guide serves as a reference for the use cases.

## Authentication

All API calls demand one API Key in order to communicate with Signer. This key must be placed in the header of all requests:

```javascript
X-Api-Key: your-application|xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

Every API Key is associated with an Organization previously registered in Signer. Therefore, the scope of this key is **restricted to that organization**, that key will only allow you to access/create documents from that same organization.

> **Note**
>
> To get an API key: if you have permission to create applications in the organization, create an application under **Applications** and generate the key with its **Keys** button, as shown in [Getting started](https://docs.lacunasoftware.com/en-us/articles/signer/get-started#step-1-create-the-application-and-the-api-key). Otherwise, ask your instance administrator for one.

## Client libraries

Lacuna publishes a client library of the API for .NET, Java, Node.js and PHP. You create the client with the URL of your Signer instance and the API key, and call the APIs through its methods. You can also call the REST API directly from any language, as [Getting started](https://docs.lacunasoftware.com/en-us/articles/signer/get-started) does with curl.

| Language | Package | Version | Install |
| --- | --- | --- | --- |
| .NET (.NET Framework 4.5 or later, .NET Standard 2.0) | [`Lacuna.Signer.Client`](https://www.nuget.org/packages/Lacuna.Signer.Client) | 1.24.0 | `dotnet add package Lacuna.Signer.Client` |
| Java | [`com.lacunasoftware.signer:signer-client`](https://central.sonatype.com/artifact/com.lacunasoftware.signer/signer-client) | 2.14.0 | Gradle: `implementation 'com.lacunasoftware.signer:signer-client:2.14.0'` |
| Node.js | [`signer-node-client`](https://www.npmjs.com/package/signer-node-client) | 1.1.0 | `npm install signer-node-client` |
| PHP | [`lacuna/signer-client`](https://packagist.org/packages/lacuna/signer-client) | 1.4.10 | `composer require lacuna/signer-client` |

The [samples on GitHub](https://github.com/LacunaSoftware/SignerSamples) use these libraries, with one scenario per use case of this guide. To embed the signing screen in your web page, use the `lacuna-signer-widget` JavaScript library: see [Embedded signature](https://docs.lacunasoftware.com/en-us/articles/signer/embedded-signature).

## How the flow works

In practice, an integration with Signer follows four stages. Each stage has a dedicated page in this guide:

1. **[Create documents](https://docs.lacunasoftware.com/en-us/articles/signer/integration/documents)**: upload the file, assemble the participant flow and (optionally) sign inside your own application.
2. **[Track documents](https://docs.lacunasoftware.com/en-us/articles/signer/integration/tracking)**: check the status, send reminders and receive webhook notifications.
3. **[Download and list](https://docs.lacunasoftware.com/en-us/articles/signer/integration/download-and-list)**: get the document versions and list documents by different criteria.
4. **[Validate signatures](https://docs.lacunasoftware.com/en-us/articles/signer/integration/validation)**: validate signatures using a validation key or the signed file.

And throughout the document's life you may need **[lifecycle](https://docs.lacunasoftware.com/en-us/articles/signer/integration/lifecycle)** operations: cancel, refuse, pause and resume, submit a new version, delete or restore.

## Use cases

| Use case | What you do |
| --- | --- |
| [Create documents](https://docs.lacunasoftware.com/en-us/articles/signer/integration/documents) | Upload, flow creation, embedded signature, pre-positioning signatures and envelopes (multiple files) |
| [Document field reference](https://docs.lacunasoftware.com/en-us/articles/signer/integration/document-fields) | Look up the participant fields, the identifier types and the participant and document options |
| [Track documents](https://docs.lacunasoftware.com/en-us/articles/signer/integration/tracking) | Check document and participant status, send reminders and set up webhooks |
| [Download and list](https://docs.lacunasoftware.com/en-us/articles/signer/integration/download-and-list) | Download the different document versions and list documents |
| [Validate signatures](https://docs.lacunasoftware.com/en-us/articles/signer/integration/validation) | Validate signatures by key or by signed file |
| [Document lifecycle](https://docs.lacunasoftware.com/en-us/articles/signer/integration/lifecycle) | Cancel, refuse, pause and resume, submit a new version, delete and restore |
| [Contacts and identifiers](https://docs.lacunasoftware.com/en-us/articles/signer/integration/contacts) | Manage the organization's contacts and a user's identifiers |

## Error responses

The APIs answer with these HTTP status codes:

| Code | Meaning |
| --- | --- |
| `200` (OK) | Request processed. The response body depends on the API: see its entry in the [API reference](https://www.dropsigner.com/swagger). |
| `400` (Bad Request) | Syntax error, for instance a required field that was not sent. |
| `401` (Unauthorized) | The API key was not sent or is invalid. |
| `403` (Forbidden) | The API key is valid, but its application does not have permission for the requested operation. |
| `422` (Unprocessable Entity) | API error, for instance an entity ID that is not found. The body is an `ErrorModel`. |

An `ErrorModel` has three fields:

| Field | Type | Content |
| --- | --- | --- |
| `code` | string | The error code. Test this field in your code, not the message. |
| `message` | string | A description of the error. |
| `details` | object, with string values | Additional information about the error. It may be `null`. |

```json
{
    "code": "DocumentNotFound",
    "message": "...",
    "details": null
}
```

The API reference lists the main codes of a `422` response: `CertificateNotFound`, `DocumentNotFound`, `FolderNotFound`, `CpfMismatch`, `CpfNotExpected`, `InvalidFlowAction` and `DocumentInvalidKey`. The list is not comprehensive, and new codes may be added at any time without notice, so handle codes you do not know. Other pages describe the codes of their operations, such as `DocumentHasNoSignatures` when [downloading a version](https://docs.lacunasoftware.com/en-us/articles/signer/integration/download-and-list#when-a-version-cannot-be-downloaded).

## Useful Links

* [API Reference (Swagger)](https://www.dropsigner.com/swagger)
* [GitHub Examples](https://github.com/LacunaSoftware/SignerSamples)
* [Embedded signature (Widget)](https://docs.lacunasoftware.com/en-us/articles/signer/embedded-signature)
* [Webhooks](https://docs.lacunasoftware.com/en-us/articles/signer/webhooks)

**Demos and samples**

- Generate a document from a PDF form template and CSV data: [Java](https://github.com/LacunaSoftware/SignerSamples/blob/master/java/console/src/main/java/com/lacunasoftware/signer/sample/scenarios/GenerateDocumentWithTwoOrMoreSignersScenario.java) · [PHP](https://github.com/LacunaSoftware/SignerSamples/blob/master/php/Scenarios/GenerateDocumentWithTwoOrMoreSignersScenario.php)
- List saved document flows: [Node.js](https://github.com/LacunaSoftware/SignerSamples/blob/master/nodejs/scenarios/listDocumentScenario.ts)