Skip to main content

​
Organization Object

The Organization object represents a physical location or office. Use organizations to manage location-specific information like addresses, office hours, and staff across multiple locations.

​
Overview

Organizations allow you to:
  • Manage Multiple Locations: Create and manage different office locations
  • Store Location Details: Keep track of addresses, phone numbers, and timezone information for each location
  • Define Office Hours: Set specific operating hours for each location, including special notes
  • Manage Staff: Maintain staff information and roles for each location
  • Integrate with Your Systems: Use external IDs to sync with your existing practice management systems
  • Flexible Bot Integration: Organizations can be associated with multiple bots, and bots can reference multiple organizations

​
API Operations

​
Creating Organizations

Use POST /organizations to create a new organization with all location details: 
{
  "name": "Downtown Dental Clinic",
  "externalId": "location_001",
  "phone": "+1-555-123-4567",
  "timezone": "America/New_York",
  "address": {
    "addressLine1": "123 Main Street",
    "addressLine2": "Suite 200",
    "city": "Springfield",
    "state": "IL",
    "country": "US",
    "zip": "62701"
  },
  "officeHours": [
    {
      "dayOfWeek": "MONDAY",
      "open": "09:00",
      "close": "17:00"
    }
  ],
  "staff": [
    {
      "name": "Dr. Jane Smith",
      "role": "DOCTOR",
      "bio": "General dentist with 15 years of experience",
      "isActive": true
    }
  ]
}

​
Retrieving Organizations

  • GET /organizations - List all organizations, optionally filter by external_id
  • GET /organizations/{id} - Get a specific organization by ID

​
Updating Organizations

Use PATCH /organizations/{id} to update any organization properties. You can update individual sections: 
{
  "officeHours": [
    {
      "dayOfWeek": "FRIDAY",
      "open": "09:00",
      "close": "15:00",
      "notes": "Early closure on Fridays"
    }
  ]
}

​
Managing Multiple Locations

For businesses with multiple locations, create separate organization objects for each location:
  1. Main Office: POST /organizations with main location details
  2. Branch Office: POST /organizations with branch location details
  3. Associate with Bots: Link your bots to multiple organizations as needed

​
Common Use Cases

​
Single Location Business

Create one organization with complete details including address, hours, and staff.

​
Multi-Location Business

Create separate organizations for each location, each with their own:
  • Unique addresses and contact information
  • Location-specific office hours
  • Staff assignments per location

​
System Integration

Use the externalId field to maintain sync with your existing systems:
  • Set externalId to your organization identifier
  • Query organizations by external ID: GET /organizations?external_id=your_organization_id
  • Update organization data when your organization data changes

​
Bot Integration

Organizations and bots have a flexible many-to-many relationship:
  • One Bot, Multiple Organizations: A single bot can be associated with multiple organizations, allowing it to handle inquiries across different locations
  • One Organization, Multiple Bots: An organization can be used by multiple bots, enabling specialized bots for different services at the same location
  • Mix and Match: You can create any combination that fits your business needs - specialty bots for specific locations, general bots across all locations, or location-specific bots
This flexibility allows you to structure your bot deployment to match your organizational structure and customer service strategy.