---
title: "REST - Lock"
canonical: "https://help.agiloft.com/space/HELP/43714340/REST+-+Lock"
format: markdown
---
The EWLock operation locks, unlocks, or checks the lock status of a record in the specified KB and table.

- **Returns**: the lock status.
- **Supported Content-Type**: <span style="color: #505050">application/</span>x-www-form-urlencoded
- Accepts a URL with URL-encoded parameters and record data. For more information about general URL conventions, see [REST Interface](https://wiki.agiloft.com/display/PROD/REST+Interface).

### > Macro (anchor)

Get the Lock Status of a Record

To get the lock status of a record, make an HTTP GET request with the following parameters:

| **Parameter** | **Value** | **Required** | **Description** |
| --- | --- | --- | --- |
| $table | The logical name of the table | yes | The table identifier |
| id | The table entry id | yes | ID of the entry to check the lock status for |

This is an example URL with the standard authentication using username/password. You can also use other types of authentication, such as an OAuth access token or JWT)

```
https://yourserver.com/ewws/EWLock?$KB=Demo&$login=*username*&$password=*password*&$lang=en &$table=al_as_agreements&id=18
```

If the request succeeds, the server then returns a JSON answer with the following keys:

| **Parameter** | **Value** |
| --- | --- |
| id | Entry ID |
| table_id | Numeric system identifier of the table |
| locked_by | Login of the user who locked the record |
| lock_status | The status of the lock. The following types are possible:<br>- NO_LOCK: when an entry has no lock
- LOCKED: when an entry is locked by the user |
| lock_expires_in_minutes | Expiration time of the lock, in minutes. This is a countdown of how many minutes remain, not the starting value. |

If the request fails, the server then returns a JSON answer with the error code and description:

| **Parameter** | **Value** |
| --- | --- |
| error | Error code. See error code descriptions below |
| error_description | Returns text describing why the request failed |

The following error codes can be transmitted:

| **Code** | **Description** |
| --- | --- |
| BAD_REQUEST | The request is missing a required parameter. This could be an invalid parameter value, duplicate parameters, etc. |
| UNAUTHORIZED | The client is not authorized to request an authorization code using this method |
| FORBIDDEN | The resource owner or server denied the request |
| CONFLICT | Requested changes will not be applied due to another user's requested changes |
| SERVER_ERROR | The server encountered an unexpected condition that prevented it from fulfilling the request |

Here is an example of a response that could be sent to the client:

```
HTTP/1.1 200 OK {"id":18,"table_id":2788,"locked_by":"admin","lock_status":"LOCKED","lock_expires_in_minutes":25}
```

<span style="color: #0752a0">Lock a Record</span>

To lock a record, make an HTTP PUT request with the following parameters:

| **Parameter** | **Value** | **Required** | **Description** |
| --- | --- | --- | --- |
| $table | The logical name of the table | yes | The table identifier |
| id | The table entry id | yes | the record ID |

Here is an example request a client might send. The expiration time of the lock is set by value of global variable lock_expiration_time from **Setup > System > Manage Global Variables**.

```
PUT /ewws/EWLock HTTP/1.1 Host: yourdomain.com $KB=Demo& id=18
```

The server then returns a JSON answer with the keys described in the [Get the Lock Status of a Record](#REST-Lock-1) section above. The JSON answer would show the locked_by user and the lock_status should now be LOCKED.

Here is an example request using a cURL utility:

```
curl -is -X PUT "https://server_example/ewws/EW
?%24KB=Demo&%24login=admin&%24password=***&%24table=al_as_agreements&%24lang=en&id=18"
```

Here is an example response:

```
HTTP/1.1 200 OK Content-Type: application/json;charset=UTF-8 {"id":18,"table_id":2788,"locked_by":"admin","lock_status":"LOCKED","lock_expires_in_minutes":25}
```

<span style="color: #0752a0">Unlock a Record</span>

To unlock a record, make an HTTP DELETE request with the following parameters:

| **Parameter** | **Value** | **Required** | **Description** |
| --- | --- | --- | --- |
| $table | The logical name of the table | yes | The table identifier |
| id | The table entry id | yes | The record ID |
| force | Any value | no | This parameter can be added to the request if:<br>- There is a need to unlock a record in a table that has been locked by another user
- You are a member of the admin group |

Here is an example request:

```
DELETE /ewws/EWLock HTTP/1.1 Host: yourserver.com $KB=Demo& id=18
```

The server then returns a JSON answer with the keys described in the [Get the Lock Status of a Record](#REST-Lock-1) section above. The JSON answer should show the locked_by user and the lock_status should now be LOCKED.

Here is an example request using a cURL utility:

```
curl -is -X DELETE "https://server_example/ewws/EWLock
%24KB=Demo&%24login=admin&%24password=***&%24table=al_as_agreements&%24lang=en&id=18"
```

Here is an example response:

```
HTTP/1.1 200 OK Content-Type: application/json;charset=UTF-8 {"id":18,"table_id":2788,"lock_status":"NO_LOCK"}
```

#### Related articles

> Macro (contentbylabel)