Locks the specified envelope, and sets the time until the lock expires, to prevent other users or recipients from accessing and changing the envelope.

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/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. Eg 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

An error code associated with the error.

messagestring

A short error message.

lockRequest

lockDurationInSecondsstring

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

lockedByAppstring

A friendly name of the application used to lock the envelope. Will be used in error messages to the user when lock conflicts occur.

lockTypestring

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

templatePasswordstring

useScratchPadstring

Reserved for future use.

Indicates whether a scratchpad is used for editing information.

userInfo

activationAccessCodestring

emailstring

errorDetailserrorDetails

loginStatusstring

sendActivationEmailstring

uristring

userIdstring

The user ID of the user being accessed. Generally this is the user ID of the authenticated user, but if the authenticated user is an Admin on the account, this may be another user the Admin user is accessing. Note: For GET /v2/accounts/{accountId}/envelopes user_id query parameter is not implemented and should not be used.

userNamestring

userStatusstring

Status of the user's account. One of:

  • ActivationRequired
  • ActivationSent
  • Active
  • Closed
  • Disabled

userTypestring

EnvelopeLocks

Envelope locks

errorDetailserrorDetails

lockDurationInSecondsstring

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

If no value is entered, then the default value of 300 seconds is used. The maximum value is 1,800 seconds.

The lock duration can be extended.

lockedByAppstring

Specifies the friendly name of the application that is locking the envelope.

lockedByUseruserInfo

A complex type containing information about the user that has the Envelope or Template locked.

lockedUntilDateTimestring

The datetime until the envelope lock expires.

lockTokenstring

A unique identifier provided to the owner of the envelope lock. Used to prove ownership of the lock.

lockTypestring

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

useScratchPadstring

Reserved for future use.

Indicates whether a scratchpad is used for editing 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> 
}} />