> ## Documentation Index
> Fetch the complete documentation index at: https://docs.answeringagent.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Welcome to the Partner API

> Build AI phone answering integrations with the Answering Agent 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

<AccordionGroup>
  <Accordion title="Partner Account" icon="handshake">
    Your account in Answering Agent. You authenticate with an **API Key** to manage all your customer organizations through the API.
  </Accordion>

  <Accordion title="Organizations" icon="building">
    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.
  </Accordion>

  <Accordion title="Users" icon="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`).
  </Accordion>

  <Accordion title="Locations" icon="map-pin">
    Phone numbers with AI answering agents. Each location belongs to an organization and has its own phone number, settings, and AI agent configuration.
  </Accordion>

  <Accordion title="External ID" icon="fingerprint">
    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.
  </Accordion>

  <Accordion title="Embed Tokens" icon="code">
    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.
  </Accordion>
</AccordionGroup>

***

## Quick Start

Get started in 5 minutes:

<Steps>
  <Step title="Get Your API Key">
    Sign in to your partner dashboard and navigate to **Settings → API Keys** to generate your API key.
  </Step>

  <Step title="Create Your First Organization">
    Use the API to create a customer organization with an owner user in a single call.
  </Step>

  <Step title="Add a Location">
    Provision a phone number for the organization to start receiving calls.
  </Step>

  <Step title="Embed the Dashboard">
    Get an embed token and integrate the dashboard into your app.
  </Step>
</Steps>

<Note>
  See the [Quickstart Guide](/v1/quickstart) for a complete walkthrough with code examples.
</Note>

<Tip>
  If you manage dashboards for customer-owned organizations, start with the [multi-organization viewer workflow](/v1/users#multi-organization-dashboard-viewers). It preserves customer ownership, requires explicit approval per organization, and keeps the embedded dashboard read-only.
</Tip>

***

## 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

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/v1/authentication">
    Learn how to authenticate with API keys
  </Card>

  <Card title="Organizations" icon="building" href="/v1/organizations">
    Create and manage customer organizations
  </Card>

  <Card title="Users" icon="users" href="/v1/users">
    Manage users within organizations
  </Card>

  <Card title="Locations" icon="map-pin" href="/v1/locations">
    Set up phone numbers and AI agents
  </Card>
</CardGroup>

### Advanced Features

<CardGroup cols={2}>
  <Card title="Embed Dashboard" icon="frame" href="/advanced/embed">
    Integrate the dashboard into your app
  </Card>

  <Card title="Chat Widget" icon="comments" href="/advanced/chat-widget">
    Add web chat to customer websites
  </Card>
</CardGroup>

***

## Typical Integration Flow

Here's how most partners integrate with Answering Agent:

<Steps>
  <Step title="Customer Signs Up">
    A customer creates an account in your platform.
  </Step>

  <Step title="Create Organization">
    Your backend calls `POST /api/v1/organizations` to create the organization and owner user.
  </Step>

  <Step title="Setup Phone Number">
    Call `POST /api/v1/locations` to provision a phone number for the customer.
  </Step>

  <Step title="Get Embed Token">
    Call `GET /api/v1/users/{external_id}/embed-token` to get a token for embedding.
  </Step>

  <Step title="Show Dashboard">
    Embed the Answering Agent dashboard in your app using the embed token, giving customers access to their calls, tasks, and analytics.
  </Step>
</Steps>

### Multi-Account Viewer Flow

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

1. Confirm each customer organization is linked and reports `permissions.can_manage_dashboard_viewers: true`.
2. Create the partner-owned identity once.
3. Attach its `external_id` to each approved organization with `PUT /organizations/{organization_id}/dashboard-viewers/{external_id}`.
4. Request a token with the selected `organization_id` and replace the embed iframe when switching organizations.
5. 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:

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

```bash theme={null}
curl -X GET "https://answeringagent.com/api/v1/organizations" \
  -H "X-API-KEY: sk_live_AbCdEfGhIjKlMnOpQrSt"
```

<Card title="Authentication Guide" icon="lock" href="/v1/authentication">
  Complete authentication documentation with examples in multiple languages
</Card>

***

## 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:

<Tabs>
  <Tab title="JavaScript" value="javascript" default>
    ```javascript theme={null}
    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);
    ```
  </Tab>

  <Tab title="Python" value="python">
    ```python theme={null}
    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)
    ```
  </Tab>
</Tabs>

***

## Resources & Support

<CardGroup cols={2}>
  <Card title="Quickstart Guide" icon="rocket" href="/v1/quickstart">
    Build your first integration in 5 minutes
  </Card>

  <Card title="API Reference" icon="book" href="/v1/organizations">
    Complete endpoint documentation
  </Card>

  <Card title="FAQ" icon="circle-question" href="/v1/faq">
    Answers to common questions
  </Card>

  <Card title="Email Support" icon="envelope" href="mailto:support@answeringagent.com">
    Get help from our team
  </Card>
</CardGroup>

***

## Need Help?

We're here to support your integration:

* **Technical Questions**: [support@answeringagent.com](mailto:support@answeringagent.com)
* **Documentation Issues**: Report on GitHub or email support
* **Security Concerns**: [security@answeringagent.com](mailto:security@answeringagent.com)

Let's build something amazing together! 🚀