For the example calls we use Postman and curl. If you're not proficient in either, that's okay. Visit our introduction to the API world. The detailed documentation of endpoints will then give you examples of calls in different languages, the logic of calling endpoints will be the same.
When feeling around the API, we recommend starting with the first example where you don't pass a file. Only when you've got it all figured out , jump into the second example. First, just deal with passing the file for signing. Only when you trigger the sending of the signature request emails, add the webhooks for feedback to your application.
- Example 1 - Getting information about the workspace founder
- Example 2 - Submitting a PDF document for signature
- Example 3 - Handing over the model documents
- Example 4 - Getting information about a document
- Example 5 - Obtaining information on the signing status of individual signatories
- Example 6 - Signature in an integrated application
- Example 7 - Invoking Remote Identification
Example 1 - Getting information about the workspace founder
On the Signi production environment https://api.signi.com the workspace isthe workspace is "Demo API" and has API key = and has API key = “71c4123d242bdd38047bee838d17e3367dc3ea6748d0975217ce501e834a224c83cab8afd35c9b0e6ade806b7987fae80f97f5c8253cfbb9089cf21f”, when making your calls, replace this API key with your workspace's API key, which you get by subscribing to the "API Integration" and API Key Generation services.
Use the Authorization > User Detail endpoint to get information about the user setting up the workspace where the documents will be sent.
Description in the documentation
Calling in Postman
The request is of type GET .
The address is https://api.signi.com/api/v1/me .
On the Authorization tab, the API Key is selected as the authorization type and the workspace API key is specified as the x-api-key value and the API key location is selected as Header.
Calling end point User Detail - User Detail in Postman.
Call result
{
"user": {
"email": "aplikace@signi.com"
},
"workspace": {
"name": "iSmlouva marketing"
},
"token": {
"expiration_date": "2030-08-07"
},
"links": {
"tokens": "https://app.ismlouva.cz/api"
}
}Example 2 - Submitting a PDF document for signature
A - Placing signatures at the end of the document
On the Signi production environment https://api.signi.com workspace is "Demo API" and has API key = “71c4123d242bdd38047bee838d17e3367dc3ea6748d0975217ce501e834a224c83cab8afd35c9b0e6ade806b7987fae80f97f5c8253cfbb9089cf21f”, when making your calls, replace this API key with your workspace's API key, which you get by subscribing to the "API Integration" and API Key Generation services.
Use the Create Contract 2.0 > From Document endpoint to submit the PDF document for signature.
In this scenario, a representative of the drafter of the document and the counterparty sign. The workspace creator with the right to draft, approve and sign is the account demo@signi.com. Therefore, this account is used as the proponent's representative in the calls. Change the counterparty's contact information i.e. in the example protistrana@firma.cz to their email when testing, then fill in the final email of the real signing counterparty.
Example:
the placement of signatures at the end of the document is prescribed,
at the same time, the place where the representative of the applicant signs is prescribed. If "In Prague" were specified as "true", the workspace setting would take over,
in this case all sign at the same time, alternatively it is possible to choose that the signatures are signed first by the representatives of the claimant and then by the opposing parties, or that "the order matters", i.e. they sign in the order specified in the call,
the counterparty signs see contract_role: sign, it could also just approve the document, then the signature would not be visible on the document,
if the signatories' phone number is also given, they will also receive a notification SMS and they will not have to enter their phone number to send the verification PIN.
- In this case, if a real representative of the claimant is to sign for the claimant, the user with the email must have been granted access to the workspace in Signi and have been set to sign. Otherwise, the API call will not go through. Alternatively, the proxy users are not Signi users and sign similarly to the counterparties. In that case, alternatively, they are not asked to log into Signi.
- If the proponent's representative would not sign the document, it is not listed in the API call.
- In the Signi UI, when a document is created via the API, the workspace founder is always listed as the author of the document.
Description in the documentation
Calling in Postman
The request is of type POST.
The address is https://api.signi.com/api/v1/contract/, on the Param tab the Type parameter is specified with the value "doc" i.e. the resulting address of the call is https://api.signi.com/api/v1/contract/?type=doc.
On the Authorization tab, API Key is selected as the authorization type and the API key workspace is specified as the x-api-key value and the API key location is selected as Header.
On the Body tab, multipart/form-data is selected as the call type and two keys are listed - data and uploaded_file_key. Note that both of these are of type file, so that files are actually physically transferred to the HTTP request. The first one is JSON with the endpoint call parameters, the second one is the file to sign - PDF or DOC, DOCX, XLS, XLSX, HTML. For each key you need to select the parameter type is File, Click "Select Files" to open the file selection, insert the appropriate one.
Param tab
Autorization tab
Body tab
The keys on the Points tab are of type "File", the file to be sent in the request is selected from your disk and uploaded via "Select Files".
JSON file with call parameters
{
"name": "irrelevant",
"number": "irrelevant",
"locale": "cs",
"settings": {
"signing_order": "all_at_once",
"autosign_proposers": "V Praze",
"missing_positions": "append_to_the_end"
},
"people": [
{
"is_proposer": true,
"email": "aplikace@signi.com",
"first_name": "Johny",
"last_name": "Doe#1",
"contract_role": "sign"
},
{
"is_proposer": false,
"email": "roman.ripa+20210341@signi.com",
"contract_role": "sign",
"person_type": "nature",
"first_name": "John",
"last_name": "Doe#2"
}
],
"file": "uploaded_file_key"
}Yes, we know, such parameter passing is not a pure REST API, we will improve the API in future versions
Call result
As a result, a notification email is sent to the counterparty's address. The End point returns an unambiguous identification of the document in contract_id, which can be used to further retrieve information about the document and its status.
The result of the endpoint call.
What happens after the call
The call in this case will receive a notification email only to the counterparty's representative. After signing, all parties involved receive an email with the signed document and either the webhook specified in the endpoint call is invoked, or the status of the document can be queried by calling the corresponding endpoints repeatedly.
The resulting signed document
The resulting document may look like this, for example:
B - Several documents signed at the same time
If you need to send several documents to be signed at the same time, where for example some documents are signed and others are only approved . e.g. GTC, this is possible via the Attafements section" in the Signi API call.
Call in Postman
More files passed in points when endpoint is called.
JSON file with call parameters
{
"contract_name": "document name - nonmandatory",
"number": "document number - nonmandatory",
"locale": "cs",
"settings": {
"signing_order": "all_at_once",
"missing_positions": "error"
},
"people": [
{
"is_proposer": true,
"email": "demo@signi.com",
"contract_role": "approve"
},
{
"is_proposer": false,
"email": "demo+zakaznik@signi.com",
"contract_role": "sign",
"person_type": "nature",
"first_name": "John",
"last_name": "Doe#2",
"positions": [
{
"x": 50,
"y": 50,
"page": 0
}
]
}
],
"file": "uploaded_file_key",
"attachments": [
{
"people": [
{
"is_proposer": true,
"email": "demo@signi.com",
"contract_role": "approve"
},
{
"is_proposer": false,
"email": "demo+zakaznik@signi.com",
"contract_role": "approve",
"person_type": "nature",
"first_name": "John",
"last_name": "Doe#2"
}
],
"file": "uploaded_file_key2"
}
]
}Passing the second document in JSON, the second one has the key uploaded_file_key2.
Multiple documents in one set when signing.
C - Use of signature fields / placeholders
The DOCX document has a table with columns at the end for each signatory, with 0px line thickness to keep the table out of the document and centering the column.
One or two signers are assumed for each page, so the placeholders signi-signature-0 to signi-signature-3 are in the document.
The field names for the signature/placeholders are inserted in white so that they are not visible in the final document.
For simplicity, the signing scenario below assumes that the proponent only approves and one counterparty representative signs. Therefore, there is only one person with the signi_signature_02 signature field in the JSON. The resulting document with one signature is in the example below. Similarly, you can send a JSON scenario with two, three or four signers to a document.
Attention!!! Meanwhile Signi displays the signature itself, the place and date of the signer's signature in the signature field. It does not display the name, position, role or company of the specific signer. If necessary, this information must be shown above or below the signature field. In the target state, the signature field will display this information i.e. only legal entities will be able to be listed as parties in the document header without their specific representatives, these will only be added when the document is signed.
Document with signature fields
Example of text with fields for placing a signature in a document.
JSON file with call parameters
{
"contract_name": "Document with placeholders - just counterparty",
"number": "2022000001",
"locale": "cs",
"settings": {
"signing_order": "all_at_once"
},
"people": [
{
"is_proposer": true,
"email": "demo@signi.com",
"contract_role": "approve"
},
{
"is_proposer": false,
"email": "zakaznik@seznam.cz",
"contract_role": "sign",
"person_type": "nature",
"first_name": "John",
"last_name": "Doe#2",
"positions": [
{
"anchor": "signi-signature-0"
}
]
}
],
"file": "uploaded_file_key"
}Resulting document
D - Signatures with certificates, qualified signatures
Uses the workspace DEMO API with its API key and users with signing rights, see above.
Uses signature placement according to signature placement fields see Example downloadable placeholder file..
JSON for signature scenario - Proponent and counterparty sign with qualified signatures
{
"contract_name": "Obě strany podpisují přes kvalifikovaný podpis, není autopodpis, podpisy přes placeholdery, použijte Signi API - Testovací dokument - Placehodery 2.pdf",
"number": "document number - 000001",
"state": "pending",
"locale": "cs",
"settings": {
"signing_order": "proposers_before_counterparties"
},
"people": [
{
"is_proposer": true,
"email": "demo@signi.com",
"contract_role": "sign_certificate",
"positions": [
{
"anchor": "signi-signature-0"
}
]
},
{
"is_proposer": false,
"email": "demo+protistrana-neregistrovana01@signi.com",
"contract_role": "sign_certificate",
"person_type": "nature",
"first_name": "John",
"last_name": "Doe#2",
"positions": [
{
"anchor": "signi-signature-2"
}
]
}
],
"file": "uploaded_file_key"
}JSON for Signature Scenario - The proponent automatically approves and the counterparty signs the qualified
{
"contract_name": "Navrhovatel schvaluje automaticky, protistrana kvalifikovaný podpis, podpisy přes placeholdery, použijte Signi API - Testovací dokument - Placehodery 2.pdf",
"number": "document number - 000001",
"state": "pending",
"locale": "cs",
"settings": {
"signing_order": "proposers_before_counterparties",
"autosign_proposers": "V Praze"
},
"people": [
{
"is_proposer": true,
"email": "demo@signi.com",
"contract_role": "approve",
"positions": [
{
"anchor": "signi-signature-0"
}
]
},
{
"is_proposer": false,
"email": "demo+protistrana-neregistrovana01@signi.com",
"contract_role": "sign_certificate",
"person_type": "nature",
"first_name": "John",
"last_name": "Doe#2",
"positions": [
{
"anchor": "signi-signature-2"
}
]
}
],
"file": "uploaded_file_key"
}Example 3 - Handing over the model documents
A - Transmission of common values - text, number, date
On the Signi production environment https://api.signi.com workspace is "Demo API" and has API key = “71c4123d242bdd38047bee838d17e3367dc3ea6748d0975217ce501e834a224c83cab8afd35c9b0e6ade806b7987fae80f97f5c8253cfbb9089cf21f”. When making your calls, replace this API key with your workspace's API key, which you get by subscribing to the "API Integration" and API Key Generation services.
Use the endpoint Create Contract 2.0 > From Template to pass the data for the document template in Signi.
The account demo@signi.com automatically signs for the drafter, the workspace creator... The counterparty in the example signs protistrana@firma.cz, change to your email when testing. The signing order is set to proposers_before_counterparties that is, the proposer's signature is inserted first and then the signature prompt goes to the counterparty.
The template is called Test Agreement with template ID 7v1 with several parameters whose IDs are 112, 131, 411, 421, 431. You can easily find out the parameters of other templates, see How to find out which parameters a template has when using templates?
Description in the documentation
Calling in Postman
The request is of type POST.
The address is https://api.signi.com/api/v1/contract/, on the Param page the Type parameter is set with the value "template", i.e. the resulting address of the call is https://api.signi.com/api/v1/contract/?type=template.
On the Authorization tab, API Key is selected as the authorization type and the API key workspace is specified as the x-api-key value and the API key location is selected as Header.
On the Body tab, multipart/form-data is selected as the call type and a single key-data is specified with a JSON file containing the parameters of the endpoint call
The keys on the Points tab are of type "File", the file to be sent in the request is selected from your disk and uploaded via "Select Files".
JSON file with call parameters
{
"contract_name":"Testovací smlouva 2022",
"number": "000001",
"locale": "cs",
"settings": {
"signing_order": "proposers_before_counterparties",
"autosign_proposers": "V Praze"
},
"people": [
{
"is_proposer": true,
"email": "demo@signi.com",
"contract_role": "sign"
},
{
"is_proposer": false,
"email": "demo+API@signi.com",
"contract_role": "sign",
"person_type": "nature",
"first_name": "John",
"last_name": "Doe´"
}
],
"template": {
"id": "7v1",
"parameters": [
{
"id": "112",
"value": "Hnutí za digitalní revoluci"
},
{
"id": "122",
"value": "Hnutí za digitalní revoluci"
},
{
"id": "131",
"value": "Chci"
},
{
"id": "411",
"value": "V šíření zpráv"
},
{
"id": "421",
"value": "27.5.2021"
},
{
"id": "431",
"value": "v Praze"
},
{
"id": "5",
"value": "true"
}
]
}
}Final document sent for signature
A user with the email protistrana@firma.cz is sent a document invitation to sign the document.
B - Passing a value from the value list
Parameter 221 of the option selection type (in the <con-options> pattern) has two possible values (in the <con-option... label="..."...> pattern) : "The recipient is not a person obliged to publish the contract in the register of contracts or the amount of the performance does not reach the legal limit for publication in the register" and "The recipient is a person obliged to publish the contract in the register of contracts and the amount of the performance reaches the legal limit for publication in the register"
When passing parameter 221, the name of a specific value from the list of values is then passed.
Example of a model code
<con-section con-id="22">
<con-options con-id="221" bind="selection-221" name="" description="" placeholder="vyberte">
<con-option con-id="2211" label="Příjemce není osobou povinnou ke zveřejnění smlouvy v registru smluv nebo výše plnění nedosahuje zákonného limitu pro zveřejnění v registru">
<p class="odsazeni"><span>V.2</span>Tato Smlouva nabývá účinnosti okamžikem jejího podpisu oběma Smluvními stranami.</p>
</con-option>
<con-option con-id="2212" label="Příjemce je osobou povinnou ke zveřejnění smlouvy v registru smluv a výše plnění dosahuje zákonného limitu pro zveřejnění v registru">
<p class="odsazeni"><span>V.2</span>Smluvní strany berou na vědomí, že tato Smlouva ke své účinnosti vyžaduje uveřejnění v registru smluv podle zákona č. 340/2015 Sb., zákon o registru smluv a s tímto uveřejnění souhlasí. Zaslání Smlouvy do registru smluv provede Příjemce neprodleně po uzavření této Smlouvy. Tato Smlouva nabývá platnosti dnem podpisu poslední Smluvní stranou a účinnosti dnem uveřejnění prostřednictvím registru smluv.</p>
</con-option>
</con-options>
</con-section>
Example of passing an option in JSON
...
{
"id": "221",
"value": "V.2 Tato Smlouva nabývá účinnosti okamžikem jejího podpisu oběma Smluvními stranami."
},
...
C - Showing and hiding parts of the pattern content
Typically, there are situations in the wording of contracts where an entire section needs to be included in the contract and sometimes omitted.
Such parts of the document are listed in a separate content block ( in the <con-part> pattern which has the hidable property).
When calling the API, you need to provide a text value of show or hide in the appropriate parameter.
Example of template code
<con-part hideable=true con-id=“5”>
.... text, který někdy je a není zobrazen
</con-part>
Example of passing an option in JSON
...
{"id": "5","value": "hide"},
...
Example 4 - Getting information about a document
On the Signi production environment https://api.signi.com workspace is "Demo API" and has API key = “71c4123d242bdd38047bee838d17e3367dc3ea6748d0975217ce501e834a224c83cab8afd35c9b0e6ade806b7987fae80f97f5c8253cfbb9089cf21f”, when making your calls, replace this API key with your workspace's API key, which you get by subscribing to the "API Integration" and API Key Generation services.
There is also a closed document with contract_id=83166 in the Demo API workspace
Description in the documentation
Call in Postman
The request is of type GET.
The address is https://api.signi.com/api/v1/contract/83166.
On the Authorization tab, the API Key is selected as the authorization type and the workspace API key is specified as the x-api-key value and the API key location is selected as Header.
Resulting document in Signi
Call result
"contract_id": "83166",
"signer_data": {
"firstname": "Roman",
"surname": "Řípa",
"address": "Praha",
"birthdate": "06-08-1970"
},
"state": "completed",
"modified": "23-06-2021",
"file": " <style>\n
...
Example 5 - Obtaining information on the signing status of individual signatories
- On the Signi production environment https://api.signi.com is workspace "Demo API" and has API key = "71c4123d242bdd38047bee838d17e3367dc3ea6748d0975217ce501e834a224c83cab8afd35c9b0e6ade806b7987fae80f97f5c8253cfbb9089cf21f", when making your calls, replace this API key with your workspace's API key, which you get by subscribing to the "API Integration" and API Key Generation services.
- There is also a closed document with contract_id=83166 in the Demo API workspace.
Description in the documentation
- Description of the enpoint Contract > Contract > List of contracts for the given signatory
Call in Postman
- The request is of type GET.
- The address is https://api.signi.com/api/v2/contract/83166/signIdentities/list .
- On the Authorization tab, the API Key is selected as the authorization type and the workspace API key is specified as the x-api-key value and the API key location is selected as Header.
Document in Signi
Call result
[
{
"docs_person": {
"email": "demo@signi.com",
"firstname": "Kapitán",
"lastname": "Demo",
"docs_role": "proposer",
"mobile": ""
},
"contract_role": "sign",
"state": "signed",
"contract_first_shown_date": "2021-06-22T15:21:18+02:00",
"signature_field_show_date": "2021-06-22T15:21:18+02:00"
},
{
"docs_person": {
"email": "roman.ripa@signi.com",
"firstname": "Roman",
"lastname": "Řípa",
"docs_role": "counterparty",
"mobile": "+420605202397"
},
"contract_role": "sign",
"state": "signed",
"contract_first_shown_date": "2021-06-22T15:22:06+02:00",
"signature_field_show_date": "2021-06-23T09:52:46+02:00"
}
]
Example 6 - Signature in an integrated application
One way to connect Signi to your application is to call up the signature page directly from the integrated application, see Submission > Signature in integrated application.
This is similar to Signature on a single device via the Signi user interface.
In response to a signing request, Signi returns the URL of the document signature page(s) that can be displayed directly to the user.
If the signing pages are branded according to the integrated application see Signi Custom Branding feature , the user may not even know that Signi is used somewhere in the background. He simply signs the document in "his" application.
At the same time, if the "one_device":true flag is used when calling the Signi API:
Signi does not send the signers email and SMS signature prompts i.e. they cannot sign remotely,
Signi will only send them the resulting signed document.
There will be a record in the control sheet that the "one-device signing" took place, i.e. the signed document was not delivered remotely. This, for example, meets the legislative requirement to deliver the signed employment document directly to the workplace see Electronic signing in HR using Signi.
JSON file with signature scenario
{
"settings":{
"signing_order": "one_at_a_time",
"one_device":true
},
"people":[
{
"is_proposer":true,
"email":"test@signi.com",
"contract_role":"sign",
"positions":[
{
"x":15,
"y":50,
"page":0
}
]
},
{
"is_proposer":false,
"party_order":1,
"email":"unregistered+1@example.com",
"contract_role":"sign",
"positions":[
{
"x":15,
"y":80,
"page":0
}
],
"first_name":"John",
"last_name":"Doe#1",
"person_type":"legal"
},
{
"is_proposer":false,
"email":"unregistered+2@example.comm",
"contract_role":"sign",
"positions":[
{
"x":50,
"y":80,
"page":0
}
],
"first_name":"John",
"last_name":"Doe#2",
"person_type":"legal"
}
],
"file":"uploaded_file_key"
}Response to request
The URL of the signature page to display in the integrated application returns enpoints to create a document from files or pattern data and looks like the following in the http response.
{
"contract_id": "1234",
"attachments": [],
"state": "pending",
"notifications": [
{
"email": "unregistered+1@example.com",
"links": {
"contract": "https://app.signi.com/contract/received/67ecf33b..."
}
},
{
"email": "unregistered+2@example.com",
"links": {
"contract": "https://app.signi.com/contract/received/b4fe4d95..."
}
}
]
}Example 7 - Invoking Remote Identification
On a Signi production environment https://api.signi.com workspace is "Demo API" and has API key = "71c4123d242bdd38047bee838d17e3367dc3ea6748d0975217ce501e834a224c83cab8afd35c9b0e6ade806b7987fae80f97f5c8253cfbb9089cf21f", when making your calls, replace this API key with your workspace's API key, which you get by subscribing to the "API Integration" and API Key Generation services.
Calling remote identification happens in 3 steps:
Creating a document from a file or template in draft state,
Getting the Signi ID of each person within the workspace,
Calling up the request for identification and signature.
Calling the request for identification and signature works as follows.
If the person has never been identified before, an identification request is sent, they provide the necessary documentation, and then the drafter's staff approves the identification and confirms the sending of the signature request.
If the person has ever been identified, a signature request is sent directly to the person when the call is made.
1. Creating a document from a file or template in draft state
Call the end point Create Document 2.0 > From Document nebo Create Document 2.0 > From Template,0 > Ze vzoru,
the JSON with the parameters specifies "state": "draft":
{
"number": "RU21001",
"contract_name": "Dokument ve stavu draft",
"state": "draft",
"locale": "cs",
....The result of the call contains, among other things, the idContract document ID, which we will use for the next call.
2. Getting the ID of each person
Call the endpoint Document > List of signers for the document. This is a GET request at https://api.signi.com/api/v2/contract//signIdentities/list
The result of the call contains the individual person ids that we will use in the next call. The id is unique within the email and workspace signi.
Data about the people in the signature scenario returned by the Signi API.
3. Vyvolání požadavku na identifikaci a podpis osoby
Call the endpoint Document > Call Identification. This is a POST request at https://api.signi.com/api/v2/contract/{idContract}/auth/group.
Attention!!! - It makes sense to call the identification requirement only for counterparties i.e. "doc_role": "counterparty", not for proposers i.e. "doc_role": "proposer". The API will return an error if identification of the proposers is requested.
The JSON with parameters specifies for which person ID we want which authentication method.
[
{
"signIdentityId": 116,
"enabledAuths": [
"aml", "bankId"
]
}
]
Based on the endpoint call, the corresponding identification prompts are sent out. At the same time, the end point returns a URL to perform the identification of each person. It is thus possible to open the identification page directly in the integrated application after calling the end point, e.g. on a website for selling a new product.
{
"links": [
{
"full_name": "Tomáš Johanovský",
"link": "https:\/\/app.test.signi.tech\/dashboard\/workspace\/597\/documents\/12291"
},
{
"full_name": "John Doe#1",
"link": "https:\/\/app.test.signi.tech\/auth\/FGDYDLF7jp6xqcf4ID6xHg6Hi4fjMNGUrtf42PL8dPbVjJRZn8IfFtE3pR6fpVJBEjVWB5FyVl2j6qFv11E0Jb7qpjM1HMdyeFXxZHMMHllXx5YKrl4NeKcC"
}
]
}Was this article helpful?
That’s Great!
Thank you for your feedback
Sorry! We couldn't be helpful
Thank you for your feedback
Feedback sent
We appreciate your effort and will try to fix the article