Normal signature posting service

<< Click to Display Table of Contents >>

Navigation:  Signant web services >

Normal signature posting service

The Normal signature posting service is the primary service for creating a standard signature posting. This web service allows you to upload documents and assign signatories. When you execute a signature posting, Signant will start to notify the signatories requesting their digital signatures to your documents. When all signatories have signed you may use the Posting Service to retrieve the signed documents.

 

Web service endpoint

Web service description endpoint in the testing environment T3: https://test3.signant.no/WS/V1/PostingsService.svc?wsdl

 

 

Posting service work flow

The illustration below demonstrate the work flow for a standard signature posting:

 

 

signant_ws_flow

 

 

Posting service steps

1.

Create posting.

Here you will use the webservice function CreateSignPosting to create and prepare a new signature posting.

2.

The Signant message service sends email notifications to all recipients.

a)Keeps track of signing priority.

b)Sends reminders to recipients that have not completed their tasks.

c)Sends notification to the posting ower and other posting managers when all recipients have successfully completed, or if onw or more have declined.

3.

Signatory login
Recipients login to the Signant portal using one of the supported eID providers for electronic identification.

4.

Recipient signs all required documents using a secure electronic identification.

5.

A Callback post notification with the final status is sent to the External system.

6.

Check status

The external system checks the signature posting status using the function GetPostingStatus.

7.

Email notification is sendt to the posting owner and all posting managers.

8.

Download files

The final step is to download the signed documents from the signature posting, and save the documents to your own business application. See the function DownloadAttachment.

 

 

Code sample for CreateSignPosting

 

 

Web service functions

The Signant Posting Service exposes the following functions:

Name

Description

CreateSignPosting

For creating a new signature document request.

GetPostingStatus

Returns a simple status overview for the posting.

GetSignPostingStatusDetails

Returns a detailed status of the posting.

DeletePosting

Delete post from the system and removes all files from server.

DownloadAttachment

Download attachment for archiving

Seal service functions


RequestEnterpriseSignature

Upload document and apply signature with enterprise certificates

 

 

Function CreateSignPosting

Function input parameters

Name

Type

Description

Required

DistributorID

String

For authentication (Provided by Signant)

Yes

AccessCode

String

For authentication (Provided by Signant)

Yes

DistributorSystemID

String

External system reference, for tracking what system is accessing the service, for example: CRM or WEB

No

ConsumerOrgNo

String

Corporate identity number of invoice recipient. Usage depending on the distributor agreement. Only to be used when Signant sends invoice to end user. Leave this field empty for normal distributor agreement.

No

ConsumerName

String

Name of invoice recipient. Usage depending on the distributor agreement. Only to be used when Signant sends invoice to end user. Leave this field empty for normal distributor agreement.

No

ConsumerInvoiceInfo

String

Label for posting, this will show on the system usage report.

Usage: To be used by distributor to retrieve extra information with the invoice.

No

ConsumerOrderOrgNo

String

Extra invoice info, this will appear on the system usage report.

Intended usage: optional info for the consumer to identify project cost.

No

ConsumerOrderOrgName

String

Extra invoice info, this will appear on the system usage report.

Intended usage: optional info for the consumer to identify project cost.

No

ConsumerOrderInvoiceInfo

String

Extra invoice info, this will appear on the system usage report.

Intended usage: optional info for the consumer to identify project cost.

No

Title

String

Name of the posting, used in emails sent to posting recipients and notifications sent to end users.

Yes

Description

String

Short description of posting, will be included in emails sent to posting recipients.

No

ActiveTo

DateTime

Expired date for posting, after this date posting will be locked for further activity (1)

Yes

WillBeDeletedDateTime

DateTime

When Posting will be deleted from system  (1)

Yes

UseWidget

Bool

Visible signature widget in the PDF file. If set to false the signature will be visible only from the “Signature panel” in Acrobat Reader

Yes

UseWidgetOnAllPages

Bool

Widget will be created on all pages. Only works when UseWidget is true.

No

PostingAdmins

PostingAdmin()

List of Posting administrators (owner) (2)

Yes

Recipients

Recipient()

List of posting Recipients

Yes

Attachments

Attachment()

List of files to sign

Yes

AutoActivate

Bool

Manual activation (3)

Yes

SenderName

String

Name of the email sender used in system emails to recipients. (4)

No

1.Cannot exceed 1 year

2.At least one PostingAdmin must be provided, first PostingAdmin will be set as PostingOwner

3.Customers that have ServiceToService mode can use the AutoActivation to skip manual activation.

4.If empty or not specified, the name of the PostingOwner will be used.

 

 

Structure PostingAdmin

Name

Type

Description

Required

Name

String

Name of admin

Yes

Email

String

Email of admin

Yes

MobileNumber

String

Mobile number to admin

Yes

SSN

String

Social security number (1)

No

NotifyByEmail

Bool

Should receive status emails or not

Yes

1) When AutoActivate is false then PostingOwner must provide SSN

 

Structure Recipient

Name

Type

Description

Required

Name

String

Full name of recipient

Yes

Email

String

Email to recipient

Yes

MobileNumber

String

Recipient Mobile Number

No

SSN

String

Social security number of recipient (1)

No

Priority

Int

0 = No priority, 2 = Must sign first (2)

No

NotifyByEmail

Bool

Should receive emails or not

Yes

1) User of WS must have permission from recipient to use their SSN

2) Read more about priority in definitions

 

Attachment

Name

Type

Description

Required

File

Binary

File to sign or to read. (1)

Yes

FileName

String

Name of file

Yes

Description

String

Short description of file

Yes

ActionType

Enum

Sign,Read

Yes

1) File for signing must be a valid PDF file

 

 

Output

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

ActivationUrl

String

Url for manual activation of posting, empty when AutoActivation = true

AttachmentInfos

AttachmentInfo()

Return information about attachments.

 

AttachmentInfo

Name

Type

Description

Description

String

Description of file

FileName

String

FileName

GroupID

Guid

GroupID gived by Signant to the attachment

AttachmentID

Guid

AttachmentID gived by Signant to the attachment

 

Webservice function GetPostingStatus

Input

Name

Type

Description

Required

DistributorID

String

Provided by Signant

Yes

AccessCode

String

Provided by Signant

Yes

PostingID

Guid

Posting ID

Yes

 

Output

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

Document signing completed count.

Activated

Bool

Posting Activation Status

PostingType

Enum

SignViewDocument, RequestDocument, SignOwnDocument

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

Ignore when Postingtype is SignViewDocument

TotalDocsRead

Int

Ignore when Postingtype is SignViewDocument

TotalDocsToUpload

Int

Ignore when Postingtype is SignViewDocument

TotalDocsUploaded

Int

Ignore when Postingtype is SignViewDocument

 

Webservice funtion GetSignPostingStatusDetails

Input

Name

Type

Description

Required

DistributorID

String

Provided by Signant

Yes

AccessCode

String

Provided by Signant

Yes

PostingID

Guid

Posting ID

Yes

AccessToken

Guid

Applies to ApplicationToService mode

No

 

Output

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

Attachments

Attachment()

Array of attachments

 

Attachment

Name

Type

Description

AttachmentID

Guid

Attachment ID

GroupID

Guid

Attachment Group ID

FileName

String

Name for file

Description

String

Attachment Description

FileSize

Int

Size of the file in bytes

FileModified

DateTime

Last time file was modified

FileCreated

DateTime

Date when file was created

FileHash

String

Md5 checksum of the file

Recipients

Recipient()

Array of attachment recipients

AttachmentStatus

Enum

Pending, Rejected,Completed

CompletedDateTime

DateTime

The date when the actions on this attachment are completed

 

Recipient

Name

Type

Description

RecipientID

Guid

Recipient ID

Name

String

Recipient Full Name

MobileNumber

String

Recipient Mobile Number

Email

String

Recipient email

ActionType

Enum

Read,Send,Sign

ActionLastDateTime

DateTime

Posting Action Date Time

ActionStatus

Enum

Sent, Completed, Rejected, Delayed

Signed

Bool

Is signed status

Read

Bool

Is Read status

Rejected

Bool

Is Rejected status

RejectReason

String

Reject Reason

LastReminderDateTime

DateTime

Date when last reminder was sent to recipient

SignatureURL

String

Signatur URL for this recipient

CompletedDateTime

DateTime

Posting Action Completed DateTime

 

Webservice function DeletePosting

Input

Name

Type

Description

Required

DistributorID

String

Provided by Signant

Yes

AccessCode

String

Provided by Signant

Yes

PostingID

Guid

Posting to delete

Yes

AccessToken

Guid

Applies to ApplicationToService mode

No





 

Output

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

 

Webservice function DownloadAttachment

Input

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

AccessToken

Guid

Applies to ApplicationToService mode

No

 

Output

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

 

 

 

Error Codes

Error Code

Description

0

No error

4201

Unauthorized access. Invalid combination of DistributorID and AccessCode

3102

Invalid parameter(s) value

3103

Error validating File. File not valid or eligible for requested operation

3104

Error validating FileToSign. File to big

3105

HSM error – timeout or not responding

3106

Enterprise certificate not present

3107

Enterprise certificate not valid or expired

3108

Operation timeout

9XXX

Other unknown

 

 

Webservice function Callback

The Callback service can be turned on upon request, Distributor then needs to provide Signant with a valid callback URL. When callback is turned on a HTTP request to the provided URL is executed for each posting after the signing process is completed, rejected or expired. This can be used to trigger the DownloadAttachment and/or DeletePosting functions.

Parameters        

Name

Type

Description

PostingID

Guid

Posting ID

PostingStatusChange

Bool

Indicates if the callback was initiated because of a status change

PostingStatus

Enum

Completed, CompletedPartially, Expired

SignatoryActivity

Bool

Indicates if the callback was initiated because of an activity by one of the posting recipients

 

Example

https://somesite.com/SignantCallBack/Callback.php?PostingID=11111111-2222-3333-4444-555555555555&PostingStatusChange=True&PostingStatus=Completed&SignatoryActivity=True

Retries

The callback URL must return a HTTP statuscode 200. Any other statuscode will trigger a retry after a short delay, the service will retry the callback up to 5 times with exponential time delay.