Updates the lock duration or the lockedByApp property for the specified envelope. The user must match the user specified by the lockByUser property, and the integrator key that you pass in must match the integrator key information. You must also include the X-DocuSign-Edit header, which contains a lockToken that proves ownership of the lock and the lockDurationInSeconds. The token that you need for this header is returned in the response to the POST and GET methods.

Example:

X-DocuSign-Edit:<DocuSignEdit><LockToken>{{lockToken}}</LockToken></DocuSignEdit>

Request

HTTP request

PUT /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
200

Successful response.

EnvelopeLocks
400

Error encountered.

errorDetails

SDK Method

Envelopes::updateLock

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> 
}} />