--- title: "Clusters & counties endpoints — API reference | Data Tactical Group" route: "/docs/api/reference/clusters-and-counties" updated: "2026-10-23" --- # Clusters & counties 17 endpoints, generated from the API's own OpenAPI document. The organization's county set and its saved clusters of codes or counties. ## GET `/v2/account/clusters` **List the organization's clusters** Credentials: API key or App session. Operation id `geoListClusters`. Returns every live (not deleted) cluster of the caller's organization, oldest first, optionally filtered by kind. Clusters are named, reusable sets of NAICS codes, SOC codes or counties, free on every plan and unlimited in number; any member may read them. Reference one on the data endpoints as `naics=cluster:`, `soc=cluster:` or `areas=cluster:` to get one summed series labelled with the cluster's name. Credential: an API key or a session; any role. Reading is not paused when payment is past due. A sandbox key sees the same organization's clusters as a live key. ### Parameters **`kind` query · "naics" | "soc" | "fips"** Only clusters of this kind (`naics`, `soc` or `fips`). ### Responses #### `200` success The organization's live clusters. As `application/json`. **`data` array of GeoCluster always present** The organization's live (not deleted) clusters, oldest first. Not paged. **`data[].id` string (uuid) always present** The cluster id; use it as `cluster:` on the data endpoints. **`data[].kind` "naics" | "soc" | "fips" always present** What a cluster's members are. `naics`: NAICS industry codes (numeric, as the platform stores them), referenced on the data endpoints as `naics=cluster:`. `soc`: SOC occupation codes, referenced as `soc=cluster:`. `fips`: 5-digit county FIPS codes, referenced as `areas=cluster:` (an area cluster). Fixed when the cluster is created and never changes. **`data[].name` string always present** The name, trimmed of surrounding spaces, 1 to 120 characters. (at most 120 characters) **`data[].codes` array of string always present** The members as saved: duplicates removed. `fips` clusters are sorted by FIPS; `naics` and `soc` clusters are in the taxonomy's own display order. NAICS codes are returned as strings of digits. **`data[].created_at` string (date-time) always present** When the cluster was created. **`data[].updated_at` string (date-time) always present** When the cluster was last renamed, re-membered or restored. #### `400` error Bad Request. Codes: [`kind_invalid`](/docs/api/errors#code-kind-invalid) (`kind` is not naics, soc or fips), [`bad_request`](/docs/api/errors#code-bad-request) (`kind` given more than once). As `application/problem+json`. #### `401` error Unauthorized. Codes: [`unauthenticated`](/docs/api/errors#code-unauthenticated) (no valid API key or session); [`key_revoked`](/docs/api/errors#code-key-revoked) (an API key that was revoked: `revoked_at`, and `reason` -- `holder`, `admin`, `member_removed`, `seat_removed`, `api_disabled`, `addon_ended`, [`account_closed`](/docs/api/errors#code-account-closed), [`org_closed`](/docs/api/errors#code-org-closed), `retired`, or null for a key revoked before T110 -- and a sentence saying when and why). As `application/problem+json`. #### `403` error Forbidden. Codes: [`no_membership`](/docs/api/errors#code-no-membership), [`account_suspended`](/docs/api/errors#code-account-suspended), [`org_suspended`](/docs/api/errors#code-org-suspended), [`org_closed`](/docs/api/errors#code-org-closed), [`wrong_instance`](/docs/api/errors#code-wrong-instance) (a key of the mode this process does not serve; `base_url` names the address that serves it). As `application/problem+json`. #### `404` error Not Found. Codes: [`not_found`](/docs/api/errors#code-not-found) (the `X-DTG-Org` header names no organization the caller may use). As `application/problem+json`. #### `429` error rate\_limited (the per-minute ceiling, X-RateLimit-\* say which), points\_exhausted (the monthly points allowance; Retry-After to the end of the UTC month), server\_busy or sandbox\_busy (load; retry after Retry-After). A refused server\_busy request is not metered. As `application/problem+json`. **`Retry-After` header** Seconds to wait before retrying. **`X-RateLimit-Limit` header** The per-minute request ceiling that applies. **`X-RateLimit-Remaining` header** Requests left in the current window. **`X-RateLimit-Reset` header** Seconds until the window refills: on every answer, the time until the bucket is full again; on a refusal, until a request is allowed (as `Retry-After`). Problem codes: [`kind_invalid`](/docs/api/errors#code-kind-invalid) (400), [`bad_request`](/docs/api/errors#code-bad-request) (400), [`unauthenticated`](/docs/api/errors#code-unauthenticated) (401), [`key_revoked`](/docs/api/errors#code-key-revoked) (401), [`account_closed`](/docs/api/errors#code-account-closed) (401), [`org_closed`](/docs/api/errors#code-org-closed) (401), [`no_membership`](/docs/api/errors#code-no-membership) (403), [`account_suspended`](/docs/api/errors#code-account-suspended) (403), [`org_suspended`](/docs/api/errors#code-org-suspended) (403), [`org_closed`](/docs/api/errors#code-org-closed) (403), [`wrong_instance`](/docs/api/errors#code-wrong-instance) (403), [`not_found`](/docs/api/errors#code-not-found) (404). Every problem is a [problem document](/docs/api/errors). ## POST `/v2/account/clusters` **Create a cluster** Credentials: API key or App session. Operation id `geoCreateCluster`. Saves a named set of NAICS codes, SOC codes or counties. Validation happens here, at save: NAICS and SOC members must exist in the current vintage's taxonomy and may not include an ancestor and a descendant of each other (so the cluster can always be summed); county (`fips`) members must lie inside the organization's active entitled county set. Names are unique per organization and kind among live clusters (case-insensitively), and so are member sets (order-independent), L10; a NAICS "Healthcare" and a SOC "Healthcare" can coexist. Clusters are free on every plan. Credential: an API key or a session; any role may create. While the organization's payment is past due, creating is refused 403 [`plan_required`](/docs/api/errors#code-plan-required) with `entitlement: "past_due"`. A sandbox key may create clusters and use them against sandbox geography: it is never past due, and every 5-digit county code passes the entitlement check (the sandbox's synthetic counties included). Side effect: one audit row, `cluster.created`. ### Request body Required; `application/json`. **`kind` "naics" | "soc" | "fips" required** What a cluster's members are. `naics`: NAICS industry codes (numeric, as the platform stores them), referenced on the data endpoints as `naics=cluster:`. `soc`: SOC occupation codes, referenced as `soc=cluster:`. `fips`: 5-digit county FIPS codes, referenced as `areas=cluster:` (an area cluster). Fixed when the cluster is created and never changes. **`name` string required** The cluster's name, 1 to 120 characters after trimming. Unique per organization and kind among live clusters, case-insensitively. (at most 120 characters) **`codes` array of string required** The members, 1 to 1,000 strings (duplicates are dropped). `naics`: numeric NAICS codes known to the current vintage's taxonomy, with no code that is an ancestor or descendant of another (so the cluster can always be summed). `soc`: SOC codes known to the current vintage's taxonomy, with the same no-overlap rule. `fips`: 5-digit county FIPS codes, every one inside the organization's ACTIVE entitled county set (the counties from `GET /v2/account/counties` that are not shed, plus the trial county while a trial runs; every 5-digit code passes for an organization entitled to every county, and for a sandbox key). ### Responses #### `201` success The created cluster. As `application/json`. **`id` string (uuid) always present** The cluster id; use it as `cluster:` on the data endpoints. **`kind` "naics" | "soc" | "fips" always present** What a cluster's members are. `naics`: NAICS industry codes (numeric, as the platform stores them), referenced on the data endpoints as `naics=cluster:`. `soc`: SOC occupation codes, referenced as `soc=cluster:`. `fips`: 5-digit county FIPS codes, referenced as `areas=cluster:` (an area cluster). Fixed when the cluster is created and never changes. **`name` string always present** The name, trimmed of surrounding spaces, 1 to 120 characters. (at most 120 characters) **`codes` array of string always present** The members as saved: duplicates removed. `fips` clusters are sorted by FIPS; `naics` and `soc` clusters are in the taxonomy's own display order. NAICS codes are returned as strings of digits. **`created_at` string (date-time) always present** When the cluster was created. **`updated_at` string (date-time) always present** When the cluster was last renamed, re-membered or restored. #### `400` error Bad Request. Codes: [`kind_invalid`](/docs/api/errors#code-kind-invalid) (kind missing or not naics, soc or fips), [`name_invalid`](/docs/api/errors#code-name-invalid) (name missing, blank, or over 120 characters), [`codes_invalid`](/docs/api/errors#code-codes-invalid) (codes not a non-empty array of strings), [`member_cap`](/docs/api/errors#code-member-cap) (more than 1,000 codes), [`bad_code`](/docs/api/errors#code-bad-code) (a county that is not 5 digits, or a NAICS code that is not numeric; `errors` names it), [`unknown_codes`](/docs/api/errors#code-unknown-codes) (codes the current taxonomy does not know; `errors` names them), [`codes_overlap`](/docs/api/errors#code-codes-overlap) (one code contains another; `errors` names the pair as `{code, contained_in}`), [`counties_outside_set`](/docs/api/errors#code-counties-outside-set) (counties outside the organization's active entitled set; `errors` lists each `{fips}`), [`malformed_json`](/docs/api/errors#code-malformed-json) (the body is not JSON). As `application/problem+json`. #### `401` error Unauthorized. Codes: [`unauthenticated`](/docs/api/errors#code-unauthenticated) (no valid API key or session); [`key_revoked`](/docs/api/errors#code-key-revoked) (an API key that was revoked: `revoked_at`, and `reason` -- `holder`, `admin`, `member_removed`, `seat_removed`, `api_disabled`, `addon_ended`, [`account_closed`](/docs/api/errors#code-account-closed), [`org_closed`](/docs/api/errors#code-org-closed), `retired`, or null for a key revoked before T110 -- and a sentence saying when and why). As `application/problem+json`. #### `403` error Forbidden. Codes: [`plan_required`](/docs/api/errors#code-plan-required) with `entitlement: "past_due"` (payment is past due; cluster editing is paused until the balance is settled, L18), [`no_membership`](/docs/api/errors#code-no-membership), [`account_suspended`](/docs/api/errors#code-account-suspended), [`org_suspended`](/docs/api/errors#code-org-suspended), [`org_closed`](/docs/api/errors#code-org-closed), [`wrong_instance`](/docs/api/errors#code-wrong-instance) (`base_url` names the address that serves the key). As `application/problem+json`. #### `404` error Not Found. Codes: [`not_found`](/docs/api/errors#code-not-found) (the `X-DTG-Org` header names no organization the caller may use). As `application/problem+json`. #### `409` error Conflict. Codes: [`cluster_name_taken`](/docs/api/errors#code-cluster-name-taken) (a live cluster of this kind already has this name), [`cluster_members_taken`](/docs/api/errors#code-cluster-members-taken) (a live cluster of this kind already has exactly these members). Both carry `existing`, the cluster that holds it. As `application/problem+json`. #### `413` error Payload Too Large. Codes: [`body_too_large`](/docs/api/errors#code-body-too-large) (the body is over 64 KiB; carries `limit_bytes`). As `application/problem+json`. #### `429` error rate\_limited (the per-minute ceiling, X-RateLimit-\* say which), points\_exhausted (the monthly points allowance; Retry-After to the end of the UTC month), server\_busy or sandbox\_busy (load; retry after Retry-After). A refused server\_busy request is not metered. As `application/problem+json`. **`Retry-After` header** Seconds to wait before retrying. **`X-RateLimit-Limit` header** The per-minute request ceiling that applies. **`X-RateLimit-Remaining` header** Requests left in the current window. **`X-RateLimit-Reset` header** Seconds until the window refills: on every answer, the time until the bucket is full again; on a refusal, until a request is allowed (as `Retry-After`). Problem codes: [`kind_invalid`](/docs/api/errors#code-kind-invalid) (400), [`name_invalid`](/docs/api/errors#code-name-invalid) (400), [`codes_invalid`](/docs/api/errors#code-codes-invalid) (400), [`member_cap`](/docs/api/errors#code-member-cap) (400), [`bad_code`](/docs/api/errors#code-bad-code) (400), [`unknown_codes`](/docs/api/errors#code-unknown-codes) (400), [`codes_overlap`](/docs/api/errors#code-codes-overlap) (400), [`counties_outside_set`](/docs/api/errors#code-counties-outside-set) (400), [`malformed_json`](/docs/api/errors#code-malformed-json) (400), [`unauthenticated`](/docs/api/errors#code-unauthenticated) (401), [`key_revoked`](/docs/api/errors#code-key-revoked) (401), [`account_closed`](/docs/api/errors#code-account-closed) (401), [`org_closed`](/docs/api/errors#code-org-closed) (401), [`plan_required`](/docs/api/errors#code-plan-required) (403), [`no_membership`](/docs/api/errors#code-no-membership) (403), [`account_suspended`](/docs/api/errors#code-account-suspended) (403), [`org_suspended`](/docs/api/errors#code-org-suspended) (403), [`org_closed`](/docs/api/errors#code-org-closed) (403), [`wrong_instance`](/docs/api/errors#code-wrong-instance) (403), [`not_found`](/docs/api/errors#code-not-found) (404), [`cluster_name_taken`](/docs/api/errors#code-cluster-name-taken) (409), [`cluster_members_taken`](/docs/api/errors#code-cluster-members-taken) (409), [`body_too_large`](/docs/api/errors#code-body-too-large) (413). Every problem is a [problem document](/docs/api/errors). ## GET `/v2/account/clusters/deleted` **List deleted clusters that can still be restored or are awaiting purge** Credentials: API key or App session. Operation id `geoListDeletedClusters`. Returns the organization's soft-deleted clusters, most recently deleted first, each with who deleted it, when, and its restore deadline (`restorable_until`). A deleted cluster can be restored for 30 days by default (D70, `cluster_restore_days` on `GET /v2/account`); after that the nightly purge deletes it for good and it leaves this list. Credential: an API key or a session; owner or admin only. ### Parameters **`kind` query · "naics" | "soc" | "fips"** Only deleted clusters of this kind (`naics`, `soc` or `fips`). ### Responses #### `200` success The deleted clusters. As `application/json`. **`data` array of GeoDeletedCluster always present** The organization's soft-deleted clusters that the nightly purge has not yet removed, most recently deleted first. Not paged. **`data[].id` string (uuid) always present** The cluster id; use it as `cluster:` on the data endpoints. **`data[].kind` "naics" | "soc" | "fips" always present** What a cluster's members are. `naics`: NAICS industry codes (numeric, as the platform stores them), referenced on the data endpoints as `naics=cluster:`. `soc`: SOC occupation codes, referenced as `soc=cluster:`. `fips`: 5-digit county FIPS codes, referenced as `areas=cluster:` (an area cluster). Fixed when the cluster is created and never changes. **`data[].name` string always present** The name, trimmed of surrounding spaces, 1 to 120 characters. (at most 120 characters) **`data[].codes` array of string always present** The members as saved: duplicates removed. `fips` clusters are sorted by FIPS; `naics` and `soc` clusters are in the taxonomy's own display order. NAICS codes are returned as strings of digits. **`data[].created_at` string (date-time) always present** When the cluster was created. **`data[].updated_at` string (date-time) always present** When the cluster was last renamed, re-membered or restored. **`data[].deleted_at` string (date-time) always present** When the cluster was deleted. **`data[].deleted_by` GeoActor or null always present** Who deleted it; null when the deleting account is no longer on record. **`data[].deleted_by.id` string (uuid)** The account id. **`data[].deleted_by.email` string or null** The account's email address; null when the account no longer carries one. **`data[].deleted_by.display_name` string or null** The account's display name; null when none was set. **`data[].restorable` boolean always present** True while the restore window is open (`restorable_until` is in the future). This list is owner/admin only, so the role half of the rule always holds here. **`data[].restorable_until` string (date-time) always present** The restore deadline: `deleted_at` plus the organization's restore window (30 days by default, D70; `GET /v2/account` reports it as `cluster_restore_days`). Always present. A value in the past means the window has closed; the nightly purge then deletes the cluster for good, after which it no longer appears here and any reference to it answers [`cluster_not_found`](/docs/api/errors#code-cluster-not-found). #### `400` error Bad Request. Codes: [`kind_invalid`](/docs/api/errors#code-kind-invalid) (`kind` is not naics, soc or fips), [`bad_request`](/docs/api/errors#code-bad-request) (`kind` given more than once). As `application/problem+json`. #### `401` error Unauthorized. Codes: [`unauthenticated`](/docs/api/errors#code-unauthenticated) (no valid API key or session); [`key_revoked`](/docs/api/errors#code-key-revoked) (an API key that was revoked: `revoked_at`, and `reason` -- `holder`, `admin`, `member_removed`, `seat_removed`, `api_disabled`, `addon_ended`, [`account_closed`](/docs/api/errors#code-account-closed), [`org_closed`](/docs/api/errors#code-org-closed), `retired`, or null for a key revoked before T110 -- and a sentence saying when and why). As `application/problem+json`. #### `403` error Forbidden. Codes: [`role_required`](/docs/api/errors#code-role-required) (the caller is a member, not an owner or admin; carries `required`), [`no_membership`](/docs/api/errors#code-no-membership), [`account_suspended`](/docs/api/errors#code-account-suspended), [`org_suspended`](/docs/api/errors#code-org-suspended), [`org_closed`](/docs/api/errors#code-org-closed), [`wrong_instance`](/docs/api/errors#code-wrong-instance) (`base_url` names the address that serves the key). As `application/problem+json`. #### `404` error Not Found. Codes: [`not_found`](/docs/api/errors#code-not-found) (the `X-DTG-Org` header names no organization the caller may use). As `application/problem+json`. #### `429` error rate\_limited (the per-minute ceiling, X-RateLimit-\* say which), points\_exhausted (the monthly points allowance; Retry-After to the end of the UTC month), server\_busy or sandbox\_busy (load; retry after Retry-After). A refused server\_busy request is not metered. As `application/problem+json`. **`Retry-After` header** Seconds to wait before retrying. **`X-RateLimit-Limit` header** The per-minute request ceiling that applies. **`X-RateLimit-Remaining` header** Requests left in the current window. **`X-RateLimit-Reset` header** Seconds until the window refills: on every answer, the time until the bucket is full again; on a refusal, until a request is allowed (as `Retry-After`). Problem codes: [`kind_invalid`](/docs/api/errors#code-kind-invalid) (400), [`bad_request`](/docs/api/errors#code-bad-request) (400), [`unauthenticated`](/docs/api/errors#code-unauthenticated) (401), [`key_revoked`](/docs/api/errors#code-key-revoked) (401), [`account_closed`](/docs/api/errors#code-account-closed) (401), [`org_closed`](/docs/api/errors#code-org-closed) (401), [`role_required`](/docs/api/errors#code-role-required) (403), [`no_membership`](/docs/api/errors#code-no-membership) (403), [`account_suspended`](/docs/api/errors#code-account-suspended) (403), [`org_suspended`](/docs/api/errors#code-org-suspended) (403), [`org_closed`](/docs/api/errors#code-org-closed) (403), [`wrong_instance`](/docs/api/errors#code-wrong-instance) (403), [`not_found`](/docs/api/errors#code-not-found) (404). Every problem is a [problem document](/docs/api/errors). ## GET `/v2/account/clusters/{id}` **Get one cluster** Credentials: API key or App session. Operation id `geoGetCluster`. Returns one of the organization's live clusters. A cluster this organization deleted (and the purge has not yet removed) answers 404 [`cluster_deleted`](/docs/api/errors#code-cluster-deleted) with its name, who deleted it, when, whether this caller may restore it, and the restore deadline. Anything else (never existed, another organization's, purged, malformed id) answers 404 [`cluster_not_found`](/docs/api/errors#code-cluster-not-found). Credential: an API key or a session; any role. ### Parameters **`id` path · string (uuid) required** The cluster id. ### Responses #### `200` success The cluster. As `application/json`. **`id` string (uuid) always present** The cluster id; use it as `cluster:` on the data endpoints. **`kind` "naics" | "soc" | "fips" always present** What a cluster's members are. `naics`: NAICS industry codes (numeric, as the platform stores them), referenced on the data endpoints as `naics=cluster:`. `soc`: SOC occupation codes, referenced as `soc=cluster:`. `fips`: 5-digit county FIPS codes, referenced as `areas=cluster:` (an area cluster). Fixed when the cluster is created and never changes. **`name` string always present** The name, trimmed of surrounding spaces, 1 to 120 characters. (at most 120 characters) **`codes` array of string always present** The members as saved: duplicates removed. `fips` clusters are sorted by FIPS; `naics` and `soc` clusters are in the taxonomy's own display order. NAICS codes are returned as strings of digits. **`created_at` string (date-time) always present** When the cluster was created. **`updated_at` string (date-time) always present** When the cluster was last renamed, re-membered or restored. #### `401` error Unauthorized. Codes: [`unauthenticated`](/docs/api/errors#code-unauthenticated) (no valid API key or session); [`key_revoked`](/docs/api/errors#code-key-revoked) (an API key that was revoked: `revoked_at`, and `reason` -- `holder`, `admin`, `member_removed`, `seat_removed`, `api_disabled`, `addon_ended`, [`account_closed`](/docs/api/errors#code-account-closed), [`org_closed`](/docs/api/errors#code-org-closed), `retired`, or null for a key revoked before T110 -- and a sentence saying when and why). As `application/problem+json`. #### `403` error Forbidden. Codes: [`no_membership`](/docs/api/errors#code-no-membership), [`account_suspended`](/docs/api/errors#code-account-suspended), [`org_suspended`](/docs/api/errors#code-org-suspended), [`org_closed`](/docs/api/errors#code-org-closed), [`wrong_instance`](/docs/api/errors#code-wrong-instance) (`base_url` names the address that serves the key). As `application/problem+json`. #### `404` error Not Found. Codes: [`cluster_not_found`](/docs/api/errors#code-cluster-not-found) (no such cluster for this organization), [`cluster_deleted`](/docs/api/errors#code-cluster-deleted) (deleted by this organization; carries `cluster`, `restorable`, `restorable_until`), [`not_found`](/docs/api/errors#code-not-found) (the `X-DTG-Org` header names no organization the caller may use). As `application/problem+json`. #### `429` error rate\_limited (the per-minute ceiling, X-RateLimit-\* say which), points\_exhausted (the monthly points allowance; Retry-After to the end of the UTC month), server\_busy or sandbox\_busy (load; retry after Retry-After). A refused server\_busy request is not metered. As `application/problem+json`. **`Retry-After` header** Seconds to wait before retrying. **`X-RateLimit-Limit` header** The per-minute request ceiling that applies. **`X-RateLimit-Remaining` header** Requests left in the current window. **`X-RateLimit-Reset` header** Seconds until the window refills: on every answer, the time until the bucket is full again; on a refusal, until a request is allowed (as `Retry-After`). Problem codes: [`unauthenticated`](/docs/api/errors#code-unauthenticated) (401), [`key_revoked`](/docs/api/errors#code-key-revoked) (401), [`account_closed`](/docs/api/errors#code-account-closed) (401), [`org_closed`](/docs/api/errors#code-org-closed) (401), [`no_membership`](/docs/api/errors#code-no-membership) (403), [`account_suspended`](/docs/api/errors#code-account-suspended) (403), [`org_suspended`](/docs/api/errors#code-org-suspended) (403), [`org_closed`](/docs/api/errors#code-org-closed) (403), [`wrong_instance`](/docs/api/errors#code-wrong-instance) (403), [`cluster_not_found`](/docs/api/errors#code-cluster-not-found) (404), [`cluster_deleted`](/docs/api/errors#code-cluster-deleted) (404), [`not_found`](/docs/api/errors#code-not-found) (404). Every problem is a [problem document](/docs/api/errors). ## PUT `/v2/account/clusters/{id}` **Rename or re-member a cluster** Credentials: API key or App session. Operation id `geoUpdateCluster`. Changes a cluster's name, its members, or both; a property left out keeps its value. `kind` cannot change (create a new cluster instead). New members are validated exactly as on create, and the name and member-set uniqueness rules apply, so a rename or re-member can answer 409. Credential: an API key or a session; any role. While payment is past due this is refused 403 [`plan_required`](/docs/api/errors#code-plan-required) with `entitlement: "past_due"`; a sandbox key is never past due. Side effect: one audit row, `cluster.updated`. ### Parameters **`id` path · string (uuid) required** The cluster id. ### Request body Required; `application/json`. **`kind` "naics" | "soc" | "fips"** Optional. May be sent only if it equals the cluster's current kind; a different kind is refused 400 [`kind_immutable`](/docs/api/errors#code-kind-immutable). **`name` string** The new name, 1 to 120 characters after trimming. Unique per organization and kind among live clusters, case-insensitively. (at most 120 characters) **`codes` array of string** The new member list, validated exactly as on create (see `GeoClusterCreate.codes`) and replacing the old one whole. ### Responses #### `200` success The updated cluster. As `application/json`. **`id` string (uuid) always present** The cluster id; use it as `cluster:` on the data endpoints. **`kind` "naics" | "soc" | "fips" always present** What a cluster's members are. `naics`: NAICS industry codes (numeric, as the platform stores them), referenced on the data endpoints as `naics=cluster:`. `soc`: SOC occupation codes, referenced as `soc=cluster:`. `fips`: 5-digit county FIPS codes, referenced as `areas=cluster:` (an area cluster). Fixed when the cluster is created and never changes. **`name` string always present** The name, trimmed of surrounding spaces, 1 to 120 characters. (at most 120 characters) **`codes` array of string always present** The members as saved: duplicates removed. `fips` clusters are sorted by FIPS; `naics` and `soc` clusters are in the taxonomy's own display order. NAICS codes are returned as strings of digits. **`created_at` string (date-time) always present** When the cluster was created. **`updated_at` string (date-time) always present** When the cluster was last renamed, re-membered or restored. #### `400` error Bad Request. Codes: [`kind_immutable`](/docs/api/errors#code-kind-immutable) (a `kind` different from the cluster's), [`name_invalid`](/docs/api/errors#code-name-invalid) (blank, or over 120 characters), [`codes_invalid`](/docs/api/errors#code-codes-invalid), [`member_cap`](/docs/api/errors#code-member-cap), [`bad_code`](/docs/api/errors#code-bad-code), [`unknown_codes`](/docs/api/errors#code-unknown-codes), [`codes_overlap`](/docs/api/errors#code-codes-overlap), [`counties_outside_set`](/docs/api/errors#code-counties-outside-set) (as on create; `errors` names the offending members), [`malformed_json`](/docs/api/errors#code-malformed-json) (the body is not JSON). As `application/problem+json`. #### `401` error Unauthorized. Codes: [`unauthenticated`](/docs/api/errors#code-unauthenticated) (no valid API key or session); [`key_revoked`](/docs/api/errors#code-key-revoked) (an API key that was revoked: `revoked_at`, and `reason` -- `holder`, `admin`, `member_removed`, `seat_removed`, `api_disabled`, `addon_ended`, [`account_closed`](/docs/api/errors#code-account-closed), [`org_closed`](/docs/api/errors#code-org-closed), `retired`, or null for a key revoked before T110 -- and a sentence saying when and why). As `application/problem+json`. #### `403` error Forbidden. Codes: [`plan_required`](/docs/api/errors#code-plan-required) with `entitlement: "past_due"` (payment is past due; cluster editing is paused, L18), [`no_membership`](/docs/api/errors#code-no-membership), [`account_suspended`](/docs/api/errors#code-account-suspended), [`org_suspended`](/docs/api/errors#code-org-suspended), [`org_closed`](/docs/api/errors#code-org-closed), [`wrong_instance`](/docs/api/errors#code-wrong-instance) (`base_url` names the address that serves the key). As `application/problem+json`. #### `404` error Not Found. Codes: [`cluster_not_found`](/docs/api/errors#code-cluster-not-found) (no such cluster for this organization), [`cluster_deleted`](/docs/api/errors#code-cluster-deleted) (deleted by this organization; restore it first), [`not_found`](/docs/api/errors#code-not-found) (the `X-DTG-Org` header names no organization the caller may use). As `application/problem+json`. #### `409` error Conflict. Codes: [`cluster_name_taken`](/docs/api/errors#code-cluster-name-taken) (another live cluster of this kind has this name), [`cluster_members_taken`](/docs/api/errors#code-cluster-members-taken) (another live cluster of this kind has exactly these members). Both carry `existing`. As `application/problem+json`. #### `413` error Payload Too Large. Codes: [`body_too_large`](/docs/api/errors#code-body-too-large) (the body is over 64 KiB; carries `limit_bytes`). As `application/problem+json`. #### `429` error rate\_limited (the per-minute ceiling, X-RateLimit-\* say which), points\_exhausted (the monthly points allowance; Retry-After to the end of the UTC month), server\_busy or sandbox\_busy (load; retry after Retry-After). A refused server\_busy request is not metered. As `application/problem+json`. **`Retry-After` header** Seconds to wait before retrying. **`X-RateLimit-Limit` header** The per-minute request ceiling that applies. **`X-RateLimit-Remaining` header** Requests left in the current window. **`X-RateLimit-Reset` header** Seconds until the window refills: on every answer, the time until the bucket is full again; on a refusal, until a request is allowed (as `Retry-After`). Problem codes: [`kind_immutable`](/docs/api/errors#code-kind-immutable) (400), [`name_invalid`](/docs/api/errors#code-name-invalid) (400), [`codes_invalid`](/docs/api/errors#code-codes-invalid) (400), [`member_cap`](/docs/api/errors#code-member-cap) (400), [`bad_code`](/docs/api/errors#code-bad-code) (400), [`unknown_codes`](/docs/api/errors#code-unknown-codes) (400), [`codes_overlap`](/docs/api/errors#code-codes-overlap) (400), [`counties_outside_set`](/docs/api/errors#code-counties-outside-set) (400), [`malformed_json`](/docs/api/errors#code-malformed-json) (400), [`unauthenticated`](/docs/api/errors#code-unauthenticated) (401), [`key_revoked`](/docs/api/errors#code-key-revoked) (401), [`account_closed`](/docs/api/errors#code-account-closed) (401), [`org_closed`](/docs/api/errors#code-org-closed) (401), [`plan_required`](/docs/api/errors#code-plan-required) (403), [`no_membership`](/docs/api/errors#code-no-membership) (403), [`account_suspended`](/docs/api/errors#code-account-suspended) (403), [`org_suspended`](/docs/api/errors#code-org-suspended) (403), [`org_closed`](/docs/api/errors#code-org-closed) (403), [`wrong_instance`](/docs/api/errors#code-wrong-instance) (403), [`cluster_not_found`](/docs/api/errors#code-cluster-not-found) (404), [`cluster_deleted`](/docs/api/errors#code-cluster-deleted) (404), [`not_found`](/docs/api/errors#code-not-found) (404), [`cluster_name_taken`](/docs/api/errors#code-cluster-name-taken) (409), [`cluster_members_taken`](/docs/api/errors#code-cluster-members-taken) (409), [`body_too_large`](/docs/api/errors#code-body-too-large) (413). Every problem is a [problem document](/docs/api/errors). ## DELETE `/v2/account/clusters/{id}` **Delete a cluster (restorable)** Credentials: API key or App session. Operation id `geoDeleteCluster`. Soft-deletes a cluster. It disappears from the list, and every reference to it (this path and `cluster:` on the data endpoints) answers 404 [`cluster_deleted`](/docs/api/errors#code-cluster-deleted). An owner or admin can restore it with `POST /v2/account/clusters/{id}/restore` until `restorable_until` (30 days by default, D70); the nightly purge then deletes it for good. Credential: an API key or a session; any role may delete. Not paused when payment is past due. Side effect: one audit row, `cluster.deleted`, recording who deleted it. ### Parameters **`id` path · string (uuid) required** The cluster id. ### Responses #### `204` success Deleted. #### `401` error Unauthorized. Codes: [`unauthenticated`](/docs/api/errors#code-unauthenticated) (no valid API key or session); [`key_revoked`](/docs/api/errors#code-key-revoked) (an API key that was revoked: `revoked_at`, and `reason` -- `holder`, `admin`, `member_removed`, `seat_removed`, `api_disabled`, `addon_ended`, [`account_closed`](/docs/api/errors#code-account-closed), [`org_closed`](/docs/api/errors#code-org-closed), `retired`, or null for a key revoked before T110 -- and a sentence saying when and why). As `application/problem+json`. #### `403` error Forbidden. Codes: [`no_membership`](/docs/api/errors#code-no-membership), [`account_suspended`](/docs/api/errors#code-account-suspended), [`org_suspended`](/docs/api/errors#code-org-suspended), [`org_closed`](/docs/api/errors#code-org-closed), [`wrong_instance`](/docs/api/errors#code-wrong-instance) (`base_url` names the address that serves the key). As `application/problem+json`. #### `404` error Not Found. Codes: [`cluster_not_found`](/docs/api/errors#code-cluster-not-found) (no such cluster for this organization), [`cluster_deleted`](/docs/api/errors#code-cluster-deleted) (already deleted), [`not_found`](/docs/api/errors#code-not-found) (the `X-DTG-Org` header names no organization the caller may use). As `application/problem+json`. #### `429` error rate\_limited (the per-minute ceiling, X-RateLimit-\* say which), points\_exhausted (the monthly points allowance; Retry-After to the end of the UTC month), server\_busy or sandbox\_busy (load; retry after Retry-After). A refused server\_busy request is not metered. As `application/problem+json`. **`Retry-After` header** Seconds to wait before retrying. **`X-RateLimit-Limit` header** The per-minute request ceiling that applies. **`X-RateLimit-Remaining` header** Requests left in the current window. **`X-RateLimit-Reset` header** Seconds until the window refills: on every answer, the time until the bucket is full again; on a refusal, until a request is allowed (as `Retry-After`). Problem codes: [`unauthenticated`](/docs/api/errors#code-unauthenticated) (401), [`key_revoked`](/docs/api/errors#code-key-revoked) (401), [`account_closed`](/docs/api/errors#code-account-closed) (401), [`org_closed`](/docs/api/errors#code-org-closed) (401), [`no_membership`](/docs/api/errors#code-no-membership) (403), [`account_suspended`](/docs/api/errors#code-account-suspended) (403), [`org_suspended`](/docs/api/errors#code-org-suspended) (403), [`org_closed`](/docs/api/errors#code-org-closed) (403), [`wrong_instance`](/docs/api/errors#code-wrong-instance) (403), [`cluster_not_found`](/docs/api/errors#code-cluster-not-found) (404), [`cluster_deleted`](/docs/api/errors#code-cluster-deleted) (404), [`not_found`](/docs/api/errors#code-not-found) (404). Every problem is a [problem document](/docs/api/errors). ## POST `/v2/account/clusters/{id}/restore` **Restore a deleted cluster** Credentials: API key or App session. Operation id `geoRestoreCluster`. Puts a soft-deleted cluster back while its restore window is open (until `restorable_until`, 30 days after deletion by default, D70). Idempotent: restoring a cluster that is already live returns it unchanged with 200. Past the window the answer is 404 [`cluster_deleted`](/docs/api/errors#code-cluster-deleted) with `restorable: false` and a `restorable_until` in the past; after the purge it is [`cluster_not_found`](/docs/api/errors#code-cluster-not-found). A name or member set taken by another cluster since the deletion answers 409. No request body. Credential: an API key or a session; owner or admin only. While payment is past due this is refused 403 [`plan_required`](/docs/api/errors#code-plan-required) with `entitlement: "past_due"`. Side effect: one audit row, `cluster.restored`. ### Parameters **`id` path · string (uuid) required** The id of the deleted cluster. ### Responses #### `200` success The restored (or already live) cluster. As `application/json`. **`id` string (uuid) always present** The cluster id; use it as `cluster:` on the data endpoints. **`kind` "naics" | "soc" | "fips" always present** What a cluster's members are. `naics`: NAICS industry codes (numeric, as the platform stores them), referenced on the data endpoints as `naics=cluster:`. `soc`: SOC occupation codes, referenced as `soc=cluster:`. `fips`: 5-digit county FIPS codes, referenced as `areas=cluster:` (an area cluster). Fixed when the cluster is created and never changes. **`name` string always present** The name, trimmed of surrounding spaces, 1 to 120 characters. (at most 120 characters) **`codes` array of string always present** The members as saved: duplicates removed. `fips` clusters are sorted by FIPS; `naics` and `soc` clusters are in the taxonomy's own display order. NAICS codes are returned as strings of digits. **`created_at` string (date-time) always present** When the cluster was created. **`updated_at` string (date-time) always present** When the cluster was last renamed, re-membered or restored. #### `401` error Unauthorized. Codes: [`unauthenticated`](/docs/api/errors#code-unauthenticated) (no valid API key or session); [`key_revoked`](/docs/api/errors#code-key-revoked) (an API key that was revoked: `revoked_at`, and `reason` -- `holder`, `admin`, `member_removed`, `seat_removed`, `api_disabled`, `addon_ended`, [`account_closed`](/docs/api/errors#code-account-closed), [`org_closed`](/docs/api/errors#code-org-closed), `retired`, or null for a key revoked before T110 -- and a sentence saying when and why). As `application/problem+json`. #### `403` error Forbidden. Codes: [`role_required`](/docs/api/errors#code-role-required) (owner or admin only; carries `required`), [`plan_required`](/docs/api/errors#code-plan-required) with `entitlement: "past_due"` (payment is past due; cluster editing is paused, L18), [`no_membership`](/docs/api/errors#code-no-membership), [`account_suspended`](/docs/api/errors#code-account-suspended), [`org_suspended`](/docs/api/errors#code-org-suspended), [`org_closed`](/docs/api/errors#code-org-closed), [`wrong_instance`](/docs/api/errors#code-wrong-instance) (`base_url` names the address that serves the key). As `application/problem+json`. #### `404` error Not Found. Codes: [`cluster_not_found`](/docs/api/errors#code-cluster-not-found) (no such cluster for this organization, or already purged), [`cluster_deleted`](/docs/api/errors#code-cluster-deleted) (the restore window has closed; `restorable` is false and `restorable_until` is in the past), [`not_found`](/docs/api/errors#code-not-found) (the `X-DTG-Org` header names no organization the caller may use). As `application/problem+json`. #### `409` error Conflict. Codes: [`cluster_name_taken`](/docs/api/errors#code-cluster-name-taken) (a live cluster of this kind took the name since the deletion), [`cluster_members_taken`](/docs/api/errors#code-cluster-members-taken) (a live cluster of this kind took the member set since the deletion). Both carry `existing`. As `application/problem+json`. #### `429` error rate\_limited (the per-minute ceiling, X-RateLimit-\* say which), points\_exhausted (the monthly points allowance; Retry-After to the end of the UTC month), server\_busy or sandbox\_busy (load; retry after Retry-After). A refused server\_busy request is not metered. As `application/problem+json`. **`Retry-After` header** Seconds to wait before retrying. **`X-RateLimit-Limit` header** The per-minute request ceiling that applies. **`X-RateLimit-Remaining` header** Requests left in the current window. **`X-RateLimit-Reset` header** Seconds until the window refills: on every answer, the time until the bucket is full again; on a refusal, until a request is allowed (as `Retry-After`). Problem codes: [`unauthenticated`](/docs/api/errors#code-unauthenticated) (401), [`key_revoked`](/docs/api/errors#code-key-revoked) (401), [`account_closed`](/docs/api/errors#code-account-closed) (401), [`org_closed`](/docs/api/errors#code-org-closed) (401), [`role_required`](/docs/api/errors#code-role-required) (403), [`plan_required`](/docs/api/errors#code-plan-required) (403), [`no_membership`](/docs/api/errors#code-no-membership) (403), [`account_suspended`](/docs/api/errors#code-account-suspended) (403), [`org_suspended`](/docs/api/errors#code-org-suspended) (403), [`org_closed`](/docs/api/errors#code-org-closed) (403), [`wrong_instance`](/docs/api/errors#code-wrong-instance) (403), [`cluster_not_found`](/docs/api/errors#code-cluster-not-found) (404), [`cluster_deleted`](/docs/api/errors#code-cluster-deleted) (404), [`not_found`](/docs/api/errors#code-not-found) (404), [`cluster_name_taken`](/docs/api/errors#code-cluster-name-taken) (409), [`cluster_members_taken`](/docs/api/errors#code-cluster-members-taken) (409). Every problem is a [problem document](/docs/api/errors). ## GET `/v2/account/counties` **The organization's county set** Credentials: API key or App session. Operation id `geoGetCounties`. Returns the organization's county set (D44: a plan buys counties) with its capacity, how many are active and leaving, the change window when scheduled removals land, the latest pending removal batch, and whether a free keep-which-counties choice is owed after an involuntary shrink. Each county carries its `source` (`manual`, `state`, `msa`, `trial`), `is_catchall`, `shed` and `remove_effective_at`. Credential: an API key or a session; any role may read (`edit_roles` says who may change it). A sandbox key reads the organization's real county set; the sandbox's own geography is not a county set (every sandbox area is entitled). ### Responses #### `200` success The county set. As `application/json`. **`counties_included` integer always present** The counties the plan includes; -1 means every county. **`counties_purchased` integer always present** Paid county slots bought beyond the plan's included counties. **`capacity` integer or "all" always present** How many counties may be active at once (`counties_included` + `counties_purchased`), or the string `all`. **`active_count` integer always present** Counties in the set that are not shed and not the trial county, including those scheduled to leave. **`leaving_count` integer always present** Of `active_count`, those with a scheduled removal. They stay entitled until the change window date but no longer hold a slot. **`count_after_pending` integer always present** `active_count` minus `leaving_count`: the count that is measured against capacity now and after the pending batches land. **`universe` integer always present** The number of counties that exist to choose from (3,194, including the 50 state catch-alls). **`county_price_usd_month` number or null always present** The monthly price in US dollars of one county slot beyond the plan's included counties; null when the plan does not sell extra counties. Prices are canonical in `GET /v2/plans`. **`change_window` object always present** When scheduled removals take effect. **`change_window.anchor_day` integer or null always present** The organization's monthly subscription anchor day; null when unknown (the 1st is then used). (1 to 31) **`change_window.next_effective_at` string (date-time) always present** The next anchor date (midnight UTC); a removal scheduled now takes effect then. Days 29 to 31 fall on a shorter month's last day. **`pending_change` GeoCountyChange or null always present** The most recently scheduled pending removal batch, or null when none is pending. Older pending batches, if any, still apply; their counties show `remove_effective_at`. **`pending_change.id` string (uuid)** The batch id; cancel it with `DELETE /v2/account/counties/changes/{id}`. **`pending_change.requested_at` string (date-time)** When the batch was scheduled. **`pending_change.effective_at` string (date-time)** When the counties leave the set (the organization's next subscription anchor date at the time it was scheduled). **`pending_change.additions` array of string** Reserved; always empty today, because additions are immediate. **`pending_change.removals` array of string** The 5-digit FIPS codes that leave on `effective_at`. **`pending_change.paid_slots_delta` integer** The change to the paid county count the batch carries; 0 unless `release_slots` was sent, negative when it gives slots back. **`pending_change.status` "pending" | "applied" | "cancelled"** Always `pending` where this object is returned. **`county_choice_pending` boolean always present** True after an involuntary shrink (a downgrade or dunning) shed counties; an owner or admin should choose which to keep with `POST /v2/account/counties/confirm`, and that choice is free. **`edit_roles` array of string always present** The roles that may change the set (`["owner", "admin"]`). **`data` array of GeoCounty always present** Every county in the set that has not been removed (shed and leaving ones included), ordered by FIPS. **`data[].fips` string always present** The 5-digit county FIPS code. **`data[].name` string or null always present** The county's name in the current vintage; null if the current vintage does not carry this code. **`data[].state` string always present** The 2-digit state FIPS code (the first two digits of `fips`). **`data[].source` "manual" | "state" | "msa" | "trial" always present** How a county joined the set. `manual`: named directly, or arrived in a mixed batch. `state`: the whole batch came from one `state:XX` shortcut. `msa`: the whole batch came from one `msa:NNNNN` shortcut. `trial`: the trial county, managed by the trial; it never counts against capacity and cannot be removed here. **`data[].is_catchall` boolean always present** True for a state's "Unknown Or Undefined" catch-all (a FIPS ending in 999, O34). It carries the employment QCEW could not place in a named county. It is a purchasable county like any other and counts toward capacity; the flag only drives presentation (an `msa:` shortcut and `/map` never include one). **`data[].shed` boolean always present** True when a downgrade composite read-locked the county because the set outgrew capacity (D20/D44). A shed county is kept, not removed, does not count toward capacity and is not entitled; an upgrade, or adding it again, restores it. **`data[].added_at` string (date-time) always present** When the county joined the set. **`data[].remove_effective_at` string (date-time) or null always present** When a scheduled removal takes the county out of the set (the change window date), or null when none is scheduled. Until then it stays entitled, but it no longer holds a slot, so a replacement can take its place at no cost (D41 rider). #### `401` error Unauthorized. Codes: [`unauthenticated`](/docs/api/errors#code-unauthenticated) (no valid API key or session); [`key_revoked`](/docs/api/errors#code-key-revoked) (an API key that was revoked: `revoked_at`, and `reason` -- `holder`, `admin`, `member_removed`, `seat_removed`, `api_disabled`, `addon_ended`, [`account_closed`](/docs/api/errors#code-account-closed), [`org_closed`](/docs/api/errors#code-org-closed), `retired`, or null for a key revoked before T110 -- and a sentence saying when and why). As `application/problem+json`. #### `403` error Forbidden. Codes: [`no_membership`](/docs/api/errors#code-no-membership), [`account_suspended`](/docs/api/errors#code-account-suspended), [`org_suspended`](/docs/api/errors#code-org-suspended), [`org_closed`](/docs/api/errors#code-org-closed), [`wrong_instance`](/docs/api/errors#code-wrong-instance) (`base_url` names the address that serves the key). As `application/problem+json`. #### `404` error Not Found. Codes: [`not_found`](/docs/api/errors#code-not-found) (the `X-DTG-Org` header names no organization the caller may use). As `application/problem+json`. #### `429` error rate\_limited (the per-minute ceiling, X-RateLimit-\* say which), points\_exhausted (the monthly points allowance; Retry-After to the end of the UTC month), server\_busy or sandbox\_busy (load; retry after Retry-After). A refused server\_busy request is not metered. As `application/problem+json`. **`Retry-After` header** Seconds to wait before retrying. **`X-RateLimit-Limit` header** The per-minute request ceiling that applies. **`X-RateLimit-Remaining` header** Requests left in the current window. **`X-RateLimit-Reset` header** Seconds until the window refills: on every answer, the time until the bucket is full again; on a refusal, until a request is allowed (as `Retry-After`). Problem codes: [`unauthenticated`](/docs/api/errors#code-unauthenticated) (401), [`key_revoked`](/docs/api/errors#code-key-revoked) (401), [`account_closed`](/docs/api/errors#code-account-closed) (401), [`org_closed`](/docs/api/errors#code-org-closed) (401), [`no_membership`](/docs/api/errors#code-no-membership) (403), [`account_suspended`](/docs/api/errors#code-account-suspended) (403), [`org_suspended`](/docs/api/errors#code-org-suspended) (403), [`org_closed`](/docs/api/errors#code-org-closed) (403), [`wrong_instance`](/docs/api/errors#code-wrong-instance) (403), [`not_found`](/docs/api/errors#code-not-found) (404). Every problem is a [problem document](/docs/api/errors). ## POST `/v2/account/counties` **Add counties (immediate)** Credentials: API key or App session. Operation id `geoAddCounties`. Adds counties to the set at once. Entries may be 5-digit FIPS codes or shortcuts expanded against the current vintage: `state:XX` (the state's counties, catch-all included, O34) and `msa:NNNNN` (the MSA's counties at the latest map, never a catch-all). A shed county named again is restored. Counties already present are reported and left as they are. Counties scheduled to leave no longer hold a slot, so swapping one county for another costs nothing (D41 rider). When the addition would exceed capacity and the plan sells extra counties, the first call is refused 409 [`confirm_purchase_required`](/docs/api/errors#code-confirm-purchase-required) with a `preview` (interval-aware: what is charged now for the rest of the period, and what at each renewal); re-send with `confirm_purchase: true` to buy the slots. The slot increase is prorated and charged to the card immediately; the counties are granted even if the card declines, and the 201's `payment` says which happened. A 201 is not proof the money moved. Credential: an API key or a session; owner or admin only. Side effects: may change the subscription's county quantity and charge the card; one audit row, `counties.added`. ### Request body Required; `application/json`. **`add` array of string required** 1 to 200 entries, each one of: a 5-digit county FIPS code; `state:XX` (every county of that state in the current vintage, its catch-all included, O34); `msa:NNNNN` (the MSA's member counties at the latest map, never a catch-all). Shortcuts expand on the server; duplicates collapse. **`confirm_purchase` boolean** Send `true` to buy the extra county slots when the addition goes over capacity. Without it an over-capacity addition is refused 409 [`confirm_purchase_required`](/docs/api/errors#code-confirm-purchase-required) with the `preview`. The slot increase is prorated to the rest of the billing period and charged to the card at once. ### Responses #### `201` success Added (and, when slots were bought, the purchase and the charge's outcome). As `application/json`. **`added` array of string always present** The 5-digit FIPS codes newly added to the set. **`restored` array of string always present** Shed counties named again and therefore made active again. **`already_present` array of string always present** Counties that were already active and were left as they were (a county with a scheduled removal stays scheduled; cancel the batch to keep it). **`expanded` array of object always present** One entry per `state:` or `msa:` shortcut, in request order. **`expanded[].selector` string always present** The shortcut as sent (trimmed). **`expanded[].counties` integer always present** How many counties it expanded to. **`counties_purchased` integer always present** The paid county slot count after the request. **`capacity` integer or "all" always present** The capacity after the request, or `all`. **`active_count` integer always present** The counted total after the request (not shed, not the trial county, not scheduled to leave). **`purchase` GeoPurchasePreview or null always present** The purchase that was made, or null when the addition fitted capacity. **`purchase.counties_after` integer** The counted county total after this addition. **`purchase.over_plan` integer** How many of those exceed the plan's included counties. **`purchase.slots_required` integer** The paid county slot count this purchase sets (equal to `over_plan`). **`purchase.interval` "month" | "year"** The organization's billing interval. **`purchase.county_price_usd` number** The price of one slot per billing interval (an annual price on a yearly plan). **`purchase.recurring_delta_usd` number** What the slots over the plan cost at each renewal, per interval. **`purchase.prorated_charge_usd` number** What is charged now for the rest of the current period. Falls back to `recurring_delta_usd` when there is no subscription to price against. **`purchase.proration` "prorated"** Always `prorated`. An increase applies at once and is prorated. **`purchase.summary` string** One plain-English sentence, such as "56 counties, 41 over your plan, $X/mo more". **`purchase.commitment` string** Plain-English terms - what is charged now, what at each renewal, and that the count can be reduced at renewal while which counties are covered can change monthly at no cost. **`payment` GeoCountyPayment or null always present** The charge's outcome when slots were bought, or null. A 201 with `payment.status` `failed` means the counties are granted and the charge was not. **`payment.status` "paid" | "failed"** `failed` when the card was declined (the subscription is now past due). **`payment.attempted_usd` number** The amount charged or attempted, in US dollars. **`payment.subscription_status` string or null** The subscription's status after the charge (for example `active` or `past_due`); null when there is none. **`payment.past_due_since` string (date-time) or null** When the subscription became past due; null when it is not. **`payment.invoice` object or null** The latest invoice when it is unpaid, so the customer can be pointed at it; null when it was paid. **`payment.invoice.id` string** The invoice id. **`payment.invoice.number` string or null** The invoice number, when one has been assigned. **`payment.invoice.status` string** The invoice status (for example `open`). **`payment.invoice.amount_due_cents` integer** The amount due, in US cents. **`payment.invoice.hosted_invoice_url` string (uri) or null** The page where the invoice can be paid, when there is one. **`payment.detail` string** One plain-English sentence describing the outcome. #### `400` error Bad Request. Codes: [`bad_request`](/docs/api/errors#code-bad-request) (`add` missing, empty, over 200 entries, a non-string entry, an entry that is not a 5-digit FIPS, `state:XX` or `msa:NNNNN`, or an unknown state, MSA or county), [`retired_msa`](/docs/api/errors#code-retired-msa) (an MSA the current map no longer defines; carries `msa`, `retired_after`, `successors`), [`malformed_json`](/docs/api/errors#code-malformed-json) (the body is not JSON). As `application/problem+json`. #### `401` error Unauthorized. Codes: [`unauthenticated`](/docs/api/errors#code-unauthenticated) (no valid API key or session); [`key_revoked`](/docs/api/errors#code-key-revoked) (an API key that was revoked: `revoked_at`, and `reason` -- `holder`, `admin`, `member_removed`, `seat_removed`, `api_disabled`, `addon_ended`, [`account_closed`](/docs/api/errors#code-account-closed), [`org_closed`](/docs/api/errors#code-org-closed), `retired`, or null for a key revoked before T110 -- and a sentence saying when and why). As `application/problem+json`. #### `403` error Forbidden. Codes: [`role_required`](/docs/api/errors#code-role-required) (owner or admin only; carries `required`), [`plan_required`](/docs/api/errors#code-plan-required) with `entitlement: "counties_included"` (the plan includes no counties, or the addition exceeds the plan's counties and the plan does not sell more), [`contract_managed`](/docs/api/errors#code-contract-managed) (an invoiced organization over capacity: contact Data Tactical Group; carries `preview`), [`no_membership`](/docs/api/errors#code-no-membership), [`account_suspended`](/docs/api/errors#code-account-suspended), [`org_suspended`](/docs/api/errors#code-org-suspended), [`org_closed`](/docs/api/errors#code-org-closed), [`wrong_instance`](/docs/api/errors#code-wrong-instance) (`base_url` names the address that serves the key). A sandbox key: [`sandbox_read_only`](/docs/api/errors#code-sandbox-read-only) (it may write only clusters). As `application/problem+json`. #### `404` error Not Found. Codes: [`not_found`](/docs/api/errors#code-not-found) (the `X-DTG-Org` header names no organization the caller may use). As `application/problem+json`. #### `409` error Conflict. Codes: [`confirm_purchase_required`](/docs/api/errors#code-confirm-purchase-required) (over capacity; carries `preview`; re-send with `confirm_purchase: true`), [`billing_in_progress`](/docs/api/errors#code-billing-in-progress) (another billing change for this organization is running; retry), [`not_subscribed`](/docs/api/errors#code-not-subscribed) (there is no active subscription to add county slots to). As `application/problem+json`. #### `413` error Payload Too Large. Codes: [`body_too_large`](/docs/api/errors#code-body-too-large) (the body is over 256 KiB; carries `limit_bytes`). As `application/problem+json`. #### `429` error rate\_limited (the per-minute ceiling, X-RateLimit-\* say which), points\_exhausted (the monthly points allowance; Retry-After to the end of the UTC month), server\_busy or sandbox\_busy (load; retry after Retry-After). A refused server\_busy request is not metered. As `application/problem+json`. **`Retry-After` header** Seconds to wait before retrying. **`X-RateLimit-Limit` header** The per-minute request ceiling that applies. **`X-RateLimit-Remaining` header** Requests left in the current window. **`X-RateLimit-Reset` header** Seconds until the window refills: on every answer, the time until the bucket is full again; on a refusal, until a request is allowed (as `Retry-After`). Problem codes: [`bad_request`](/docs/api/errors#code-bad-request) (400), [`retired_msa`](/docs/api/errors#code-retired-msa) (400), [`malformed_json`](/docs/api/errors#code-malformed-json) (400), [`unauthenticated`](/docs/api/errors#code-unauthenticated) (401), [`key_revoked`](/docs/api/errors#code-key-revoked) (401), [`account_closed`](/docs/api/errors#code-account-closed) (401), [`org_closed`](/docs/api/errors#code-org-closed) (401), [`role_required`](/docs/api/errors#code-role-required) (403), [`plan_required`](/docs/api/errors#code-plan-required) (403), [`contract_managed`](/docs/api/errors#code-contract-managed) (403), [`no_membership`](/docs/api/errors#code-no-membership) (403), [`account_suspended`](/docs/api/errors#code-account-suspended) (403), [`org_suspended`](/docs/api/errors#code-org-suspended) (403), [`org_closed`](/docs/api/errors#code-org-closed) (403), [`wrong_instance`](/docs/api/errors#code-wrong-instance) (403), [`sandbox_read_only`](/docs/api/errors#code-sandbox-read-only) (403), [`not_found`](/docs/api/errors#code-not-found) (404), [`confirm_purchase_required`](/docs/api/errors#code-confirm-purchase-required) (409), [`billing_in_progress`](/docs/api/errors#code-billing-in-progress) (409), [`not_subscribed`](/docs/api/errors#code-not-subscribed) (409), [`body_too_large`](/docs/api/errors#code-body-too-large) (413). Every problem is a [problem document](/docs/api/errors). ## POST `/v2/account/counties/remove` **Schedule a removal batch for the next anchor date** Credentials: API key or App session. Operation id `geoRemoveCounties`. Schedules the named counties to leave the set on the organization's next monthly subscription anchor date (`effective_at`); until then they stay entitled. The batch frees their slots at once, so a replacement can be added immediately at no cost (D41 rider). It does NOT change the paid county count: `slots_releasable` reports how many slots are now spare, and `release_slots: true` also gives them back (at period end, not credited). The trial county is refused (listed in `refused`); counties not in the set are ignored. Cancel with `DELETE /v2/account/counties/changes/{id}`. When the batch lands, owners and admins are notified (`county_batch_applied`). Credential: an API key or a session; owner or admin only. Side effect: one audit row, `counties.removal_scheduled`. ### Request body Required; `application/json`. **`remove` array of string required** 1 to 200 counties to remove, in the same forms as `add` (5-digit FIPS, `state:XX`, `msa:NNNNN`). Counties not in the set are ignored; the trial county is refused. **`release_slots` boolean** Default false: the paid county count is left alone (a set change is not a count change, D41 rider) and `slots_releasable` reports what could be given back. True also lowers the paid count by that many slots, at period end, not credited, usable until then. (default false) ### Responses #### `202` success The batch was scheduled. As `application/json`. **`id` string (uuid) always present** The batch id; cancel with `DELETE /v2/account/counties/changes/{id}`. **`status` "pending" always present** Always `pending`. **`effective_at` string (date-time) always present** The organization's next anchor date, when the counties leave the set. **`removals` array of string always present** The counties scheduled to leave. **`refused` array of string always present** Named counties that were not scheduled because they are the trial county. **`paid_slots_delta` integer always present** 0, or the negative slot change when `release_slots` was true. **`counties_purchased_after` integer always present** The paid county slot count once the batch and any release have taken effect. **`active_count_after` integer always present** The counted total once the batch lands (counties already scheduled to leave are already left out). **`slots_releasable` integer always present** How many paid slots this removal makes spare. Not given back unless `release_slots` was true; reducing the count separately is `POST /v2/account/county-slots`. **`note` string always present** A plain-English summary of when the change lands and what happens to the paid count. #### `400` error Bad Request. Codes: [`bad_request`](/docs/api/errors#code-bad-request) (`remove` missing, empty, over 200 entries, malformed or unknown entries; or none of the named counties is in the set; or the only one named is the trial county), [`retired_msa`](/docs/api/errors#code-retired-msa) (an MSA the current map no longer defines), [`malformed_json`](/docs/api/errors#code-malformed-json) (the body is not JSON). As `application/problem+json`. #### `401` error Unauthorized. Codes: [`unauthenticated`](/docs/api/errors#code-unauthenticated) (no valid API key or session); [`key_revoked`](/docs/api/errors#code-key-revoked) (an API key that was revoked: `revoked_at`, and `reason` -- `holder`, `admin`, `member_removed`, `seat_removed`, `api_disabled`, `addon_ended`, [`account_closed`](/docs/api/errors#code-account-closed), [`org_closed`](/docs/api/errors#code-org-closed), `retired`, or null for a key revoked before T110 -- and a sentence saying when and why). As `application/problem+json`. #### `403` error Forbidden. Codes: [`role_required`](/docs/api/errors#code-role-required) (owner or admin only; carries `required`), [`plan_required`](/docs/api/errors#code-plan-required) with `entitlement: "counties_included"` (the plan includes no counties), [`no_membership`](/docs/api/errors#code-no-membership), [`account_suspended`](/docs/api/errors#code-account-suspended), [`org_suspended`](/docs/api/errors#code-org-suspended), [`org_closed`](/docs/api/errors#code-org-closed), [`wrong_instance`](/docs/api/errors#code-wrong-instance) (`base_url` names the address that serves the key). A sandbox key: [`sandbox_read_only`](/docs/api/errors#code-sandbox-read-only) (it may write only clusters). As `application/problem+json`. #### `404` error Not Found. Codes: [`not_found`](/docs/api/errors#code-not-found) (the `X-DTG-Org` header names no organization the caller may use). As `application/problem+json`. #### `413` error Payload Too Large. Codes: [`body_too_large`](/docs/api/errors#code-body-too-large) (the body is over 256 KiB; carries `limit_bytes`). As `application/problem+json`. #### `429` error rate\_limited (the per-minute ceiling, X-RateLimit-\* say which), points\_exhausted (the monthly points allowance; Retry-After to the end of the UTC month), server\_busy or sandbox\_busy (load; retry after Retry-After). A refused server\_busy request is not metered. As `application/problem+json`. **`Retry-After` header** Seconds to wait before retrying. **`X-RateLimit-Limit` header** The per-minute request ceiling that applies. **`X-RateLimit-Remaining` header** Requests left in the current window. **`X-RateLimit-Reset` header** Seconds until the window refills: on every answer, the time until the bucket is full again; on a refusal, until a request is allowed (as `Retry-After`). Problem codes: [`bad_request`](/docs/api/errors#code-bad-request) (400), [`retired_msa`](/docs/api/errors#code-retired-msa) (400), [`malformed_json`](/docs/api/errors#code-malformed-json) (400), [`unauthenticated`](/docs/api/errors#code-unauthenticated) (401), [`key_revoked`](/docs/api/errors#code-key-revoked) (401), [`account_closed`](/docs/api/errors#code-account-closed) (401), [`org_closed`](/docs/api/errors#code-org-closed) (401), [`role_required`](/docs/api/errors#code-role-required) (403), [`plan_required`](/docs/api/errors#code-plan-required) (403), [`no_membership`](/docs/api/errors#code-no-membership) (403), [`account_suspended`](/docs/api/errors#code-account-suspended) (403), [`org_suspended`](/docs/api/errors#code-org-suspended) (403), [`org_closed`](/docs/api/errors#code-org-closed) (403), [`wrong_instance`](/docs/api/errors#code-wrong-instance) (403), [`sandbox_read_only`](/docs/api/errors#code-sandbox-read-only) (403), [`not_found`](/docs/api/errors#code-not-found) (404), [`body_too_large`](/docs/api/errors#code-body-too-large) (413). Every problem is a [problem document](/docs/api/errors). ## POST `/v2/account/counties/confirm` **Choose which counties to keep after an involuntary shrink (free)** Credentials: API key or App session. Operation id `geoConfirmCounties`. The keep-which-counties choice owed after a downgrade or dunning shed counties (`county_choice_pending` on `GET /v2/account/counties`, D20/D44). The counties named in `keep` stay active, up to capacity; remaining capacity is filled with the most recently used, then most recently added; the rest are shed (read-locked, never deleted). The choice is free and clears `county_choice_pending`. It may also be called when no choice is pending, to re-pick the active counties within capacity. The trial county is never affected. Credential: an API key or a session; owner or admin only. Side effect: one audit row, `counties.confirmed`. ### Request body Optional; `application/json`. **`keep` array of string** Optional. The counties to keep, in the same forms as `add` (5-digit FIPS, `state:XX`, `msa:NNNNN`), up to capacity, in priority order. Entries not in the set are ignored. Capacity left over is filled by the default order: most recently used in the last 90 days, then most recently added. Leave it out to accept that default. ### Responses #### `200` success The counties kept and shed. As `application/json`. **`kept` array of string always present** The counties active after the choice (not counting the trial county). **`shed` array of string always present** The counties newly read-locked by this choice. **`capacity` integer always present** The capacity the choice was made against; -1 means every county. **`free_swap` true always present** Always true. This choice costs nothing. #### `400` error Bad Request. Codes: [`bad_request`](/docs/api/errors#code-bad-request) (`keep` given but empty, over 200 entries, or holding malformed or unknown entries), [`retired_msa`](/docs/api/errors#code-retired-msa) (an MSA the current map no longer defines), [`malformed_json`](/docs/api/errors#code-malformed-json) (the body is not JSON). As `application/problem+json`. #### `401` error Unauthorized. Codes: [`unauthenticated`](/docs/api/errors#code-unauthenticated) (no valid API key or session); [`key_revoked`](/docs/api/errors#code-key-revoked) (an API key that was revoked: `revoked_at`, and `reason` -- `holder`, `admin`, `member_removed`, `seat_removed`, `api_disabled`, `addon_ended`, [`account_closed`](/docs/api/errors#code-account-closed), [`org_closed`](/docs/api/errors#code-org-closed), `retired`, or null for a key revoked before T110 -- and a sentence saying when and why). As `application/problem+json`. #### `403` error Forbidden. Codes: [`role_required`](/docs/api/errors#code-role-required) (owner or admin only; carries `required`), [`no_membership`](/docs/api/errors#code-no-membership), [`account_suspended`](/docs/api/errors#code-account-suspended), [`org_suspended`](/docs/api/errors#code-org-suspended), [`org_closed`](/docs/api/errors#code-org-closed), [`wrong_instance`](/docs/api/errors#code-wrong-instance) (`base_url` names the address that serves the key). A sandbox key: [`sandbox_read_only`](/docs/api/errors#code-sandbox-read-only) (it may write only clusters). As `application/problem+json`. #### `404` error Not Found. Codes: [`not_found`](/docs/api/errors#code-not-found) (the `X-DTG-Org` header names no organization the caller may use). As `application/problem+json`. #### `413` error Payload Too Large. Codes: [`body_too_large`](/docs/api/errors#code-body-too-large) (the body is over 256 KiB; carries `limit_bytes`). As `application/problem+json`. #### `429` error rate\_limited (the per-minute ceiling, X-RateLimit-\* say which), points\_exhausted (the monthly points allowance; Retry-After to the end of the UTC month), server\_busy or sandbox\_busy (load; retry after Retry-After). A refused server\_busy request is not metered. As `application/problem+json`. **`Retry-After` header** Seconds to wait before retrying. **`X-RateLimit-Limit` header** The per-minute request ceiling that applies. **`X-RateLimit-Remaining` header** Requests left in the current window. **`X-RateLimit-Reset` header** Seconds until the window refills: on every answer, the time until the bucket is full again; on a refusal, until a request is allowed (as `Retry-After`). Problem codes: [`bad_request`](/docs/api/errors#code-bad-request) (400), [`retired_msa`](/docs/api/errors#code-retired-msa) (400), [`malformed_json`](/docs/api/errors#code-malformed-json) (400), [`unauthenticated`](/docs/api/errors#code-unauthenticated) (401), [`key_revoked`](/docs/api/errors#code-key-revoked) (401), [`account_closed`](/docs/api/errors#code-account-closed) (401), [`org_closed`](/docs/api/errors#code-org-closed) (401), [`role_required`](/docs/api/errors#code-role-required) (403), [`no_membership`](/docs/api/errors#code-no-membership) (403), [`account_suspended`](/docs/api/errors#code-account-suspended) (403), [`org_suspended`](/docs/api/errors#code-org-suspended) (403), [`org_closed`](/docs/api/errors#code-org-closed) (403), [`wrong_instance`](/docs/api/errors#code-wrong-instance) (403), [`sandbox_read_only`](/docs/api/errors#code-sandbox-read-only) (403), [`not_found`](/docs/api/errors#code-not-found) (404), [`body_too_large`](/docs/api/errors#code-body-too-large) (413). Every problem is a [problem document](/docs/api/errors). ## DELETE `/v2/account/counties/changes/{id}` **Cancel a pending removal batch** Credentials: API key or App session. Operation id `geoCancelCountyChange`. Cancels a pending removal batch: its counties stay in the set and count toward capacity again. Refused 409 [`capacity_exceeded`](/docs/api/errors#code-capacity-exceeded) when replacements have already taken the departing counties' slots (buy more slots or remove other counties first). If the batch was giving slots back, the paid count is restored. Credential: an API key or a session; owner or admin only. Side effect: one audit row, `counties.removal_cancelled`. ### Parameters **`id` path · string (uuid) required** The batch id (from `POST /v2/account/counties/remove` or `pending_change.id`). ### Responses #### `204` success Cancelled. #### `401` error Unauthorized. Codes: [`unauthenticated`](/docs/api/errors#code-unauthenticated) (no valid API key or session); [`key_revoked`](/docs/api/errors#code-key-revoked) (an API key that was revoked: `revoked_at`, and `reason` -- `holder`, `admin`, `member_removed`, `seat_removed`, `api_disabled`, `addon_ended`, [`account_closed`](/docs/api/errors#code-account-closed), [`org_closed`](/docs/api/errors#code-org-closed), `retired`, or null for a key revoked before T110 -- and a sentence saying when and why). As `application/problem+json`. #### `403` error Forbidden. Codes: [`role_required`](/docs/api/errors#code-role-required) (owner or admin only; carries `required`), [`no_membership`](/docs/api/errors#code-no-membership), [`account_suspended`](/docs/api/errors#code-account-suspended), [`org_suspended`](/docs/api/errors#code-org-suspended), [`org_closed`](/docs/api/errors#code-org-closed), [`wrong_instance`](/docs/api/errors#code-wrong-instance) (`base_url` names the address that serves the key). A sandbox key: [`sandbox_read_only`](/docs/api/errors#code-sandbox-read-only) (it may write only clusters). As `application/problem+json`. #### `404` error Not Found. Codes: [`not_found`](/docs/api/errors#code-not-found) (no pending batch with this id for this organization, a malformed id, or an `X-DTG-Org` header naming no organization the caller may use). As `application/problem+json`. #### `409` error Conflict. Codes: [`capacity_exceeded`](/docs/api/errors#code-capacity-exceeded) (cancelling would leave more counties than capacity; carries `counties_after` and `capacity`). As `application/problem+json`. #### `429` error rate\_limited (the per-minute ceiling, X-RateLimit-\* say which), points\_exhausted (the monthly points allowance; Retry-After to the end of the UTC month), server\_busy or sandbox\_busy (load; retry after Retry-After). A refused server\_busy request is not metered. As `application/problem+json`. **`Retry-After` header** Seconds to wait before retrying. **`X-RateLimit-Limit` header** The per-minute request ceiling that applies. **`X-RateLimit-Remaining` header** Requests left in the current window. **`X-RateLimit-Reset` header** Seconds until the window refills: on every answer, the time until the bucket is full again; on a refusal, until a request is allowed (as `Retry-After`). Problem codes: [`unauthenticated`](/docs/api/errors#code-unauthenticated) (401), [`key_revoked`](/docs/api/errors#code-key-revoked) (401), [`account_closed`](/docs/api/errors#code-account-closed) (401), [`org_closed`](/docs/api/errors#code-org-closed) (401), [`role_required`](/docs/api/errors#code-role-required) (403), [`no_membership`](/docs/api/errors#code-no-membership) (403), [`account_suspended`](/docs/api/errors#code-account-suspended) (403), [`org_suspended`](/docs/api/errors#code-org-suspended) (403), [`org_closed`](/docs/api/errors#code-org-closed) (403), [`wrong_instance`](/docs/api/errors#code-wrong-instance) (403), [`sandbox_read_only`](/docs/api/errors#code-sandbox-read-only) (403), [`not_found`](/docs/api/errors#code-not-found) (404), [`capacity_exceeded`](/docs/api/errors#code-capacity-exceeded) (409). Every problem is a [problem document](/docs/api/errors). ## GET `/v2/account/regions` **Retired (D44); always 404 region\_retired** (deprecated) Credentials: API key or App session. Operation id `geoRegionsRetiredGet`. Retired, not aliased: a plan buys counties, and named sets are area clusters. Every method on `/v2/account/regions` and on any path below it answers 404 [`region_retired`](/docs/api/errors#code-region-retired), with `replaced_by` naming `/v2/account/counties` and `areas=cluster:`. (Authentication and the rate limit still run first, so the usual 401, 403 and 429 refusals can precede it.) ### Responses #### `404` error Not Found. Codes: [`region_retired`](/docs/api/errors#code-region-retired) (always; carries `replaced_by`). As `application/problem+json`. Problem codes: [`region_retired`](/docs/api/errors#code-region-retired) (404). Every problem is a [problem document](/docs/api/errors). ## PUT `/v2/account/regions` **Retired (D44); always 404 region\_retired** (deprecated) Credentials: API key or App session. Operation id `geoRegionsRetiredPut`. Retired. Answers 404 [`region_retired`](/docs/api/errors#code-region-retired) on this path and any path below it; use area clusters (`/v2/account/clusters`). ### Responses #### `403` error Forbidden. [`sandbox_read_only`](/docs/api/errors#code-sandbox-read-only) (a sandbox key may write only clusters), and the authentication middleware's [`no_membership`](/docs/api/errors#code-no-membership), [`account_suspended`](/docs/api/errors#code-account-suspended), [`org_suspended`](/docs/api/errors#code-org-suspended), [`org_closed`](/docs/api/errors#code-org-closed), [`wrong_instance`](/docs/api/errors#code-wrong-instance) (`base_url` names the address that serves the key). As `application/problem+json`. #### `404` error Not Found. Codes: [`region_retired`](/docs/api/errors#code-region-retired) (always; carries `replaced_by`). As `application/problem+json`. Problem codes: [`sandbox_read_only`](/docs/api/errors#code-sandbox-read-only) (403), [`no_membership`](/docs/api/errors#code-no-membership) (403), [`account_suspended`](/docs/api/errors#code-account-suspended) (403), [`org_suspended`](/docs/api/errors#code-org-suspended) (403), [`org_closed`](/docs/api/errors#code-org-closed) (403), [`wrong_instance`](/docs/api/errors#code-wrong-instance) (403), [`region_retired`](/docs/api/errors#code-region-retired) (404). Every problem is a [problem document](/docs/api/errors). ## POST `/v2/account/regions` **Retired (D44); always 404 region\_retired** (deprecated) Credentials: API key or App session. Operation id `geoRegionsRetiredPost`. Retired. Answers 404 [`region_retired`](/docs/api/errors#code-region-retired) on this path and any path below it; use `POST /v2/account/counties` or `POST /v2/account/clusters` (kind `fips`). ### Responses #### `403` error Forbidden. [`sandbox_read_only`](/docs/api/errors#code-sandbox-read-only) (a sandbox key may write only clusters), and the authentication middleware's [`no_membership`](/docs/api/errors#code-no-membership), [`account_suspended`](/docs/api/errors#code-account-suspended), [`org_suspended`](/docs/api/errors#code-org-suspended), [`org_closed`](/docs/api/errors#code-org-closed), [`wrong_instance`](/docs/api/errors#code-wrong-instance) (`base_url` names the address that serves the key). As `application/problem+json`. #### `404` error Not Found. Codes: [`region_retired`](/docs/api/errors#code-region-retired) (always; carries `replaced_by`). As `application/problem+json`. Problem codes: [`sandbox_read_only`](/docs/api/errors#code-sandbox-read-only) (403), [`no_membership`](/docs/api/errors#code-no-membership) (403), [`account_suspended`](/docs/api/errors#code-account-suspended) (403), [`org_suspended`](/docs/api/errors#code-org-suspended) (403), [`org_closed`](/docs/api/errors#code-org-closed) (403), [`wrong_instance`](/docs/api/errors#code-wrong-instance) (403), [`region_retired`](/docs/api/errors#code-region-retired) (404). Every problem is a [problem document](/docs/api/errors). ## PATCH `/v2/account/regions` **Retired (D44); always 404 region\_retired** (deprecated) Credentials: API key or App session. Operation id `geoRegionsRetiredPatch`. Retired. Answers 404 [`region_retired`](/docs/api/errors#code-region-retired) on this path and any path below it; use area clusters (`/v2/account/clusters`). ### Responses #### `403` error Forbidden. [`sandbox_read_only`](/docs/api/errors#code-sandbox-read-only) (a sandbox key may write only clusters), and the authentication middleware's [`no_membership`](/docs/api/errors#code-no-membership), [`account_suspended`](/docs/api/errors#code-account-suspended), [`org_suspended`](/docs/api/errors#code-org-suspended), [`org_closed`](/docs/api/errors#code-org-closed), [`wrong_instance`](/docs/api/errors#code-wrong-instance) (`base_url` names the address that serves the key). As `application/problem+json`. #### `404` error Not Found. Codes: [`region_retired`](/docs/api/errors#code-region-retired) (always; carries `replaced_by`). As `application/problem+json`. Problem codes: [`sandbox_read_only`](/docs/api/errors#code-sandbox-read-only) (403), [`no_membership`](/docs/api/errors#code-no-membership) (403), [`account_suspended`](/docs/api/errors#code-account-suspended) (403), [`org_suspended`](/docs/api/errors#code-org-suspended) (403), [`org_closed`](/docs/api/errors#code-org-closed) (403), [`wrong_instance`](/docs/api/errors#code-wrong-instance) (403), [`region_retired`](/docs/api/errors#code-region-retired) (404). Every problem is a [problem document](/docs/api/errors). ## DELETE `/v2/account/regions` **Retired (D44); always 404 region\_retired** (deprecated) Credentials: API key or App session. Operation id `geoRegionsRetiredDelete`. Retired. Answers 404 [`region_retired`](/docs/api/errors#code-region-retired) on this path and any path below it; use `POST /v2/account/counties/remove` or `DELETE /v2/account/clusters/{id}`. ### Responses #### `403` error Forbidden. [`sandbox_read_only`](/docs/api/errors#code-sandbox-read-only) (a sandbox key may write only clusters), and the authentication middleware's [`no_membership`](/docs/api/errors#code-no-membership), [`account_suspended`](/docs/api/errors#code-account-suspended), [`org_suspended`](/docs/api/errors#code-org-suspended), [`org_closed`](/docs/api/errors#code-org-closed), [`wrong_instance`](/docs/api/errors#code-wrong-instance) (`base_url` names the address that serves the key). As `application/problem+json`. #### `404` error Not Found. Codes: [`region_retired`](/docs/api/errors#code-region-retired) (always; carries `replaced_by`). As `application/problem+json`. Problem codes: [`sandbox_read_only`](/docs/api/errors#code-sandbox-read-only) (403), [`no_membership`](/docs/api/errors#code-no-membership) (403), [`account_suspended`](/docs/api/errors#code-account-suspended) (403), [`org_suspended`](/docs/api/errors#code-org-suspended) (403), [`org_closed`](/docs/api/errors#code-org-closed) (403), [`wrong_instance`](/docs/api/errors#code-wrong-instance) (403), [`region_retired`](/docs/api/errors#code-region-retired) (404). Every problem is a [problem document](/docs/api/errors). Generated from `taigan/openapi.yaml` at catahoula `77925fab712f`(API document version 2.0).