JS SDK: Organizations

Understanding Organizations

Organizations in Recal serve as containers for managing users and their calendar integrations. This hierarchical structure enables two primary use cases:

Create separate organizations for each of your business customers. For example, if you provide scheduling software for different companies, each company gets its own organization with isolated user management.

Direct-to-Consumer B2C Applications

Skip organizations entirely and manage all individual users directly under your main organization. Perfect for consumer calendar apps where users don't need to be grouped by company.

Organization Management

Get Organization

// Get organization by slug
const org = await recal.organizations.get('acme-corp')

List All Organizations

// Get all organizations in your account
const orgs = await recal.organizations.list()

// Get all organizations for a specific user
const userOrgs = await recal.users.getOrganizations('user_id')

Create Organization

// Create a new organization
const org = await recal.organizations.create(
    'acme-corp',  // slug
    'Acme Corporation'  // name
)

Note: Slugs must be unique and lowercase. It's recommended to match your internal database IDs for easier usage.

Update Organization

// Update organization
const updated = await recal.organizations.update('acme-corp', {
    slug: 'new-slug',
    name: 'New Name'
})

Delete Organization

// Delete an organization and remove all member associations
await recal.organizations.delete('acme-corp')

Member Management

Organizations can have multiple members. Members are users assigned to an organization, enabling shared calendar operations and team scheduling.

Get Members

// Get all members of an organization
const members = await recal.organizations.getMembers('acme-corp')

Add Members

// Add users to an organization
await recal.organizations.addMembers(
    'acme-corp',
    ['user_id_1', 'user_id_2']
)

Remove Members

// Remove users from an organization
await recal.organizations.removeMembers(
    'acme-corp',
    ['user_id_1', 'user_id_2']
)

Organization-Wide Availability

Organizations support team-wide availability queries for coordinating across multiple members.

Get Organization Busy Times

// Get consolidated busy times for all organization members
const orgBusy = await recal.organizations.getBusyTimes('acme-corp', {
    start: '2024-01-15T00:00:00Z',
    end: '2024-01-20T23:59:59Z'
})

// With provider filter
const orgBusyGoogle = await recal.organizations.getBusyTimes('acme-corp', {
    start: '2024-01-15T00:00:00Z',
    end: '2024-01-20T23:59:59Z',
    provider: ['google']
})

Find Team Availability Slots

// Find times when the entire organization is available
const slots = await recal.organizations.getScheduling('acme-corp', {
    start: '2024-01-15T00:00:00Z',
    end: '2024-01-19T23:59:59Z',
    slotDuration: '60',  // 60 minutes
    padding: '15'  // 15 minutes padding between meetings
})

// With additional constraints
const constrainedSlots = await recal.organizations.getScheduling('acme-corp', {
    start: '2024-01-15T00:00:00Z',
    end: '2024-01-19T23:59:59Z',
    slotDuration: '30',
    padding: '10',
    earliestTimeEachDay: '09:00',
    latestTimeEachDay: '17:00',
    provider: ['google', 'microsoft'],
    timeZone: 'America/New_York'
})

Use Cases:

Team meeting scheduling
Department-wide availability
Cross-team coordination
Resource allocation

Best Practices

Unique Slugs: Use lowercase, URL-safe slugs that match your internal database IDs
Member Management: Add users to organizations before querying their calendar data
Team Queries: Use organization-level methods for multi-user availability checks
Hierarchy: Structure organizations to match your business model (B2B vs B2C)
Cleanup: Remove members before deleting organizations to maintain data integrity

Organizations