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
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. Each organization has an owner, users, and locations (phone numbers). Organizations are the top-level container for your customers.

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 tokens that allow you to embed the Answering Agent dashboard in your application, giving customers access to calls, tasks, and analytics.

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.

API Structure

All Partner API endpoints follow this structure:

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

Authentication: X-API-KEY header

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.

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

Authentication Overview

Authentication Guide

Code Examples

Example: Complete Onboarding

Resources & Support

Quickstart Guide

API Reference

FAQ

Email Support

Need Help?

Getting Started

Guides

POS Integrations

API Reference

API Playground

Documentation Index

​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

​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

Authentication Overview

Code Examples

Example: Complete Onboarding

Resources & Support

Need Help?