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

​
Authentication & API Keys

Sign in to your partner dashboard at answeringagent.com and navigate to Settings → API Keys. Click Generate New Key and copy it immediately - it’s only shown once!
While you technically can, we strongly recommend generating separate API keys for each environment:This makes it easier to debug issues and rotate keys without affecting production.
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! 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.
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
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.

​
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! Users can be added to multiple organizations with different roles in each. This is useful for consultants, franchise owners, or team members who work across multiple locations.
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 [email protected] 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 [email protected] 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
You need an embed token whenever you want to show your customers their Answering Agent data.
  • 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.
No, embed tokens don’t have a built-in expiration. However, they are invalidated when you generate a new token for the same user. For security, consider rotating them periodically.
The embedded dashboard uses your customers’ branding by default. For deeper customization (colors, logos, features), contact [email protected] to discuss white-label options.
Regenerating an embed token immediately invalidates all previous tokens for that user. Any embedded dashboards using the old token will stop working and need to be updated with the new 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.
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 [email protected] to discuss enterprise limits.
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!

​
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.
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 [email protected] to join the beta.
Yes! We provide a dedicated Playground environment at 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
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.
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.
Currently, list endpoints return all results. Pagination will be added as the API evolves. If you’re managing a large number of organizations, contact [email protected] for guidance.

​
Environments

FeaturePlaygroundProduction
Base URLplayground.answeringagent.comansweringagent.com
PurposeTesting & developmentLive customer calls
Phone NumbersTest numbers (may have limits)Real, production-grade numbers
DataTest data (can be deleted)Customer data (permanent)
API KeysSeparate playground keysSeparate production keys
When to useBuilding your integrationAfter 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!
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 [email protected].
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)

​
Billing & Pricing

Partner billing is custom and depends on your agreement. Contact your account manager or [email protected] 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 [email protected] to discuss options.
No! The Playground environment is provided free to all partners for testing and development. You’re only charged for production usage.

​
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 [email protected] and we’ll get back to you quickly!