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,refundedorrefund_failed - cancelable: Boolean | whether you may cancel it now with Cancel a Workspace Move
- 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
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-Accountto 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 theX-Auth-Accountworkspace, or it is not a reseller (without the header: you are not an admin) - 422
account_invalid| the account failed validation, including an unknownparent_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_digestyou 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_centsyou 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:
- Send the request. It answers
422requires_confirmationwith apreviewand apreview_digest. - Send it again with
confirm_preview_digest. If the move has changed in the meantime, it answerspreview_stalewith 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
202with{ "move": { "guid": "…", "status": "…" } }instead of the account; - follow the move with
moveon View Account, or cancel it with Cancel a Workspace Move; - send
confirm_total_centsto 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 |
noneorrequired - billing_quote: Object | only when
billingisrequired- currency: String
- charge_subtotal_cents: Integer
- tax_cents: Integer |
nullwhen 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
- user: Object |
- parent_before: Object |
- 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_guidnames 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| reviewpreview, then confirm - 422
preview_stale| the move has changed; confirm with the new digest - 422
drift| the total moved by more than 50 cents fromconfirm_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 inblockersfirst - 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,tasksorreseller_billing_plan - count: Integer
- code: String |
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