Accounts

Accounts represent your customers in DialStack. Each account is isolated and can have multiple users, phone numbers, and devices.

Create an Account

const account = await dialstack.accounts.create({
  email: 'customer@example.com',
});

console.log(account.id); // 'acct_01h2xcejqtf2nbrexx3vqjhp41'

Parameters

Parameter	Type	Required	Description
email	string	No	Account email address

Response

interface Account {
  id: string;
  email: string | null;
  created_at: string;
  updated_at: string;
}

Retrieve an Account

const account = await dialstack.accounts.retrieve('acct_01h2xcejqtf2nbrexx3vqjhp41');

console.log(account.email);

Parameters

Parameter	Type	Required	Description
accountId	string	Yes	Account ID

Update an Account

const account = await dialstack.accounts.update('acct_01h2xcejqtf2nbrexx3vqjhp41', {
  email: 'newemail@example.com',
});

Parameters

Parameter	Type	Required	Description
accountId	string	Yes	Account ID
email	string	No	New email address

Delete an Account

await dialstack.accounts.del('acct_01h2xcejqtf2nbrexx3vqjhp41');

Destructive Action

Deleting an account removes all associated users, devices, and data. This action cannot be undone.

Parameters

Parameter	Type	Required	Description
accountId	string	Yes	Account ID

List Accounts

const response = await dialstack.accounts.list({
  limit: 20,
});

for (const account of response.data) {
  console.log(account.id, account.email);
}

if (response.has_more) {
  // Fetch next page
}

Parameters

Parameter	Type	Default	Description
limit	number	10	Results per page (max 100)
starting_after	string	-	Cursor for next page
ending_before	string	-	Cursor for previous page

Response

interface ListResponse<Account> {
  data: Account[];
  has_more: boolean;
}

Auto-Pagination

Iterate All Accounts

for await (const account of dialstack.accounts.list().autoPagingEach()) {
  console.log(account.id);
}

Collect to Array

const allAccounts = await dialstack.accounts.list().autoPagingToArray({ limit: 1000 });

console.log(`Total accounts: ${allAccounts.length}`);

Examples

Create Account with Error Handling

import { DialStack, DialStackValidationError, DialStackError } from '@dialstack/sdk/server';

async function createAccount(email: string) {
  try {
    const account = await dialstack.accounts.create({ email });
    return { success: true, account };
  } catch (error) {
    if (error instanceof DialStackValidationError) {
      return { success: false, error: 'Invalid email format' };
    }
    throw error;
  }
}

Sync Accounts from External System

async function syncAccounts(externalAccounts: ExternalAccount[]) {
  const results = [];

  for (const ext of externalAccounts) {
    // Check if account exists
    let account: Account | null = null;

    try {
      account = await dialstack.accounts.retrieve(ext.dialstackId);
    } catch (error) {
      if (!(error instanceof DialStackNotFoundError)) {
        throw error;
      }
    }

    if (account) {
      // Update existing
      account = await dialstack.accounts.update(ext.dialstackId, {
        email: ext.email,
      });
    } else {
      // Create new
      account = await dialstack.accounts.create({
        email: ext.email,
      });
    }

    results.push(account);
  }

  return results;
}

List with Pagination

async function getAllAccounts() {
  const accounts: Account[] = [];
  let hasMore = true;
  let startingAfter: string | undefined;

  while (hasMore) {
    const response = await dialstack.accounts.list({
      limit: 100,
      starting_after: startingAfter,
    });

    accounts.push(...response.data);
    hasMore = response.has_more;

    if (response.data.length > 0) {
      startingAfter = response.data[response.data.length - 1].id;
    }
  }

  return accounts;
}

Next Steps

• Users - Manage users in accounts
• Sessions - Create session tokens