# 4. Create Device Session – Start a Remote Test Session

Once your allocation request has been accepted and you have received an `allocationId`, you can start a remote session with the assigned device. This session allows you to perform live testing or automated tests using tools like Appium.

You can also optionally enable video recording for the session, which lets you later review a playback of the test execution.

### Purpose

This endpoint creates an active session tied to a specific allocated device and user. The session acts as a live connection channel for automation, device control, and video capture.

### Endpoint

Send a POST request to the following URL:

```
https://devicepark.testinium.io/session/api/device-sessions
```

### Required Headers

* **Authorization**: `Bearer <ACCESS_TOKEN>`
* **Content-Type**: `application/json`

### Request Body Parameters

| Field          | Type    | Required | Description                                    |
| -------------- | ------- | -------- | ---------------------------------------------- |
| allocationId   | UUID    | ✅        | ID of the allocated device from previous step  |
| userId         | Integer | ✅        | ID of the user initiating the session          |
| userEmail      | String  | ✅        | Email of the session owner                     |
| companyId      | Integer | ✅        | Associated company ID                          |
| companyName    | String  | ✅        | Company name                                   |
| videoRecording | Boolean | Optional | Whether to enable video recording (true/false) |

### Example Request Body

```json
{
  "allocationId": "f230263f-707b-4505-a841-4dd483e46388",
  "userId": 1,
  "userEmail": "test@company.com",
  "companyId": 1,
  "companyName": "company_name",
  "videoRecording": true
}
```

### Example cURL Command

```bash
curl --location --request POST 'https://devicepark.testinium.io/session/api/device-sessions' \
--header 'Authorization: Bearer <ACCESS_TOKEN>' \
--header 'Content-Type: application/json' \
--data '{
  "allocationId": "f230263f-707b-4505-a841-4dd483e46388",
  "userId": 1,
  "userEmail": "test@company.com",
  "companyId": 1,
  "companyName": "company_name",
  "videoRecording": true
}'
```

### Example Successful Response

```json
{
  "sessionId": "61e52320-eea7-480a-a35d-2b7e2f03da29",
  "state": "ACTIVE",
  "deviceSerial": "R5CT31AB4FV",
  "videoRecording": true,
  "videoRecordUrl": "https://devicepark.testinium.io/storage/api/sessions/61e52320-eea7-480a-a35d-2b7e2f03da29/screen-records",
  "startDate": "2025-10-14T10:44:38.46056",
  "hubIp": "10.0.15.20",
  ...
}
```

Key fields:

* **sessionId**: Unique identifier for the created session
* **state**: Current state of the session (e.g., `ACTIVE`)
* **deviceSerial**: Serial number / UDID of the connected device
* **videoRecording**: Whether video recording is enabled
* **videoRecordUrl**: URL to access the video recording (.m3u format)
* **hubIp**: The internal IP of the device hub where tests will run\\

## Get Device Serial (UDID)

Retrieve the `deviceSerial` field from the session response using the previous request. This value represents the device's unique identifier (UDID) and should be added to the Appium Desired Capabilities configuration for test initialization.

### POST - Request

```bash
curl --location --request GET 'https://devicepark.testinium.io/session/
api/device-sessions/{sessionId}' \
--header 'Authorization: Bearer <ACCESS_TOKEN>'
```

### Response

```json
{
...
...
"deviceSerial": "R5CT31AB4FV"
...
...,}
```

### Notes

* The session remains active until manually closed or it times out.
* You will need the `sessionId` and `deviceSerial` in the next steps to:
  * Run automated tests (e.g., Appium)
  * Upload application files
  * Close the session when finished
