---
title: "Create a phone"
method: POST
path: "/v1/phones"
tags: ["phone"]
---

# Create a phone

`POST /v1/phones`

## Request

- Base URL: `https://phonebox.dev`
- URL: `https://phonebox.dev/v1/phones`
- Auth: HTTP bearer

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `name` string
  - `country` 'AR' | 'AU' | 'AT' | 'BE' | 'BR' | 'CA' | 'CL' | 'CO' | 'CZ' | 'DK' | 'EG' | 'FI' | 'FR' | 'DE' | 'GR' | 'HK' | 'IN' | 'ID' | 'IE' | 'IL' | 'IT' | 'JP' | 'KE' | 'MY' | 'MX' | 'NL' | 'NZ' | 'NG' | 'NO' | 'PH' | 'PL' | 'PT' | 'RO' | 'SA' | 'SG' | 'ZA' | 'KR' | 'ES' | 'SE' | 'CH' | 'TW' | 'TH' | 'TR' | 'UA' | 'AE' | 'GB' | 'US' | 'VN'
  - `metadata` object
  - `idle_timeout` integer
  - `max_duration` integer
  - `wait` boolean

## Response `201`

The phone is ready.

- Phone
  - `id` string, required
  - `object` 'phone', required
  - `name` string, required
  - `status` 'creating' | 'starting' | 'ready' | 'parking' | 'parked' | 'unavailable' | 'failed' | 'deleted', required
  - `country` string, nullable, required
  - `metadata` object, required
  - `created_at` string, date-time, required: ISO 8601 timestamp (UTC)
  - `last_active_at` string, date-time, nullable, required: ISO 8601 timestamp (UTC)
  - `session` object, nullable, required
    - `id` string, required
    - `started_at` string, date-time, required: ISO 8601 timestamp (UTC)
    - `ready_at` string, date-time, nullable, required: ISO 8601 timestamp (UTC)
    - `idle_timeout` integer, required
    - `max_duration` integer, required
    - `parks_at` string, date-time, required: ISO 8601 timestamp (UTC)
    - `park_reason` 'idle' | 'max_duration', required
    - `reserved_usd` string, required: US dollars as a decimal string with six places, such as 0.060000
  - `failure` object, nullable, required
    - `code` string, required
    - `message` string, required
    - `at` string, date-time, required: ISO 8601 timestamp (UTC)

## Other responses

- `202`: The phone was created but isn't ready yet: wait was false, the ~50 s wait ran out, or the wait itself failed. Poll GET /v1/phones/{id}?wait=ready while the phone is creating or starting; any other status ends the loop, so read status and failure and act on them (a failed phone never becomes ready). If the key was revoked meanwhile, the poll answers 401 key_revoked. A replayed Idempotency-Key answers with the phone as it is now, a failed one included.
- `400`: Invalid request; details.issues lists each problem as {path, message}
- `401`: Missing or invalid key
- `402`: Insufficient credits, spending limit reached, or the project is frozen
- `403`: Insufficient scope, a phone this key can't use, a browser request, or a setup request that was declined
- `404`: Not found
- `409`: Conflict: the phone's status doesn't allow this, a phone limit is reached, the Idempotency-Key was used with another body, another install is still running on the phone, a newer version of the app is on the phone, an upload that isn't ready, the project's upload storage is full, the clipboard can't be read, a recording is already running or isn't ready, the project keeps 20 recordings, a setup request that expired or already delivered its key, the project has 50 active keys
- `413`: Body too large
- `422`: The request can't be applied, such as an app that isn't in Phonebox's app library, a file that isn't an APK, an install the phone refused, or a feature this phone doesn't offer (feature_unavailable)
- `429`: Rate limited
- `500`: Unexpected server error; keep the request ID
- `502`: The phone service returned an error, or didn't confirm the action
- `503`: No capacity, the phone is briefly unavailable, Phonebox is paused, or payments aren't connected. A batch refused with this error body did nothing on the phone; a 502 or 504 without it, from a proxy or the platform, leaves the outcome unknown.
- `504`: The phone didn't respond in time

---

[API](https://skmtc.dev/phonebox/apis/phonebox-api.md) · [All operations](https://skmtc.dev/phonebox/apis/phonebox-api/llms.txt) · [OpenAPI document](https://skmtc.dev/phonebox/apis/phonebox-api/revisions/87eb2f5211b2?raw)