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

# Partner API overview

> Provision organizations, users, phone numbers, and embedded dashboards for your customers.

<Warning>
  The Partner API is for reseller accounts only. A key from a regular Answering Agent team gets `401` on these endpoints. To read your own team's conversations, tasks, contacts, and reports, use the [Customer API](/api/overview).
</Warning>

The Partner API lets a reseller account:

* Create and manage organizations for its customers.
* Add users to those organizations with a role.
* Provision phone numbers (locations) answered by the AI.
* Embed the Answering Agent dashboard in its own app.
* Give one partner login read-only dashboard access to several customer-owned organizations, with each owner's approval.

## How the accounts fit together

```
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...
```

<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 stay owned by existing Answering Agent customers. Partner writes to a linked organization are denied unless its owner or 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 organization, and can have more users. You identify users by your own system's ID (`external_id`).
  </Accordion>

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

  <Accordion title="External ID" icon="fingerprint">
    Your ID for a user in your system. It maps your users to Answering Agent users without exposing internal IDs.
  </Accordion>

  <Accordion title="Embed tokens" icon="code">
    Tokens that let you 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 bearer bound to that organization.
  </Accordion>
</AccordionGroup>

## Base URL and authentication

The Partner API shares the Customer API's base URL and header:

```
Base URL: https://answeringagent.com/api/v1
Header:   X-API-KEY
```

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://answeringagent.com/api/v1/organizations" \
    -H "X-API-KEY: $ANSWERING_AGENT_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const res = await fetch('https://answeringagent.com/api/v1/organizations', {
    headers: { 'X-API-KEY': process.env.ANSWERING_AGENT_API_KEY },
  });
  if (!res.ok) throw new Error(`${res.status}: ${await res.text()}`);
  const organizations = await res.json();
  ```
</CodeGroup>

The key is the only credential. Requests are not signed, so keep the key on your server and treat it like a password. See [Partner API authentication](/partner-api/authentication).

## Typical integration flow

<Steps>
  <Step title="A customer signs up">
    A customer creates an account in your platform.
  </Step>

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

  <Step title="Provision a phone number">
    Call `POST /locations` to provision a phone number for the customer.
  </Step>

  <Step title="Get an embed token">
    Call `GET /users/{external_id}/embed-token`.
  </Step>

  <Step title="Show the dashboard">
    Embed the Answering Agent dashboard in your app with the token. Your customer sees their calls, tasks, and reports.
  </Step>
</Steps>

The [Partner API quickstart](/partner-api/quickstart) walks through each call with code.

### Multi-account viewer flow

An account manager can use 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`. Replace the embed iframe when you switch organizations.
5. To remove access to one organization, detach that relationship. The identity and its other organizations stay as they are.

This access is read-only. It ends at once when the viewer relationship, the owner's grant, the partner link, the membership, or the user is removed. See [multi-organization dashboard viewers](/partner-api/users#multi-organization-dashboard-viewers).

## Example: onboard a customer

```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:', result);
```

## Partner API pages

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/partner-api/quickstart">
    Create an organization, a location, and an embed token.
  </Card>

  <Card title="Authentication" icon="key" href="/partner-api/authentication">
    Create a key and send it with each request.
  </Card>

  <Card title="Organizations" icon="building" href="/partner-api/organizations">
    Create and manage customer organizations.
  </Card>

  <Card title="Users" icon="users" href="/partner-api/users">
    Manage users within organizations.
  </Card>

  <Card title="Locations" icon="map-pin" href="/partner-api/locations">
    Provision phone numbers answered by the AI.
  </Card>

  <Card title="Embed the dashboard" icon="frame" href="/advanced/embed">
    Show the Answering Agent dashboard inside your app.
  </Card>
</CardGroup>

## Get help

* Integration questions and documentation errors: [support@answeringagent.com](mailto:support@answeringagent.com)
* Security reports: [security@answeringagent.com](mailto:security@answeringagent.com)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.