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

# Frequently Asked Questions

> Common questions about the Answering Agent Partner API

Get answers to the most common questions about integrating with the Answering Agent Partner API.

***

## Authentication & API Keys

<AccordionGroup>
  <Accordion title="Where do I get an API key?">
    Sign in to your partner dashboard at [answeringagent.com](https://answeringagent.com) and navigate to **Settings → API Keys**. Click **Generate New Key** and copy it immediately - it's only shown once!
  </Accordion>

  <Accordion title="Can I use the same API key for development and production?">
    While you technically can, we strongly recommend generating separate API keys for each environment:

    * **Playground** (testing) - Use [playground.answeringagent.com](https://playground.answeringagent.com)
    * **Production** (live customers) - Use [answeringagent.com](https://answeringagent.com)

    This makes it easier to debug issues and rotate keys without affecting production.
  </Accordion>

  <Accordion title="What happens if my API key is compromised?">
    Immediately revoke the compromised key in **Settings → API Keys** and generate a new one. The old key will stop working as soon as you revoke it. Update your integration with the new key as quickly as possible.
  </Accordion>

  <Accordion title="Do I need to sign my requests with HMAC or add timestamps?">
    **No!** Simply include your API key in the `X-API-KEY` header. No additional signing, HMAC calculations, or timestamps are required. Authentication is simple and straightforward.
  </Accordion>

  <Accordion title="Can I use multiple API keys simultaneously?">
    Yes! You can have multiple active API keys at the same time. This is useful for:

    * Key rotation (generate new, update systems, then revoke old)
    * Different services or teams using separate keys
    * Separate playground and production environments
  </Accordion>

  <Accordion title="How is this different from the /api/auth/login endpoint?">
    The `/api/auth/login` endpoint is used internally by the Answering Agent dashboard for user logins. As a partner, you use API keys with the `/api/v1/*` endpoints instead. You never need to call the login endpoint.
  </Accordion>
</AccordionGroup>

***

## Organizations & Users

<AccordionGroup>
  <Accordion title="What's the difference between an organization and a user?">
    * **Organization**: Your customer's business (e.g., "Pizza Palace"). Contains users and locations.
    * **User**: A person who belongs to an organization (e.g., "Maria Rodriguez, owner of Pizza Palace")

    Think of it as: Organization = Company, User = Employee
  </Accordion>

  <Accordion title="What is an 'external_id' and why do I need it?">
    The `external_id` is **your** system's unique identifier for a user. It allows you to:

    * Link Answering Agent users to your database without exposing internal IDs
    * Look up users using your own IDs instead of ours
    * Maintain a clean mapping between systems

    Example: If your user's ID is `"user_12345"` in your database, use that as the `external_id` when creating them in Answering Agent.
  </Accordion>

  <Accordion title="Can a user belong to multiple organizations?">
    Yes. Create one partner-owned identity and attach it independently to each approved organization. For owner-linked organizations, the owner/admin must grant viewer management first, and the attached role is always read-only `user`. Request embed tokens with the intended `organization_id`.
  </Accordion>

  <Accordion title="Can a partner attach viewers to any linked organization?">
    No. Partner links make an organization visible, but viewer writes remain default-deny. The organization owner or an admin must separately enable dashboard-viewer management. Your API can confirm this with `permissions.can_manage_dashboard_viewers` on the organization response; it cannot self-approve the grant.
  </Accordion>

  <Accordion title="What happens when I detach a multi-organization viewer?">
    `DELETE /organizations/{organization_id}/dashboard-viewers/{external_id}` removes access only to that organization. The user identity and other organization relationships remain. Existing compact and exchanged tokens for the detached relationship stop authorizing requests.
  </Accordion>

  <Accordion title="Can I create an organization without creating a user?">
    No. Organizations must have at least one owner user. When you create an organization, you must provide owner details in the same API call. This ensures every organization has an accountable owner from day one.
  </Accordion>

  <Accordion title="What happens when I delete an organization?">
    Organizations can only be deleted if they have **no users**. Remove all users first, then delete the organization. This prevents accidental data loss.

    Note: Deleting an organization will also delete all associated locations (phone numbers) and call data.
  </Accordion>

  <Accordion title="How do I handle customers who already exist in my system?">
    When creating an organization for an existing customer:

    1. Use their existing ID from your system as the `external_id`
    2. Use their real email address
    3. Store the returned `organization.id` in your database

    This maintains a clean bidirectional mapping between your system and Answering Agent.
  </Accordion>
</AccordionGroup>

***

## Locations & Phone Numbers

<AccordionGroup>
  <Accordion title="What is a 'location' in Answering Agent?">
    A location is a phone number with an AI answering agent. Each location:

    * Has its own phone number
    * Belongs to one organization
    * Has customizable AI agent settings
    * Receives and tracks calls independently

    Many organizations have multiple locations (e.g., different store branches).
  </Accordion>

  <Accordion title="How do phone numbers get provisioned?">
    When creating a location with an `area_code`, we automatically provision a phone number from Twilio in that area code. The number is assigned and ready to receive calls immediately.

    If you don't specify an `area_code`, the location is created with `status: "pending"` and no phone number. You can assign one later.
  </Accordion>

  <Accordion title="Can I use my own phone number (porting)?">
    Not through the API currently. Contact [support@answeringagent.com](mailto:support@answeringagent.com) to discuss porting existing phone numbers into Answering Agent.
  </Accordion>

  <Accordion title="What happens if no phone numbers are available in my area code?">
    If the requested area code has no available numbers, the API will return an error. Try:

    * A nearby area code
    * Calling our support team for assistance
    * Creating the location without an area code, then contacting support to manually assign a number
  </Accordion>

  <Accordion title="Can I have multiple locations (phone numbers) per organization?">
    Absolutely! Organizations can have unlimited locations. This is common for:

    * Multi-location businesses (franchises, chains)
    * Businesses with department-specific numbers
    * Organizations testing different AI configurations
  </Accordion>

  <Accordion title="How much does each phone number cost?">
    Pricing varies based on your partner agreement. Contact your account manager or [support@answeringagent.com](mailto:support@answeringagent.com) for pricing details.
  </Accordion>
</AccordionGroup>

***

## Embedding & Dashboard Access

<AccordionGroup>
  <Accordion title="What are embed tokens and when do I need them?">
    Embed tokens allow you to embed the Answering Agent dashboard directly in your application, giving your customers access to:

    * Call history and recordings
    * Tasks and follow-ups
    * Analytics and insights
    * AI agent settings for normal provisioned users

    You need an embed token whenever you want to show your customers their Answering Agent data.

    Organization-scoped partner viewers are read-only. They can see approved organization data, but cannot change settings, members, or roles or trigger recurring AI/model work.
  </Accordion>

  <Accordion title="How do embed tokens differ from API keys?">
    * **API Keys**: Used by your backend to manage organizations, users, and locations via API
    * **Embed Tokens**: Used by your frontend to display a customer's dashboard in your app

    API keys are for you (the partner), embed tokens are for your customers.
  </Accordion>

  <Accordion title="Do embed tokens expire?">
    The compact token placed in the iframe URL has no built-in expiration, but it can be invalidated immediately. The iframe exchanges it for an Answering Agent bearer that expires after 15 minutes. Scoped viewer authority is revalidated on every request.
  </Accordion>

  <Accordion title="Can I customize the embedded dashboard?">
    The embedded dashboard uses your customers' branding by default. For deeper customization (colors, logos, features), contact [support@answeringagent.com](mailto:support@answeringagent.com) to discuss white-label options.
  </Accordion>

  <Accordion title="What happens if I regenerate an embed token?">
    For a scoped viewer, include `organization_id`: regeneration immediately invalidates previous tokens for that organization relationship only. Other approved organization contexts remain valid. For an unscoped provisioned user, the existing user-wide rotation behavior still applies.
  </Accordion>

  <Accordion title="What else revokes a scoped viewer token?">
    Detaching the viewer, disabling or revoking the organization grant, revoking the partner link, removing the team membership, or deleting the user revokes the affected authority. Re-enabling a grant alone does not restore access; attach the viewer again and request a fresh token.
  </Accordion>
</AccordionGroup>

***

## Integration & Best Practices

<AccordionGroup>
  <Accordion title="Should I create organizations in real-time or batch?">
    **Real-time is recommended** for the best user experience. Create organizations when customers sign up in your platform, so their phone number is ready immediately.

    Batch creation is fine for migrations or bulk imports.
  </Accordion>

  <Accordion title="How should I store Answering Agent data in my database?">
    We recommend storing:

    * `organization_id` - Link to your customer record
    * `phone_number` - Display in your UI
    * `embed_token` - Show embedded dashboard

    Store the `external_id` you used when creating users so you can easily make API calls later.
  </Accordion>

  <Accordion title="What if my customer wants to cancel their account?">
    1. Delete all locations for the organization (`DELETE /locations/{id}`)
    2. Remove all users from the organization
    3. Delete the organization (`DELETE /organizations/{id}`)

    Or simply delete the organization record in your database and stop using their phone numbers.
  </Accordion>

  <Accordion title="How do I handle errors in the API?">
    The API returns standard HTTP status codes:

    * `200/201` - Success
    * `401` - Unauthorized (check your API key)
    * `404` - Resource not found
    * `422` - Validation error (check request body)
    * `500` - Server error (contact support)

    All errors include a JSON body with an `error` or `message` field explaining the issue.
  </Accordion>

  <Accordion title="What's the API rate limit?">
    The Partner API has generous rate limits designed for production use. If you hit rate limits, you'll receive a `429 Too Many Requests` response.

    For high-volume integrations, contact [support@answeringagent.com](mailto:support@answeringagent.com) to discuss enterprise limits.
  </Accordion>

  <Accordion title="Can I test the API without affecting production?">
    **Yes!** We provide a **Playground environment** specifically for testing and development:

    * **Playground**: `https://playground.answeringagent.com`
    * **Production**: `https://answeringagent.com`

    During onboarding, you'll receive credentials for the playground environment where you can:

    * Test your integration without affecting production
    * Create test organizations and users
    * Experiment with API calls
    * Debug your implementation

    Once your integration is ready, you'll receive production credentials to go live.

    **Important**: Use separate API keys for playground and production environments!
  </Accordion>
</AccordionGroup>

***

## Technical Questions

<AccordionGroup>
  <Accordion title="What happens to call data when I delete a location?">
    Call data is **permanently deleted** when you delete a location. Make sure to export or archive any important call recordings or transcripts before deleting a location.
  </Accordion>

  <Accordion title="Can I get webhooks for call events?">
    Webhook support is coming soon! You'll be able to subscribe to events like:

    * New call received
    * Call ended
    * Task created
    * Customer follow-up needed

    Contact [support@answeringagent.com](mailto:support@answeringagent.com) to join the beta.
  </Accordion>

  <Accordion title="Is there a sandbox/test environment?">
    **Yes!** We provide a dedicated **Playground environment** at [playground.answeringagent.com](https://playground.answeringagent.com).

    **How it works:**

    1. During partner onboarding, you'll receive playground credentials
    2. Build and test your integration using the playground
    3. Once ready, you'll receive production credentials for [answeringagent.com](https://answeringagent.com)

    **Key differences:**

    * Playground uses test Twilio numbers (may have limitations)
    * Production uses real phone numbers for live customer calls
    * Keep your API keys separate between environments!

    The playground is a full replica of production, so your integration code will work the same in both environments - just change the base URL and API key.
  </Accordion>

  <Accordion title="What data can I access via the API?">
    Currently, the Partner API focuses on provisioning and management:

    * Create/read/update/delete organizations
    * Create/read/update/delete users
    * Create/read/update/delete locations
    * Generate embed tokens

    For accessing call data, analytics, and tasks, use the embedded dashboard or contact support about data export options.
  </Accordion>

  <Accordion title="Does the API support pagination?">
    Currently, list endpoints return all results. Pagination will be added as the API evolves. If you're managing a large number of organizations, contact [support@answeringagent.com](mailto:support@answeringagent.com) for guidance.
  </Accordion>
</AccordionGroup>

***

## Environments

<AccordionGroup>
  <Accordion title="What's the difference between Playground and Production?">
    | Feature           | Playground                      | Production                     |
    | ----------------- | ------------------------------- | ------------------------------ |
    | **Base URL**      | `playground.answeringagent.com` | `answeringagent.com`           |
    | **Purpose**       | Testing & development           | Live customer calls            |
    | **Phone Numbers** | Test numbers (may have limits)  | Real, production-grade numbers |
    | **Data**          | Test data (can be deleted)      | Customer data (permanent)      |
    | **API Keys**      | Separate playground keys        | Separate production keys       |
    | **When to use**   | Building your integration       | After integration is complete  |

    **Pro tip**: Build your integration to use environment variables for the base URL and API key. This makes switching between playground and production as simple as changing config values!
  </Accordion>

  <Accordion title="How do I get access to the Playground environment?">
    During partner onboarding, you'll automatically receive:

    * Playground account credentials
    * Playground API key
    * Access to the playground dashboard

    If you haven't received these, contact [support@answeringagent.com](mailto:support@answeringagent.com).
  </Accordion>

  <Accordion title="Can I use Playground for demos?">
    Absolutely! The Playground environment is perfect for:

    * Internal demos and testing
    * Showing your team how the integration works
    * QA and integration testing
    * Customer demos (just make sure they know it's a test environment)
  </Accordion>
</AccordionGroup>

***

## Billing & Pricing

<AccordionGroup>
  <Accordion title="How does billing work for partners?">
    Partner billing is custom and depends on your agreement. Contact your account manager or [support@answeringagent.com](mailto:support@answeringagent.com) for pricing information.
  </Accordion>

  <Accordion title="Do I get charged for API calls?">
    No, API calls themselves are free. You're charged based on your partner agreement, typically per:

    * Active phone number (location)
    * Call minutes used
    * Number of organizations

    Check your partner agreement for details.
  </Accordion>

  <Accordion title="Can my customers pay directly?">
    This depends on your partner agreement. Some partners:

    * Bill customers directly (you handle billing)
    * Have us bill customers (we handle billing)
    * Mix of both (you bill for your service, we bill for phone services)

    Contact [support@answeringagent.com](mailto:support@answeringagent.com) to discuss options.
  </Accordion>

  <Accordion title="Does the Playground environment cost anything?">
    No! The Playground environment is provided free to all partners for testing and development. You're only charged for production usage.
  </Accordion>
</AccordionGroup>

***

## Still Have Questions?

We're here to help!

<CardGroup cols={2}>
  <Card title="Technical Support" icon="envelope" href="mailto:support@answeringagent.com">
    Email our support team for technical questions
  </Card>

  <Card title="Documentation" icon="book" href="/v1/organizations">
    Browse the complete API reference
  </Card>

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

  <Card title="Security Issues" icon="shield" href="mailto:security@answeringagent.com">
    Report security concerns
  </Card>
</CardGroup>

***

**Can't find your answer?** Email [support@answeringagent.com](mailto:support@answeringagent.com) and we'll get back to you quickly!