Skip to main content

​
Overview

Organizations represent your customers’ businesses in Answering Agent. Think of an organization as a company - it has an owner, team members (users), and business locations (phone numbers with AI agents).
Use the organization-first flow to onboard customers: Create the organization and owner user in a single API call, then add locations and additional users as needed.

​
Data Hierarchy

Understanding how organizations fit into the Answering Agent structure: 
Your Partner Account
  │
  ├─ Organization (Customer Business)
  │   ├─ Owner User (created with org)
  │   ├─ Additional Users (team members)
  │   └─ Locations (phone numbers)
  │       └─ AI Agents (handle calls)
  │
  └─ More Organizations...
Key Points:
  • Organizations must have at least one owner user
  • Owners are created automatically when you create an organization
  • Users are identified by your system’s external_id for easy mapping
  • Locations (phone numbers) belong to organizations
  • All data is scoped to your partner account - you only see your organizations

​
Base URL

Playground: https://playground.answeringagent.com/api/v1 Production: https://answeringagent.com/api/v1 All requests must include the X-API-KEY header containing a valid API key.

​
Endpoints

Method & EndpointCapability
GET /organizationsList all your customer organizations
POST /organizationsCreate organization with owner
GET /organizations/{organization_id}Get organization details
PATCH /organizations/{organization_id}Update organization
DELETE /organizations/{organization_id}Delete organization

​
1. List Organizations

PropertyValue
MethodGET
Endpoint/organizations
Success200 OK
List all organizations for the authenticated reseller.

​
Example

curl -H "X-API-KEY: <your-api-key>" \
     https://answeringagent.com/api/v1/organizations

​
Success Response

200 OK
[
  {
    "id": 123,
    "name": "Acme Corporation",
    "created_at": "2025-05-14T10:30:00Z",
    "updated_at": "2025-05-14T10:30:00Z",
    "users": [
      {
        "id": 456,
        "external_id": "user_123",
        "name": "John Doe",
        "email": "[email protected]"
      }
    ],
    "phone_numbers": [
      {
        "id": 789,
        "name": "Main Office",
        "phone_number": "+13035551234",
        "status": "active"
      }
    ]
  }
]

​
2. Create Organization

PropertyValue
MethodPOST
Endpoint/organizations
Success201 Created
Create a new organization with an owner. This is the recommended way to onboard new customers as it creates both the organization and owner user in a single operation.

​
Request Fields

FieldTypeRequiredNotes
namestring✔︎Organization name
descriptionstring–Optional organization description
ownerobject✔︎Owner user details
owner.external_idstring✔︎Your unique identifier for the owner user
owner.emailstring✔︎Owner’s email address
owner.namestring–Owner’s display name

​
Example

curl -X POST -H "X-API-KEY: <your-api-key>" \
     -H "Content-Type: application/json" \
     -d '{
           "name": "Acme Corporation",
           "description": "A technology company specializing in innovative solutions",
           "owner": {
             "external_id": "user_123",
             "email": "[email protected]",
             "name": "John Doe"
           }
         }' \
     https://answeringagent.com/api/v1/organizations

​
Success Response

201 Created
{
  "organization": {
    "id": 123,
    "name": "Acme Corporation",
    "created_at": "2025-05-14T10:30:00Z",
    "updated_at": "2025-05-14T10:30:00Z"
  },
  "owner": {
    "id": 456,
    "external_id": "user_123",
    "name": "John Doe",
    "email": "[email protected]",
    "created_at": "2025-05-14T10:30:00Z",
    "updated_at": "2025-05-14T10:30:00Z"
  }
}
The owner user is automatically created and assigned full access to manage the organization. They can add team members, configure locations, and manage all settings.

​
3. Get Organization

PropertyValue
MethodGET
Endpoint/organizations/{organization_id}
Success200 OK

​
Example

curl -H "X-API-KEY: <your-api-key>" \
     https://answeringagent.com/api/v1/organizations/123

​
Success Response

200 OK
{
  "id": 123,
  "name": "Acme Corporation",
  "created_at": "2025-05-14T10:30:00Z",
  "updated_at": "2025-05-14T10:30:00Z",
  "users": [
    {
      "id": 456,
      "external_id": "user_123",
      "name": "John Doe",
      "email": "[email protected]"
    }
  ],
  "phone_numbers": [
    {
      "id": 789,
      "name": "Main Office",
      "phone_number": "+13035551234",
      "status": "active"
    }
  ]
}

​
4. Update Organization

PropertyValue
MethodPATCH
Endpoint/organizations/{organization_id}
Success200 OK

​
Request Fields

FieldTypeRequiredNotes
namestring–Updated organization name
descriptionstring–Updated organization description

​
Example

curl -X PATCH -H "X-API-KEY: <your-api-key>" \
     -H "Content-Type: application/json" \
     -d '{
           "name": "Acme Corp",
           "description": "Updated description"
         }' \
     https://answeringagent.com/api/v1/organizations/123

​
Success Response

200 OK
{
  "id": 123,
  "name": "Acme Corp",
  "created_at": "2025-05-14T10:30:00Z",
  "updated_at": "2025-05-14T11:15:00Z"
}

​
5. Delete Organization

PropertyValue
MethodDELETE
Endpoint/organizations/{organization_id}
Success200 OK
Organizations can only be deleted if they have no users. Remove all users from the organization before attempting to delete it.

​
Example

curl -X DELETE -H "X-API-KEY: <your-api-key>" \
     https://answeringagent.com/api/v1/organizations/123

​
Success Response

200 OK
{
  "message": "Organization deleted successfully"
}

​
Organization-First Workflow

The recommended workflow for onboarding new customers:
  1. Create Organization: Use POST /organizations with owner details
  2. Add Additional Users: Use POST /users?organization_id={id} for additional team members
  3. Create Locations: Use POST /locations?organization_id={id} for phone numbers
  4. Generate Embed Token: Use GET /users/{external_id}/embed-token for dashboard access

​
Complete Example

# 1. Create organization with owner
curl -X POST -H "X-API-KEY: <your-api-key>" \
     -H "Content-Type: application/json" \
     -d '{
           "name": "Pizza Palace",
           "owner": {
             "external_id": "owner_456",
             "email": "[email protected]",
             "name": "Maria Rodriguez"
           }
         }' \
     https://answeringagent.com/api/v1/organizations

# 2. Add additional user to organization
curl -X POST -H "X-API-KEY: <your-api-key>" \
     -H "Content-Type: application/json" \
     -d '{
           "external_id": "staff_789",
           "email": "[email protected]",
           "name": "John Smith"
         }' \
     "https://answeringagent.com/api/v1/users?organization_id=123"

# 3. Create location for organization
curl -X POST -H "X-API-KEY: <your-api-key>" \
     -H "Content-Type: application/json" \
     -d '{
           "name": "Main Location",
           "address": "123 Pizza St, Denver, CO",
           "area_code": "303"
         }' \
     "https://answeringagent.com/api/v1/locations?organization_id=123"

# 4. Get embed token for dashboard access
curl -H "X-API-KEY: <your-api-key>" \
     https://answeringagent.com/api/v1/users/owner_456/embed-token

​
Error Codes

CodeMeaningTypical Cause
401UnauthorizedMissing or invalid X-API-KEY
404Not FoundOrganization not found
422Validation ErrorMissing required fields or duplicate email
500Internal Server ErrorUnexpected error during creation

​
Benefits of Organization-First Flow

  • Single API Call: Create both organization and owner in one request
  • Atomic Operations: Either both are created successfully or neither
  • Simplified Onboarding: Fewer API calls needed for customer setup
  • Automatic Relationships: Owner is automatically linked to organization
  • Better Data Consistency: Reduces chance of orphaned records