Create envelope

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.

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	Description
dataText	text	Envelope metadata in JSON format
data	file	Envelope metadata in JSON format. 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.
file1-n	file	Envelope documents. Document assignment to the process is done via the reference attribute described in table below

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--

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",
	"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": {}
}

{
	"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": {}
}

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 – draft : only envelope draft is created – 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		Envelope name
email	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	{}	The signing process can be configured using rules 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

Rules #

All possible rules are described in chapter Rules

Relevant rules can only be assigned to a specific process using the dot notation {ruleName}.{signer}. Where signer is the value from processes.signer attribute. For example :

"emailTo.user": "customer1@company.com",
"emailTo.user2": "customer2@company.com",

"emailTo.user": "customer1@company.com",
"emailTo.user2": "customer2@company.com",

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"
					}
				}
			]
		}
	]
}

{
	"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": "9ec82484-8af0-45ef-9c52-c80895905379",
    "userId": "demo.api",
    "state": "ready",
    "envelopetypeid": 4,
    "expirationtime": 1830395240000,
    "extension": {},
    "processes": [
        {
            "id": "48a1aa4f-7951-40e4-9869-50c481e36ad2",
            "userId": "demo.api",
            "envelopeid": "9ec82484-8af0-45ef-9c52-c80895905379",
            "signer": "user",
            "state": "ready",
            "extension": {},
            "sigtype": "bio",
            "envelopetypeid": 4,
            "tenant": "demo",
            "rules": {}
        }
    ],
    "type": "menu1",
    "product": [],
    "contact": {},
    "tenant": "demo",
    "rules": {
        "lang": "en",
        "resulturl": "https://signatus.com"
    }
}

{
    "id": "9ec82484-8af0-45ef-9c52-c80895905379",
    "userId": "demo.api",
    "state": "ready",
    "envelopetypeid": 4,
    "expirationtime": 1830395240000,
    "extension": {},
    "processes": [
        {
            "id": "48a1aa4f-7951-40e4-9869-50c481e36ad2",
            "userId": "demo.api",
            "envelopeid": "9ec82484-8af0-45ef-9c52-c80895905379",
            "signer": "user",
            "state": "ready",
            "extension": {},
            "sigtype": "bio",
            "envelopetypeid": 4,
            "tenant": "demo",
            "rules": {}
        }
    ],
    "type": "menu1",
    "product": [],
    "contact": {},
    "tenant": "demo",
    "rules": {
        "lang": "en",
        "resulturl": "https://signatus.com"
    }
}

Error response example :

{
    "message": "err.envelope.create",
    "value": "sigtype value not allowed, sigtype is error"
}

{
    "message": "err.envelope.create",
    "value": "sigtype value not allowed, sigtype is error"
}

Updated on 07/05/2026

Core API Services - Signatus 2

Use Cases - Signatus 2