Phonebox / Docs
API reference

Account

Read the project's balance, reservations, monthly spending, limits, phone counts, price, countries, starter credit, top-up link and plan, and create a checkout link for credits.

View as Markdown

The account belongs to the project that the key selects. Pricing and credits explains balances, reservations and the spending limit.

Get the account

GET /v1/account needs the phones:read scope.

It reads the project and touches no phone, so it is a cheap way to check that a key works.

curl https://phonebox.dev/v1/account \
  -H "Authorization: Bearer $PHONEBOX_API_KEY"
Response: account
{
  "project": "Checkout QA",
  "balance_usd": "21.400000",
  "reserved_usd": "7.200000",
  "available_usd": "14.200000",
  "spend_limit_usd": "100.000000",
  "spent_this_month_usd": "4.120000",
  "limits": { "phones": 10, "running": 5 },
  "running": 1,
  "phones": 3,
  "price": { "per_minute_usd": "0.060000", "minimum_seconds": 60 },
  "countries": [
    { "code": "AR", "name": "Argentina" },
    { "code": "AU", "name": "Australia" },
    { "code": "US", "name": "United States" }
  ],
  "starter_credit": { "claimable": false, "amount_usd": "2.000000", "claim_url": null },
  "top_up_url": "https://phonebox.dev/topup/MS5qZDdhYmMxMjMuMTc5NDc4NzIwMA.3q2-7wQx9Kx0pE3w1n1q0c2l6m8s9v4b7y5z0a1b2c3",
  "plan": {
    "tier": "starter",
    "state": "subscribed",
    "status": "active",
    "trial_ends_at": null,
    "renews_at": "2026-12-06T10:00:00.000Z",
    "limits": {
      "running_phones": 5, "phones": 10, "idle_max_seconds": 3600, "session_max_seconds": 10800, "team_members": 5,
      "recordings": 20, "recording_days": 30, "saved_phone_days": null,
      "features": { "countries": true, "device_writes": true, "recordings": true, "credit": true }
    },
    "next_url": "https://phonebox.dev/topup/MS5qZDdhYmMxMjMuMTc5NDc4NzIwMA.3q2-7wQx9Kx0pE3w1n1q0c2l6m8s9v4b7y5z0a1b2c3"
  }
}
FieldTypeMeaning
projectstringThe project's name.
balance_usdmoneyYour credit, before reservations.
reserved_usdmoneyThe credit held by open sessions.
available_usdmoneyWhat a new session can reserve: balance_usd minus reserved_usd, never below zero.
spend_limit_usdmoneyThe monthly spending limit.
spent_this_month_usdmoneyWhat sessions that ended this calendar month, in UTC, were charged.
limits.phonesintegerThe most phones the project can have, not counting deleted or failed ones.
limits.runningintegerThe most phones the project can run at once. The limit counts all of your projects together.
runningintegerPhones with an open session: creating, starting or ready.
phonesintegerPhones that count toward the phone limit: every phone that isn't deleted or failed.
price.per_minute_usdmoneyThe price of a phone-minute.
price.minimum_secondsintegerThe shortest time a session is billed for.
countriesarrayThe countries a phone can be created in, as {code, name}, sorted by name. Pass a code as country when you create a phone. The example shows three of them. A country is where the phone appears to be.
starter_credit.claimablebooleanWhether the project's owner can still unlock the one-time starter credit into this project by answering one question. Only an account's first project receives it.
starter_credit.amount_usdmoneyThe starter credit's amount.
starter_credit.claim_urlstring or nullWhere the owner signs in and answers the question, while claimable is true; otherwise null. Send your user here before you offer a paid top-up.
top_up_urlstringA page where a member of this project signs in and pays for its credit, from $20. Give it to your user when credit runs out. It works for 30 days, and is the same link all day.

Treat top_up_url like a key you'd share with your user only: anyone who has it can pay for this project's credit, though it shows nothing but the project's name and grants nothing else. Every insufficient_credits error on a project that can buy credit carries the same link in details.top_up_url.

The plan

plan says which plan the project is on and what to do next. The limits under it are what the plan allows; the top-level limits above are the project's own phone limits, which can be lower.

FieldTypeMeaning
plan.tierstringlegacy (a project from before plans), lapsed (no plan), trial (the free week), starter or pro.
plan.statestringWhat to do next: no_trial (the free week can start), trialing, subscribed, lapsed (start a plan again) or legacy. The same value is details.plan_state on an insufficient_credits error.
plan.statusstring or nullThe subscription's status, such as trialing, active or past_due; null with no plan.
plan.trial_ends_atstring or nullWhen the free week ends and the paid plan starts; null outside a free week.
plan.renews_atstring or nullWhen the plan renews; null with no plan or one set to end.
plan.limits.running_phonesintegerPhones that can run at once.
plan.limits.phonesintegerPhones the project can hold.
plan.limits.idle_max_seconds, plan.limits.session_max_secondsintegerThe longest idle timeout and session a phone can have.
plan.limits.team_membersintegerPeople on the project, pending invites included.
plan.limits.recordings, plan.limits.recording_daysintegerRecordings kept, and for how many days. 0 means none.
plan.limits.saved_phone_daysinteger or nullDays a parked phone is kept; null keeps it for good.
plan.limits.featuresobjectcountries, device_writes, recordings and credit, each true or false. A false one answers 403 plan_required.
plan.next_urlstringA page where a member of the project signs in to take the next step for its state: start the free week, start Starter now, start a plan again, or add credit.

The balance, reservations, spending, limits and price are always the project's. For a key limited to certain phones, running and phones count only the phones that key may use.

This endpoint returns no errors of its own. The common errors apply.

POST /v1/credits/checkout needs the phones:control scope.

Creates a checkout page where a person buys credits for the key's project. It is the same purchase as on the console's Billing page, so an agent or a terminal can ask for credit without sending anyone to the console. The body is optional.

FieldTypeDefaultRules
amount_usdinteger20The credit to buy, in whole US dollars, from 20 to 1000.
POST /v1/credits/checkout
{
  "amount_usd": 25
}
curl https://phonebox.dev/v1/credits/checkout \
  -H "Authorization: Bearer $PHONEBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount_usd": 25}'

It answers 201 Created:

Response: checkout
{
  "url": "https://checkout.example.com/c/9f2b7c1e",
  "amount_usd": 25
}
FieldTypeMeaning
urlstringThe checkout page, on our payment provider's site. Give it to a person, who pays there. Tax is added at checkout, and a discount code can be entered.
amount_usdintegerThe credit the purchase adds, before tax and any discount.

Nothing is charged until the person pays. The credit is added when the payment is confirmed, not when the page closes, so poll the account until balance_usd shows it. A link that nobody pays costs nothing.

ErrorWhen
400 validation_failedamount_usd isn't a whole number from 20 to 1000, or the body has another field.
403 insufficient_scopeThe key is Read-only.
403 plan_requiredThe project is on the free week or has no plan, which can't buy credit (details.feature is credit). details.upgrade_url is where a person starts a plan.
429 rate_limitedThe project created 10 checkout links within the hour. Retry-After says when the next one can be created.
503 billing_not_configuredPayments aren't connected on this deployment.

The common errors apply too.

On this page