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

​
Authentication & API Keys

Sign in at 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.
No. Create a separate key for each service or server that calls the API. You can then revoke one key without breaking the others.
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.
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.
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

​
Organizations & Users

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

​
Locations & Phone Numbers

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).
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.
Not through the API currently. Contact support@answeringagent.com to discuss porting existing phone numbers into Answering Agent.
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
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
Pricing varies based on your partner agreement. Contact your account manager or support@answeringagent.com for pricing details.

​
Embedding & Dashboard Access

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.
  • 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.
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.
The embedded dashboard uses your customers’ branding by default. For deeper customization (colors, logos, features), contact support@answeringagent.com to discuss white-label options.
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.
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.

​
Integration & Best Practices

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.
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.
  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.
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.
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 allows 120 requests per minute for each user.For high-volume integrations, contact support@answeringagent.com.
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 to plan testing before you go live.

​
Technical Questions

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.
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 for the payload and delivery rules.task.created is the only event today.
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 (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.
Partner API list endpoints return all results in one response. If you manage a large number of organizations, contact support@answeringagent.com for guidance.Customer API list endpoints return pages of up to 50 results.

​
Billing & Pricing

Partner billing is custom and depends on your agreement. Contact your account manager or support@answeringagent.com for pricing information.
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.
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 to discuss options.

​
Still Have Questions?

We’re here to help!

Technical Support

Email our support team for technical questions

Documentation

Browse the complete API reference

Quickstart Guide

Build your first integration in 5 minutes

Security Issues

Report security concerns
Can’t find your answer? Email support@answeringagent.com and we’ll get back to you quickly!