2.2 Create signature request

Create signature Request is the most important API Service, that allows the uploaded document to be signed and register new signing request together with definition signing process parameters.

Create signature Request can be used in following cases (more details can be found in chapter 4 Use cases):

Upload new document (content of the document in base 64 format) in case of the first round of signing
Link to document ID in case of other rounds of signing

Service specifications:

URL	https://apidev.okdokument.com/JSON/signatureRequest
Method	POST
Authentication	Authentication set header x-api-key
Content Type	application/json
Request body	data in JSON format – see table below
Response	HTTP status 200 when successful

Example for the upload of a new document:

{
    "resulturl": "https://okdokument.com",
    "filedata": {
        "content": "xyz_JVBERi0xLjc=="
    }
}

Example of an existing document:

{
    "resulturl": "https://okdokument.com",
    "id": "y7Ki_u1mrUwijfb-o_S1JiphSsoXya8iypH380F",
    "allowedFields": {
        "SIGNATURE": "_SO1_"
    }
}

Key	Format	Required	Default value	Description
resulturl	String	No	OKdokument ThankYou page	URL to redirect the browser after finishing the signing process
filedata	JSON Object	Yes, if document upload is need		JSON Object of PDF file
filename	String	No		Name of the document. This parameter is mandatory if you want to do the file conversion to PDF format. For conversion the file postfix must be: contract.doccontract.docxcontract.xlscontract.xlsx Name of the document with PDF postfix is also used in the email template.
content	base64 String	Yes		The binary content of the uploaded PDF file in base64 format. https://base64.guru/converter/encode/file Maximal document size is 10 MB Parameter content can be also called with $content.
state	String	No	tosign	The state of the document: tosign – document ready for signingtags – pre-processing document, searching for tags and inserting signature acrofields. After inserting signature acrofields, document changes state to tosign.tostamp – pre-processing document, inserts digital stamp into document
sendInfoURL	String	No		Info service provider by Portal application used for backed to backed communication after the document is submitted as signed or cancelled.
allowedFields	JSON ARRAY	No	[]	Defines acrofields that are allowed in document “allowedFields” : {“SIGNATURE” : “_SO1_”}
changeState	String	No		Used to change state after finishing the round of signing: tosign
id	String	Yes, if document is preloaded		Preloaded document id, used in the second round of signing, when the document is already in OKdokument temporary storage. When parameter id is filled, parameter filedata must be empty.
rules	String	No		All rules are described in the table below
sigData	JSON object	No	{}	Parameter for storing secret information into encrypted part of signature directly in PDF structure. “sigData” : {“systemId”:“1234567″, “email”:”johnsmith@gmail.com”}

Example of combigning rules:

{
  "rules": {
    "guiSignerName": "John Smith",
    "guiRequestSignerName": false,
    "signAnywhereEnabled": false
  }
}

Rule name	Parameter	Description
signAnywhereEnabled	false	Parameter for disabling sign anywhere function
guiRequestSignerName	true	Parameter for enabling the input for signer name
guiSignerName	Signer name	Predefined value for signer name, max 40 characters. If guiRequestSignerName is enabled, signer name can by changed by signer
emailTo	Signer email	Signers’ email to which signature Request url will be delivered.
emailFrom	Sender email	Senders’ email. Mandatory if emailTo rule is used
nameFrom	Sender name	Senders’ name, that will be used in the email templates
emailNotification		Rule that enables email reminder. Email reminder sends email every morning at 7:00 for signature requests that are not signed. The email is sent to emailTo and emailFrom – according to signatureRequest configuration.
emailFinal	Signer email	Email to deliver the signed document. If emailFinal is without parameter, the signed document will be sent to emailTo.
openOtpPhone	Signer phone	Signers’ phone number to which the one-time password for accessing the document 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.
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.
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.
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.
lang	sk, cs, en, ro, uk, pl, pt, hu	Language of email and SMS template: sk – Slovakcs – Czechen – Englishpl – Polishro – Romanianuk – Ukrainianpt – Portuguesehu – Hungarian If the rule is not set, Slovak as a default language is used.
mouseSignature	false	Rule for disabling signing with the mouse.
otpCode	number	Predefined code used in combination with openOtp
guiOpenSignature	true	Automatically opens the signature field when the document is loaded
guiAutoSubmit	true	Automatically submits the document after the signing is completed

Create signature Request has also some additional data that are used in the process of signing:

Key	Format	Required	Default value	Description
signatureRequestId	String	No	GUID	Random unique value
state	String	No	tosign;canceled	tosign – sigigning only available where document is in state tosigntosign, cancelled – signing is available also in state cancelled (when signer closes the document, the document can be opened again and signed)signed – used when stamping document (state to stamp in signatureRequest). After stamping document, document changes state to signed
expirationTime	Long	No	actual time + 24 hours	signature Request ID expiration time. Time in Milliseconds since Jan 1, 1970 00:00:00 UTC
fieldConfig	JSON ARRAY	No		Array of JSON object that describe, how the value will be set to acrofields, and set read only option
name	String	Yes		Name of the acrofield
value	String	Yes		Acrofield value
readOnly	Boolean	No	false	If true, acrofield value cannot be change during the signing process. If change is forced in browser value from signatureRequest will be used

Use of all parameters can be found in the 5 Configuration of the signing process.

Success response example

{
    "message": "msg.signature.request.id.created",
    "result": "1d58a59e-e8f7-4d07-bb99-d3fa39cb58a8"    "url": "https://apidev.okdokument.com/openDocument/1d58a59e-e8f7-4d07-bb99-d3fa39cb58a8",
    "documentId": "y7Ki_u1mrUwijfb-o_S1JiphSsoXya8iypH380F"}

When a request is made, OKDokument API Server validates the content of the data parameter request. When a problem is detected, it returns the status of HTTP 400/500 and a report of the problem found in the body of the response in JSON format.

Error response Body Example:

{    "message": "err.json.syntax"}

Or

{    "message": "err.missing.required",
    "result": "1d58a59e-e8f7-4d07-bb99-d3fa39cb58a8"}

Data parameter validation description:

Parameter name	Validation description	Message
state	Allowed range	err.signature.request.state
id	Required attribute	err.missing.required.attribute
id	Document	err.signature.request.documentid
id	Document state	err.invalid.document.state
resulturl	Format	err.signature.request.resulturl
expirationTime	Format	err.signature.request.expirationTime.format
expirationTime	Allowed range	err.signature.request.expirationTime
fieldsBeforeSigning	Allowed range	err.signature.request.fieldsBeforeSigning
fieldConfig	Format	err.signature.request.fieldConfig

Updated on 31/03/2025

1. API concept

2. Core API services

3. Additional API services

4. Use cases

5. Configuration of the signing process

2.2 Create signature request