Platform tenancy

Every platform you connect to has its own notion of “your account over there.” Five9 calls it a Domain. GetDialed’s generic name for it is a tenant. Your rate limits, your quota budget, and your per-action dispatch settings all belong to that record — not to the individual credentials you used to reach it. GetDialed stores it as a first-class object so N credentials pointing at the same tenant share one budget instead of racing each other into a throttle. A tenant is also what a credential belongs to: a credential serves every compatible service of its tenant, which is why the tenant rather than the service is the record that owns the budget.

What a Domain is

A Domain is Five9’s own tenant boundary. You never type its identifier in: when you create a Five9 credential, GetDialed calls Five9 with the credentials you supplied, reads back the canonical Domain identifier from getVCCConfiguration, and binds the credential to that Domain — creating the record if this is the first time your account has connected to it. The label comes from the catalog. Each platform publishes a tenancy_unit describing what it calls its own tenant record, so the API can label it correctly without a hard-coded lookup:

{
  "tenancy_unit": {
    "name": "Domain",
    "plural": "Domains",
    "key_field": "domain_id",
    "key_source": "getVCCConfiguration.domainId"
  }
}

Five9 returns “Domain”. Every other platform returns its own word, and the same concepts on this page apply under that name:

Platform	Calls its tenant	Discovered from
Five9	Domain	The Five9 login you supplied, at credential-create time
Postmark	Server	The connected server itself — GetDialed asks the Postmark server token which server it belongs to, at credential-create time

A Postmark Server is a narrower boundary than an Account, and that is the point. A Postmark account can hold many servers, and a server owns its own token, its own suppression list, its own inbound hook and its own message history. Anchoring on the server rather than the account is what keeps one connection’s mail — including the message content Postmark retains after delivery — out of another’s reach. See connecting Postmark.

A tenant’s identity always comes from the provider, never from you. There is no field to type an account id into on either platform — GetDialed calls the provider with the material you supplied and reads the canonical identifier back. That is what makes the record trustworthy as a budget key: an operator-typed identifier could collide with another account’s, drift after a rename, or simply be wrong, and every one of those failures would show up as two tenants quietly sharing one provider budget.The one exception is a tenant you name yourself, where there is no provider identity to discover — and those are marked is_manual precisely so the two are never confused.

Tenants you name yourself

Not every platform publishes a way to identify your account with it, and not every credential is tied to a vendor at all. For those, you supply the label instead of the platform: pass tenant_name when creating the credential and GetDialed files it under a manual tenant of that name, in the same call. There is no create-the-tenant-first step. A manual tenant is the same kind of record as a discovered one — it is listed, renamed and retired the same way — with two differences worth knowing:

Its budget is empty. There is no provider publishing rate caps for it, so there are no caps to seed and nothing to correct against a live reading.
Its name is unique to your organization only. Two organizations may both have a tenant called acme-crm; nothing is claimed platform-wide.

is_manual on the tenant record tells the two apart, and you can filter a list on it.

One tenant, one budget

Five9’s rate limits are counted per Domain, not per login. Two credentials using two different Five9 users against the same Domain draw down the same 20-calls-per-minute upload allowance. GetDialed models that directly: the second credential resolves to a Domain that already exists, so it binds to the existing record rather than creating a duplicate. Every credential carries the resulting tenancy_id back-reference:

{
  "id": "cred_e5f6g7h8",
  "name": "Five9 Production",
  "platform_id": "five9",
  "auth_method": "basic_auth",
  "status": "active",
  "tenancy_id": "ten_9f2c1a7b3d4e5f60"
}

tenancy_id is server-managed — you cannot set it on create or update, and any value you send is ignored. Credentials sharing a tenancy_id are credential lanes into one budget.

One account per Domain

A Five9 Domain belongs to exactly one GetDialed account, platform-wide. This is not a per-organization check: if any other GetDialed account has already connected that Domain, your create is refused.

POST /credentials returns 409 Conflict with a message telling you the Domain is already connected to another account and to reach out to us for support. Nothing is stored — no credentials, no record.
Both credential-test endpoints report the same thing at 200 with error: "PERMISSION_DENIED", so you find out before you save. Testing writes nothing either way.

Manual tenants are exempt from this: nothing is claimed platform-wide for a tenant you named yourself, so two organizations can hold the same label without conflict.

Resolution is a network call to Five9. If the credentials are wrong or Five9 cannot be reached, creating the credential fails with a 400 rather than storing a credential that has no Domain. The failure message tells you which of the two happened without echoing anything Five9 said back.

Deleting the last credential bound to a Domain releases the platform-wide claim, and any account — including yours — is free to claim it again. There is no support gate and no waiting period. The Domain record itself is archived rather than destroyed, so re-adding a credential restores the safety margins and lane settings you configured.

Rate buckets and effective limits

A Domain groups its limits into rate buckets, keyed by Five9’s own apiOperationType names (Query, Modify, Upload, and so on). Each bucket holds the raw provider caps for three windows — 60 seconds, 3,600 seconds (one hour), and 86,400 seconds (one day) — seeded from the catalog defaults and then corrected against a live getCallCountersState reading taken on the same session that resolved the Domain. On top of the raw caps sits a safety margin: a percentage, set per bucket, that can only ever reduce the budget.

effective = cap × margin_pct / 100

Raw caps and margin are stored separately and the product is computed at read. That is what lets a limits refresh overwrite the provider caps without clobbering your margin, and a margin edit change nothing about the provider caps. Margins accept 1–100; anything above 100 is rejected, because a margin above the provider cap would hand out budget Five9 never granted, and 0 would be a permanent outage rather than a safety margin.

{
  "Upload": {
    "label": "Uploading (batch)",
    "caps": { "60": 20, "3600": 400, "86400": 2000 },
    "margin_pct": 80,
    "max_records_per_request": 50000,
    "source": "live",
    "observed_at": "2026-07-25T18:00:00Z",
    "effective": { "60": 16, "3600": 320, "86400": 1600 }
  }
}

A bucket also stores a minimum interval — a floor on the gap between two calls, for providers whose real constraint is per-second rather than per-minute. It is seeded from the platform’s catalog default when the tenant is bound, and it is the value the dispatcher reads on every claim, exactly like the caps beside it. Your safety margin is deliberately not applied to it: a margin multiplies call counts, and applying it to a duration would shorten the gap rather than lengthen it.

The stored minimum interval is not on this read surface yet. The bucket response above reports the caps, the margin, the payload cap and the effective budget; the pacing floor is enforced but not yet returned. To see the default your platform ships, read the service’s rate_buckets in the catalog, which does publish it.

The record’s sync_status tells you where the caps came from:

Value	Meaning
`catalog_default`	The caps are the provider’s published defaults from the catalog and have never been live-corrected. A manual tenant reports this permanently — there is no provider to read counters from.
`live`	The caps were observed from Five9 and folded into the record. `counters_synced_at` records when.
`stale`	A refresh was attempted but the reading came back unusable, so the previous caps are still in force.

stale is a deliberate outcome, not a failure to fix. A garbled or zero-valued counter reading never overwrites a good stored cap, because a bad reading that zeroed a budget would silently stop all delivery against that Domain. Inspect sync_status rather than the status code when you refresh. The caps above are the denominators; how much of each is left right now is a separate read. Quota and progress covers the remaining-budget surface, the queue depth with its estimated completion, a pre-flight cost estimate for an upload you have not sent yet, and — because several credentials can share one Domain’s budget — which credential has been spending it.

Lanes and ordering

Actions against a Domain are placed into one of four named dispatch lanes:

Lane	Intended for	Claims capacity
`interactive`	Small, latency-sensitive calls a person is waiting on.	First, always
`compliance`	Regulatory work that must not wait behind bulk traffic — DNC writes are the canonical case.	Second
`bulk`	High-volume writes, such as batched list uploads. The default lane.	Shares the remainder, 3 parts
`backfill`	Lowest-priority catch-up work that should yield to everything else.	Shares the remainder, 1 part

The catalog seeds a default lane per action. An admin can override that placement for their own Domain (lane_overrides) and fix the order actions run in within a lane (lane_order). Ordering is an explicit ordered list of action IDs, not a numeric weight — the lane set is fixed and finite so the resulting order is deterministic and explainable. Lane prioritization is in force: dispatch is paced against the effective budget, the lane order above decides who claims each freed call, and every lane carries a maximum wait that overrides that order rather than letting a busy lane starve a quieter one. Changing lane_overrides changes the order your work actually dispatches in. See lane order and the starvation floor for the weights, the per-lane bounds, and how the within-lane priority boost interacts with them. A lane can also be paused individually.

Endpoints

There are two views onto the same records. /v1/tenants is the platform-agnostic one — it lists every tenant you hold across every platform, including the ones you named yourself. /v1/platforms/five9/domains is the Five9-flavored one, and it is where the Five9-specific operations live: the rate-bucket and lane tuning, the live limits refresh, and the quota surfaces.

All tenants — `/v1/tenants`

Method	Endpoint	Access	Purpose
`GET`	`/tenants`	Any organization member	List every tenant you hold, on any platform. Filter with `platform_id`, or with `is_manual` to separate tenants you named from discovered vendor accounts. Sort with `sort_by` (`created_at`, `label`) and `order`; paginate with `limit` and `skip`.
`GET`	`/tenants/{tenancy_id}`	Any organization member	Fetch one tenant, with its rate budget.
`PATCH`	`/tenants/{tenancy_id}`	Admin	Rename a tenant — change its display `label`, and only that.
`DELETE`	`/tenants/{tenancy_id}`	Admin	Retire a tenant, freeing the provider account it holds.

A rename changes the label and nothing else. A tenant’s identity is fixed when it is created, because every record that points at it — your credentials, its stored rate budget, queued work — is keyed on that identity. Nothing is keyed on the label, so renaming affects no credential, no budget and no queued work. Any field other than label in the body is rejected with 422 rather than quietly ignored. A retire is guarded, and never cascades. DELETE /tenants/{tenancy_id} is refused with 409 while anything still references the tenant — its credentials, its stored rate-limit budget, or queued dispatch work — because those records are keyed on it and would be left pointing at nothing. The refusal names which category is blocking and how many references it found. Nothing is written on a refusal, so the same request can be retried once the references are gone. No credential and no stored secret is ever removed by retiring a tenant. The record is archived rather than destroyed and its tuned rate-limit configuration is kept, so re-adding the same provider account later restores your margins and lane settings instead of starting from defaults. Retiring an already-retired tenant succeeds — the operation is idempotent. A tenancy id belonging to another organization returns 404, never 403, on all four.

Five9 Domains — `/v1/platforms/five9/domains`

Domains are system-managed: they are created by credential binding and released when the last bound credential is deleted, so there is deliberately no create endpoint here.

Method	Endpoint	Access	Purpose
`GET`	`/platforms/five9/domains`	Any organization member	List your Domains. Sort with `sort_by` (`created_at`, `domain_name`) and `order`; paginate with `limit` and `skip`.
`GET`	`/platforms/five9/domains/{tenancy_id}`	Any organization member	Fetch one Domain.
`PATCH`	`/platforms/five9/domains/{tenancy_id}`	Admin	Edit per-bucket `margins`, `lane_overrides`, and `lane_order`. Raw caps are never writable here.
`POST`	`/platforms/five9/domains/{tenancy_id}/refresh-limits`	Admin	Re-read Five9’s live counters through an active bound credential and fold the observed caps in. The margin is untouched.
`GET`	`/platforms/five9/domains/{tenancy_id}/headroom`	Any organization member	Remaining budget for every bucket and window. A live projection, never a reservation.
`GET`	`/platforms/five9/domains/{tenancy_id}/queue`	Any organization member	Queue depth and estimated completion per bucket, naming the window that binds.
`GET`	`/platforms/five9/domains/{tenancy_id}/attribution`	Any organization member	Which credential spent the budget, per bucket and window, including the unattributed remainder.
`GET`	`/platforms/five9/domains/{tenancy_id}/usage`	Any organization member	Recorded usage history, newest first. Counts only, retained 30 days, cursor-paged.
`POST`	`/platforms/five9/domains/{tenancy_id}/estimate`	Any organization member	Price an upload before sending it. Commits nothing — no batch, no records, no reservation.

Reading one:

curl "$BASE_URL/platforms/five9/domains/ten_9f2c1a7b3d4e5f60" \
  -H "X-API-Key: $GETDIALED_API_KEY"

{
  "id": "ten_9f2c1a7b3d4e5f60",
  "org_id": "org_a1b2c3d4",
  "platform_id": "five9",
  "domain_id": "100200",
  "domain_name": "Acme Corp",
  "api_host": "api.five9.com",
  "tenancy_unit": {
    "name": "Domain",
    "plural": "Domains",
    "key_field": "domain_id",
    "key_source": "getVCCConfiguration.domainId"
  },
  "buckets": {
    "Upload": {
      "label": "Uploading (batch)",
      "caps": { "60": 20, "3600": 400, "86400": 2000 },
      "margin_pct": 80,
      "max_records_per_request": 50000,
      "source": "live",
      "observed_at": "2026-07-25T18:00:00Z",
      "effective": { "60": 16, "3600": 320, "86400": 1600 }
    }
  },
  "bucket_map": {
    "five9__configuration_service__add_to_list": {
      "operation_types": ["Upload"],
      "resolved": true
    }
  },
  "lane_overrides": {
    "five9__configuration_service__add_to_list": "bulk"
  },
  "lane_order": {
    "bulk": ["five9__configuration_service__add_to_list"]
  },
  "sync_status": "live",
  "counters_synced_at": "2026-07-25T18:00:00Z",
  "status": "active",
  "created_at": "2026-07-25T17:00:00Z",
  "updated_at": "2026-07-25T18:00:00Z"
}

Editing a margin, leaving everything else alone:

curl -X PATCH "$BASE_URL/platforms/five9/domains/ten_9f2c1a7b3d4e5f60" \
  -H "X-API-Key: $GETDIALED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"margins": {"Upload": 80}}'

Omit a field to leave it untouched — an explicit null is rejected rather than treated as “clear this”, and an empty body is a no-op that returns the record unchanged. A Domain ID belonging to another organization returns 404, never 403.

Next steps

Credentials

Create the credentials that bind to a tenant.

Integration catalog

See the published rate buckets a Domain seeds its caps from.

Batched delivery

Bulk writes that consume the Upload bucket.

API reference

Full request and response schemas for every Domain endpoint.

Getting Started

Core Concepts

Building Flows

Triggers & Streaming

What a Domain is

Tenants you name yourself

One tenant, one budget

One account per Domain

Rate buckets and effective limits

Lanes and ordering

Endpoints

All tenants — `/v1/tenants`

Five9 Domains — `/v1/platforms/five9/domains`

Next steps

Credentials

Integration catalog

Batched delivery

API reference

​What a Domain is

​Tenants you name yourself

​One tenant, one budget

​One account per Domain

​Rate buckets and effective limits

​Lanes and ordering

​Endpoints

​All tenants — /v1/tenants

​Five9 Domains — /v1/platforms/five9/domains

​Next steps

Credentials

Integration catalog

Batched delivery

API reference

What a Domain is

Tenants you name yourself

One tenant, one budget

One account per Domain

Rate buckets and effective limits

Lanes and ordering

Endpoints

All tenants — `/v1/tenants`

Five9 Domains — `/v1/platforms/five9/domains`

Next steps