Skip to main content
Vida 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.

​
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.