Skip to content

Accounts

Account endpoints are not available via OAuth — account management requires a session or API-key credential.

List All Accounts

This is not account scoped and will return ALL accounts this user has access to.

GET /api/accounts

Returned Params
  • accounts: Array
    • id: String
    • name: String
    • reseller: Boolean
    • is_trial: Boolean
    • trial_start: DateTime
    • trial_end: DateTime
    • parent_account: Object | sub-accounts only — see the warning below
      • id: String
      • name: String
    • reseller_billing_plan: Object | sub-accounts with a reseller billing plan only — see the warning below
      • id: String
      • name: String
    • nameservers: Array
    • created_at
    • updated_at

When an account has no parent, parent_account and reseller_billing_plan are absent from the JSON, not null — test for key presence. The list does not include account_roles; get them from View Account or List Account Roles.


View Account

GET /api/accounts/:id

Returns a single account object with all the fields of a list entry plus account_roles, which the list does not return, and, while one exists, move. Each entry in account_roles has the same shape as an entry in List Account Roles.

Returned Params (additional)
  • account: Object
    • move: Object | only while a workspace move whose billing moves with the workspace is open, or for 30 days after it failed or was refunded. Otherwise the key is absent, not null
      • guid: String
      • status: String | charging, requires_action, awaiting_payment, applying, payment_failed, refunded or refund_failed
      • cancelable: Boolean | whether you may cancel it now with Cancel a Workspace Move
Errors
  • 401 forbidden | the token's user cannot view the account
  • 404 | no such account, or not one of yours; no body

Create Account

Two modes:

  • Top-level account — omit X-Auth-Account. Requires an admin user.
  • Sub-account — set X-Auth-Account to the parent Account ID. Requires an admin role on the parent and the parent must be a reseller.

POST /api/accounts

Params
  • account: Object
    • name: String (required)

Admin-only params

Admin callers may additionally set is_trial, trial_start, trial_end, reseller, reseller_bill_trial, billing_plan_id, and parent_account_guid.

A sub-account takes the brand of the workspace in X-Auth-Account, like users created through POST /api/users.

Returns 201 with the account on success.

Errors
  • 401 forbidden | you are not an admin of the X-Auth-Account workspace, or it is not a reseller (without the header: you are not an admin)
  • 422 account_invalid | the account failed validation, including an unknown parent_account_guid

Update Account

PATCH /api/accounts/:id

Requires edit permission. Non-admin callers can only update name. Admin callers may additionally set is_trial, trial_start, trial_end, reseller, reseller_bill_trial, and billing_plan_id. Returns 202 with the account.

Sending parent_account_guid moves the workspace; see below.

Params
  • account: Object
    • name: String
    • parent_account_guid: String | optional. The new parent; an empty string detaches the workspace
  • confirm_preview_digest: String | the preview_digest you were shown, to confirm a move
  • keep_access: Boolean | optional, default false. Keep your own access; see below
  • confirm_total_cents: Integer | optional: the billing_quote.charge_total_cents you reviewed
Errors
  • 401 forbidden | you may not edit this account
  • 404 | no such account, or not one of yours; no body
  • 422 account_invalid | the account failed validation

Moving a workspace

You need an admin role on the workspace's current parent (or on the workspace itself when it has none) and on the new parent. Under a non-reseller parent the workspace is billed through that parent; detached, it pays for itself on the default plan. A refused move changes nothing.

Confirming. A move that changes the billing plan or the brand, or that takes away anyone's access (access_lost), must be confirmed:

  1. Send the request. It answers 422 requires_confirmation with a preview and a preview_digest.
  2. Send it again with confirm_preview_digest. If the move has changed in the meantime, it answers preview_stale with a fresh preview and digest.

Keeping your access. Everyone whose role is inherited from a workspace the move leaves loses access. If that includes you, send keep_access: true to get a direct role on the workspace (the role you hold now on the closest workspace it leaves).

Moves that change who pays. Live subscriptions move with the workspace: the new payer is charged for the rest of the current period (against its default payment method), the old payer is credited, and the workspace moves once the payment has gone through. Then:

  • the preview carries billing_quote, and confirming always needs the digest;
  • the confirm answers 202 with { "move": { "guid": "…", "status": "…" } } instead of the account;
  • follow the move with move on View Account, or cancel it with Cancel a Workspace Move;
  • send confirm_total_cents to have the move refused (drift) if the total has changed by more than 50 cents.

With an admin key, send a move with no other attributes (only parent_account_guid, confirm_preview_digest, keep_access), or it is refused move_must_be_submitted_alone.

Preview (in requires_confirmation and preview_stale bodies)
  • preview: Object
    • parent_before: Object | { id, name }, or absent
    • parent_after: Object | { id, name }, or absent
    • payer_before: Object | { id, name }
    • payer_after: Object | { id, name }
    • billing_plan_before: Object | { id, name }, or absent
    • billing_plan_after: Object | { id, name }, or absent
    • brand_before: Object | { id, name }, or absent
    • brand_after: Object | { id, name }, or absent
    • inherit_billing: Boolean
    • billing: String | none or required
    • billing_quote: Object | only when billing is required
      • currency: String
      • charge_subtotal_cents: Integer
      • tax_cents: Integer | null when the tax is not known yet
      • charge_total_cents: Integer
      • seats: Array | one entry per moved subscription, with its charge and credit amounts and billing period
    • access_lost: Array | empty when nobody loses access
      • user: Object | id, name, email
      • role: Object | id, name, label
  • preview_digest: String
Move errors
  • 400 no_default_payment_method | the new payer has no default payment method or billing address
  • 401 forbidden | you are not an admin of the current or the new parent
  • 422 unknown_parent | parent_account_guid names no workspace of yours
  • 422 invalid_parent | the workspace cannot go there (itself, one of its sub-workspaces, a deleted workspace, or its current parent)
  • 422 brand_locked | the move would change or remove the workspace's brand; only an administrator of the workspace that owns that brand may do that
  • 422 requires_confirmation | review preview, then confirm
  • 422 preview_stale | the move has changed; confirm with the new digest
  • 422 drift | the total moved by more than 50 cents from confirm_total_cents
  • 422 move_in_progress | this workspace is already being moved
  • 422 move_must_be_submitted_alone | admin key: send the move without other attributes
  • 422 billing_migration_unsupported, payer_not_billable, payer_in_dunning, subscription_suspended, billing_in_progress, domain_renewal_due, billing_needs_reconciliation | the billing cannot move now; the message says why
  • 422 payer_invoice_open | the old or the new payer has an unpaid invoice. Pay it, then retry
  • 422 uninvoiced_ledger_entries | either payer has usage that is not invoiced yet. Retry once it is invoiced and paid
  • 422 payment_failed | the payment failed; nothing was changed
  • 422 payment_requires_action | the bank wants the payment confirmed; confirm the move in the dashboard
  • 503 billing_unavailable | the billing system could not be reached

Error bodies are { "errors": ["…"], "code": "…" }; the refusals that carry a preview also include preview and preview_digest.


Cancel a Workspace Move

DELETE /api/accounts/:account_id/move

Cancels the workspace's open move while move.cancelable on View Account is true. The charge is canceled, nothing is moved, and the move ends payment_failed. Requires an admin role on both the workspace the move leaves and the one it joins. Returns 200.

Returned Params
  • move: Object
    • guid: String
    • status: String | payment_failed
Errors
  • 401 forbidden | you may not make this move
  • 404 no_open_move | the workspace has no open move
  • 404 | no such account, or not one of yours; no body
  • 422 move_still_confirming | the payment is still being confirmed; try again in a few minutes
  • 422 move_not_cancelable | the move is being applied, or a bank debit is being collected
  • 422 payment_went_through | the payment went through; the workspace is being moved
  • 503 billing_unavailable | the payment provider could not be reached; nothing was canceled. Retry

Delete Account

DELETE /api/accounts/:id

Deletes an empty workspace. Invoices and audit history are kept. A deleted workspace can only be restored by contacting support. Sites, cPanel accounts and mailspaces already pending deletion do not block it. Requires an admin role on the workspace. Returns 202 with no body.

Errors
  • 401 forbidden | you are not an admin of this account
  • 401 last_workspace | it is your only account
  • 404 | no such account, or not one of yours; no body
  • 422 workspace_not_empty | remove what is listed in blockers first
  • 422 move_in_progress | a workspace move involving it is still open
  • 422 already_archived | it is already deleted; only returned to CloudPress staff
workspace_not_empty body
  • blockers: Array<Object>
    • code: String | sub_workspaces, sites, cpanel_accounts, mailspaces, domain_registrations, dns_zones, domains, subscriptions, invoices, dunning_cases, disputes, cart_checkouts, managed_users, tasks or reseller_billing_plan
    • count: Integer

Account Roles

Manage which users have access to an account, and at what role. Requires an admin role on the account. Not available via OAuth.

List Account Roles

GET /api/accounts/:account_id/roles

Returned Params
  • account_roles: Array<Object>
    • inherited_from: String | account id, or null
    • created_at: DateTime
    • updated_at: DateTime
    • role: Object
      • id: Integer
      • name: String
      • label: String
      • is_admin: Boolean
      • can_edit: Boolean
      • can_create: Boolean
      • can_destroy: Boolean
      • billing: Boolean
      • wp_login: Boolean
    • user: Object
      • id: String
      • fname: String
      • lname: String
      • email: String
      • account_brand_id: Integer
      • locale: String
      • created_at: DateTime
      • updated_at: DateTime

View a User's Role

GET /api/accounts/:account_id/roles/:user_id

Returns one entry, wrapped in a single account_role object rather than the account_roles array the list returns.

Returned Params
  • account_role: Object
    • inherited_from: String | account id, or null
    • created_at: DateTime
    • updated_at: DateTime
    • role: Object
      • id: Integer
      • name: String
      • label: String
      • is_admin: Boolean
      • can_edit: Boolean
      • can_create: Boolean
      • can_destroy: Boolean
      • billing: Boolean
      • wp_login: Boolean
    • user: Object
      • id: String
      • fname: String
      • lname: String
      • email: String
      • account_brand_id: Integer
      • locale: String
      • created_at: DateTime
      • updated_at: DateTime

Invite a User

Invite an existing user to the account by email. Returns 202.

POST /api/accounts/:account_id/roles

Params
  • email: String
  • user_role_id: Integer | see User Roles

Change a User's Role

PATCH /api/accounts/:account_id/roles/:user_id

Params
  • account_role: Object
    • user_role_id: Integer

Returns the updated role in the same shape as GET /api/accounts/:account_id/roles/:user_id.

Returned Params
  • account_role: Object
    • inherited_from: String | account id, or null
    • created_at: DateTime
    • updated_at: DateTime
    • role: Object
      • id: Integer
      • name: String
      • label: String
      • is_admin: Boolean
      • can_edit: Boolean
      • can_create: Boolean
      • can_destroy: Boolean
      • billing: Boolean
      • wp_login: Boolean
    • user: Object
      • id: String
      • fname: String
      • lname: String
      • email: String
      • account_brand_id: Integer
      • locale: String
      • created_at: DateTime
      • updated_at: DateTime

Remove a User

DELETE /api/accounts/:account_id/roles/:user_id

Returns 202.

Inherited roles

A role inherited from a parent account cannot be removed at the child level — doing so returns 422 {"errors":["Unable to remove an inherited role."]}. Change the parent role to update all descendants.


User Roles

List the available role definitions. Use the returned id when inviting or updating users on an account.

GET /api/user_roles

Returned Params
  • user_roles: Array<Object>
    • id: Integer
    • name: String
    • label: String
    • is_admin: Boolean
    • can_edit: Boolean
    • can_create: Boolean
    • can_destroy: Boolean
    • billing: Boolean
    • wp_login: Boolean