- What are the options for invoking signing from the integrated application?
- How are the signing documents submitted?
- What parameters are optional in the call and what are they used for?
- What is the simplest signing scenario for integration?
- How to insert signatures automatically?
- How to send multiple documents in one set?
- How do I choose which signature types to use?
- How do I appropriately determine the title of a document?
- How are document identification numbers transmitted?
- Can I change the texts of emails and SMS?
- How do I get the result of submitting documents for signature
What are the options for invoking signing from the integrated application?
There are several ways to connect Signi to an application. Users can be given access to one method or more, so that they can choose a method that fits the situation in which they need to sign.
Different ways of calling Signi from the integrated application.
1. Distance signature
When a signature is invoked in the integrated application, Signi sends email messages with links to the signing pages in the order specified by the signature scenario. If a phone number is provided, SMS notifications may also go out. This is similar to sending a standard document for signature via the Signi user interface. The user does not see Signi at all, he works exclusively with the integrated application.
When the Signi API is called, the document is passed to the To be sent state i.e. "state": "pending".
For more information see Example 2 - Submitting a PDF document for signature.
2. Signature in the integrated application
In the Signi user interface, there is a Signature on One Device option where the proponent and all counterparty(s) are in one place and sign in Signi at one time on one device.
When integrating with another application, this can be implemented similarly, with signing in the integrated application. Signi returns the URL for each signer's signature when documents or template documents are passed - see How do I get the result of passing the signature documents. The integrated application then displays pages with these URLs for one or more signers to sign. Note that if there are multiple signers, they must all have their own signature space. If multiple documents are being signed at once in a set, everything is still displayed under one signature page URL, the user just sees multiple tabs with individual documents in the left pane.
When the Signi API is called, the document is passed to the To be sent state i.e. "state": "pending".
See Example 6 - Signature in an integrated application for more details.
3. Signi as a work queue
In this mode, the integrated application sends the document to Signi so that it shows up in Signi to the proposer's employee working with a tablet or mobile phone as a document to be processed.
A salesman dealing with a client on the premises or at the client's site, a driver handing over goods, a service technician intervening at the customer's site will sign the document on his device - typically a tablet or mobile.
When a Signi API call is made, the document is passed to the Work in Progress state, i.e. "state": "draft".
4. Sign via QR code
In this variation, one employee uses both a computer with company IS and Signi
The linked application displays a QR code with the URL of the page to be described, which is returned by the Signi API when the document is submitted for signature. This code loads the tablet and displays the appropriate page for signature. No one needs to be logged into Signi from it while doing so. When the Signi API is called, the document is passed to the To be sent state i.e. "state": "pending".
Alternatively, when Signi is called, the document can be passed to the Signi document list for signature. The QR code in this case will be used to display the document to the user logged in Signi for further processing.
How are the signing documents submitted?
1. file transfer
A file is passed to Signi from your Application for signing, see format What formats are used to pass files for signing? and information about the location of the signatures in the document.
The counterparty is then shown the document including the fields to sign when approving the document.
The document, including the signatures, is sent from Signi back to the application as a PDF file.
For more information, see Create Contract/Document 2.0 > From Document and "How do I pass signature location information when submitting documents for description?" below.
2. Passing parameters for a template
In Signi, a document template is prepared with tags corresponding to each document parameter in appropriate locations in the document.
Specific parameter values, such as the client's name, are passed as supporting documents when the contract creation request is invoked.
The document, including signatures, is sent back to the application from Signi as a PDF.
More on Creating a contract / document 2.0 > From a template and the paragraph below How to pass parameters to be filled in the template when using templates for signing.
What parameters are optional in the call and what are they used for?
Only email, first and last name are required to send a document for signature. A phone number is only required if you do not allow the counterparties to enter and change it. However, other identifying information is among the parameters.
Some information is required when submitting documents for the template, where there is no identification of the counterparties in the template document, and is filled in from the parameters passed in the call.
Here again, the name is mandatory, the date of birth makes sense to enter when the customer wants it to be provided for more accurate identification of the contracting party.
They are not required when the documents are passed, however to keep the same parameter structure they remain there.
In messages signed via SMS and email, the First Name, Last Name or Organization is used as identification of the sender of the document. As in the sender's name in the email header.
If the signatories' details are transmitted in a structured form, it would be possible to show them their documents signed without registration after their subsequent registration. Due to the GDPR and the potential risk of error, this feature will probably not be available.
What is the simplest signing scenario for integration?
When integrating, it's a good idea to start with the simplest signing scenario and then, if necessary, compose it according to the users' needs. What it looks like:
The author / drafter of the documents (is_proposer=true when calling the API ) is the email of the founder of the workspace in Signi , to which the documents are sent via the API, i.e. typically the email of the main Signi account for the company, or someone who has signing rights there. It only approves the document (contract_role="approve"), i.e. the signature is not visible on the document. When the API call is made, the approval is done automatically.
All signatories or approvers, regardless of whether they are from the proposer's company or not, are marked as counterparties (is_proposer=false). As a result, they do not need to have an account in Signi at all, only in the integrated application. Signature prompts come to all of them and they can sign the document. The only downside is that they have to physically sign every document.
See Example 2 for more
How to insert signatures automatically?
If the organization's employees:
have created an account on Signi,
have been invited by the workspace owner to the workspace with signing rights set and have accepted the invitation,
they have pre-set their signature in their account, and
automatic signing by the proposer is enabled on the workspace/workspace, including specifying the location of the signature, e.g. "Prague",
their signature can be automatically inserted into the document. According to EIDAS this is fine, the signing is done in a controlled Signi environment that ensures the signature is inextricably attached to the corresponding documents, and the calling application (yours) has authenticated and authorized the person to create, sign and forward the document to other counterparties for signature.
The signing scenario passed through the API will then contain, for example, as follows , the author / drafter of the document whose signature can be automatically inserted under the conditions above is podepisujiciobchodnik@firmanavrhujicidokument.cz:
{
"settings": {
"signing_order": "one_at_a_time",
"autosign_proposers": "V Praze"
},
"people": [
{
"is_proposer": true,
"email": "podepisujiciobchodnik@firmanavrhujicidokument.cz",
"contract_role": "sign"
},
{
"is_proposer": false,
"party_order": 1,
"email": "podepisujícizakazník@firmaprotistrana.cz",
"contract_role": "sign"
}
],Any workpace user with signature rights as author/designer of a document can be signed automatically. However, they must sign first before counterparties. The API key of the workspace founder can be used to connect to Signi. Thus, the 3 worker(s) in HR can be automatically signed on "their" documents, only when calling the API their emails are listed as the emails of the proposer i.e. "is_proposer": true for the person in the first position of the signature scenario in the Person field.
Read more about What are the signing options for representatives of an organization using Signi?
How to send multiple documents in one set?
Call sequence
endpoint template {.... Last_document:false… }
endpoint template attachment {.... Last_document:false… }
endpoint template attachment {.... Last_document:false… }
endpoint template attachment {.... Last_document:true… }
A document can have an unlimited number of attachments, each signature is charged as a separate signature.
If a person has to sign multiple documents in one batch, they will only receive one SMS and email. Then he will be shown the individual documents that he has to sign one by one.
Several documents sent in one set - for example, the customer receives one e-mail, after clicking on it he has access to all documents in the set see above and can sign them (e.g. offer or contract) or just approve them (e.g. - General Terms and Conditions).
PREPARE: The result of signing each of the documents is now transmitted by a separate call to the appropriate webhook for that document. We want to add an option where the webhook will only be called once for the entire submitted set.
How do I choose which signature types to use?
Signi allows you to sign multiple signature types, see Signature Types in Signi. Signature types are specified for each signer separately in the Person section of the "contract_role" attribute. Possible values of the "contract_role" attribute and corresponding signature types:
notice - Person only receives a notification email when the document is closed or when all operations on the document are performed, see more about the " Note" function and an example API call.
approve - The signer has to click the "Approve" button, but his signature is not visible anywhere on the document
Sign - Biometric Signature - Signature is similar to a handwritten signature on a document, the signature may or may not include sensitive personal information depending on workspace settings.
sign_bank_id_sign - BankID SIGN - Sign via one of the Bank Identity / BankID services, enabling the signature must be activated in Signi or an error message will be returned, contact sales@signi.com to activate and agree on how to operate - either the proposer has a contract with Bank Identity and uses their service settings in Signi or Signi can resell the service to them.
sign_certificate - Signature by certificate and qualified signature - Signature by qualified or commercial certificate, enabling signature needs to be activated in Signi, otherwise error message
"Contract role [sign_certificate] is not enabled for this workspace"
To activate, please contact sales@signi.com. Signi does not issue qualified or commercial certificates, you need to secure them from certification authorities such as Post Signum, 1. CA of another publisher or specialized services that will help you with the establishment of certificates.
For specific examples of Signi API calls with different signature types, see Example 2 - Submitting a PDF document for signature.
Temporary restrictions on signature type elections:Multiple signature types for one signer
- For the time being it is not possible to combine multiple signature types for one signer, e.g. biometric or BankID SIGN.
Qualified signatures
In principle, automatic signature insertion is not possible.
In a single signature scenario they can be combined with Approval and Acknowledge but not other signature types (otherwise error message "All people need to have role [approve OR sign_certificate] assigned" ).
Can be signed on MS Windows and Apple Mac. Cannot sign on tablets and mobile phones that do not have native support for working with certificates in the operating system, the necessary connections to HMS for storing certificates are being prepared.
Cannot yet be combined with placing signatures on an added Signature Sheet. We now assume that the inserted document can no longer be manipulated, only drive signatures into the signature layer.
BankID SIGN
In principle, automatic signature insertion is not possible.
In a single signature scenario, scenarios can be combined with Approval and Acknowledgement but not other signature types.
So far it is not possible to combine with placing signatures on the Signature Sheet. We now assume that the inserted document can no longer be manipulated, only the signatures can be managed in the signature layer.
The inserted document must already be in the PDF/A signature format, some banks do not allow other signatures. The conversion may cause visual changes to the document, we prepare the document conversion including enforcing it when calling the API.
Note
- Not yet available on production environments
How do I appropriately determine the title of a document?
The document name is also the name of the PDF file of the signed document that is passed back to the integrated system or when the document is downloaded from the user interface. At the same time, the PDF file of the checklist is named the same as the PDF of the signed document, but with the prefix KL_ in the name.
It is therefore advisable during integration to send some unique value to the API in the document name, i.e. contract_name, at the same time understandable to the signers. It will then be easy to uniquely trace both the document and its checklist. At the same time, it should be kept in mind that the document name is shown to signatories in email and SMS notifications, i.e. it is not entirely appropriate to send e.g. the number itself. Example of a correct name: "Affidavit of Claim No. 6493543".
How are document identification numbers transmitted?
Now the document number in Signi - Contract_ID is used for identification, which is the result of the signature invocation and is also part of the webhook call (in the HEAD section).
If you want to also pass the document identification in the integrated system, as a workaround it is possible to embed this identification in the webhook address.
PREPARE: Passing the document identification in the integrated system in the "your number/our number" logic to the signature and webhook invocation parameters.
Can I change the texts of emails and SMS?
Yes, they can - this is a workspace/workspace-wide setting and can be changed by any user with access to the workspace.
It is also possible to specify the name of the sender or the name of the recipient of the reply (REPLY TO).
Parameters in texts to be changed according to the current state:
{CONTRACTNAME} - Completes the document name if the name of the file or pattern used is not filled in.
{NAME} - Fills in the full name of the workspace owner
{CLIENTNAME} - Fills in the full name of the client - first and last name for persons, for companies?
How do I get the result of submitting documents for signature
You will get the immediate result of the signature submission synchronously as a "Response" to the call of the corresponding endpoint.
If the documents are complete and valid, the response code is 200. Error codes start with 400 , where the dots contain a description of the error. Occasionally you may encounter a universal error 500, we try to minimize this.
In the BODY response you will also get the value of the Contract_ID variable, which is the identification of the document in Signi. This is then used in the webhook (see below), it can be used to download a Checklist with the progress of signing the document, etc.
The response also includes the URLs of unique pages for signing the document by specific signatories/approvers, which can be used in the integration.
Examples of the results of a document or pattern signature request.
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