Instant signature posting service

<< Click to Display Table of Contents >>

Navigation:  Signant web services >

Instant signature posting service

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_sequence_diagram

 

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.

 

Instant_signature_ttl

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

 

 

Functions description

 

Function: CreateInstantPosting

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

 

 

Object: InstantPosting

 

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

Email

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).

 

 

Object: Attachment

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

 

 

Object: UrlToSigning

Field name

Type

Description

Name

String

Name of person to sign (from InstantPostingRecipient)

Url

String

Url to signature page

 

 

Function GetPostingStatus

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