AssureSign: ListSignatories

Important: beginning with AssureSign version 4.4, the correct method of presenting a signing link through your own code is by querying the links through a call to GetSigningLinks. Manual building of links will continue to be supported only for legacy clients.

The ListSignatories operation is a legacy method used to create a seamless flow from order entry to AssureSign document signing. This ability to present the document for signing within your workflow (that is, without requiring that an email invitation to sign be sent) is called Immediate Presentment. For example, it could be used in the case where a customer enters data in a validated web environment which is used to pass through a DocumentNOW submission operation; following the return of a Document ID and AuthToken, the values could be returned within the ListSignatories operation to retrieve the signer's SignatoryAuthToken (which will be unique for each signatory within each signing step). This SignatoryAuthToken could be combined with the DocumentID and Document AuthToken to create a URL which will take the signatory to the signing page. This complex operation may be accomplished with guidance from AssureSign's consulting services team.

The ListSignatories operation requires knowledge of the following:

• the Document ID of the document to cancel (this is returned as an element in the returned XML from a document submission operation)
• the AssureSign account ContextIdentifier (this is exposed in the AssureSign administrative application account settings and serves to provide some security to the transaction)
• the AuthToken of the document to cancel (this is returned as an element in the returned XML from a document submission operation)

Sample XML

<?xml version="1.0" encoding="utf-8"?> 
<ListSignatories xmlns="https://www.assuresign.net/Services/DocumentNOW/ListSignatories"> 
    <SignatoryListQuery 
        ContextIdentifier="06C4A84A-693C-46CB-8DF2-40A8215AA056" 
        Id="2CE11EF1-8938-DD11-8735-00065B8CE99B" 
        AuthToken="8CC9A84B-693C-46CC-4342-40A8215AD76A" /> 
</ListSignatories>

The SOAP Action header is

https://www.assuresign.net/Services/DocumentNOW/ListSignatories/IListSignatoriesService/ListSignatories

The response will contain a list of signatories who are available to sign within the currently active step in the document workflow. If your document was configured passing first and last name separately, then the signatory result will reflect the separate first and last name. If, however, a signatory was configured with a full name only, the signatory result will contain the full name. For example:

<?xml version="1.0" encoding="utf-8"?> 
<ListSignatoriesResponse xmlns="https://www.assuresign.net/Services/DocumentNOW/ListSignatories"> 
    <SignatoryListQueryResult Id="2CE11EF1-8938-DD11-8735-00065B8CE99B"> 
        <Signatories> 
            <SignatoryItem 
                SignatoryId="95DD027C-8238-DD11-8735-00065B8CE99B" 
                SignatoryAuthToken="AB29A84B693C46CC434240A8215ADAAA" 
                FirstName="Bob" 
                LastName="Smith" 
                EmailAddress="bsmith@example.com" 
                MobilePhone="3215556789"/> 
        </Signatories> 
    </SignatoryListQueryResult> 
</ListSignatoriesResponse>

The SignatoryListQueryResult should be checked for the presence of an Exceptions element, which may contain multiple SignatoryListException items.

Note that the ListSignatories operation will return an error if the document was created with the immediate presentment availability flagged turned off. Templates are created by default to allow access for immediate presentment; however, you may choose to mark certain templates as unavailable in order to fulfill security requirements of your organization.

In order to use the returned information from the ListSignatoriesResponse, it will be necessary to match the information in the Signatories section to the user who is to sign (for example, you could match the SignatoryItem based on the signatory's email address). This may seem redundant in a situation with a single signer, but templates that include multi-party signatures within a single step (rather than in sequential steps) will return back multiple SignatoryItem elements within the response XML. Once matched, the signatory may be directed to the signing landing page by building a URL in the form:
[AssureSignSiteBaseURL]/Landing.aspx?i=[value]&a=[value]&s=[value]&sa=[value]&redirect=[value]

where the parameters are defined as

• i – the document ID
• a – the document AuthToken
• s – the signatory ID returned by the ListSignatories operation
• sa – the signatory AuthToken returned by the ListSignatories operation
• redirect – an optional URL to which the signatory will be redirected upon signing step completion or inability to complete. Note that this may also be set at an account level by logging into the AssureSign administration site, clicking on the Administration tab and the Customization link, and choosing “Redirect signers to an alternate page”; if this has been set at an account level, then passing the redirect parameter will not be necessary except to override the account setting.

If this mechanism is used with a valid redirect location, the redirect URL will be appended with a number of parameters.

Note: In order for your redirect URL to pass back request parameters that you specify beside those automatically returned by AssureSign, you must properly URL encode the redirect string passed in the transfer to the landing page. For example, to specify

http://www.yoursite.com/completed.aspx?FirstName=Tom&LastName=Jones

you should pass in

http://www.yoursite.com/completed.aspx?FirstName=Tom&LastName=Jones