Create Allocation

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

a pool id from List Pools

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.

SDK Method

Java	Node.js
client.allocations().create(request)	await client.allocations().create(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:

{
  "serial": "R58M123456A",
  "priority": 3,
  "removeApps": "NO_REMOVE"
}

Pool body:

{
  "devicePoolId": "android-regression",
  "priority": 3,
  "removeApps": "NO_REMOVE"
}

Criteria body:

{
  "platform": "Android",
  "platformVersion": "14",
  "manufacturer": "Samsung",
  "model": "SM-S911B",
  "priority": 3,
  "removeApps": "NO_REMOVE"
}

Exact Device Example

Allocation allocation = client.allocations().create(
        DeviceAllocationRequest.builder()
                .serial("R58M123456A")
                .priority(3)
                .build()
);

System.out.println(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.

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()
);

Pool Example

Allocation allocation = client.allocations().create(
        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:

{
  "allocationId": "allocation-123",
  "deviceSerial": "R58M123456A",
  "requestId": "request-456",
  "position": null,
  "expiresAt": "2026-07-28T12:30:00Z"
}

Queued assignment:

{
  "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. Do not create duplicate allocations while waiting.

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.