> ## Documentation Index
> Fetch the complete documentation index at: https://vida.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Accounts, access, and customer onboarding

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

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

| Account type  | Typical responsibility                                                                                    |
| ------------- | --------------------------------------------------------------------------------------------------------- |
| Organization  | Owns Agent accounts and organization-wide settings. This is the normal starting point for most customers. |
| Reseller      | Optionally owns multiple customer organizations and reseller-level templates, branding, and defaults.     |
| Partner       | Optionally owns multiple resellers.                                                                       |
| Agent account | Owns one Agent's configuration, communications, Tasks, and—when enabled—Computer Agent resources.         |

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.

## 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 Vida account to a stable identifier in your system.
* `externalBillingId` links the account to a billing record when your integration manages that relationship.

Store returned Vida 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 Vida 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. Read the current account, preserve entries outside the intended change, write the complete new array, and re-read it. 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.