External references
Your own stable handle for a tenant — the idempotency key on create and an accepted fallback lookup afterward. The canonical address is the tenant_id returned by create.
An external_ref is your own stable handle for a tenant. Its primary job is to make create idempotent: the pair (account, external_ref) is the create idempotency lock, so a retried provision returns the same tenant instead of making a new one. create takes only external_ref (the tenant has no UUID yet).
After create, the canonical address is the tenant_id returned in the create response — pass that to every later endpoint. Those endpoints also accept external_ref as a fallback lookup (supply exactly one of tenant_id or external_ref), but tenant_id is the identifier the API treats as primary.
Format
Use a <panel>:<id> shape so the source system is obvious at a glance:
| Panel | Example |
|---|---|
| WHMCS | whmcs:1234 |
| Upmind | upmind:acct_abc |
| Custom | custom:org_42 |
The value is scoped per account — the same string can exist under two different platform accounts without collision. It is stored as text; keep it under roughly 200 characters.
Never reuse a value
Do not reuse an external_ref for a different service, even after the original
tenant has been terminated. The mapping is permanent, and reuse will resolve to
the old, now-deleted tenant rather than provisioning a new one.
tenant_id vs external_ref
Store the tenant_id from the create response and use it on every later call — it is the canonical address. Keep your external_ref too: it is the create idempotency key, and any endpoint will also accept it as a fallback lookup if you ever lose the tenant_id (it survives panel restarts and DB migrations because it is yours). Supply exactly one of the two on a call; if you send both, tenant_id wins.
Data model
How platform accounts, tenants, and web-host users fit together — and which of them is the billing entity.
WHMCS module
Resell Swarmz from WHMCS with no code. Install the module, set your API key once, create a server, and every WHMCS service lifecycle event provisions, signs in, suspends, and tears down a tenant for you.