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 returns a lockToken parameter. You must use the lockToken to update or delete an existing lock. You must also include the lockToken in the header for every PUT call that you make on the envelope while it is locked. If you do not include the lockToken, the system returns 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"
}

Note: Users must have envelope locking capability enabled to use this function (userSetting canLockEnvelopes must be set to true for the user).

Request

HTTP request

POST /v2.1/accounts/{accountId}/envelopes/{envelopeId}/lock

Parameters

Parameter NameValueDescription
Path Parameters
accountIdstring

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

envelopeIdstring

The envelope's GUID.

Example: 93be49ab-afa0-4adf-933c-f752070d71ec

Request Body

lockRequest

Responses

CodeDescriptionReference
201

Successful response.

EnvelopeLocks
400

Error encountered.

errorDetails

SDK Method

Envelopes::createLock

Definitions

errorDetails

This object describes errors that occur. It is only valid for responses and ignored in requests.

errorCodestring

The code associated with the error condition.

messagestring

A brief message describing the error condition.

lockRequest

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

lockDurationInSecondsstring

The number of seconds to lock the envelope for editing. This value must be greater than 0 seconds.

lockedByAppstring

The human-readable name of the application that is locking the envelope or template. This value displays to the user in error messages when lock conflicts occur.

lockTypestring

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

templatePasswordstring

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.

useScratchPadstring

When set to true, a scratchpad is used to edit information.

userInfo

accountIdstring

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

accountNamestring

The name of the account associated with the current workspace user.

activationAccessCodestring

Access code provided to the user to activate the account.

emailstring

errorDetailserrorDetails

This object describes errors that occur. It is only valid for responses and ignored in requests.

loginStatusstring

Boolean value that indicates whether the user is currently logged in or not.

membershipIdstring

The user's membership ID.

sendActivationEmailstring

When set to true, specifies that an activation email be sent to the user.

uristring

A URI containing the user ID.

userIdstring

The ID of the user to access. Generally this is the ID of the current authenticated user, but if the authenticated user is an Administrator on the account, userId can represent another user whom the Administrator is accessing.

userNamestring

The name of the user.

userStatusstring

Status of the user's account. One of:

  • ActivationRequired
  • ActivationSent
  • Active
  • Closed
  • Disabled

userTypestring

The type of user, for example CompanyUser.

EnvelopeLocks

This section provides information about envelope locks.

errorDetailserrorDetails

This object describes errors that occur. It is only valid for responses and ignored in requests.

lockDurationInSecondsstring

Sets the time, in seconds, until the lock expires when there is no activity on the envelope.

The default value is 300 seconds. The maximum value is 1,800 seconds.

The lock duration can be extended.

lockedByAppstring

The human-readable name of the application that is locking the envelope or template. This value displays to the user in error messages when lock conflicts occur.

lockedByUseruserInfo

A complex type containing information about the user that has the envelope or template locked.

lockedUntilDateTimestring

The date and time that the lock expires.

lockTokenstring

A unique identifier provided to the owner of the lock. You must use this token with subsequent calls to prove ownership of the lock.

lockTypestring

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

useScratchPadstring

When set to true, a scratchpad is used to edit information.

Examples

Generic JSON Request/Response

Request
{
  "lockedByApp": "sample string 1",
  "lockDurationInSeconds": "sample string 2",
  "lockType": "sample string 3",
  "useScratchPad": "sample string 4",
  "templatePassword": "sample string 5"
}
Response
{
  "lockedByUser": {
    "userName": "sample string 1",
    "userId": "sample string 2",
    "email": "sample string 3",
    "userType": "sample string 4",
    "userStatus": "sample string 5",
    "uri": "sample string 6",
    "loginStatus": "sample string 7",
    "sendActivationEmail": "sample string 8",
    "activationAccessCode": "sample string 9",
    "errorDetails": {
      "errorCode": "sample string 1",
      "message": "sample string 2"
    }
  },
  "lockedByApp": "sample string 1",
  "lockedUntilDateTime": "sample string 2",
  "lockDurationInSeconds": "sample string 3",
  "lockType": "sample string 4",
  "useScratchPad": "sample string 5",
  "lockToken": "sample string 6",
  "errorDetails": {
    "errorCode": "SUCCESS",
    "message": ""
  }
}
Generic XML Request/Response

Request
<lockRequest xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.docusign.com/restapi">
  <lockDurationInSeconds>sample string 2</lockDurationInSeconds>
  <lockType>sample string 3</lockType>
  <lockedByApp>sample string 1</lockedByApp>
  <templatePassword>sample string 5</templatePassword>
  <useScratchPad>sample string 4</useScratchPad>
</lockRequest> 
Response
<lockInformation xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.docusign.com/restapi">
  <errorDetails>
    <errorCode>SUCCESS</errorCode>
    <message></message>
  </errorDetails>
  <lockDurationInSeconds>sample string 3</lockDurationInSeconds>
  <lockToken>sample string 6</lockToken>
  <lockType>sample string 4</lockType>
  <lockedByApp>sample string 1</lockedByApp>
  <lockedByUser>
    <activationAccessCode>sample string 9</activationAccessCode>
    <email>sample string 3</email>
    <errorDetails>
      <errorCode>sample string 1</errorCode>
      <message>sample string 2</message>
    </errorDetails>
    <loginStatus>sample string 7</loginStatus>
    <sendActivationEmail>sample string 8</sendActivationEmail>
    <uri>sample string 6</uri>
    <userId>sample string 2</userId>
    <userName>sample string 1</userName>
    <userStatus>sample string 5</userStatus>
    <userType>sample string 4</userType>
  </lockedByUser>
  <lockedUntilDateTime>sample string 2</lockedUntilDateTime>
  <useScratchPad>sample string 5</useScratchPad>
</lockInformation> 
}} />