--- title: Create Allocation slug: devicepark/sdk-documentation/allocations/create-allocation description: Reserve a device by serial, pool or matching criteria. docTags: createdAt: 2026-08-10T08:03:44.631Z --- ## What Is an Allocation? An allocation is a temporary reservation for a Device Park device. A session cannot normally be started until a device has been allocated. Create an allocation when your application or test runner is ready to use a device. The allocation keeps the selected device available for your test flow until the allocation expires or you release it. One allocation can be used to create more than one session while the allocation remains active. For example, you can stop the first session and start another session with the same `allocationId` without requesting a new device. Do not delete the allocation between those sessions. ## Before You Begin Select one of these inputs: - a serial from [List Devices](docId\:T2lFRSsG2mhohPOA4K26-) - a pool id from [List Pools](docId\:fmKLq2CPwGu4aurSboUFg) - platform criteria such as Android 14 Create the allocation only when the test runner is ready to use the device. Allocations are temporary and include an expiration time. ## How Device Selection Works You can request: - one exact device with `serial` - any suitable device in a pool with `devicePoolId` - a matching device with `platform`, `platformVersion`, `manufacturer` or `model` Use at least one meaningful target. `priority` controls queue order from `1` (highest) to `5` (lowest) and defaults to `3`. :::hint{type="warning"} A device must belong to a pool before it can be allocated. A device that appears in List Devices and reports a healthy state is not necessarily allocatable; if it belongs to no pool, the request fails with `ALLOCATION_ERR003` ("No matching devices found for allocation") even when you pass its exact `serial`. Add the device to a pool first, or ask a Device Park administrator to do so. ::: ## SDK Method | Java | Node.js | .NET | | -------------------------------------- | -------------------------------------------- | ----------------------------------------------- | | `client.allocations().create(request)` | `await client.allocations().create(request)` | `await client.Allocations.CreateAsync(request)` | ## Request Fields | Field | Required | Description | | ----------------- | ----------- | ----------------------------------------------- | | `serial` | Conditional | Exact device serial | | `devicePoolId` | Conditional | Device pool identifier | | `platform` | Conditional | Android or iOS | | `platformVersion` | No | Required operating-system version | | `manufacturer` | No | Required manufacturer | | `model` | No | Required device model | | `priority` | No | Queue priority, default `3` | | `removeApps` | No | Application cleanup policy, default `NO_REMOVE` | At least one device-selection field should be supplied. `priority` accepts `1` through `5`, where `1` is highest priority. `removeApps` accepts `NO_REMOVE` or `REMOVE_WITHOUT_IS_DEFAULT_APPS`. ## Request Mapping The SDK serializes the built request as a JSON body. Authentication and content headers are added by the SDK client; callers do not supply them to `create(...)`. Exact-device body: ```json { "serial": "R58M123456A", "priority": 3, "removeApps": "NO_REMOVE" } ``` Pool body: ```json { "devicePoolId": "android-regression", "priority": 3, "removeApps": "NO_REMOVE" } ``` Criteria body: ```json { "platform": "Android", "platformVersion": "14", "manufacturer": "Samsung", "model": "SM-S911B", "priority": 3, "removeApps": "NO_REMOVE" } ``` ## Exact Device Example :::CodeblockTabs ```java Allocation allocation = client.allocations().create( DeviceAllocationRequest.builder() .serial("R58M123456A") .priority(3) .build() ); System.out.println(allocation.allocationId()); ``` ```typescript import { DeviceAllocationRequestBuilder } from "@device-park/public-sdk"; const allocation = await client.allocations().create( new DeviceAllocationRequestBuilder() .serial("R58M123456A") .priority(3) .build() ); console.log(allocation.allocationId); ``` ```csharp var allocation = await client.Allocations.CreateAsync( new DeviceAllocationRequest.Builder() .Serial("R58M123456A") .Priority(3) .Build()); Console.WriteLine(allocation.AllocationId); ``` ::: ## Remove Non-default Applications Use `REMOVE_WITHOUT_IS_DEFAULT_APPS` when the selected device should be cleaned before allocation while preserving applications marked as default. :::CodeblockTabs ```java import io.testinium.devicepark.model.allocation.RemoveAppSelection; Allocation allocation = client.allocations().create( DeviceAllocationRequest.builder() .devicePoolId("android-regression") .removeApps(RemoveAppSelection.REMOVE_WITHOUT_IS_DEFAULT_APPS) .build() ); ``` ```typescript import { DeviceAllocationRequestBuilder, RemoveAppSelection } from "@device-park/public-sdk"; const allocation = await client.allocations().create( new DeviceAllocationRequestBuilder() .devicePoolId("android-regression") .removeApps(RemoveAppSelection.REMOVE_WITHOUT_IS_DEFAULT_APPS) .build() ); ``` ```csharp var allocation = await client.Allocations.CreateAsync( new DeviceAllocationRequest.Builder() .DevicePoolId("android-regression") .RemoveApps(RemoveAppSelection.REMOVE_WITHOUT_IS_DEFAULT_APPS) .Build()); ``` ::: ## Pool Example :::CodeblockTabs ```java Allocation allocation = client.allocations().create( DeviceAllocationRequest.builder() .devicePoolId("android-regression") .priority(3) .build() ); ``` ```typescript const allocation = await client.allocations().create( new DeviceAllocationRequestBuilder() .devicePoolId("android-regression") .priority(3) .build() ); ``` ```csharp var allocation = await client.Allocations.CreateAsync( new DeviceAllocationRequest.Builder() .DevicePoolId("android-regression") .Priority(3) .Build()); ``` ::: ## Result and Queue Behavior The method returns one `Allocation`. | Field | Type | Nullable | Meaning | | -------------- | --------------- | -------- | ------------------------------------------------------- | | `allocationId` | string | Yes | Identifier used for sessions, status checks and cleanup | | `deviceSerial` | string | Yes | Assigned device; `null` while waiting | | `requestId` | string | Yes | Allocation request tracking identifier | | `position` | number | Yes | Queue position when assignment is pending | | `expiresAt` | ISO-8601 string | Yes | Time after which the allocation is no longer valid | Immediate assignment: ```json { "allocationId": "allocation-123", "deviceSerial": "R58M123456A", "requestId": "request-456", "position": null, "expiresAt": "2026-07-28T12:30:00Z" } ``` Queued assignment: ```json { "allocationId": "allocation-123", "deviceSerial": null, "requestId": "request-456", "position": 2, "expiresAt": "2026-07-28T12:30:00Z" } ``` If no matching device is immediately available, the allocation can enter a queue. Keep the same `allocationId` and inspect it with [List Allocations](docId\:GGobQpsUr2aKNz0jfCNYD). Do not create duplicate allocations while waiting. :::hint{type="warning"} Store and reuse the first `allocationId` while waiting. Creating another allocation can reserve an additional device or create another queue entry. ::: ## Important Rules - Store `allocationId` immediately. - Start sessions only while the allocation is active. - Multiple sessions can use the same active allocation. - Stop active sessions before releasing the allocation. - Release the allocation in cleanup code when no more sessions are needed. Continue with [Start Session](docId\:ouSu3HjjBQLFsC2bURFU-).