Accounts, access, and customer onboarding

Use the account structure your GetVoiceBot plan provides, then create and verify only the resources each customer needs.

GetVoiceBot accounts form an authorization and ownership hierarchy. Not every customer has every level.

Read GET /api/v2/account before choosing an onboarding workflow. Use only hierarchy levels the authenticated account is authorized to manage. Do not create a reseller or partner layer for an ordinary organization.

Separate hierarchy scope from product access

Call GET /api/v2/account without a target first. That response identifies the key owner and its
Partner Admin, Reseller Admin, Organization Admin, or Agent-account scope. Human members can be
returned as accountType: "user"; use the hierarchy relationships described in
Authentication, and honor any nonempty permittedAccountIds
restriction.

Hierarchy scope answers which accounts the key may select. It does not mean every operation is
available within those accounts:

• active and plan state affect whether paid platform capabilities are available.
• Account features determine which optional capabilities may be configured.
• The selected target must belong to the key's authorized hierarchy.
• Individual endpoints can require a particular account level, feature, or resource state.

Read the relevant catalog, status, or resource endpoint for the requested operation. Do not test a
collection of unrelated endpoints and treat their failure statuses as a privilege-discovery API.
A later GET /api/v2/account?targetAccountId=... describes the selected account, not the original
key owner.

Keep the identifiers separate

• targetAccountId selects an authorized account for an API request.
• accountId identifies the Agent account that owns a Task.
• agentConfigId identifies an Agent configuration record. It is not an account ID.
• externalAccountId links a GetVoiceBot account to a stable identifier in your system.
• externalBillingId links the account to a billing record when your integration manages that relationship.

Store returned GetVoiceBot IDs. Do not reconstruct them from names or external IDs.

Onboard an organization and its Agents

For a normal organization account:

1. Read the organization with GET /api/v2/account and confirm its product access.
2. List existing Agent accounts with GET /api/v2/listAccounts?targetOrganizationId=....
3. Create only the required Agent accounts with POST /api/v2/createAccount. Preserve the returned account IDs.
4. Discover the models, voices, functions, apps, and other capabilities available to each Agent account.
5. Create or edit staging configuration, test it, publish with explicit approval, and verify live configuration.
6. Connect only the communications and Computer resources the Agent needs.
7. Create members with the minimum access required and verify their effective account access.

Creating accounts, assigning plans, purchasing numbers, or provisioning Computers can affect billing. Present that impact before the write when it is not already part of an approved automated workflow.

Onboard downstream customers

Use these branches only when the authenticated account has the corresponding role:

• A reseller can list and create organizations, then create Agent accounts inside each organization.
• A partner can list and create resellers, and can then operate within an authorized reseller or organization scope.

Use the endpoint's explicit targetResellerId, targetOrganizationId, or targetAccountId selector. Read the created account and hierarchy after every write; a successful response is not enough if the resource was created under the wrong parent.

Check plans and features before configuration

Read the product catalog and GET /api/v2/features before promising a capability. Partner and reseller administrators can assign only features they are already authorized to grant by using POST /api/v2/features/assign. Re-read the child account afterward.

Feature creation and internal enablement are not public API operations. If a required feature is unavailable, contact GetVoiceBot rather than trying to manufacture or bypass an entitlement.

Configure reporting defaults carefully

POST /api/v2/account can update supported account settings in addition to profile fields:

• settings.reportingFields defines typed reporting fields at a reseller or organization level.
• settings.metrics defines organization dashboard metrics.
• settings.defaultOrgSettings.metrics defines the metrics new organizations inherit from a reseller.

Arrays supplied at one of these paths replace the current array at that level; they do not append or
merge entries. Read the current account, retain the complete array, change only the intended entry,
write the complete result, and re-read it. Never send only a new metric or reporting field unless the
user explicitly intends to replace the entire list.

An organization dashboard can show inherited or standard metric defaults even when
settings.metrics is absent or empty. In that case, do not create a partial organization override.
Confirm the complete desired panel first. Agent-specific reporting fields remain part of the Agent
staging and publish lifecycle.

Manage members and API tokens

Use the Members API for human access and the Authorization API for integration credentials.

• Read the member list before inviting or changing access.
• Use permittedAccountIds when a member should see only selected child accounts.
• Do not remove the current administrator's last viable access.
• Create a new API token, verify it with a read, move the integration, and only then revoke the old token.
• Generate one-time authentication tokens only from a trusted backend after verifying the user belongs to the intended customer account.

End every onboarding workflow with an account read, an Agent configuration read, and a representative capability test.