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--
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": {}
}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 |
| type | String | 20 | No | Envelope type | |
| folder | String | 30 | No | Envelope folder name | |
| 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 | 40 | 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 |
| 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 #
List of rules:
{
"rules": {
"emailFinal": "employer@company.com",
"emailFrom": "employer@anasoft.com",
"emailMessage": "E-mail additional message",
"emailTo": "customer@company.com",
"guiAutoEnvelopeSubmit": false,
"guiAutoSubmit": false,
"guiOneButton": false,
"guiOpenSignature": false,
"guiReadRequired" : true,
"guiRemoteQRCodeEnabled": false,
"guiRequestSignerName": false,
"guiSignatureNumber": 1,
"guiSignerName": "John Doe",
"lang": "en",
"mouseSignature": true,
"nameFrom": "Employer",
"notificationExpiration": true,
"openOtpCode": "1234",
"openOtpEmail": "customer@company.com",
"openOtpPhone": "+421905123456",
"resulturl": "https://signatus.com",
"sendInfo": "https://sts.signatus.sk/STSTest/info",
"sendInfo.user": "https://sts.signatus.sk/STSTest/info",
"signAnywhereEnabled": true,
"signOtpCode": "1234",
"signOtpEmail": "customer@company.com",
"signOtpPhone": "+421905123456"
}
}Rules description :
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",| Rule name | Value | Description |
| emailFinal | Email to which signed documents will be delivered. It is possible to use multiple addresses separated by semicolons | |
| emailFrom | Sender email | Senders’ email. Mandatory if emailTo rule is used |
| emailMessage | message | Additional email message |
| emailTo | Signer email | Signers’ email to which signature Request email will be delivered. |
| guiAutoEnvelopeSubmit | true | Automatically submits the envelope after the signing is completed |
| guiAutoSubmit | true | Automatically submits the document after the signing is completed |
| guiOneButton | true | Only one button is visible during the signing process |
| guiOpenSignature | true | Automatically opens the signature modal window when the document is loaded |
| guiReadRequired | true | If the document is mandatory to read (method : read) user have to scroll to the bottom of the document. Default is false . |
| guiRemoteQRCodeEnabled | false | Disable “Switch to mobile” functionality |
| guiRequestSignerName | true | Parameter for enabling the input for signer name |
| guiSignatureNumber | number | Specifies the exact number of signatures required in the document. |
| guiSignerName | Signer name | Predefined value for signer name, max 40 characters. If guiRequestSignerName is enabled, signer name can by changed by signer |
| lang | sk, cs, en, ro, uk, pl, pt, hu | Language of GUI, email and SMS template: – sk : Slovak – cs : Czech – en : English – pl : Polish – ro : Romanian – uk : Ukrainian – pt : Portuguese – hu : Hungarian If the rule is not set, Slovak as a default language is used. |
| mouseSignature | false | Disable signing with the mouse. |
| nameFrom | Sender name | Senders’ name, that will be used in the email templates |
| notificationExpiration | true | Enable email reminder. Sends an email if the process is not signed and the expiration time occurs in 2 days. The email is sent to emailTo address |
| openOtpCode | code | The code that will secure access to the documents. |
| openOtpEmail | Signer email | Signers email to which the one-time password for accessing the document will be delivered. Per signatureReuqest only 3 OTP codes can be sent. After that signatureReuqest is blocked and new one must be created. Signer has 3 attempts to insert correct OTP, after that OTP is blocked and new OTP must be sent. |
| openOtpPhone | Signer phone | Signers’ phone number to which the one-time password for accessing the documents will be delivered. International phone format is required. Allowed country prefixes are: +43, +32, +359, +357, +420, +49, +45, +372, +34, +358, +33, +30, +385, +36, +353, +39, +371, +352, +370, +356, +31, +48, +351, +40, +46, +386, +421, +380 Assumption: to use SMS OTP, you must buy signature Request package with SMS. Per signatureReuqest only 3 OTP codes can be sent. After that signatureReuqest is blocked and new one must be created. Signer has 3 attempts to insert correct OTP, after that OTP is blocked and new OTP must be sent. |
| resulturl | url | URL to redirect the browser after finishing the signing process |
| sendInfo | url | URL of the service where Signatus sends information after the envelope is finished. |
| sendInfo.user | url | URL of the service where Signatus sends information after the process is finished. |
| signAnywhereEnabled | false | Disable sign anywhere function |
| signOtpCode | code | The code that will be used to sign the decuments |
| signOtpEmail | Signer email | Signers email to which the one-time password for signing the document will be delivered. OTP signature requires signature acrofield. Per signatureReuqest only 3 OTP codes can be sent. After that signatureReuqest is blocked and new one must be created. Signer has 3 attempts to insert correct OTP, after that OTP is blocked and new OTP must be sent. |
| signOtpPhone | Signer phone | Signers’ phone number to which the one-time password for signing the document will be delivered. OTP signature requires signature acrofield. International phone format is required. Allowed country prefixes are: +43, +32, +359, +357, +420, +49, +45, +372, +34, +358, +33, +30, +385, +36, +353, +39, +371, +352, +370, +356, +31, +48, +351, +40, +46, +386, +421, +380 Assumption: to use SMS OTP, you must buy signature Request package with SMS. Per signatureReuqest only 3 OTP codes can be sent. After that signatureReuqest is blocked and new one must be created. Signer has 3 attempts to insert correct OTP, after that OTP is blocked and new OTP must be sent. |
Document data #
Additional 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"
}
}
]
}
]
}Document data description
| Name | Value | Description |
| allowedFields | JSON Object | Configuration of which AcroFields will be allowed during signing. |
| allowedFields.key | String | Acrofield type. Allowed values : – TEXT, – CHECKBOX – SIGNATURE – RADIO – COMBOBOX |
| allowedFields.value | JSON Array | AcroField names |
| fieldConfig | JSON Array | Array of JSON object that describe, how the value will be set to acrofield, and and read only possibility |
| fieldConfig.name | String | AcroField name |
| fieldConfig.value | String | Acrofield value |
| fieldConfig.readOnly | boolean | AcroField read only flag |
| ignoreRequired | JSON Array | Array of strings that describes, which type of acrofields are not required to be fill in. Allowed values : – TEXT, – CHECKBOX – SIGNATURE – RADIO – COMBOBOX |
| fieldsBeforeSigning | String | PDF acrofields manipulation before pdf signing – flatten : acrofields are destroyed – readOnly : acrofields are set to read only mode – keep : acrofields mode are not changed Default : flatten |
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"
}
}Error response example :
{
"message": "err.envelope.create",
"value": "sigtype value not allowed, sigtype is error"
}