Skip to main content

Account Hierarchy

Manage parent-child relationships between accounts for organizational structure and resource sharing.

Overview​

Account hierarchy allows you to:

  • Create sub-accounts under a parent account
  • Manage organizational structure
  • Share resources between accounts
  • Inherit permissions from parent accounts
  • Establish billing relationships

Endpoints​

GET /v1/accounts/{accountId}/children
POST /v1/accounts/{accountId}/children
PATCH /v1/accounts/{accountId}/parent
DELETE /v1/accounts/{accountId}/parent

Concept​

Parent Account​

The top-level account that can have sub-accounts (children). Parent accounts manage billing, permissions, and overall structure.

Child Account (Sub-Account)​

An account that belongs to a parent account. Child accounts inherit certain settings and permissions while maintaining their own data.

Root Account​

The highest-level account in the hierarchy with no parent.

Get Sub-Accounts​

Retrieve all child accounts under a parent account.

Endpoint​

GET https://api.audian.com:8443/v2/accounts/{accountId}/children

Query Parameters​

ParameterTypeDescription
limitintegerNumber of results to return (default: 10, max: 100)
offsetintegerPagination offset (default: 0)
statusstringFilter by status (active, suspended, closed)

Example​

curl -X GET "https://api.audian.com:8443/v2/accounts/acc_1234567890/children?limit=20" \
  -H "X-Auth-Token: YOUR_API_TOKEN"

Response​

{
  "data": [
    {
      "id": "acc_0987654321",
      "name": "Acme - New York Office",
      "status": "active",
      "createdAt": "2023-10-15T10:30:00Z",
      "userCount": 15,
      "deviceCount": 8
    },
    {
      "id": "acc_1111111111",
      "name": "Acme - Boston Office",
      "status": "active",
      "createdAt": "2023-10-16T14:22:00Z",
      "userCount": 8,
      "deviceCount": 4
    }
  ],
  "pagination": {
    "limit": 20,
    "offset": 0,
    "total": 2
  }
}

Create Sub-Account​

Create a new sub-account under a parent account.

Endpoint​

POST https://api.audian.com:8443/v2/accounts/{accountId}/children

Request Body​

ParameterTypeRequiredDescription
namestringYesSub-account name
emailstringYesPrimary contact email
settingsobjectNoInherited settings override
metadataobjectNoCustom metadata

Example​

curl -X POST https://api.audian.com:8443/v2/accounts/acc_1234567890/children \
  -H "Content-Type: application/json" \
  -H "X-Auth-Token: YOUR_API_TOKEN" \
  -d '{
    "name": "Acme - Chicago Office",
    "email": "chicago@acme.com",
    "settings": {
      "timezone": "America/Chicago"
    }
  }'

Response​

{
  "id": "acc_2222222222",
  "name": "Acme - Chicago Office",
  "parent_id": "acc_1234567890",
  "email": "chicago@acme.com",
  "status": "active",
  "createdAt": "2023-10-20T09:15:00Z"
}

Set Parent Account​

Change the parent account for an existing account.

Endpoint​

PATCH https://api.audian.com:8443/v2/accounts/{accountId}/parent

Request Body​

ParameterTypeRequiredDescription
parentIdstringYesNew parent account ID
inheritSettingsbooleanNoInherit parent settings (default: true)

Example​

curl -X PATCH https://api.audian.com:8443/v2/accounts/acc_0987654321/parent \
  -H "Content-Type: application/json" \
  -H "X-Auth-Token: YOUR_API_TOKEN" \
  -d '{
    "parentId": "acc_1234567890",
    "inheritSettings": true
  }'

Response​

{
  "id": "acc_0987654321",
  "name": "Acme - New York Office",
  "parent_id": "acc_1234567890",
  "status": "active",
  "inheritSettings": true,
  "updatedAt": "2023-10-20T10:00:00Z"
}

Remove Parent Account​

Promote a sub-account to a root account by removing its parent.

Endpoint​

DELETE https://api.audian.com:8443/v2/accounts/{accountId}/parent

Example​

curl -X DELETE https://api.audian.com:8443/v2/accounts/acc_0987654321/parent \
  -H "X-Auth-Token: YOUR_API_TOKEN"

Response​

{
  "id": "acc_0987654321",
  "name": "Acme - New York Office",
  "parent_id": null,
  "status": "active",
  "message": "Account is now a root account"
}

Permission Inheritance​

Inherited Permissions​

Child accounts inherit:

  • Parent account administrators (configurable)
  • Parent account billing contacts
  • Parent account default settings
  • Parent account audit policies

Overridable Settings​

Each child account can override:

  • Timezone
  • Language
  • Recording settings
  • Custom policies

Local Permissions​

Child accounts maintain independent:

  • Local user permissions
  • Local device assignments
  • Local resource allocation
  • Local audit logs

Best Practices​

  1. Organization Structure: Use hierarchy to mirror organizational structure (departments, locations, divisions)
  2. Billing Management: Use parent account for consolidated billing of child accounts
  3. Permission Control: Manage access through parent account for consistency
  4. Resource Sharing: Child accounts can share services provisioned at parent level
  5. Audit Trail: Parent accounts can audit all child account activity

Hierarchy Limits​

  • Maximum hierarchy depth: 5 levels
  • Maximum child accounts per parent: 100
  • Circular relationships: Not allowed
  • Self-parenting: Not allowed

Example Structure​

Root Account (Acme Corporation)
├── New York Office
│   ├── Sales Team
│   └── Support Team
├── Boston Office
│   ├── Engineering
│   └── Operations
└── Chicago Office