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

# Quickstart Guide

> Get started with the Answering Agent Partner API in 5 minutes

Get your first customer organization up and running with AI phone answering in under 5 minutes!

## What You'll Build

By the end of this guide, you'll have:

* ✅ An authenticated API connection
* ✅ A customer organization created
* ✅ A phone number provisioned with AI answering
* ✅ An embed token to display the dashboard

***

## Prerequisites

<Steps>
  <Step title="Partner Account">
    You need a partner account with Answering Agent. If you don't have one, [contact us](mailto:support@answeringagent.com) to get started.
  </Step>

  <Step title="API Key">
    Sign in to your partner dashboard and generate an API key at **Settings → API Keys**. Copy it somewhere safe!
  </Step>

  <Step title="Development Environment">
    You can use any language or tool that makes HTTP requests. We'll show examples in cURL and JavaScript.
  </Step>
</Steps>

***

## Step 1: Test Your API Key

First, let's verify your API key works by listing your organizations:

<Tabs>
  <Tab title="cURL" value="curl" default>
    ```bash theme={null}
    # Set your API key
    export API_KEY="123|AbCdEf0123456789AbCdEf0123456789AbCdEf01234"

    # Test the connection
    curl -X GET "https://answeringagent.com/api/v1/organizations" \
      -H "X-API-KEY: $API_KEY" \
      -H "Content-Type: application/json"
    ```
  </Tab>

  <Tab title="JavaScript" value="javascript">
    ```javascript theme={null}
    // Set your API key (use environment variables in production!)
    const API_KEY = '123|AbCdEf0123456789AbCdEf0123456789AbCdEf01234';
    const BASE_URL = 'https://answeringagent.com/api/v1';

    // Test the connection
    const response = await fetch(`${BASE_URL}/organizations`, {
      headers: {
        'X-API-KEY': API_KEY,
        'Content-Type': 'application/json'
      }
    });

    const organizations = await response.json();
    console.log('Your organizations:', organizations);
    ```
  </Tab>
</Tabs>

**Expected Response:**

```json theme={null}
[]
```

An empty array is perfect! It means your API key is working and you have no organizations yet.

<Note>
  If you get a 401 error, double-check that your API key is correct and you're using the `X-API-KEY` header (not `Authorization`).
</Note>

***

## Step 2: Create Your First Organization

Now let's create an organization for a customer. We'll create the organization and its owner user in a single API call:

<Tabs>
  <Tab title="cURL" value="curl" default>
    ```bash theme={null}
    curl -X POST "https://answeringagent.com/api/v1/organizations" \
      -H "X-API-KEY: $API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "name": "Pizza Palace",
        "description": "A local pizzeria serving Denver since 1995",
        "owner": {
          "external_id": "customer_001",
          "email": "maria@pizzapalace.com",
          "name": "Maria Rodriguez"
        }
      }'
    ```
  </Tab>

  <Tab title="JavaScript" value="javascript">
    ```javascript theme={null}
    const orgResponse = await fetch(`${BASE_URL}/organizations`, {
      method: 'POST',
      headers: {
        'X-API-KEY': API_KEY,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        name: 'Pizza Palace',
        description: 'A local pizzeria serving Denver since 1995',
        owner: {
          external_id: 'customer_001',  // Your system's ID for this user
          email: 'maria@pizzapalace.com',
          name: 'Maria Rodriguez'
        }
      })
    });

    const { organization, owner } = await orgResponse.json();
    console.log('Organization created!', organization);
    console.log('Owner user created!', owner);

    // Save this for next steps
    const ORG_ID = organization.id;
    const USER_EXTERNAL_ID = owner.external_id;
    ```
  </Tab>
</Tabs>

**Expected Response:**

```json theme={null}
{
  "organization": {
    "id": 123,
    "name": "Pizza Palace",
    "created_at": "2025-01-24T10:30:00Z",
    "updated_at": "2025-01-24T10:30:00Z"
  },
  "owner": {
    "id": 456,
    "external_id": "customer_001",
    "name": "Maria Rodriguez",
    "email": "maria@pizzapalace.com",
    "created_at": "2025-01-24T10:30:00Z",
    "updated_at": "2025-01-24T10:30:00Z"
  }
}
```

🎉 **Great!** You've created your first organization with an owner user. Note the `organization.id` - you'll need it for the next step.

<Tip>
  The `external_id` is **your** system's ID for this user. Use it to link this Answering Agent user to your database. All future API calls can use this ID instead of the internal Answering Agent user ID.
</Tip>

***

## Step 3: Add a Phone Number

Now let's provision a phone number for this organization:

<Tabs>
  <Tab title="cURL" value="curl" default>
    ```bash theme={null}
    # Replace 123 with your organization ID from step 2
    ORG_ID=123

    curl -X POST "https://answeringagent.com/api/v1/locations" \
      -H "X-API-KEY: $API_KEY" \
      -H "Content-Type: application/json" \
      -d "{
        \"organization_id\": $ORG_ID,
        \"name\": \"Main Location\",
        \"address\": \"123 Main St, Denver, CO 80202\",
        \"area_code\": \"303\"
      }"
    ```
  </Tab>

  <Tab title="JavaScript" value="javascript">
    ```javascript theme={null}
    const locationResponse = await fetch(`${BASE_URL}/locations`, {
      method: 'POST',
      headers: {
        'X-API-KEY': API_KEY,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        organization_id: ORG_ID,  // From step 2
        name: 'Main Location',
        address: '123 Main St, Denver, CO 80202',
        area_code: '303'  // Denver area code
      })
    });

    const { location } = await locationResponse.json();
    console.log('Phone number provisioned!', location.phone_number);
    ```
  </Tab>
</Tabs>

**Expected Response:**

```json theme={null}
{
  "location": {
    "id": 789,
    "name": "Main Location",
    "phone_number": "+13035551234",
    "status": "active",
    "address": "123 Main St, Denver, CO 80202",
    "created_at": "2025-01-24T10:35:00Z",
    "updated_at": "2025-01-24T10:35:00Z"
  }
}
```

📞 **Awesome!** The phone number is now active and ready to receive calls with AI answering!

***

## Step 4: Get an Embed Token

Finally, let's get an embed token so your customer can access their dashboard:

<Tabs>
  <Tab title="cURL" value="curl" default>
    ```bash theme={null}
    # Replace with your user's external_id from step 2
    USER_EXTERNAL_ID="customer_001"

    curl -X GET "https://answeringagent.com/api/v1/users/$USER_EXTERNAL_ID/embed-token" \
      -H "X-API-KEY: $API_KEY"
    ```
  </Tab>

  <Tab title="JavaScript" value="javascript">
    ```javascript theme={null}
    const tokenResponse = await fetch(
      `${BASE_URL}/users/${USER_EXTERNAL_ID}/embed-token`,
      {
        headers: { 'X-API-KEY': API_KEY }
      }
    );

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

    // Use this token to embed the dashboard in your app
    const embedUrl = `https://answeringagent.com/dashboard/embed?token=${embed_token}`;
    console.log('Embed URL:', embedUrl);
    ```
  </Tab>
</Tabs>

**Expected Response:**

```json theme={null}
{
  "embed_token": "MTIzNDV8ZDgyZDk3Mzg1OTAxNTkzNA",
  "user_id": "customer_001"
}
```

🔑 **Perfect!** You now have an embed token that lets your customer access their Answering Agent dashboard.

***

## Complete Example

Here's the entire flow in one script:

```javascript theme={null}
const API_KEY = '123|AbCdEf0123456789AbCdEf0123456789AbCdEf01234';  // Use env vars in production!
const BASE_URL = 'https://answeringagent.com/api/v1';

async function onboardCustomer() {
  try {
    // 1. Create organization with owner
    console.log('Creating organization...');
    const orgResponse = await fetch(`${BASE_URL}/organizations`, {
      method: 'POST',
      headers: {
        'X-API-KEY': API_KEY,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        name: 'Pizza Palace',
        description: 'A local pizzeria serving Denver since 1995',
        owner: {
          external_id: 'customer_001',
          email: 'maria@pizzapalace.com',
          name: 'Maria Rodriguez'
        }
      })
    });
    const { organization, owner } = await orgResponse.json();
    console.log('✓ Organization created:', organization.id);

    // 2. Add phone number
    console.log('Provisioning phone number...');
    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 Location',
        address: '123 Main St, Denver, CO 80202',
        area_code: '303'
      })
    });
    const { location } = await locationResponse.json();
    console.log('✓ Phone number provisioned:', location.phone_number);

    // 3. Get embed token
    console.log('Generating embed token...');
    const tokenResponse = await fetch(
      `${BASE_URL}/users/${owner.external_id}/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,
      embedUrl: `https://answeringagent.com/dashboard/embed?token=${embed_token}`
    };
  } catch (error) {
    console.error('Error:', error);
    throw error;
  }
}

// Run it!
onboardCustomer().then(result => {
  console.log('\n🎉 Success! Customer onboarded:');
  console.log(result);
});
```

***

## Already-Owned Organizations: Multi-Account Viewer Flow

The quickstart above provisions organizations owned by your partner account. If your customers already own their Answering Agent organizations, use the owner-linked viewer flow instead:

1. The customer owner accepts the partner link.
2. The owner or an organization admin grants your partner account dashboard-viewer management.
3. Create one identity with `POST /users` and an approved linked `organization_id`, or reuse an existing identity with `PUT /organizations/{organization_id}/dashboard-viewers/{external_id}`.
4. Request `GET /users/{external_id}/embed-token?organization_id={organization_id}`.
5. Put that compact token in a single `/dashboard/embed` iframe. Request a different scoped token and replace the iframe `src` when the account manager switches organizations.

<Tabs>
  <Tab title="cURL" value="curl" default>
    ```bash theme={null}
    # Attach an existing partner identity to an independently approved organization
    curl -X PUT -H "X-API-KEY: $API_KEY" \
      https://answeringagent.com/api/v1/organizations/456/dashboard-viewers/account-manager-42

    # Issue the token for exactly that organization
    curl -H "X-API-KEY: $API_KEY" \
      "https://answeringagent.com/api/v1/users/account-manager-42/embed-token?organization_id=456"
    ```
  </Tab>

  <Tab title="JavaScript" value="javascript">
    ```javascript theme={null}
    // Attach an existing partner identity to an independently approved organization
    const attachRes = await fetch('https://answeringagent.com/api/v1/organizations/456/dashboard-viewers/account-manager-42', {
      method: 'PUT',
      headers: { 'X-API-KEY': API_KEY },
    });
    if (!attachRes.ok) throw new Error(`${attachRes.status}: ${await attachRes.text()}`);
    const viewer = await attachRes.json();

    // Issue the token for exactly that organization
    const tokenRes = await fetch('https://answeringagent.com/api/v1/users/account-manager-42/embed-token?organization_id=456', {
      headers: { 'X-API-KEY': API_KEY },
    });
    if (!tokenRes.ok) throw new Error(`${tokenRes.status}: ${await tokenRes.text()}`);
    const { embed_token } = await tokenRes.json();
    ```
  </Tab>
</Tabs>

<Warning>
  The scoped viewer is organization-wide and read-only. It cannot change settings, manage members or roles, call mutation endpoints, or trigger recurring AI/model work. Detach or owner-side revocation invalidates stale scoped authority without removing access to other organizations.
</Warning>

***

## What's Next?

You've successfully onboarded your first customer! Here's what you can do next:

<CardGroup cols={2}>
  <Card title="Embed the Dashboard" icon="frame" href="/advanced/embed">
    Learn how to embed the Answering Agent dashboard in your application
  </Card>

  <Card title="Add More Users" icon="users" href="/partner-api/users">
    Add team members to the organization
  </Card>

  <Card title="Customize AI Settings" icon="robot" href="/partner-api/organizations">
    Configure the AI agent's behavior and responses
  </Card>

  <Card title="Explore All Endpoints" icon="book" href="/partner-api/organizations">
    See the complete API reference
  </Card>
</CardGroup>

***

## Troubleshooting

### "Invalid credentials" Error

* Double-check your API key is correct
* Make sure you're using the `X-API-KEY` header (not `Authorization: Bearer`)
* Verify your partner account is active

### "Organization not found" Error

* Make sure you're using the correct organization ID
* Verify the organization belongs to your partner account
* Check that the organization wasn't deleted

### Phone Number Not Provisioning

* Ensure the `area_code` is valid (3 digits, US/Canada)
* Some area codes may have limited availability
* Try a different area code if provisioning fails

### Embed Token Not Working

* Verify the user's `external_id` is correct
* Make sure the user belongs to the organization
* For multi-organization viewers, include the intended `organization_id` when requesting the token
* Check that the owner-approved viewer grant and partner link remain active
* Ensure the scoped relationship has not been detached or rotated

***

## Need Help?

Email [support@answeringagent.com](mailto:support@answeringagent.com) with integration questions or documentation errors.


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