Continuous polling of open document status via calls to CheckStatus is not scalable, and is considered poor design. Appropriate handling for ensuring you have the most up to date status is to perform a DocumentTRAK web hook operation on document life cycle events.
The CheckStatus operation is used to query the current status of a document (for example, whether the document is completed).
The CheckStatus 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)
<?xml version="1.0" encoding="utf-8"?> <CheckStatus xmlns="https://www.assuresign.net/Services/DocumentNOW/CheckStatus"> <DocumentStatusChecks> <DocumentStatusCheck ContextIdentifier="06C4A84A-693C-46CB-8DF2-40A8215AA056" Id="2CE11EF1-8938-DD11-8735-00065B8CE99B" AuthToken="8CC9A84B-693C-46CC-4342-40A8215AD76A" /> </DocumentStatusChecks> </CheckStatus>
The SOAP Action header is
A response will return a single enumerated status of the document with the date and time of the last update of the status:
<?xml version="1.0" encoding="utf-8"?> <CheckStatusResponse xmlns="https://www.assuresign.net/Services/DocumentNOW/CheckStatus"> <DocumentStatusCheckResults> <DocumentStatusCheckResult Id="2CE11EF1-8938-DD11-8735-00065B8CE99B" StatusDate="2008-03-19T11:24:08.5231954-04:00" StatusType="Completed" /> </DocumentStatusCheckResults> </CheckStatusResponse>
Possible values for StatusType include:
- SigningStepInProgress - signing pre-events have occurred and document is waiting for signatories to complete signing
- Completed - signed and concluded
- Expired - expiration date reached and signing is no longer possible
- Cancelled - a cancel was requested through the UI or via API, and signing is no longer possible
- Declined - a signatory declined to sign and signing is no longer possible
- Staled - document setup was not finalized, and document was removed from active status
- SignerAuthenticationFailed - authentication failed, however document is not yet marked as complete, expired or cancelled
The DocumentStatusCheckResult should be checked for the presence of an Exceptions element, which may contain multiple StatusCheckException items.
In the case that StatusType is SigningStepInProgress, then the StatusDetails attribute will contain additional information about the current active step ("Step 1", "Step 2", etc.).