### Install Automat

Source: https://apidocsv2.livionkey.com/index

Installs a new key automat into the LivionKey system, registering its details and location.

```APIDOC
## POST /v2/automats/install

### Description
Installs a new key automat to LivionKey system.

### Method
POST

### Endpoint
/v2/automats/install

### Parameters
#### Request Body
- **name** (string) - Required - Logical name of the automat (e.g., 'Mainstreet 1').
- **organizationUnitId** (string) - Optional - The organization unit ID for the installation location.
- **label** (string) - Optional - A label to differentiate multiple key automats (e.g., 'A', 'B').
- **groupId** (string) - Optional - The ID of the group to which the automat belongs.
- **address** (string) - Required - The street address of the automat.
- **postalCode** (string) - Required - The postal code of the automat.
- **postalOffice** (string) - Required - The postal office of the automat.
- **timezone** (string) - Required - The timezone of the automat (e.g., 'Europe/Helsinki').
- **product** (string) - Required - Enum: "key20" "key30". The product identifier for the automat.

### Request Example
```json
{
  "name": "string",
  "organizationUnitId": "string",
  "label": "string",
  "groupId": "string",
  "address": "string",
  "postalCode": "string",
  "postalOffice": "string",
  "timezone": "string",
  "product": "key20"
}
```

### Response
#### Success Response (201)
- **id** (string) - The unique identifier of the installed automat.
- **name** (string) - The name of the automat.
- **location** (object) - The location of the automat.
  - **address** (string) - The street address.
  - **postalCode** (string) - The postal code.
  - **postalOffice** (string) - The postal office.
- **label** (string) - The device label.
- **groups** (array of objects) - An array of groups the automat belongs to.
  - **id** (string) - The group ID.
  - **name** (string) - The group name.
- **hwId** (string) - The hardware identifier of the automat.
- **timezone** (string) - The timezone of the automat.
- **installationPincode** (string) - The installation pincode.
- **lockers** (array of objects) - Information about the lockers in the automat.
  - **lockerIndex** (string) - The index of the locker.
  - **isKeyInside** (boolean) - Indicates if a key is inside the locker.
  - **key** (object or null) - Information about the key if present.
    - **id** (string) - The key ID.
    - **name** (string) - The key name.
- **lifecycleState** (string) - The current lifecycle state of the automat.

#### Response Example (201)
```json
{
  "id": "string",
  "name": "string",
  "location": {
    "address": "string",
    "postalCode": "00100",
    "postalOffice": "Helsinki"
  },
  "label": "string",
  "groups": [
    {
      "id": "string",
      "name": "string"
    }
  ],
  "hwId": "string",
  "timezone": "string",
  "installationPincode": "string",
  "lockers": [
    {
      "lockerIndex": "0",
      "isKeyInside": true,
      "key": {
        "id": "7c813082-8786-4a71-a3b5-30bf10004fe1",
        "name": "740FE4C"
      }
    },
    {
      "lockerIndex": "1",
      "isKeyInside": false,
      "key": null
    }
  ],
  "lifecycleState": "string"
}
```
```

--------------------------------

### Install Automats (POST)

Source: https://apidocsv2.livionkey.com/index

Installs a new key automat into the LivionKey system. Requires a JSON payload with details such as name, address, postal code, postal office, timezone, and product type. Optional fields include organizationUnitId, label, and groupId.

```json
{
  "name": "string",
  "organizationUnitId": "string",
  "label": "string",
  "groupId": "string",
  "address": "string",
  "postalCode": "string",
  "postalOffice": "string",
  "timezone": "string",
  "product": "key20"
}
```

--------------------------------

### Get Mechanical Key by ID (GET)

Source: https://apidocsv2.livionkey.com/index

Fetches a single mechanical key by its unique identifier. Requires the key's ID in the path. Returns the full details of the key if found, or a 404 error if the key does not exist.

```HTTP
GET /v2/mechanical/keys/{id}
```

--------------------------------

### Get List of Automats

Source: https://apidocsv2.livionkey.com/index

Retrieves a list of automats. Supports pagination and filtering by product type.

```APIDOC
## GET /v2/automats

### Description
Retrieves a list of automats. Supports pagination and filtering by product type.

### Method
GET

### Endpoint
/v2/automats

### Parameters
#### Query Parameters
- **after** (string) - Optional - Number of items to skip for pagination.
- **limit** (number) - Optional - Number of items to return. Default is 20, Max is 100.
- **products** (array of strings) - Optional - Filter automats by product types. Items Enum: "key30" "key20". Defaults to ["key30", "key20"] if not specified. Use comma-separated values for multiple products.

### Responses
#### Success Response (200)
- **after** (string) - Identifier for the next page of results.
- **limit** (number) - The limit of items returned per page.
- **hasNext** (boolean) - Indicates if there are more pages of results.
- **data** (array) - An array of automat objects.
  - **id** (string) - The unique identifier of the automat.
  - **name** (string) - The name of the automat.
  - **location** (object) - The location details of the automat.
    - **address** (string) - The street address.
    - **postalCode** (string) - The postal code.
    - **postalOffice** (string) - The postal office.
  - **label** (string) - A label for the automat.
  - **groups** (array) - An array of group objects associated with the automat.
    - **id** (string) - The unique identifier of the group.
    - **name** (string) - The name of the group.
  - **hwId** (string) - The hardware identifier of the automat.
  - **timezone** (string) - The timezone of the automat.
  - **installationPincode** (string) - The installation PIN code for the automat.
  - **lockers** (array) - An array of locker objects within the automat.
    - **lockerIndex** (string) - The index of the locker.
    - **isKeyInside** (boolean) - Indicates if a key is inside the locker.
    - **key** (object|null) - Details of the key if present.
      - **id** (string) - The unique identifier of the key.
      - **name** (string) - The name or identifier of the key.
  - **lifecycleState** (string) - The current lifecycle state of the automat.

### Response Example
```json
{
  "after": "string",
  "limit": 0,
  "hasNext": true,
  "data": [
    {
      "id": "string",
      "name": "string",
      "location": {
        "address": "string",
        "postalCode": "00100",
        "postalOffice": "Helsinki"
      },
      "label": "string",
      "groups": [
        {
          "id": "string",
          "name": "string"
        }
      ],
      "hwId": "string",
      "timezone": "string",
      "installationPincode": "string",
      "lockers": [
        {
          "lockerIndex": "0",
          "isKeyInside": true,
          "key": {
            "id": "7c813082-8786-4a71-a3b5-30bf10004fe1",
            "name": "740FE4C"
          }
        },
        {
          "lockerIndex": "1",
          "isKeyInside": false,
          "key": null
        }
      ],
      "lifecycleState": "string"
    }
  ]
}
```
```

--------------------------------

### Automat Response Sample

Source: https://apidocsv2.livionkey.com/index

This is a sample JSON response for an automat. It includes details like ID, name, location, groups, hardware ID, timezone, installation pincode, locker status, and lifecycle state.

```json
{
  "id": "string",
  "name": "string",
  "location": {
    "address": "string",
    "postalCode": "00100",
    "postalOffice": "Helsinki"
  },
  "label": "string",
  "groups": [
    {
      "id": "string",
      "name": "string"
    }
  ],
  "hwId": "string",
  "timezone": "string",
  "installationPincode": "string",
  "lockers": [
    {
      "lockerIndex": "0",
      "isKeyInside": true,
      "key": {
        "id": "7c813082-8786-4a71-a3b5-30bf10004fe1",
        "name": "740FE4C"
      }
    },
    {
      "lockerIndex": "1",
      "isKeyInside": false,
      "key": null
    }
  ],
  "lifecycleState": "string"
}
```

--------------------------------

### Response Sample for Created Key Contract (JSON)

Source: https://apidocsv2.livionkey.com/index

This JSON structure represents a successful response after creating a key contract. It includes a unique contract ID, access right IDs, start and end times, detailed contact information with notification settings, and information about the keys, including their status and storage details.

```json
{
  "id": "string",
  "accessRightIds": [
    "string"
  ],
  "start": "2019-08-24T14:15:22Z",
  "end": "2019-08-24T14:15:22Z",
  "contact": {
    "name": "John Doe",
    "email": "john.doe@livion.fi",
    "phoneNumber": "+358401234567",
    "sendSms": true,
    "sendEmail": true,
    "language": "en | fi | sv | de | no | fr",
    "iloqPersonId": "f5ac6bce-eac9-4508-a5cf-a0114dc06477",
    "notifications": {
      "contractKeyFetched": {
        "sms": false,
        "email": false
      },
      "contractKeyReturned": {
        "sms": false,
        "email": false
      },
      "contractCreated": {
        "sms": false,
        "email": false
      },
      "contractStartReminder": {
        "sms": false,
        "email": false
      },
      "contractEndReminder": {
        "sms": false,
        "email": false
      },
      "contractKeysNotReturned": {
        "sms": false,
        "email": true
      },
      "contractUpdated": {
        "sms": false,
        "email": false
      },
      "contractSignatureRequested": {
        "sms": false,
        "email": false
      }
    }
  },
  "keys": [
    {
      "id": "f5ac6bce-eac9-4508-a5cf-a0114dc06477",
      "status": "key-fetched",
      "storageInfo": {
        "deviceId": "00331",
        "pincode": "233123"
      },
      "inHistory": false
    }
  ],
  "numberOfKeys": 1,
  "keyIds": [
    "string"
  ],
  "keyAutomatId": "string",
  "groupId": "string",
  "contractType": 1
}
```

--------------------------------

### Create Fetch-Only Contract for Mechanical Keys (JSON)

Source: https://apidocsv2.livionkey.com/index

Creates a fetch-only contract for mechanical keys, typically used for keys stored in an automat. It requires a start date, contact information, and the keys to be fetched, optionally including user verification details.

```json
{
  "start": "2025-02-16T08:20:00.000Z",
  "contact": {
    "name": "John Doe",
    "email": "john.doe@livion.fi",
    "phoneNumber": "+358401234567",
    "sendSms": true,
    "sendEmail": true,
    "language": "en"
  },
  "keys": [
    {
      "id": "keyId",
      "storageInfo": {
        "pincode": "123456"
      }
    }
  ]
}
```

--------------------------------

### Create Return-Only Contract (JSON)

Source: https://apidocsv2.livionkey.com/index

Creates a return-only contract, specifying the start and end dates, contact information, and the keys to be included. This contract type is used when keys are loaned out and must be returned.

```json
{
  "end": "2025-02-20T08:20:00.000Z",
  "contact": {
    "name": "John Doe",
    "email": "john.doe@livion.fi",
    "phoneNumber": "+358401234567",
    "sendSms": true,
    "sendEmail": true,
    "language": "en"
  },
  "keys": [
    {
      "id": "keyId1"
    },
    {
      "id": "keyId2"
    }
  ]
}
```

--------------------------------

### Get List of Groups Response Sample

Source: https://apidocsv2.livionkey.com/index

This JSON response provides a paginated list of groups. It includes pagination details like 'after', 'limit', and 'hasNext', along with an array of group data.

```json
{
  "after": "string",
  "limit": 0,
  "hasNext": true,
  "data": [
    {
      "id": "string",
      "name": "string",
      "customerId": "string",
      "type": 1,
      "members": [
        {
          "id": "string",
          "name": "string"
        }
      ]
    }
  ]
}
```

--------------------------------

### List Mechanical Keys (GET)

Source: https://apidocsv2.livionkey.com/index

Retrieves a paginated list of mechanical keys. Supports filtering by various parameters like 'after', 'limit', 'search', 'selectedStorage', 'automatId', and 'organizationUnitId'. Returns a list of key objects with pagination information.

```HTTP
GET /v2/mechanical/keys?limit=20&after=string&search=string&selectedStorage=string&automatId=string&organizationUnitId=string
```

--------------------------------

### Response Sample for Listing Key Contracts (JSON)

Source: https://apidocsv2.livionkey.com/index

This JSON response provides a paginated list of key contracts. It includes pagination details like 'after', 'limit', and 'hasNext', along with an array 'data' containing contract objects. Each contract object mirrors the structure of a single contract response.

```json
{
  "after": "string",
  "limit": 0,
  "hasNext": true,
  "data": [
    {
      "id": "string",
      "accessRightIds": [
        "string"
      ],
      "start": "2019-08-24T14:15:22Z",
      "end": "2019-08-24T14:15:22Z",
      "contact": {
        "name": "John Doe",
        "email": "john.doe@livion.fi",
        "phoneNumber": "+358401234567",
        "sendSms": true,
        "sendEmail": true,
        "language": "en | fi | sv | de | no | fr",
        "iloqPersonId": "f5ac6bce-eac9-4508-a5cf-a0114dc06477",
        "notifications": {
          "contractKeyFetched": {
            "sms": false,
            "email": false
          },
          "contractKeyReturned": {
            "sms": false,
            "email": false
          },
          "contractCreated": {
            "sms": false,
            "email": false
          },
          "contractStartReminder": {
            "sms": false,
            "email": false
          },
          "contractEndReminder": {
            "sms": false,
            "email": false
          },
          "contractKeysNotReturned": {
            "sms": false,
            "email": true
          },
          "contractUpdated": {
            "sms": false,
            "email": false
          },
          "contractSignatureRequested": {
            "sms": false,
            "email": false
          }
        }
      },
      "keys": [
        {
          "id": "f5ac6bce-eac9-4508-a5cf-a0114dc06477",
          "status": "key-fetched",
          "storageInfo": {
            "deviceId": "00331",
            "pincode": "233123"
          },
          "inHistory": false
        }
      ],
      "numberOfKeys": 1,
      "keyIds": [
        "string"
      ],
      "keyAutomatId": "string",
      "groupId": "string",
      "contractType": 1
    }
  ]
}
```

--------------------------------

### Request Sample for Creating a Key Contract (JSON)

Source: https://apidocsv2.livionkey.com/index

This JSON payload demonstrates the structure for creating a new key contract. It includes details about the contract type, number of keys, pincodes, automat ID, access rights, validity period, and contact information. Ensure all required fields are populated correctly.

```json
{
  "input": {
    "contractType": 1,
    "numberOfKeys": 1,
    "pincodes": [
      "123444"
    ],
    "keyAutomatId": "253559",
    "accessRightIds": [
      "a1a68982-5f93-47cf-8701-3da907c6a987"
    ],
    "start": "2025-02-16T08:20:00.000Z",
    "end": "2025-02-20T08:20:00.000Z",
    "contact": {
      "name": "John doe",
      "email": "john.doe@livion.fi",
      "phoneNumber": "+358401234567",
      "language": "en",
      "sendSms": false,
      "sendEmail": true
    }
  }
}
```

--------------------------------

### Get Contract by ID

Source: https://apidocsv2.livionkey.com/index

Retrieves a specific key contract by its unique identifier.

```APIDOC
## GET /v2/iloq/keycontracts/{id}

### Description
Retrieves a specific key contract by its unique identifier.

### Method
GET

### Endpoint
/v2/iloq/keycontracts/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the contract to retrieve.

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the contract.
- **accessRightIds** (array of strings) - List of access right IDs associated with the contract.
- **start** (string) - The start date and time of the contract.
- **end** (string) - The end date and time of the contract.
- **contact** (object) - Contact person details.
  - **name** (string) - The name of the contact person.
  - **email** (string) - The email address of the contact person.
  - **phoneNumber** (string) - The phone number of the contact person.
  - **sendSms** (boolean) - Whether SMS notifications are sent.
  - **sendEmail** (boolean) - Whether email notifications are sent.
  - **language** (string) - The preferred language for communication.
  - **iloqPersonId** (string) - The ILOQ person ID.
  - **notifications** (object) - Notification settings.
- **keys** (array of objects) - Details of the keys associated with the contract.
  - **id** (string) - The unique identifier for the key.
  - **status** (string) - The current status of the key.
  - **storageInfo** (object) - Information about the key's storage location.
    - **deviceId** (string) - The ID of the device where the key is stored.
    - **pincode** (string) - The pincode for accessing the key.
  - **inHistory** (boolean) - Indicates if the key is in the history.
- **numberOfKeys** (number) - The total number of keys for the contract.
- **keyIds** (array of strings) - List of key IDs.
- **keyAutomatId** (string) - The ID of the key automat.
- **groupId** (string) - The group ID.
- **contractType** (number) - The type of contract.

#### Response Example
```json
{
  "id": "string",
  "accessRightIds": [
    "string"
  ],
  "start": "2019-08-24T14:15:22Z",
  "end": "2019-08-24T14:15:22Z",
  "contact": {
    "name": "John Doe",
    "email": "john.doe@livion.fi",
    "phoneNumber": "+358401234567",
    "sendSms": true,
    "sendEmail": true,
    "language": "en | fi | sv | de | no | fr",
    "iloqPersonId": "f5ac6bce-eac9-4508-a5cf-a0114dc06477",
    "notifications": {
      "contractKeyFetched": {
        "sms": false,
        "email": false
      },
      "contractKeyReturned": {
        "sms": false,
        "email": false
      },
      "contractCreated": {
        "sms": false,
        "email": false
      },
      "contractStartReminder": {
        "sms": false,
        "email": false
      },
      "contractEndReminder": {
        "sms": false,
        "email": false
      },
      "contractKeysNotReturned": {
        "sms": false,
        "email": true
      },
      "contractUpdated": {
        "sms": false,
        "email": false
      },
      "contractSignatureRequested": {
        "sms": false,
        "email": false
      }
    }
  },
  "keys": [
    {
      "id": "f5ac6bce-eac9-4508-a5cf-a0114dc06477",
      "status": "key-fetched",
      "storageInfo": {
        "deviceId": "00331",
        "pincode": "233123"
      },
      "inHistory": false
    }
  ],
  "numberOfKeys": 1,
  "keyIds": [
    "string"
  ],
  "keyAutomatId": "string",
  "groupId": "string",
  "contractType": 1
}
```
```

--------------------------------

### Create Group Response Sample

Source: https://apidocsv2.livionkey.com/index

This is a sample JSON response upon successful creation of a group. It includes the group's ID, name, customer ID, type, and a list of its members.

```json
{
  "id": "string",
  "name": "string",
  "customerId": "string",
  "type": 1,
  "members": [
    {
      "id": "string",
      "name": "string"
    }
  ]
}
```

--------------------------------

### GET /v2/mechanical/keys/{id}

Source: https://apidocsv2.livionkey.com/index

Retrieves a specific mechanical key by its unique identifier.

```APIDOC
## GET /v2/mechanical/keys/{id}

### Description
Retrieves a specific mechanical key by its unique identifier.

### Method
GET

### Endpoint
https://api.livionkey.com/v2/mechanical/keys/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the key.

### Response
#### Success Response (200)
- **name** (string) - The name of the key.
- **organizationUnitId** (string) - The ID of the organization unit the key belongs to.
- **id** (string) - The unique identifier for the key.
- **rfidHex** (string) - The RFID/NFC hex identifier.
- **selectedStorage** (object) - Information about the selected storage for the key.
  - **automatId** (string) - The ID of the automat where the key is selected to be stored.
- **storage** (object) - Information about the current storage of the key.
  - **automatId** (string) - The ID of the automat where the key is currently stored.
- **targetStorage** (object) - Information about the target storage for the key.
  - **automatId** (string) - The ID of the automat where the key is targeted to be stored.
- **status** (object) - The current status of the key.
  - **available** (boolean) - Indicates if the key is available.
- **shared** (boolean) - Indicates if the key is shared.

#### Error Response (404)
Key not found.

#### Response Example
```json
{
  "name": "KeyName",
  "organizationUnitId": "OrganizationUnitId",
  "id": "KeyId",
  "rfidHex": "1A00D1",
  "selectedStorage": {
    "automatId": "DeviceId"
  },
  "storage": {
    "automatId": "DeviceId"
  },
  "targetStorage": {
    "automatId": "DeviceId"
  },
  "status": {
    "available": true
  },
  "shared": false
}
```
```

--------------------------------

### Create Service Account Response Sample

Source: https://apidocsv2.livionkey.com/index

This JSON represents a successful response after creating a service account. It includes the service account's ID, name, role, private key, and the organization unit ID it belongs to.

```json
{
  "id": "string",
  "name": "string",
  "role": "string",
  "privateKey": "string",
  "organizationUnitId": "string"
}
```

--------------------------------

### Get Automat by ID

Source: https://apidocsv2.livionkey.com/index

Retrieves details for a specific automat using its unique identifier.

```APIDOC
## GET /v2/automats/{id}

### Description
Retrieves details for a specific automat using its unique identifier.

### Method
GET

### Endpoint
/v2/automats/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the automat.

### Responses
#### Success Response (200)
- Description: Get automat by id. Returns the automat object with all its details (similar to the response of GET /v2/automats).

#### Error Response (404)
- Description: Automat not found.
```

--------------------------------

### iLOQ Key Contract Creation

Source: https://apidocsv2.livionkey.com/index

This endpoint allows for the creation of iLOQ key contracts, which can be of type default, fetch, or return. It supports various methods for selecting keys, including by key automat, key group, or explicit key IDs.

```APIDOC
## POST /v2/iloq/keycontracts

### Description
Creates a contract which will be synced to device(s). If notification flag(s) are enabled, notifications will also be sent to the user. Contract type defines the type of contract to be created. Depending on the contract type, different fields are required.

Different types of contracts:
`1` = default
`2` = fetch
`3` = return

When creating return type contract, keys will be added to the system if they do not exist.

Select contractType to see required fields.

## Key Location Selection for DEFAULT and FETCH Contracts
When creating a contract you must specify which keys to include using **exactly one** of the following methods:
- `keyAutomatId`: Select keys from a specific key automat device
- `keyIds`: Provide an explicit list of key IDs
- `groupId`: Select keys from a specific key group

### Validation Rules
- **Required**: At least one of `keyAutomatId`, `keyIds`, or `groupId` must be provided
- **Mutually exclusive** (for contract types 1 and 2): Only one selection method should be used per request
- **numberOfKeys vs keyIds**: These parameters are mutually exclusive
    - Use `numberOfKeys` with `keyAutomatId` or `groupId` to specify how many keys you need
    - Use `keyIds` to explicitly specify which keys to include. Key pickup/return location is determined by the keys themselves.

## Key Location Selection for RETURN Contracts
When creating a return type contract:
- **New keys**: Keys will be automatically created in the system if they do not already exist
- **Return location**: Specify where keys should be returned using **exactly one** of the following:
    - `keyAutomatId` - Return keys to a specific key automat device
    - `groupId` - Return keys to a specific key group
- **Key selection**: Use `keyIds` to specify which keys are being returned

Check Request samples to see examples of how to create different types of contracts with various key selection methods.

### Method
POST

### Endpoint
/v2/iloq/keycontracts

### Parameters
#### Query Parameters
None

#### Request Body
- **contractType** (number) - Required - Type of contract: `1` = default, `2` = fetch, `3` = return
- **accessRightIds** (Array of strings) - Required - An array of iLOQ key access rights that will be programmed to the key when key is fetched
- **contact** (object) - Optional - Contact information of the recipient. The notifications field is optional and allows fine-grained control over notifications for different event types. IMPORTANT: When the notifications object is provided, the sendSms and sendEmail fields at the contact level are completely ignored. BEST PRACTICES:
  * Use the notifications object when a third-party system will handle sending notifications to end users.
  * When using a third-party notification system, consider enabling at least the contractKeysNotReturned notification.
  * If you want LivionKey to handle notifications using organization defaults, use the global sendSms and sendEmail fields instead and do not provide the notifications object.
- **numberOfKeys** (number) - Optional - Amount of keys needed for the handover. Required if `keyAutomatId` or `groupId` is provided
- **pincodes** (Array of strings) - Optional - List of pincodes for the keys. If not provided, LivionKey will generate random pincodes for each key. Note that the amount of pincodes must match the amount of keys.
- **groupId** (string) - Optional - Device group id, configured in LivionKey system
- **keyAutomatId** (string) - Optional - Key automat device id from where the keys should be collected
- **keyIds** (Array of strings) - Optional - List of iLOQ key ids to be handed over
- **start** (string) - Required - <date-time> Start date of the contract. Mandatory for default and fetch only contracts.
- **end** (string) - Required - <date-time> End date of the contract. Mandatory if contract type is default, otherwise optional

### Request Example
```json
{
  "contractType": 1,
  "accessRightIds": ["accessRight1", "accessRight2"],
  "contact": {
    "notifications": {
      "contractKeysNotReturned": true
    }
  },
  "keyAutomatId": "automat123",
  "numberOfKeys": 5,
  "start": "2023-10-27T10:00:00Z",
  "end": "2023-10-27T12:00:00Z"
}
```

### Response
#### Success Response (201)
Contract has been successfully created

#### Response Example
```json
{
  "message": "Contract created successfully",
  "contractId": "contract456"
}
```

#### Error Responses
- **400**: Bad Request
- **409**: No device(s) with requested number of keys available for the handover
```

--------------------------------

### Create Organization Unit Response Sample

Source: https://apidocsv2.livionkey.com/index

This JSON represents a successful response after creating an organization unit. It includes the newly created unit's ID, name, customer ID, parent ID, type, and associated user information.

```json
{
  "id": "string",
  "name": "string",
  "customerId": "string",
  "iloqApiUser": {
    "username": "string",
    "password": "string",
    "customerCode": "string",
    "serviceAddress": "string"
  },
  "parentId": "string",
  "type": 0
}
```

--------------------------------

### Get List of Access Rights

Source: https://apidocsv2.livionkey.com/index

Retrieves a list of access rights. Supports pagination and filtering by name.

```APIDOC
## GET /v2/iloq/accessRights

### Description
Retrieves a list of access rights. Supports pagination and filtering by name.

### Method
GET

### Endpoint
/v2/iloq/accessRights

### Parameters
#### Query Parameters
- **after** (string) - Optional - Number of items to skip for pagination.
- **limit** (number) - Optional - Number of items to return. Default is 20, Max is 100.
- **returnDefaultAccessesOnly** (boolean) - Optional - Default: "true". Return only access rights which are displayed by default in iLOQ manager.
- **search** (string) - Optional - Search for access rights by name.

### Responses
#### Success Response (200)
- **after** (string) - Identifier for the next page of results.
- **limit** (number) - The limit of items returned per page.
- **data** (array) - An array of access right objects.
  - **id** (string) - The unique identifier of the access right.
  - **name** (string) - The name of the access right.
  - **realEstatePath** (string) - The real estate path associated with the access right.

### Response Example
```json
{
  "after": "string",
  "limit": 0,
  "data": [
    {
      "id": "fdef8481-98ad-42b8-b4b6-4eade261e281",
      "name": "Access right name",
      "realEstatePath": "Access right real estate path"
    }
  ]
}
```
```

--------------------------------

### Request Sample for Contract Creation (JSON)

Source: https://apidocsv2.livionkey.com/index

This JSON payload represents a sample request for creating a contract. It includes details about the contract period, contact information, user verification, and pickup instructions. The 'notifications' object allows for granular control over different types of alerts.

```json
{
  "start": "2025-02-16T08:20:00.000Z",
  "end": "2025-02-16T08:20:00.000Z",
  "contact": {
    "name": "John Doe",
    "email": "john.doe@livion.fi",
    "phoneNumber": "+358401234567",
    "sendSms": true,
    "sendEmail": true,
    "language": "en | fi | sv | de | no | fr",
    "notifications": {
      "contractKeyFetched": {
        "sms": false,
        "email": false
      },
      "contractKeyReturned": {
        "sms": false,
        "email": false
      },
      "contractCreated": {
        "sms": false,
        "email": false
      },
      "contractStartReminder": {
        "sms": false,
        "email": false
      },
      "contractEndReminder": {
        "sms": false,
        "email": false
      },
      "contractKeysNotReturned": {
        "sms": false,
        "email": true
      },
      "contractUpdated": {
        "sms": false,
        "email": false
      },
      "contractSignatureRequested": {
        "sms": false,
        "email": false
      }
    }
  },
  "userVerification": "1",
  "pickUpInfoForManualStorageKeys": "Pick up the key from the reception desk. Reception is open from 8:00 to 16:00."
}
```

--------------------------------

### Mechanical Keys - Get By ID Mechanical Key

Source: https://apidocsv2.livionkey.com/index

Retrieves details for a specific mechanical key by its ID.

```APIDOC
## GET /mechanical/keys/:id

### Description
Get a mechanical key by its ID.

### Method
GET

### Endpoint
/mechanical/keys/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the mechanical key to retrieve.

#### Query Parameters
None

### Request Example
```json
{}
```

### Response
#### Success Response (200)
- **keyId** (string) - Unique identifier for the mechanical key.
- **name** (string) - Name or description of the key.

#### Response Example
```json
{
  "keyId": "key_abcde",
  "name": "Main Office Key"
}
```
```

--------------------------------

### Response Sample: Contract Details (JSON)

Source: https://apidocsv2.livionkey.com/index

This JSON object represents a successful response (HTTP 201 Created) for a key contract. It includes the contract ID, type, duration, contact details with notification preferences, key status, and information related to locker availability and user verification.

```json
{
  "id": "234567",
  "contractType": 1,
  "start": "2025-02-16T08:20:00.000Z",
  "end": "2025-02-20T08:20:00.000Z",
  "contact": {
    "name": "John Doe",
    "email": "john.doe@livion.fi",
    "phoneNumber": "+358401234567",
    "sendSms": true,
    "sendEmail": true,
    "language": "en | fi | sv | de | no | fr",
    "notifications": {
      "contractKeyFetched": {
        "sms": false,
        "email": false
      },
      "contractKeyReturned": {
        "sms": false,
        "email": false
      },
      "contractCreated": {
        "sms": false,
        "email": false
      },
      "contractStartReminder": {
        "sms": false,
        "email": false
      },
      "contractEndReminder": {
        "sms": false,
        "email": false
      },
      "contractKeysNotReturned": {
        "sms": false,
        "email": true
      },
      "contractUpdated": {
        "sms": false,
        "email": false
      },
      "contractSignatureRequested": {
        "sms": false,
        "email": false
      }
    }
  },
  "keys": [
    {
      "id": "keyId",
      "storageInfo": {
        "manualStorageInfo": "Shelf 1, Drawer 1"
      },
      "status": "key-fetched",
      "inHistory": false
    }
  ],
  "freeLockerAfterFetch": true,
  "userVerification": "1",
  "pickUpInfoForManualStorageKeys": "string",
  "returnLocationInfoForManualStorageKeys": "string"
}
```

--------------------------------

### Mechanical Key Contracts - Get By ID Mechanical Key Contract

Source: https://apidocsv2.livionkey.com/index

Retrieves details for a specific mechanical key contract by its ID.

```APIDOC
## GET /mechanical/keycontracts/:id

### Description
Get a mechanical key contract by its ID.

### Method
GET

### Endpoint
/mechanical/keycontracts/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the contract to retrieve.

#### Query Parameters
None

### Request Example
```json
{}
```

### Response
#### Success Response (200)
- **contractId** (string) - The ID of the contract.
- **contractDetails** (object) - Details of the contract.

#### Response Example
```json
{
  "contractId": "contract_xyz789",
  "contractDetails": {
    "type": "1",
    "inHistory": false
  }
}
```
```