---
title: "Check cPanel (mode uapi) or WHM (mode whm) sign-in details in a few seconds, before creating an import. The address is cleaned the same way an import cleans it; the credentials are used for this call only"
method: POST
path: "/migrations/cpanel/test"
tags: ["Migrations"]
---

# Check cPanel (mode uapi) or WHM (mode whm) sign-in details in a few seconds, before creating an import. The address is cleaned the same way an import cleans it; the credentials are used for this call only

`POST /migrations/cpanel/test`

## Request

- Base URL: `https://hostingsurge.com/api/v1`
- URL: `https://hostingsurge.com/api/v1/migrations/cpanel/test`
- Auth: one of:
  - HTTP bearer
  - API key in cookie `__Host-hs_session`

## Query parameters

- `orgId` string

## Request body

- object
  - `mode` 'uapi' | 'whm' | 'auto': uapi: one account; whm: a whole server; auto: let the details decide (the dashboard)
  - `host` string, required
  - `port` integer
  - `username` string: the cPanel user (or a domain of the account, looked up through WHM); root or empty for a whole server
  - `auth` 'token' | 'password' | 'auto' | 'whm': what `token`/`password`/`secret` holds; auto: a 32-character token or a password; whm: a WHM API token (made in WHM as root or a reseller), tried on WHM only — for one account (username) or the whole server
  - `whmUser` string: auth "whm": the WHM user the token belongs to (default: root, then username as a reseller)
  - `token` string: Access token (read access is enough; a Vercel or Netlify import with envBridge: true also creates and deletes its temporary builds with it). Encrypted, bound to this migration and wiped when it ends (at most 24 h). Never returned or logged
  - `password` string
  - `secret` string: the token or password, whichever it is (auth auto)

## Response `200`

The result: ok, or what went wrong and what to do (never an HTTP error for a failed connection)

- object
  - `ok` boolean, required
  - `code` 'ok' | 'invalid_host' | 'invalid_input' | 'dns' | 'blocked_address' | 'refused' | 'timeout' | 'tls' | 'wrong_port' | 'not_cpanel' | 'unauthorized' | 'two_factor' | 'locked' | 'ip_not_allowed' | 'permission_denied' | 'api_disabled' | 'rate_limited' | 'unavailable' | 'network' | 'too_large' | 'module_error' | 'invalid_response' | 'size_mismatch' | 'account_not_found' | 'root_password' | 'sign_in_paused', required: ok, or what went wrong
  - `message` string, required: what happened and what to do, in plain English
  - `mode` 'uapi' | 'whm', required: what the details turned out to be for: one account (uapi, also when it is reached through WHM) or a whole server (whm)
  - `host` string, nullable, required: the cleaned host the import will use (the name on the certificate when an IP or a website domain was typed)
  - `port` integer, nullable, required: the port that answered (or was tried last)
  - `username` string, nullable, required: uapi: the cPanel account; whm: the WHM user
  - `mainDomain` string, nullable, required
  - `domains` integer, nullable, required: uapi: domains on the account
  - `accounts` integer, nullable, required: whm: cPanel accounts on the server
  - `certificateNames` string[]: tls: the names the certificate is valid for
  - `suggestion` 'use_whm' | 'use_cpanel' | 'use_token' | 'try_whm_token' | 'null', nullable, required: use_whm: these are WHM details, import the whole server (mode whm); use_cpanel: these are cPanel account details (mode uapi); use_token: the account needs an API token (two-factor authentication); try_whm_token: the token was tried as the account's cPanel token only and WHM answers on this server: if it was made in WHM, test again with auth "whm"
  - `auth` 'token' | 'password' | 'whm' | 'null', nullable: ok: how the import signs in; "whm" = this one account through WHM with the WHM token of whmUser (create the import with auth "whm")
  - `whmUser` string, nullable: auth "whm": the WHM user the token belongs to
  - `connectFrom` string, nullable: the IP address our requests come from (for a firewall, cPHulk or a token allow-list)
  - `serverAccounts` string[]: account_not_found: the cPanel accounts the WHM token can see (at most 20)
  - `retryAfterSeconds` integer: sign_in_paused: the server refused several of our sign-ins within the last hour; none is sent to it for this many seconds (so its firewall does not block our address)
  - `attempts` object[]: what was tried, in order (never a credential)
    - `panel` 'cpanel' | 'whm', required
    - `host` string, required
    - `port` integer, required
    - `as` 'user' | 'root' | 'none', required: the typed user, root, or nobody (the credential-free check)
    - `auth` 'token' | 'password' | 'whm' | 'probe', required
    - `result` string, required: ok, or the problem class
    - `status` integer, nullable, required
    - `reason` string, nullable, required
    - `ms` integer, required

## Other responses

- `400`: Invalid request (code invalid_request)
- `401`: Missing or invalid session/token (code unauthorized)
- `403`: Authenticated but not permitted (code forbidden)
- `404`: Not found or not visible to the caller (code not_found)
- `409`: Conflicting state (code conflict)
- `429`: Too many requests (code rate_limited); see Retry-After
- `501`: Not available on this server (code not_configured)
- `503`: Hosting engine unavailable (code provider_unavailable)

---

[API](https://skmtc.dev/hostingsurge/apis/hostingsurge-platform-api.md) · [All operations](https://skmtc.dev/hostingsurge/apis/hostingsurge-platform-api/llms.txt) · [OpenAPI document](https://skmtc.dev/hostingsurge/apis/hostingsurge-platform-api/revisions/4d08337cdff1?raw)