From the moment it is created until its termination, a transaction undergoes different states.
Start a transaction
A transaction is created in draft until it is started. Once the transaction is started, documents are ready to be processed by the first participants in queue. A started transaction can be updated if modifications do not affect tasks already completed by participants.
To start a transaction, send a request to POST /v1/transactions/{transaction_id}/start.
curl
https://api.universign.com/v1/transactions/tx_dy9Qn27PQ3mb/start \
The API returns a transaction object with a started_at date. Once the transaction is started, you can still update it dynamically, as long as your requests are compatible with either the state of the resource or sub-resource you interact with, and coherent with the signature flow. For example, it is not possible to change a document name after the document has been signed. Nor is it possible to update a signer’s details once s/he has signed.
Pause a transaction
When a transaction is paused, you can edit it with no immediate effect. Modifications will be effective when you restart the transaction. While the transaction is paused, participants cannot complete any of the required actions on the signature page and do not receive notifications. Note that pausing a transaction does not impact its expiration: the countdown still runs normally. A paused transaction will therefore expire if not restarted after the allowed duration.
To pause a transaction, send a request to POST /v1/transactions/{transaction_id}/pause.
curl
https://api.universign.com/v1/transactions/tx_dy9Qn27PQ3mb/pause \
The API returns a transaction object with a paused state. Although participants will no longer be able to access a paused transaction nor receive notifications, please note that pausing a transaction does not affect its expiration. If you wish to postpone the transaction expiration date, you need to do so by updating the transaction (note that a transaction duration cannot exceed 45 days after it is started).
Cancel a transaction
A cancelled transaction can no longer be edited, and partially signed documents cannot be retrieved. If a transaction was in draft state before cancellation, it is permanently deleted after 24 hours. If it was started or paused before cancellation, it is permanently deleted after 60 or 180 days depending on your workspace configuration.
To cancel a transaction, send a request to POST /v1/transactions/{transaction_id}/cancel.
curl
https://api.universign.com/v1/transactions/tx_dy9Qn27PQ3mb/cancel \
The API returns a transaction object with a cancelled state and a cancel_code if you specified one. If you try to cancel a transaction with any other state than draft, started or paused, you are returned an API error. Please note that cancelled transactions are permanently deleted from the system after 60 days. Also, note that it is not possible to download documents from a cancelled transaction, even if they have been signed partially.
Retrieve a transaction
To retrieve information about a specific transaction initiated by your workspace, send a request to GET /v1/transactions/{transaction_id}/.
curl
https://api.universign.com/v1/transactions/tx_dy9Qn27PQ3mb \
The API returns a transaction object, as it was last updated.
List all transactions
To retrieve all the transactions initiated by your workspace that you have the permission to edit and/or view, send a request to GET /v1/transactions and set optional filters to refine your request.
curl
https://api.universign.com/v1/transactions?size=5&state=started&text_search=^contract \
The API returns the list of all transactions matching your request.
