AssureSign: GetSigningLinks

The GetSigningLinks operation allows you to query for the signing links to present to signatories on a document or envelope. This method should be used if you are presenting links to signing sessions yourself (sometimes referred to as Immediate Presentment  rather than via AssureSign emails.

A typical mechanism used to find the correct link for a specific signer is to match either the signer's email address or mobile phone to the SignatoryEmail or SignatoryMobilePhone values of a returned SigningLink element.

The GetSigningLinks operation requires knowledge of the following:

• the AssureSign account ContextIdentifier (this is exposed in the AssureSign administrative application account settings and serves to provide some security to the transaction)
• Either, document or envelope identifiers:
  • for a document
    • the DocumentId of the document to be signed (this is returned as an element in the returned XML from a document submission operation)
    • the AuthToken of the document to be signed (this is returned as an element in the returned XML from a document submission operation)
  • or for an envelope
    • The EnvelopeId of the envelope to be signed (this is returned as an element in the returned XML from an envelope creation operation)
    • The AuthToken of the envelope to be signed (this is returned as an element in the returned XML from an envelope creation  operation)

Optionally, you may specify:

• IncludeOnlyCurrentSigners: when true, results will be filtered to include signing links for signers that are assigned to the current signing step in the specified document or to the current signing step in any document currently available for signing in the specified envelope.
• IsAuthenticated: when true, the returned link will bypass the landing page and take the signer directly to the signing page. Important: if the specified account is not explicitly configured to allow the landing page to be bypassed, this property will be ignored during processing.
• LinkExpirationDate: if specified, indicates the expiration date to enforce for the requested signing link(s). Any use of the requested signing links after the specified expiration date will result in the display of a "link has expired" message. This will always be interpreted as being in Coordinated Universal Time (UTC).
• RedirectUrl: a URL that signers will be redirected to after signing (see information on what data is passed in the redirect process )

Note: if a LinkExpirationDate is not passed then the default Signing Link expiration defined in the Document Link Expiration Configuration account settings  will be used as the basis for defining the link expirations.

Sample XML

An example of requesting the signing links only for current signers on a single document:

<?xml version="1.0" encoding="utf-8"?> 
<GetSigningLinks xmlns="https://www.assuresign.net/Services/DocumentNOW/Links">
    <Request ContextIdentifier="06C4A84A-693C-46CB-8DF2-40A8215AA056" DocumentId="2CE11EF1-8938-DD11-8735-00065B8CE99B" DocumentAuthToken="2CE11EF1-8938-DD11-8735-00065B8CE99B" LinkExpirationDate="2015-04-10T23:59:59" IncludeOnlyCurrentSigners="true" IsAuthenticated="false" />
</GetSigningLinks>

The SOAP Action header is

https://www.assuresign.net/Services/DocumentNOW/Links/ILinkService/GetSigningLinks

A response is returned providing the signing links which will contain an Exceptions node only if some issue has occurred:

<GetSigningLinksResponse xmlns="https://www.assuresign.net/Services/DocumentNOW/Links">
  <GetSigningLinksResult DocumentId="b1d35c31-8c70-4381-a71e-746ada30fbbf">
    <SigningLinks>
      <SigningLink DocumentId="2CE11EF1-8938-DD11-8735-00065B8CE99B" SignatoryId="77d5d1bc-d759-4705-bf4c-6f5aba2ae33e" SignatoryEmail="signer1@example.com" SignatoryMobilePhone="3055556789" Url="https://www.assuresign.net/link?id=81a8245d-e2f3-4a90-8151-034a25fe5301&amp;signature=OaJar0IZL_KGZ99BkQ7ryPTfJeh9JOHNADqXFxcMED8." ExpirationDate="2015-04-10T23:59:59" />
      <SigningLink DocumentId="2CE11EF1-8938-DD11-8735-00065B8CE99B" SignatoryId="839495bf-c852-42fb-bfd9-ca91926a5844" SignatoryEmail="signer2@example.com" SignatoryMobilePhone="3135552345" Url="https://www.assuresign.net/link?id=aebd5125-5d54-467a-b47c-fad5e839a379&amp;signature=NbVXECAHTprX0Y-ADAq8duRL3Vu0vGcJvu4KWc0BkG8." ExpirationDate="2015-04-10T23:59:59" />
    </SigningLinks>
  </GetSigningLinksResult>
</GetSigningLinksResponse>

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