Skip to main content
POST
JavaScript
Requests an app install on the device. background (default false) selects the response contract:
  • background: false (default) — installs inline; the response is the actual outcome: 200 on success, an error status on failure.
  • background: true — accepts the request and runs the download + install in the background; a 202 response means the request was accepted, not that the app is installed yet — poll list-apps until the app appears, or poll list-app-installs for the backend’s view of the install attempt itself (useful while the device is offline or crashed, when list-apps can’t be called at all).
Both modes are subject to the same concurrency cap: a request is refused with 409 Conflict once 2 other installs are already running on the device. A repeat request for an app that already has an install running is also refused with 409 Conflict rather than superseding it — retry once that attempt reaches a terminal state. Provide exactly one of:
  • packageName — Android package name. Resolved against the device owner’s app library, so upload the APK first.
  • bundleId — iOS bundle identifier (e.g. com.example.app) or a numeric App Store ID. The app is installed from the App Store.
Uploaded Android app versions may additionally be selected with:
  • country — ISO 3166-1 alpha-2 country stored on the uploaded version (for example, MY or SG).
  • versionCode — exact uploaded app version code.
Pass both fields when the app library contains multiple regional versions for the same package name. Omitting them preserves the legacy lookup behavior, including Apps API’s default US country.
Protected system packages cannot be installed over. Requests targeting a protected package fail with 403 Forbidden.

Authorizations

Authorization
string
header
required

Bearer token via Authorization header

Headers

X-Device-Display-ID
integer<int64>
default:0
Required range: x >= 0

Path Parameters

deviceId
string
required

Body

application/json
bundleId
string
required

iOS bundle identifier (e.g. com.example.app)

Minimum string length: 1
background
boolean
default:false

true: return 202 immediately and install in the background (poll list-app-installs). false/omitted: install inline and return the outcome directly (200 on success, an error status on failure).

country
string

Optional ISO 3166-1 alpha-2 country of the uploaded app version (e.g. MY or SG).

Pattern: ^[A-Za-z]{2}$
packageName
string

Android package name (e.g. com.example.app)

Minimum string length: 1
versionCode
integer

Optional exact app-library version code. Use with country when multiple regional versions share an identifier.

Required range: x >= 1

Response

Install finished synchronously (background omitted or false).