Organizations

Overview

Organizations represent your customers’ businesses in Answering Agent. They can be provisioned by your partner account or independently owned and linked to it. Linked organizations remain customer-owned and default-deny for partner writes.

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 provisioned organizations and organizations visible through an accepted partner link
partner_type identifies provisioned vs linked organizations
permissions.can_manage_dashboard_viewers tells you whether a linked organization’s owner/admin approved viewer management

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 & Endpoint	Capability
`GET /organizations`	List all your customer organizations
`POST /organizations`	Create organization with owner
`GET /organizations/{organization_id}`	Get organization details
`PATCH /organizations/{organization_id}`	Update organization
`DELETE /organizations/{organization_id}`	Delete organization
`PUT /organizations/{organization_id}/dashboard-viewers/{external_id}`	Attach one read-only viewer to an approved linked organization
`DELETE /organizations/{organization_id}/dashboard-viewers/{external_id}`	Detach one viewer without deleting the identity

1. List Organizations

Property	Value
Method	`GET`
Endpoint	`/organizations`
Success	`200 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",
    "partner_type": "provisioned",
    "permissions": {
      "can_view_dashboard": true,
      "can_manage_dashboard_viewers": true
    },
    "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": "john@acme.com"
      }
    ],
    "phone_numbers": [
      {
        "id": 789,
        "name": "Main Office",
        "phone_number": "+13035551234",
        "status": "active"
      }
    ]
  }
]

2. Create Organization

Property	Value
Method	`POST`
Endpoint	`/organizations`
Success	`201 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

Field	Type	Required	Notes
`name`	string	✔︎	Organization name
`description`	string	–	Optional organization description
`owner`	object	✔︎	Owner user details
`owner.external_id`	string	✔︎	Your unique identifier for the owner user
`owner.email`	string	✔︎	Owner’s email address
`owner.name`	string	–	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": "john@acme.com",
             "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": "john@acme.com",
    "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

Property	Value
Method	`GET`
Endpoint	`/organizations/{organization_id}`
Success	`200 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": "john@acme.com"
    }
  ],
  "phone_numbers": [
    {
      "id": 789,
      "name": "Main Office",
      "phone_number": "+13035551234",
      "status": "active"
    }
  ]
}

4. Update Organization

Property	Value
Method	`PATCH`
Endpoint	`/organizations/{organization_id}`
Success	`200 OK`

Request Fields

Field	Type	Required	Notes
`name`	string	–	Updated organization name
`description`	string	–	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

Property	Value
Method	`DELETE`
Endpoint	`/organizations/{organization_id}`
Success	`200 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:

Create Organization: Use POST /organizations with owner details
Add Additional Users: Use POST /users?organization_id={id} for additional team members
Create Locations: Use POST /locations?organization_id={id} for phone numbers
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": "manager@pizzapalace.com",
             "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": "staff@pizzapalace.com",
           "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

Owner-Linked Organization Workflow

Use this flow when the customer already owns their Answering Agent organization and your account managers need approved, read-only embedded dashboard access.

1. Confirm visibility and permission

After the customer owner accepts the partner link, list or fetch the organization:

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

{
  "id": 456,
  "name": "Customer-Owned Wash Group",
  "partner_type": "linked",
  "permissions": {
    "can_view_dashboard": true,
    "can_manage_dashboard_viewers": true
  }
}

If can_manage_dashboard_viewers is false, the organization owner or an admin must enable it in Answering Agent before your API can attach viewers. The partner API cannot self-approve this grant.

2. Attach an existing partner identity

curl -X PUT -H "X-API-KEY: <your-api-key>" \
  https://answeringagent.com/api/v1/organizations/456/dashboard-viewers/account-manager-42

The external_id must identify a user provisioned by your partner account. A successful response shows organization 456 in that user’s organizations array with role user. The same identity can be attached independently to other approved linked organizations.

3. Request an organization-scoped token

curl -H "X-API-KEY: <your-api-key>" \
  "https://answeringagent.com/api/v1/users/account-manager-42/embed-token?organization_id=456"

Pass the returned compact token to a /dashboard/embed iframe. It authorizes read-only access to all current and future locations in organization 456, never to another organization.

4. Detach without deleting the identity

curl -X DELETE -H "X-API-KEY: <your-api-key>" \
  https://answeringagent.com/api/v1/organizations/456/dashboard-viewers/account-manager-42

This returns 204 No Content, invalidates stale scoped authority for organization 456, and preserves the identity and its other organization relationships.

Disabling or revoking the grant, revoking the partner link, removing the team membership, or deleting the user also revokes scoped authority. Re-enabling a grant does not silently restore viewers; attach each viewer again and issue a fresh token.

Error Codes

Code	Meaning	Typical Cause
401	Unauthorized	Missing or invalid `X-API-KEY`
404	Not Found	Organization not found
422	Validation Error	Missing required fields or duplicate email
500	Internal Server Error	Unexpected 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

Getting Started

Guides

POS Integrations

API Reference

API Playground

Overview

Data Hierarchy

Base URL

Endpoints

1. List Organizations

Example

Success Response

2. Create Organization

Request Fields

Example

Success Response

3. Get Organization

Example

Success Response

4. Update Organization

Request Fields

Example

Success Response

5. Delete Organization

Example

Success Response

Organization-First Workflow

Complete Example

Owner-Linked Organization Workflow

1. Confirm visibility and permission

2. Attach an existing partner identity

3. Request an organization-scoped token

4. Detach without deleting the identity

Error Codes

Benefits of Organization-First Flow

​Overview

​Data Hierarchy

​Base URL

​Endpoints

​1. List Organizations

​Example

​Success Response

​2. Create Organization

​Request Fields

​Example

​Success Response

​3. Get Organization

​Example

​Success Response

​4. Update Organization

​Request Fields

​Example

​Success Response

​5. Delete Organization

​Example

​Success Response

​Organization-First Workflow

​Complete Example

​Owner-Linked Organization Workflow

​1. Confirm visibility and permission

​2. Attach an existing partner identity

​3. Request an organization-scoped token

​4. Detach without deleting the identity

​Error Codes

​Benefits of Organization-First Flow

Overview

Data Hierarchy

Base URL

Endpoints

1. List Organizations

Example

Success Response

2. Create Organization

Request Fields

Example

Success Response

3. Get Organization

Example

Success Response

4. Update Organization

Request Fields

Example

Success Response

5. Delete Organization

Example

Success Response

Organization-First Workflow

Complete Example

Owner-Linked Organization Workflow

1. Confirm visibility and permission

2. Attach an existing partner identity

3. Request an organization-scoped token

4. Detach without deleting the identity

Error Codes

Benefits of Organization-First Flow