Quickstart Guide

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

Partner Account

You need a partner account with Answering Agent. If you don’t have one, contact us to get started.

API Key

Development Environment

You can use any language or tool that makes HTTP requests. We’ll show examples in cURL, JavaScript, and Python.

Step 1: Test Your API Key

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

cURL
JavaScript
Python

# Set your API key
export API_KEY="sk_live_YourApiKeyHere"

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

// Set your API key (use environment variables in production!)
const API_KEY = 'sk_live_YourApiKeyHere';
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);

import requests

# Set your API key (use environment variables in production!)
API_KEY = 'sk_live_YourApiKeyHere'
BASE_URL = 'https://answeringagent.com/api/v1'

# Test the connection
response = requests.get(
    f'{BASE_URL}/organizations',
    headers={
        'X-API-KEY': API_KEY,
        'Content-Type': 'application/json'
    }
)

organizations = response.json()
print('Your organizations:', organizations)

Expected Response:

[]

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

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

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:

cURL
JavaScript
Python

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"
    }
  }'

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;

org_response = requests.post(
    f'{BASE_URL}/organizations',
    headers={
        'X-API-KEY': API_KEY,
        'Content-Type': 'application/json'
    },
    json={
        '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'
        }
    }
)

data = org_response.json()
organization = data['organization']
owner = data['owner']

print('Organization created!', organization)
print('Owner user created!', owner)

# Save this for next steps
ORG_ID = organization['id']
USER_EXTERNAL_ID = owner['external_id']

Expected Response:

{
  "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.

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.

Step 3: Add a Phone Number

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

cURL
JavaScript
Python

# 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\"
  }"

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);

location_response = requests.post(
    f'{BASE_URL}/locations',
    headers={
        'X-API-KEY': API_KEY,
        'Content-Type': 'application/json'
    },
    json={
        'organization_id': ORG_ID,  # From step 2
        'name': 'Main Location',
        'address': '123 Main St, Denver, CO 80202',
        'area_code': '303'  # Denver area code
    }
)

location = location_response.json()['location']
print('Phone number provisioned!', location['phone_number'])

Expected Response:

{
  "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:

cURL
JavaScript
Python

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

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/embed?token=${embed_token}`;
console.log('Embed URL:', embedUrl);

token_response = requests.get(
    f'{BASE_URL}/users/{USER_EXTERNAL_ID}/embed-token',
    headers={'X-API-KEY': API_KEY}
)

embed_token = token_response.json()['embed_token']
print('Embed token:', embed_token)

# Use this token to embed the dashboard in your app
embed_url = f'https://answeringagent.com/embed?token={embed_token}'
print('Embed URL:', embed_url)

Expected Response:

{
  "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
Python

const API_KEY = 'sk_live_YourApiKeyHere';  // 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/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);
});

import requests

API_KEY = 'sk_live_YourApiKeyHere'  # Use env vars in production!
BASE_URL = 'https://answeringagent.com/api/v1'

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

    # 1. Create organization with owner
    print('Creating organization...')
    org_response = requests.post(
        f'{BASE_URL}/organizations',
        headers=headers,
        json={
            'name': 'Pizza Palace',
            'description': 'A local pizzeria serving Denver since 1995',
            'owner': {
                'external_id': 'customer_001',
                'email': 'maria@pizzapalace.com',
                'name': 'Maria Rodriguez'
            }
        }
    )
    org_response.raise_for_status()
    org_data = org_response.json()
    organization = org_data['organization']
    owner = org_data['owner']
    print(f'✓ Organization created: {organization["id"]}')

    # 2. Add phone number
    print('Provisioning phone number...')
    location_response = requests.post(
        f'{BASE_URL}/locations',
        headers=headers,
        json={
            'organization_id': organization['id'],
            'name': 'Main Location',
            'address': '123 Main St, Denver, CO 80202',
            'area_code': '303'
        }
    )
    location_response.raise_for_status()
    location = location_response.json()['location']
    print(f'✓ Phone number provisioned: {location["phone_number"]}')

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

    # Return data for your system
    return {
        'organization_id': organization['id'],
        'phone_number': location['phone_number'],
        'embed_token': embed_token,
        'embed_url': f'https://answeringagent.com/embed?token={embed_token}'
    }

# Run it!
if __name__ == '__main__':
    try:
        result = onboard_customer()
        print('\n🎉 Success! Customer onboarded:')
        print(result)
    except Exception as error:
        print(f'Error: {error}')

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:

The customer owner accepts the partner link.
The owner or an organization admin grants your partner account dashboard-viewer management.
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}.
Request GET /users/{external_id}/embed-token?organization_id={organization_id}.
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.

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

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.

What’s Next?

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

Embed the Dashboard

Learn how to embed the Answering Agent dashboard in your application

Add More Users

Add team members to the organization

Customize AI Settings

Configure the AI agent’s behavior and responses

Explore All Endpoints

See the complete API reference

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?

We’re here to help you succeed:

Technical Support: support@answeringagent.com
Documentation Issues: Report on GitHub or email support
Integration Questions: Our team is happy to jump on a call

Happy building! 🚀

Getting Started

Guides

POS Integrations

API Reference

API Playground

What You’ll Build

Prerequisites

Step 1: Test Your API Key

Step 2: Create Your First Organization

Step 3: Add a Phone Number

Step 4: Get an Embed Token

Complete Example

Already-Owned Organizations: Multi-Account Viewer Flow

What’s Next?

Embed the Dashboard

Add More Users

Customize AI Settings

Explore All Endpoints

Troubleshooting

”Invalid credentials” Error

”Organization not found” Error

Phone Number Not Provisioning

Embed Token Not Working

Need Help?

​What You’ll Build

​Prerequisites

​Step 1: Test Your API Key

​Step 2: Create Your First Organization

​Step 3: Add a Phone Number

​Step 4: Get an Embed Token

​Complete Example

​Already-Owned Organizations: Multi-Account Viewer Flow

​What’s Next?

Embed the Dashboard

Add More Users

Customize AI Settings

Explore All Endpoints

​Troubleshooting

​”Invalid credentials” Error

​”Organization not found” Error

​Phone Number Not Provisioning

​Embed Token Not Working

​Need Help?

What You’ll Build

Prerequisites

Step 1: Test Your API Key

Step 2: Create Your First Organization

Step 3: Add a Phone Number

Step 4: Get an Embed Token

Complete Example

Already-Owned Organizations: Multi-Account Viewer Flow

What’s Next?

Troubleshooting

”Invalid credentials” Error

”Organization not found” Error

Phone Number Not Provisioning

Embed Token Not Working

Need Help?