docusign.envelope-locks.post-envelope-lock

This method locks the specified envelope and sets the time until the lock expires to prevent other users or recipients from changing the envelope. The response to this request includes a lockToken parameter that you must use in the X-DocuSign-Edit header for every PUT method (typically a method that updates an envelope) while the envelope is locked. If you do not provide the lockToken when accessing a locked envelope, you will get the following error: { "errorCode": "EDIT_LOCK_NOT_LOCK_OWNER", "message": "The user is not the owner of the lock. The template is locked by another user or in another application" } ### The X-DocuSign-Edit header The X-DocuSign-Edit header looks like this and can be specified in either JSON or XML. JSON { "LockToken": "token-from-response", "LockDurationInSeconds": "600" } XML <DocuSignEdit> <LockToken>token-from-response</LockToken> <LockDurationInSeconds>600</LockDurationInSeconds> </DocuSignEdit> In the actual HTTP header, you would remove the linebreaks: X-DocuSign-Edit: {"LockToken": "token-from-response", "LockDurationInSeconds": "600" } or X-DocuSign-Edit:<DocuSignEdit><LockToken>token-from-response</LockToken><LockDurationInSeconds>600</LockDurationInSeconds></DocuSignEdit> ### Related topics - Common API Tasks: Locking and unlocking envelopes

Locks an envelope.

Overview

Property	Value
Workflow type	Atomic
Library	App-docusign
Version	1.0

Input Schema

Field	Type	Required	Default	Description
`base_url`	string	Yes	—	Docusign API root, e.g. https://<host>/api
`api_token`	string	No	—	Bearer token; omit to use the workflow's token env var
`accountid`	string	Yes	—	The external account number (int) or account ID GUID.
`envelopeid`	string	Yes	—	The envelope's GUID. Example: `93be49ab-xxxx-xxxx-xxxx-f752070d71ec`
`lockdurationinseconds`	string	No	—	The number of seconds to lock the envelope for editing. Must be greater than 0 seconds.
`lockedbyapp`	string	No	—	A friendly name of the application used to lock the envelope. Will be used in error messages to the user when lock conflicts occur.
`locktype`	string	No	—	The type of lock. Currently `edit` is the only supported type.
`templatepassword`	string	No	—	The password for the template. If you are using a lock for a template that has a password or an envelope that is based on a template that has a password, you must enter the `templatePassword` to save the changes.
`usescratchpad`	string	No	—	When true, a scratchpad is used to edit information.

Output Schema

Field	Type	Required	Default	Description
`base_url`	string	Yes	—	Docusign API root, e.g. https://<host>/api
`api_token`	string	No	—	Bearer token; omit to use the workflow's token env var
`accountid`	string	Yes	—	The external account number (int) or account ID GUID.
`envelopeid`	string	Yes	—	The envelope's GUID. Example: `93be49ab-xxxx-xxxx-xxxx-f752070d71ec`
`lockdurationinseconds`	string	No	—	The number of seconds to lock the envelope for editing. Must be greater than 0 seconds.
`lockedbyapp`	string	No	—	A friendly name of the application used to lock the envelope. Will be used in error messages to the user when lock conflicts occur.
`locktype`	string	No	—	The type of lock. Currently `edit` is the only supported type.
`templatepassword`	string	No	—	The password for the template. If you are using a lock for a template that has a password or an envelope that is based on a template that has a password, you must enter the `templatePassword` to save the changes.
`usescratchpad`	string	No	—	When true, a scratchpad is used to edit information.
`status_code`	integer	No	—	HTTP status code of the completed call
`response`	json	No	—	Parsed JSON response body
`failure_reason`	string	No	—	—
`failure_type`	string	No	—	—
`failed_at`	string	No	—	—
`failed_step`	string	No	—	—
`failed_layer`	string	No	—	—
`failed_at_state`	string	No	—	—
`error`	string	No	—	—
`error_type`	string	No	—	—

States

State	Initial	Terminal	Success	Auto-advance	Description
`pending`	Yes	No	—	`execute`	Waiting to call POST /v2.1/accounts/{accountId}/envelopes/{envelopeId}/lock
`completed`	No	Yes	Yes	—	HTTP call succeeded
`failed`	No	Yes	No	—	HTTP call failed

State Diagram

Transitions

From	Action	To	Description
`pending`	`execute`	`completed`	Perform POST /v2.1/accounts/{accountId}/envelopes/{envelopeId}/lock
`*` (any state)	`fail`	`failed`	Record the failure reason

API Usage

bash

POST /api/workflows/start
Content-Type: application/json

{
  "workflow_type": "docusign.envelope-locks.post-envelope-lock",
  "initial_data": {
    "base_url": "value",
    "accountid": "value",
    "envelopeid": "value"
  }
}

docusign.envelope-locks.post-envelope-lock ​

Overview ​

Input Schema ​

Output Schema ​

States ​

State Diagram ​

Transitions ​

API Usage ​