> ## 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 at [answeringagent.com](https://answeringagent.com) and go to **Settings → API Keys**. Click **New API Token**, enter a name, and click **Create**. Copy the key right away. The dashboard shows it once. Team owners and admins can create keys.
  </Accordion>

  <Accordion title="Should I use one API key everywhere?">
    No. Create a separate key for each service or server that calls the API. You can then revoke one key without breaking the others.
  </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. Send your API key in the `X-API-KEY` header. Requests are not signed, so the key is the only credential. Keep it on your server, and revoke it if it leaks.
  </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
  </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?">
    Sending partner link invites (`POST /partner-links`) and updating partner links (`PATCH /partner-links/{link}`) allow 10 requests per minute for each user. Over the limit, the API returns `429` with a `Retry-After` header. Other Partner API endpoints have no published per-key limit.

    The [Customer API](/api/overview) allows 120 requests per minute for each user.

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

  <Accordion title="Is there a test environment?">
    No. There is no public test environment. Every API call goes to production at `https://answeringagent.com/api/v1`. Creating a location with an `area_code` provisions a real phone number.

    Email [support@answeringagent.com](mailto:support@answeringagent.com) to plan testing before you go live.
  </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?">
    Yes, for new tasks. Answering Agent sends a `task.created` event to one HTTPS address per team the moment the AI creates a task. A team owner or admin sets the address in **Settings → Webhooks**. See [Webhooks](/webhooks) for the payload and delivery rules.

    `task.created` is the only event today.
  </Accordion>

  <Accordion title="What data can I access via the API?">
    There are two APIs under the same base URL.

    * **Partner API** (reseller accounts): create, read, update, and delete organizations, users, and locations, manage partner links, and issue embed tokens. It does not return conversations, transcripts, or tasks.
    * **[Customer API](/api/overview)** (any team): read a team's conversations, transcripts, call recordings, tasks, contacts, and reports. It reads the team of the person who created the key. It can also update a task's status and assignee.

    To read a customer organization's calls and tasks, someone on that organization creates a Customer API key.
  </Accordion>

  <Accordion title="Does the API support pagination?">
    Partner API list endpoints return all results in one response. If you manage a large number of organizations, contact [support@answeringagent.com](mailto:support@answeringagent.com) for guidance.

    [Customer API](/api/overview#pages-and-time-ranges) list endpoints return pages of up to 50 results.
  </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>
</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="/partner-api/organizations">
    Browse the complete API reference
  </Card>

  <Card title="Quickstart Guide" icon="rocket" href="/partner-api/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!


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