Welcome to the Partner API

Welcome to the Answering Agent Partner API! This documentation will help you integrate AI-powered phone answering capabilities into your platform, allowing you to offer 24/7 customer support to your customers.

What You Can Build

The Partner API enables you to:

Provision Customer Organizations - Create and manage organizations for your customers
Onboard Users - Add users to organizations with appropriate roles and permissions
Setup Phone Numbers - Provision phone numbers (locations) with AI answering agents
Embed Dashboards - Give customers access to their data through embedded dashboards
Support Multi-Account Viewers - Reuse one partner identity across independently approved customer organizations with read-only scope
Automate Workflows - Programmatically manage customers at scale

How It Works

The Partner API uses a simple, hierarchical structure:

Your Partner Account
  │
  ├─ Customer Organization (e.g., "Acme Corp")
  │   ├─ Owner User (john@acme.com)
  │   ├─ Additional Users (team members)
  │   └─ Locations (phone numbers)
  │       └─ AI Agents (handle calls)
  │
  ├─ Customer Organization (e.g., "Pizza Palace")
  │   ├─ Owner User (maria@pizzapalace.com)
  │   └─ Locations (phone numbers)
  │
  └─ More Organizations...

Key Concepts

Partner Account

Your account in Answering Agent. You authenticate with an API Key to manage all your customer organizations through the API.

Organizations

Your customers’ businesses. provisioned organizations are owned by your partner account. linked organizations remain owned by existing Answering Agent customers and default-deny partner writes unless their owner/admin grants the narrow dashboard-viewer capability.

Users

People who belong to organizations. Each organization has an owner (created with the org) and can have additional users. Users are identified by your system’s ID (external_id).

Locations

Phone numbers with AI answering agents. Each location belongs to an organization and has its own phone number, settings, and AI agent configuration.

External ID

Your unique identifier for users in your system. This allows you to maintain a mapping between your users and Answering Agent users without exposing internal IDs.

Embed Tokens

Secure compact tokens that allow you to embed the Answering Agent dashboard. For multi-account viewers, issue a separate token for each organization_id; the iframe exchanges it for a short-lived, organization-bound bearer.

Quick Start

Get started in 5 minutes:

Get Your API Key

Create Your First Organization

Use the API to create a customer organization with an owner user in a single call.

Add a Location

Provision a phone number for the organization to start receiving calls.

Embed the Dashboard

Get an embed token and integrate the dashboard into your app.

See the Quickstart Guide for a complete walkthrough with code examples.

If you manage dashboards for customer-owned organizations, start with the multi-organization viewer workflow. It preserves customer ownership, requires explicit approval per organization, and keeps the embedded dashboard read-only.

API Structure

All Partner API endpoints follow this structure:

Base URL: https://answeringagent.com/api/v1

Authentication: X-API-KEY header

This is the permanent production URL. The legacy api.answeringagent.com hostname remains redirect-compatible for existing integrations, but should not be used for new clients.

Core Resources

Authentication

Learn how to authenticate with API keys

Organizations

Create and manage customer organizations

Users

Manage users within organizations

Locations

Set up phone numbers and AI agents

Advanced Features

Embed Dashboard

Integrate the dashboard into your app

Chat Widget

Add web chat to customer websites

Typical Integration Flow

Here’s how most partners integrate with Answering Agent:

Customer Signs Up

A customer creates an account in your platform.

Create Organization

Your backend calls POST /api/v1/organizations to create the organization and owner user.

Setup Phone Number

Call POST /api/v1/locations to provision a phone number for the customer.

Get Embed Token

Call GET /api/v1/users/{external_id}/embed-token to get a token for embedding.

Show Dashboard

Embed the Answering Agent dashboard in your app using the embed token, giving customers access to their calls, tasks, and analytics.

Multi-Account Viewer Flow

For an account manager who needs one login across several customer-owned organizations:

Confirm each customer organization is linked and reports permissions.can_manage_dashboard_viewers: true.
Create the partner-owned identity once.
Attach its external_id to each approved organization with PUT /organizations/{organization_id}/dashboard-viewers/{external_id}.
Request a token with the selected organization_id and replace the embed iframe when switching organizations.
Detach one relationship without deleting the identity or affecting other organizations.

This access is read-only and is revoked immediately when the viewer relationship, owner grant, partner link, membership, or user is removed.

Authentication Overview

The Partner API uses API keys for authentication:

Generate an API key from your partner dashboard
Include the key in the X-API-KEY header for every request
That’s it! No complex signing or HMAC required

curl -X GET "https://answeringagent.com/api/v1/organizations" \
  -H "X-API-KEY: sk_live_AbCdEfGhIjKlMnOpQrSt"

Authentication Guide

Complete authentication documentation with examples in multiple languages

Code Examples

All documentation includes code examples in multiple languages:

cURL (for testing)
JavaScript/Node.js
Python
PHP

Each endpoint shows complete request and response examples with real-world use cases.

Example: Complete Onboarding

Here’s a complete example of onboarding a new customer:

JavaScript
Python

const API_KEY = process.env.ANSWERING_AGENT_API_KEY;
const BASE_URL = 'https://answeringagent.com/api/v1';

async function onboardCustomer(customerData) {
  // 1. Create organization with owner
  const orgResponse = await fetch(`${BASE_URL}/organizations`, {
    method: 'POST',
    headers: {
      'X-API-KEY': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: customerData.businessName,
      description: customerData.businessDescription,
      owner: {
        external_id: customerData.userId, // Your system's user ID
        email: customerData.email,
        name: customerData.name
      }
    })
  });

  const { organization, owner } = await orgResponse.json();
  console.log('✓ Organization created:', organization.id);

  // 2. Add a phone number location
  const locationResponse = await fetch(`${BASE_URL}/locations`, {
    method: 'POST',
    headers: {
      'X-API-KEY': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      organization_id: organization.id,
      name: 'Main Office',
      address: customerData.address,
      area_code: customerData.areaCode
    })
  });

  const { location } = await locationResponse.json();
  console.log('✓ Phone number provisioned:', location.phone_number);

  // 3. Get embed token for dashboard access
  const tokenResponse = await fetch(
    `${BASE_URL}/users/${customerData.userId}/embed-token`,
    {
      headers: { 'X-API-KEY': API_KEY }
    }
  );

  const { embed_token } = await tokenResponse.json();
  console.log('✓ Embed token generated');

  // Return data for your system
  return {
    organizationId: organization.id,
    phoneNumber: location.phone_number,
    embedToken: embed_token
  };
}

// Usage
const result = await onboardCustomer({
  userId: 'user_123',
  email: 'john@acme.com',
  name: 'John Doe',
  businessName: 'Acme Corporation',
  businessDescription: 'Technology consulting firm',
  address: '123 Main St, Denver, CO',
  areaCode: '303'
});

console.log('Customer onboarded successfully:', result);

import os
import requests

API_KEY = os.getenv('ANSWERING_AGENT_API_KEY')
BASE_URL = 'https://answeringagent.com/api/v1'

def onboard_customer(customer_data):
    headers = {
        'X-API-KEY': API_KEY,
        'Content-Type': 'application/json'
    }

    # 1. Create organization with owner
    org_response = requests.post(
        f'{BASE_URL}/organizations',
        headers=headers,
        json={
            'name': customer_data['business_name'],
            'description': customer_data['business_description'],
            'owner': {
                'external_id': customer_data['user_id'],
                'email': customer_data['email'],
                'name': customer_data['name']
            }
        }
    )
    org_response.raise_for_status()
    org_data = org_response.json()
    organization = org_data['organization']
    print(f'✓ Organization created: {organization["id"]}')

    # 2. Add a phone number location
    location_response = requests.post(
        f'{BASE_URL}/locations',
        headers=headers,
        json={
            'organization_id': organization['id'],
            'name': 'Main Office',
            'address': customer_data['address'],
            'area_code': customer_data['area_code']
        }
    )
    location_response.raise_for_status()
    location = location_response.json()['location']
    print(f'✓ Phone number provisioned: {location["phone_number"]}')

    # 3. Get embed token
    token_response = requests.get(
        f'{BASE_URL}/users/{customer_data["user_id"]}/embed-token',
        headers=headers
    )
    token_response.raise_for_status()
    embed_token = token_response.json()['embed_token']
    print('✓ Embed token generated')

    return {
        'organization_id': organization['id'],
        'phone_number': location['phone_number'],
        'embed_token': embed_token
    }

# Usage
result = onboard_customer({
    'user_id': 'user_123',
    'email': 'john@acme.com',
    'name': 'John Doe',
    'business_name': 'Acme Corporation',
    'business_description': 'Technology consulting firm',
    'address': '123 Main St, Denver, CO',
    'area_code': '303'
})

print('Customer onboarded successfully:', result)

Resources & Support

Quickstart Guide

Build your first integration in 5 minutes

API Reference

Complete endpoint documentation

FAQ

Answers to common questions

Email Support

Get help from our team

Need Help?

We’re here to support your integration:

Technical Questions: support@answeringagent.com
Documentation Issues: Report on GitHub or email support
Security Concerns: security@answeringagent.com

Let’s build something amazing together! 🚀

Getting Started

Guides

POS Integrations

API Reference

API Playground

What You Can Build

How It Works

Key Concepts

Quick Start

API Structure

Core Resources

Authentication

Organizations

Users

Locations

Advanced Features

Embed Dashboard

Chat Widget

Typical Integration Flow

Multi-Account Viewer Flow

Authentication Overview

Authentication Guide

Code Examples

Example: Complete Onboarding

Resources & Support

Quickstart Guide

API Reference

FAQ

Email Support

Need Help?

​What You Can Build

​How It Works

​Key Concepts

​Quick Start

​API Structure

​Core Resources

Authentication

Organizations

Users

Locations

​Advanced Features

Embed Dashboard

Chat Widget

​Typical Integration Flow

​Multi-Account Viewer Flow

​Authentication Overview

Authentication Guide

​Code Examples

​Example: Complete Onboarding

​Resources & Support

Quickstart Guide

API Reference

FAQ

Email Support

​Need Help?

What You Can Build

How It Works

Key Concepts

Quick Start

API Structure

Core Resources

Advanced Features

Typical Integration Flow

Multi-Account Viewer Flow

Authentication Overview

Code Examples

Example: Complete Onboarding

Resources & Support

Need Help?