# 2. Create Allocation Request – Reserving a Device

## Create Allocation Request – Reserving a Device

Once you have authenticated and obtained a bearer token, the next step is to request a mobile device that matches specific criteria such as manufacturer, model, operating system, and OS version. DevicePark will attempt to allocate a real device that matches your request.

This process is essential to reserve a device before initiating any automated test or live session.

### Purpose

The allocation request allows you to programmatically filter and reserve a device by specifying its characteristics. If a matching device is available, it will be reserved for you. If not, your request will be queued in that device's dedicated queue.

### Endpoint

You will send a POST request to the following URL:

```
https://devicepark.testinium.io/allocation/api/device-allocations-requests
```

### Required Headers

* **Authorization**: `Bearer <ACCESS_TOKEN>` (Use the token obtained in step 1)
* **Content-Type**: `application/json`

### Request Body Parameters

You must specify the device characteristics in the JSON body:

* **manufacturer** (string) – The brand of the device (e.g., `samsung`, `apple`)
* **model** (string) – The model name (e.g., `SM-G990E`)
* **platform** (string) – The mobile operating system (`Android` or `iOS`)
* **platformVersion** (string) – The OS version (e.g., `14`)

Example request body:

```json
{
  "manufacturer": "samsung",
  "model": "SM-G990E",
  "platform": "Android",
  "platformVersion": "14"
}
```

### Example cURL Command

```bash
curl --location --request POST 'https://devicepark.testinium.io/allocation/api/device-allocations-requests' \
--header 'Authorization: Bearer <ACCESS_TOKEN>' \
--header 'Content-Type: application/json' \
--data '{
  "manufacturer": "samsung",
  "model": "SM-G990E",
  "platform": "Android",
  "platformVersion": "14"
}'
```

### Example Successful Response

If the request is accepted, the API will respond with a unique `requestId` that you will use in the next step to check the status of this allocation request.

```json
{
  "requestId": "5d8ad0c3-ecdc-495f-a89b-8c0017d871fe"
}
```

* **requestId**: A unique identifier that represents this allocation request. You'll use this in Step 3 to check whether the device has been successfully allocated or if it is waiting in a queue.

### How Allocation Works

* If a matching device is available, it will be allocated immediately, and you can proceed to create a session.
* If all matching devices are busy, your request will be placed in that specific device's queue (FIFO order), and you will be notified when it becomes available.

Each device has its own individual queue, ensuring that test requests are handled fairly and predictably.
