--- title: Introduction to Signatus 2 API Integration description: Signatus 2 API enables electronic signing to be integrated directly into existing information systems, portals, or business applications. The goal is to allow a business system to create and control signing processes automatically, without requiring users to prepare them manually… url: "https://wiki.signatus.com/documentation/signatus-2-api/introduction-to-signatus-2-api-integration/" updated: "2026-10-08" category: Introduction to Signatus 2 API --- # Introduction to Signatus 2 API Integration Signatus 2 API enables electronic signing to be integrated directly into existing information systems, portals, or business applications. The goal is to allow a business system to create and control signing processes automatically, without requiring users to prepare them manually in the Signatus application. Typical use cases include signing customer contracts, approving documents, signing orders or protocols, and multi-step signing involving several participants. From the integration system's perspective, Signatus is a service that receives documents together with information about **who should sign them, how they should sign them, and how the signing process should behave**. Signatus then handles the signing workflow, interaction with signers, and processing of the final signed documents. ## **Envelope as the Main Business Object** The main object in the API is the **Envelope**. An Envelope represents one complete signing or business case. It contains the documents to be processed, participants in the signing workflow, signing methods, and configuration rules. For example, one Envelope may represent: - a contract signed by one customer, - a contract with multiple attachments, - a document signed by several people in sequence, - a combination of signing and approval, - or a more complex multi-step workflow. An Envelope should therefore be understood as a **digital representation of one signing process**, not only as a container for documents. Inside the Envelope, individual processes define who interacts with the documents and how. A process may represent a customer signature, an employee signature, approval, or another processing step. ## **Basic Integration Flow** From a business perspective, a basic integration consists of the following steps: 1. the integration system authorizes itself against Signatus, 2. it creates an Envelope with documents and participants, 3. Rules define how the signing process should behave, 4. Signatus executes the signing workflow, 5. the integration system receives information about the result, 6. the final signed documents are downloaded. This separates the responsibilities of both systems. The **integration system** manages the business context, such as the customer, contract, order, or internal workflow. **Signatus** manages the signing process, including documents, signers, signing methods, user interaction, and signing results. It is therefore recommended to store both the business identifier and the Signatus Envelope ID so that both systems can be reliably linked. ## **Minimum Integration** A basic production integration can be built around five main areas: **Authorization → Create Envelope → Rules → Info Service → Download Envelope** These components cover the complete lifecycle from creating a signing request to receiving the final signed documents. **1. Authorization** All API communication starts with authentication. The integration application obtains an authorization token and uses it for subsequent Signatus API calls. Authorization should be implemented as a shared infrastructure component rather than separately for every signing process. The integration should handle: - secure storage of credentials, - obtaining the authorization token, - using the token for API requests, - refreshing or obtaining a new token when required. **2. Create Envelope** Creating an Envelope is the central operation of the integration. The integration system sends documents to Signatus and defines the required signing workflow. Conceptually, the request means: “These are the documents to process, these are the participants, and this is how the process should be executed.” An Envelope typically defines: - documents, - participants, - signing methods, - signing order or rounds, - relationships between documents and participants, - an external business reference, - additional process configuration. After creation, Signatus returns an Envelope ID. This ID should be stored by the integration system and used for further API communication. The business identifier and the Signatus Envelope ID should remain separate. For example, the business system may use CONTRACT-2026-001245, while Signatus assigns its own technical Envelope ID. **3. Rules** Rules define how the signing process behaves. While the Envelope describes the documents and participants, Rules configure the workflow around them. Rules can control areas such as: - email notifications, - user interface behaviour, - redirects after signing, - callbacks to the integration system, - additional user verification, - signer-specific behaviour. From an integration perspective, Rules can be treated as **workflow configuration**. This makes it possible to use the same basic Envelope structure for different business scenarios while changing only the required process behaviour. **4. Info Service** Signing is usually asynchronous. A signer may complete the process minutes, hours, or even days after the Envelope is created. The integration system therefore cannot assume that the result will be available immediately. The **Info Service** provides a callback mechanism through which Signatus informs the integration system about the result or relevant status changes. The basic model is: **Integration System → Create Envelope → Signatus → Signing Process → Callback to Integration System** After receiving the callback, the integration system can, for example: - mark a contract as signed, - continue with the next business workflow step, - notify a user, - start document archiving, - download the final documents. The callback endpoint should be implemented reliably and should safely handle repeated notifications. **5. Download Envelope** After the signing process is completed, the integration system can retrieve the final result. Using the API, it can download the completed Envelope and the signed or otherwise processed documents. A typical final step is: 1. identify the completed Envelope, 2. download the resulting documents, 3. store them with the related business record, 4. update the business process status, 5. continue with archiving or further processing. This closes the integration lifecycle. ## **Minimum End-to-End Scenario** The complete minimum scenario can be summarized as: **1. Authorization** The integration system authenticates against Signatus API. **2. Create Envelope** Documents, participants, and the signing workflow are submitted. **3. Rules** The required process behaviour, notifications, redirects, and callbacks are configured. **4. Signing Process** Signatus manages interaction with the signer and executes the signing workflow. **5. Info Service** Signatus informs the integration system about the result. **6. Download Envelope** The integration system downloads the final signed documents and stores them in the related business process. From a business perspective, the principle is simple: **Create a signing case → let Signatus execute the signing process → receive and store the result.** More advanced API features can then extend this basic model with multi-step signing, different signing methods, document fields, advanced authentication, or signer-specific behaviour.