The instant signature web service is intended for situations where the signature posting is to be signed immediately by the signatories.
A typical use case is a web form where the user completes the form and commit an electronic signature in the same session.
As the signatories needs to be present at the time of signing, the instant signature web service does not send any notifications to the signatories. Instead you may run the instant service several times in order to add more signatures to a document.
Web service endpoint
Web service description endpoint in the testing environment T3: https://test3.signant.no/WS/V1/InstantSignatureService.svc?wsdl
Instant sign sequence diagram
The following sequence diagram demonstrates the data flow and operational sequence in an instant signature posting.
Instant signature steps
1.Integrator web initializes a new “Instant Sign” posting.
2.Url to signing is returned.
3.User is redirected to signature page.
4.After successful signing the user is redirected back to Integrator web.
5.Integrator backend checks status (every 5 minutes), or when user is redirected back to Integrator web.
6.Signant WS returns signature status.
7.When signature status is completed Integrator backend downloads the document.
8.Signant WS returns the signed document.
Time to live
The instant signature service creates a signature posting for a limited period of time while the signatories perform their signatures. The posting will then be removed from the service.
This is how the posting expiry time is set and updated:
-Upon creation the posting will expire after 15 minutes.
-When user begins the signing process the posting expiry will be set to 15 minutes from that time.
-When signing process is done the posting expiry will again be set to 15 from that time.
Example of a posting expired date being moved 15 minutes for each time an action is executed.
It is crucial for the “Integrator backend” to check the status regularly (every 5 min) and download the document as soon as the WS returns a status indicating that the document has been signed. If this step is not executed correctly the Integrator can potentially lose the signed documents because it will be deleted from Signant servers when the expired date has been reached.
Code sample for CreateInstantPosting
Web service functions
This web service exposes the following functions:
Name |
Description |
---|---|
CreateInstantPosting |
For creating a new instant sign posting. |
GetPostingStatus |
Returns a simple status overview for the posting. |
DownloadInstantAttachment |
Download attachment for archiving |
Function to create the instant signature posting.
Name |
Type |
Description |
Required |
---|---|---|---|
DistributorID |
String |
For authentication (Provided by Signant) |
Yes |
AccessCode |
String |
For authentication (Provided by Signant) |
Yes |
Posting |
InstantPosting |
InstantPosting object |
Yes |
Field name |
Type |
Description |
Required |
---|---|---|---|
DistributorSystemID |
String |
External system reference, for tracking what system is accessing the service, for example: WebDisclaimer or OrderTerms |
No |
Title |
String |
Title of the posting. |
Yes |
Description |
String |
Short description of posting |
No |
UseWidget |
Bool |
Add visible signature widget in PDF document |
Yes |
Recipients |
InstantPostingRecipient() |
List of InstantPostingRecipient |
Yes |
AttachmentToSign |
Attachment |
Attachment object |
|
AfterSignAction |
Enum |
Specifies what action should be performed after successful signing. Valid values are: NoAction, Redirect, CloseWindow 1) |
Yes |
AfterSignRedirectUrl |
String |
Redirect URL if AfterSignAction is set to Redirect |
No |
AfterSignRedirectDelay |
Int |
Redirect delay in sec, should not be set if AfterSignRedirectCaption is used |
No |
AfterSignRedirectCaption |
String |
If Action is set to Redirect and AfterSignRedirectDelay is not set then this will be the caption on the redirect link |
No |
CancelUrl |
String |
Redirect url if the user cancels in the signing process. This must be a https address |
No |
1)CloseWindow only works if the browser window is opened from a parent window. |
Object: InstantPostingRecipient
Field name |
Type |
Description |
Required |
---|---|---|---|
Name |
String |
Full name of recipient |
Yes |
String |
Email to recipient |
No |
|
SSN |
String |
Social security number of recipient (1) |
No |
MinimumAge |
Int |
If this field is set, t will be considered as a constraint for minimum age. Signing process will be cancelled if person does not meet this criteria (2) |
No |
MaximumAge |
Int |
If this field is set, it will be considered as a constraint for maximum age. Signing process will be cancelled if person does not meet this criteria (2) |
No |
DateOfBirthRequired |
DateTime |
Signing process will be cancelled if person does not meet this criteria (2) |
No |
1)User of WS must have permission from recipient to use their SSN 2)If this check fails, the user will be redirected to CancelUrl from InstantPosting object (if that parameter is set). |
Field name |
Type |
Description |
Required |
---|---|---|---|
File |
Binary |
File to sign (1) |
Yes |
FileName |
String |
Name of file |
Yes |
Description |
String |
Short description of file |
No |
ActionType |
Enum |
Must be: Sign |
Yes |
CancelUrl |
String |
Redirect if user cancelled the process. (2) |
No |
1)File for signing must be a valid PDF file 2)BankID requires a https adress. |
CreateInstantPosting output - object CreateInstantPostingResponse
Field name |
Type |
Description |
---|---|---|
Success |
Bool |
Method call Result |
Message |
String |
Error/Validation Message when Success is false |
ErrorCode |
Int |
Error/Validation code when Success is false |
PostingID |
Guid |
ID of newly created posting |
AttachmentID |
Guid |
AttachmentID of attachment created by Signant |
SignUrls |
UrlToSigning () |
Array of UrlToSigning, one for each recipient |
Field name |
Type |
Description |
---|---|---|
Name |
String |
Name of person to sign (from InstantPostingRecipient) |
Url |
String |
Url to signature page |
Used to check posting status. When function returns “Incorrect postingID/ErrorCode: 4008” posting is expired and has been deleted from the system.
Field name |
Type |
Description |
Required |
---|---|---|---|
DistributorID |
String |
Provided by Signant |
Yes |
AccessCode |
String |
Provided by Signant |
Yes |
PostingID |
Guid |
Posting ID |
Yes |
GetPostingStatus output - object: GetPostingStatusResponse
Field name |
Type |
Description |
---|---|---|
Success |
Bool |
Method call Result |
Message |
String |
Error/Validation Message when Success is false |
ErrorCode |
Int |
Error/Validation code when Success is false |
PostingID |
Guid |
Posting ID |
Status |
Enum |
Sent, Completed, CompletedPartially, Expired |
TotalDocsToSign |
Int |
Total documents to be signed |
TotalDocsSigned |
Int |
Document count where recipients have signed |
TotalDocsRejected |
Int |
Document count where at least one recipient has rejected |
ToBeSignedCount |
Int |
Document signing request count. |
SignatureCount |
Int |
Number of completed signatures. |
Activated |
Bool |
Posting Activation Status |
PostingType |
Enum |
For Instant Sign this will be: InstantSign |
ActiveTo |
DateTime |
Posting Expiration DateTime |
CreatedDateTime |
DateTime |
Posting Creation DateTime |
LastModifiedDateTime |
DateTime |
Posting Modified DateTime |
WillBeDeletedDateTime |
DateTime |
Date when the posting will to be deleted |
Title |
String |
Title of the posting |
Description |
String |
Short description on |
DefaultLanguage |
String |
Default Language Code |
CompletedDateTime |
DateTime |
Posting completed date time |
LastReminderDateTime |
DateTime |
Not in use |
TotalDocsToRead |
Int |
Not in use |
TotalDocsRead |
Int |
Not in use |
TotalDocsToUpload |
Int |
Not in use |
TotalDocsUploaded |
Int |
Not in use |
Function: DownloadInstantAttachment
For downloading the attachment after successful signing. Attachment cannot be downloaded after posting has expired.
Parameter name |
Type |
Description |
Required |
---|---|---|---|
DistributorID |
String |
Provided by Signant |
Yes |
AccessCode |
String |
Provided by Signant |
Yes |
PostingID |
Guid |
Posting ID |
Yes |
AttachmentID |
Guid |
Attachment ID |
Yes |
DownloadInstantAttachment output - object: DownloadInstantAttachmentResponse
Field name |
Type |
Description |
---|---|---|
Success |
Bool |
Method call Result |
Message |
String |
Error/Validation Message when Success is false |
ErrorCode |
Int |
Error/Validation code when Success is false |
AttachmentID |
Guid |
Attachment ID |
FileName |
String |
Name for file |
AttachmentFile |
Byte[] |
The file |
Description |
String |
Attachment Description |
FileHash |
String |
Md5 checksum of the file |
Sample requests
The sample requests and responses have been shortened down for readability and will therefore not work “as is“, you will have to replace all required fields with correct data before trying to send a request to the service.
Sample request: CreateInstantPosting
The request above will return the following result
Sample request: GetPostingStatus
The request above will return the following result
Sample request: DownloadInstantAttachment
The request above will return the following result