The GetAccessLink operation allows you to query for the link to a document. Available links, depending on the state of the document, are:
- Original Document Link - link to the document as it existed prior to signing
- Interim Document Link - link to the document as it might be if signing has started but has not yet completed
- Completed Document Link - link to the document after signing has been completed
The completed document link is the same as generated by the Link - Final Document merge field used in DocumentTRAK and email notifications. The GetAccessLink operation might be used for sending your own notifications or making documents available via your own reporting tools.
The GetAccessLink 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 accessed (this is returned as an element in the returned XML from a document submission operation)
- the AuthToken of the document to be accessed (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 accessed (this is returned as an element in the returned XML from an envelope creation operation)
- The AuthToken of the envelope to be accessed (this is returned as an element in the returned XML from an envelope creation operation)
- for a document
- the DocumentType, one of ORIGINAL, INTERIM or COMPLETED
Optionally, you may specify:
- SignatoryId: when specified identifies the unique internal identifier of the signer for whom an access link should be generated (returned by the ListSignatories method)
- SignatoryEmail: if specified, identifies the email address of the signer for whom an access link should be generated. For example, this may be relevant in the case of requesting a link to an envelope where any one signatory may not have access to all the documents.
- SignatoryMobilePhone: If specified, identifies the mobile phone of the signer for whom an access link should be generated.
- LinkExpirationDate: if specified, indicates the expiration date to enforce for the requested link. Any use of the requested link 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).
Note: if a LinkExpirationDate is not passed then the default expirations defined in the Document Link Expiration Configuration account settings will be used as the basis for defining the link expirations.
An example of requesting the completed link on a single document:
<?xml version="1.0" encoding="utf-8"?> <GetAccessLink 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" DocumentType="Completed" /> </GetAccessLink >
The SOAP Action header is
A response is returned providing the signing links which will contain an Exceptions node only if some issue has occurred:
<GetAccessLinkResponse xmlns="https://www.assuresign.net/Services/DocumentNOW/Links"> <GetAccessLinkResult DocumentId="b1d35c31-8c70-4381-a71e-746ada30fbbf"> <Link DocumentId="2CE11EF1-8938-DD11-8735-00065B8CE99B" SignatoryId="77d5d1bc-d759-4705-bf4c-6f5aba2ae33e" SignatoryEmail="firstname.lastname@example.org" SignatoryMobilePhone="3055556789" Url="https://sb.assuresign.net/link?id=be5d095f-9afd-440e-ba94-9efb067e1a4e&signature=YfvGxW7-eQAub9j4q1JKTe0CA31eD23udhE2s4p33MA" ExpirationDate="2015-04-10T23:59:59" DocumentType="Completed" /> </GetAccessLinkResult > </GetAccessLinkResponse>
The GetAccessLinkResult should be checked for the presence of an Exceptions element, which may contain multiple LinkException items.