Docusign eSignature API
Docusign Developer CenterGet a developer account
HomeAPI ReferenceSDKsContext Plugin
Envelope Locks

Locks an envelope

POST
/v2.1/accounts/{accountId}/envelopes/{envelopeId}/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" }    orX-DocuSign-Edit:<DocuSignEdit><LockToken>token-from-response</LockToken><LockDurationInSeconds>600</LockDurationInSeconds></DocuSignEdit>

Related topics

Authorization

OAuth2
AuthorizationBearer <token>

OAuth 2.0 access token obtained via Authorization Code Grant or JWT Grant.

In: header

Path Parameters

accountId*string

The external account number (int) or account ID GUID.

envelopeId*string

The envelope's GUID.

Example: 93be49ab-xxxx-xxxx-xxxx-f752070d71ec

Request Body

application/json

This request object contains information about the lock that you want to create or update.

lockDurationInSeconds?string

The number of seconds to lock the envelope for editing. Must be greater than 0 seconds.

lockedByApp?string

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

The type of lock. Currently edit is the only supported type.

templatePassword?string

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

When true, a scratchpad is used to edit information.

Response Body

application/json

application/json

curl -X POST "https://example.com/v2.1/accounts/string/envelopes/string/lock" \  -H "Content-Type: application/json" \  -d '{}'
{  "errorDetails": {    "errorCode": "string",    "message": "string"  },  "lockDurationInSeconds": "string",  "lockedByApp": "string",  "lockedByUser": {    "accountId": "string",    "accountName": "string",    "activationAccessCode": "string",    "email": "string",    "errorDetails": {      "errorCode": "string",      "message": "string"    },    "ipAddress": "string",    "loginStatus": "string",    "membershipId": "string",    "sendActivationEmail": "string",    "uri": "string",    "userId": "string",    "userName": "string",    "userStatus": "string",    "userType": "string"  },  "lockedUntilDateTime": "string",  "lockToken": "string",  "lockType": "string",  "useScratchPad": "string"}

Gets envelope lock information GET

Retrieves general information about an envelope lock. The user requesting the information must be the same user who locked the envelope. You can use this method to recover the lock information, including the `lockToken`, for a locked envelope. The `X-DocuSign-Edit` header is included in the response. See [EnvelopeLocks: create](https://developers.docusign.com/docs/esign-rest-api/reference/envelopes/envelopelocks/create/) for a description of the `X-DocuSign-Edit` header. ### Related topics - [Common API Tasks: Locking and unlocking envelopes](https://www.docusign.com/blog/dsdev-common-api-tasks-locking-and-unlocking-envelopes)

Deletes an envelope lock DELETE

Deletes the lock from the specified envelope. The user deleting the lock must be the same user who locked the envelope. You must include the `X-DocuSign-Edit` header as described in [EnvelopeLocks: create](https://developers.docusign.com/docs/esign-rest-api/reference/envelopes/envelopelocks/create/). This method takes an optional query parameter that lets you specify whether changes made while the envelope was locked are kept or discarded. | Query Parameter | Description | | :-------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `save_changes` | When **true** (the default), any changes made while the lock was active are saved. When **false,** any changes made while the envelope was locked are discarded. | ### Related topics - [Common API Tasks: Locking and unlocking envelopes](https://www.docusign.com/blog/dsdev-common-api-tasks-locking-and-unlocking-envelopes)