This section describes how to create an envelope in the Signatus 2 API. An envelope is the main container used to group documents, define recipients, and configure signing or approval steps. Creating an envelope is the first step in initiating a document workflow in Signatus.
This section explains the API calls required to create an envelope, including setting its basic properties, documents, recipients, and workflow configuration.
Create envelope is the most important API Service, that allows upload documents and envelope metadata.
Signatus 2 URL #
| Environment | URL |
| INT | https://signatus.ana.sk/app |
| PROD | https://app.signatus.com |
Service specifications #
| URL | /api/envelope |
| Method | POST |
| Authentication | Bearer access token |
| Content Type | multipart/form-data |
| Response type | application/json |
Request description #
Request parameters:
| Key | Type | Required | Description |
| dataText | text | One of dataText/data | Envelope metadata serialized as JSON text. |
| data | file | One of dataText/data | File containing the envelope metadata JSON.. You can use the dataText parameter to send metadata as text directly in the request, or the data parameter to send metadata as a file. |
| <document key> | file | When reference is used | One or more PDF files. The multipart field name must equal documents[].reference. |
HTTP- Click to view HTTP code snippet
POST /app/api/envelope HTTP/1.1
Host: signatus.ana.sk
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJJTGNWSnp4SFkyd1RDcGlLZU5Oa2VmbWZHa1ljUnBtQ1lMMUhsNG13Zm5VIn0.eyJleHAiOjE3NTM5NTIzNzEsImlhdCI6MTc1Mzk1MjA3MSwianRpIjoiYWI1YTJlYmEtNTZkZi00Y2ZkLTkyOGYtMTU3ZWMyYzU1N2RlIiwiaXNzIjoiaHR0cHM6Ly9vYXV0aC5hbmEuc2svcmVhbG1zL1NpZ25hdHVzIiwiYXVkIjoiYWNjb3VudCIsInN1YiI6ImYzYmUxYTY2LTU1M2YtNGFlOC04OTUyLTY3OGQ4NTU2ZDAxYiIsInR5cCI6IkJlYXJlciIsImF6cCI6InNpZ25hdHVzIiwic2lkIjoiYTczMTkzMmItOTAyNC00ZWU5LWFlOTEtNWZlNTJmYWIzNjliIiwiYWNyIjoiMSIsImFsbG93ZWQtb3JpZ2lucyI6WyIvKiJdLCJyZWFsbV9hY2Nlc3MiOnsicm9sZXMiOlsiUk9MRV9QUk9YWSIsImRlZmF1bHQtcm9sZXMtc2lnbmF0dXMiLCJST0xFX1BPUlRBTCIsIlJPTEVfVVNFUiJdfSwicmVzb3VyY2VfYWNjZXNzIjp7ImFjY291bnQiOnsicm9sZXMiOlsibWFuYWdlLWFjY291bnQiLCJtYW5hZ2UtYWNjb3VudC1saW5rcyIsInZpZXctcHJvZmlsZSJdfX0sInNjb3BlIjoicGhvbmUgZ3JvdXBzIHRlbmFudGlkIHByb2ZpbGUgZW1haWwiLCJlbWFpbF92ZXJpZmllZCI6ZmFsc2UsInRlbmFudGlkIjoiZGVtbyIsIm5hbWUiOiJQYXZvbCBQdW5hIiwicHJlZmVycmVkX3VzZXJuYW1lIjoiZGVtby5hcGkiLCJnaXZlbl9uYW1lIjoiUGF2b2wiLCJmYW1pbHlfbmFtZSI6IlB1bmEiLCJlbWFpbCI6InBhdm9sLnB1bmFAYW5hc29mdC5jb20ifQ.PP-jqR34m5dLEzpLNKK0hgk2PM9L3Q2WqR9aZjFRRG7mPZJ538gqlyh9WZU8R33njAjIq6Uo4Ty8qTrwGgRrpqnA8lVRvPnKimLzN8qDmAzBE29JxitQ3AYLC4VFpvp2zU0WTugypE84X1Km3Dd5O8efhDe2M41LNtsaT1ys2Y8qZb6dZVkTOexQ2YAqycCE4TCD1bPXYRQzI2miiuiz2Ik0KK-3ommk7C4JM83jw1ZxZF3ZLka7xmILxKZcHqIkahPDltmF-yxox5yPKIwnbbgvu8M8oqgsZp33fEH-6I4p8jInzymDseYze0O0hDdHzb58aV-cmoDXb5YBQ5VDtQ
Content-Length: 655
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="dataText"
{
"envelopetype": "default",
"state": "ready",
"type": "menu1",
"folder": "Zmluva",
"expirationtime": 1830395240000,
"rules": {
"resulturl": "https://signatus.com",
"lang": "en"
},
"processes": [
{
"signer": "user",
"sigtype": "bio",
"documents": [
{
"method": "write",
"reference": "file1"
}
]
}
],
"extension": {}
}
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="file1"; filename="Signatus2-API/Test.pdf"
Content-Type: application/pdf
(data)
------WebKitFormBoundary7MA4YWxkTrZu0gW--
Example of dataText :
{
"envelopetype": "default",
"name" : "Contract no. 1245726",
"state": "ready",
"folder": "Contract",
"expirationtime": 1830395240000,
"rules": {
"resulturl": "https://signatus.com",
"lang": "en"
},
"processes": [
{
"signer": "user",
"sigtype": "bio",
"documents": [
{
"method": "write",
"reference": "file1"
}
]
}
],
"extension": {}
}Envelope data description:
| Key | Format | Max range | Required | Default value | Description |
| enevlopetype | String | 40 | No | deafult | Envelope type name |
| state | String | 20 | No | ready | Envelope state – ready : envelope is ready for signing – attach : allows the first signer to add an attachment. |
| type | String | 20 | No | Envelope type | |
| folder | String | 30 | No | Envelope folder name | |
| name | String | 80 | No | dd.MM.yyyy HH.mm.ss | Envelope name. Recommended set a descriptive name to make the envelope easy to identify in GUI lists. |
| String | 76 | No | Envelope owner email | ||
| expirationtime | Long | No | Current time + 1 day | Envelope expiration time Format : timestamp in milliseconds since epoch (January 1, 1970, 00:00:00 GMT) | |
| rules | JSON Object | 3000 | No | {} | Optional settings that control how the envelope is delivered, signed and completed, for example notification emails, OTP verification, GUI behavior, language and redirect URL after signing. Rules are described in the Rules chapter |
| extension | JSON Object | 3000 | No | {} | Additional envelope data |
| product | JSON Array | 3000 | No | [] | Additional information about products |
| contact | JSON Object | 3000 | No | {} | Additional information about contact |
| base64 | JSON Object | Yes if referenceBase64 is used in documents section | {} | The binary content of the uploaded PDF file in base64 format. https://base64.guru/converter/encode/file Maximal document size is 10 MB | |
| processes | JSON Array | Yes | Process represents one round of the signing done by specific signer | ||
| processes.signer | String | 76 | No | signer + {position in array} | Signer Id |
| processes.sigtype | String | 10 | No | bio | Signing type – bio : Handwritten signature with dynamic signature characteristics – otp : One time password signing – data : One-Click Approval – qes : Signing with a Qualified Electronic Signature |
| processes.extension | JSON Object | 3000 | No | {} | Additional process data |
| processes.documents | JSON Array | Yes | Documents data for process | ||
| processes.documents.method | String | 10 | No | write | How the document will be processed during signing. – write : Mandatory to signed – read : Mandatory to read – optional : Optional to read – attachment : Added attachment |
| processes.documents.displayName | String | 150 | No | file key from request | Document display name |
| processes.documents.reference | String | Yes if file content is used in request | file key from request | Assigning the document to the process | |
| processes.documents.referenceBase64 | String | Yes if file content is used in base64 attribute | key from base64 JSON object | Assigning the document to the process | |
| processes.documents.data | JSON Object | No | {} | Additional document fields configuration Data are described in the Document data chapter | |
| processes.documents.template | String | 20 | No | Assigning the templates documents to the process |
Document data #
Additional document fields configuration are described in chapter Document fields configuration
Document data example :
{
"processes": [
{
"signer": "user1",
"signing": "document",
"sigtype": "bio",
"documents": [
{
"reference": "file1",
"data": {
"allowedFields": {
"SIGNATURE": [
"SC_signature"
],
"TEXT": [
"TO_text",
"TC_text"
]
},
"fieldConfig": [
{
"name": "TC_text",
"value": "New value"
},
{
"name": "TO_text",
"value": "New readonly value",
"readOnly": true
}
],
"ignoreRequired": [
"SIGNATURE"
],
"fieldsBeforeSigning": "keep"
}
}
]
}
]
}Response description #
| Status code | Description |
| 200 OK | Envelope created successfully. You’ll find the envelope data in the response. |
| 400 Bad Request | When neither data file nor dataText is provided |
| 401 Unauthorized | When user is not authenticated |
| 403 Forbidden | When user lacks required permissions |
| 500 Internal Server Error | Server processing error |
Success response example :
{
"id": "90523892-4bff-42e0-b151-89e967db0658",
"userId": "demo.api",
"created": 1730308840000,
"updated": 1730308840000,
"state": "ready",
"envelopetypeid": 27,
"expirationtime": 1830395240000,
"extension": {},
"processes": [
{
"id": "655daf4d-409d-454f-a566-b8fd92223f50",
"userId": "demo.api",
"created": 1730308840000,
"updated": 1730308840000,
"envelopeid": "90523892-4bff-42e0-b151-89e967db0658",
"signer": "user",
"state": "ready",
"extension": {},
"sigtype": "bio",
"envelopetypeid": 27,
"tenant": "demo",
"user": "demo.api",
"rules": {}
}
],
"type": "menu1",
"folder": "Contract",
"name": "Contract no. 1245726",
"email": "employer@anasoft.com",
"source": "api",
"product": [],
"contact": {},
"tenant": "demo",
"rules": {
"resulturl": "https://signatus.com",
"lang": "en"
}
}Error response example :
{
"message": "err.envelope.create",
"value": "sigtype value not allowed, sigtype is error"
}API envelope limit #
Each user has a limit on the number of envelopes that can be created through the API. The limit applies only to envelopes created with source = api, that is, via POST /api/envelope. Envelopes created in the Signatus web application are not affected.
The current state of the limit can be checked at any time with the Counters service (GET /api/counters):
When envelopesAvailable is 0 or less, a request to create an envelope is rejected and no envelope is created. It is therefore recommended to check envelopesAvailable before sending a large batch of requests.
Return codes of Create envelope :
| Status code | Message | Description |
| 500 Internal Server Error | error.envelopes.api.limit | Envelope metadata |
| 500 Internal Server Error | error.envelopes.maximum.number | The maximum number of envelopes of the user’s package is reached. |
| 500 Internal Server Error | error.envelopes.maximum.size | The maximum total size of stored documents of the user’s package is exceeded. |
Error response example :
{
"message": "error.envelopes.api.limit",
"value": "base",
"tenant": "demo"
}