Authentication

Every public API request must include your API key as a bearer token in the Authorization header:

Authorization: Bearer YOUR_API_KEY

The public API base URL is:

https://api.teamfollowup.ai/api

Example:

curl https://api.teamfollowup.ai/api/agent-builder/agents \
  -H "Authorization: Bearer YOUR_API_KEY"

Only send API keys over HTTPS. Do not expose API keys in browser code, mobile app bundles, client-side logs, screenshots, or support tickets.

Manage keys

Create, rotate, and revoke API keys from the API Keys page in the dashboard. Keys are shown once when created or rotated. Store the value securely before leaving the page. The same bearer API keys authenticate the MCP action endpoint. Its advertised tool list is filtered by these scopes. That endpoint also accepts OAuth 2.1, which is the better fit for a hosted AI assistant: the user approves the scopes in a browser instead of pasting a key into a chat. The scopes below are the same ones the consent screen grants. See MCP action tools for the flow. Agency admins can manage keys for their own agency.

Scopes

API keys are scoped by module. Launch scopes are:

Scope	Allows
`agents:read`	List agents, get one agent, and read its skills and tools
`agents:write`	Create, update, clone, and delete agents, and manage their skills and tools
`voices:read`	Browse the voice catalogue, list your added voices, and preview what removing one would change
`voices:write`	Search for voices to add, add a voice to your library, and remove one
`calls:read`	Read call history, its filters, one call’s detail, and campaign test-run results
`calls:write`	Trigger test calls and campaign tests
`campaigns:read`	Read a campaign’s outcome prompts
`campaigns:write`	Update campaign configuration and outcome prompts, and enrol existing leads
`campaign_workflows:read`	Read campaign workflow configuration
`campaign_workflows:write`	Save campaign workflow configuration
`contacts:read`	Read contacts, their filters, and one contact’s call history
`contacts:write`	Set or clear a contact’s do-not-call flag, mark a contact as your own test lead, and add a contact to a sub-account that keeps its contacts on the platform
`ghl:read`	Read the custom fields, custom values, calendars, tags and contact lookups in a connected GoHighLevel sub-account. A sub-account that keeps its contacts here uses `contacts:` for its fields and `projects:` for its calendars
`ghl:write`	Create contacts in a connected GoHighLevel sub-account, and update approved workflow settings
`phone_numbers:read`	List and search phone numbers
`phone_numbers:write`	Buy, attach, assign, unassign, and move phone numbers
`phone_numbers:release`	Permanently release phone numbers from the agency pool
`power_dialer:read`	Read pipeline, callback, and cadence data
`power_dialer:write`	Run leads now, move them between steps, remove them, and update a cadence
`projects:read`	Read projects, agencies, systems, calendars, and campaign validation results
`projects:write`	Update a project and its campaign configuration
`projects:delete`	Disconnect and hide projects from the customer workspace
`dashboard:read`	Read dashboard metrics and project filters
`dashboard:write`	Manage dashboard layouts and saved views
`events:read`	Read tenant-scoped events and event types
`webhooks:read`	Read outbound webhook endpoints and their delivery history
`webhooks:write`	Create, update, and remove outbound webhook endpoints
`configuration:read`	Read agency configuration
`configuration:write`	Update agency configuration
`whitelabel:read`	Read agency branding and custom-domain status
`whitelabel:write`	Manage agency branding, logos, and custom domains
`billing:read`	Read your agency’s billing: balance, spend, transactions, invoices and receipts, and sub-account wallets
`billing:write`	Change auto-recharge, rebilling, Credit Guard and linked Stripe customers. Cannot charge a card
`billing:charge`	Charge saved cards: buy plans, and charge a sub-account’s client. Not included in `billing:write`, and not available to OAuth clients or over MCP

For module scopes with both read and write variants, write scope also covers the same module’s read scope. For example, agents:write covers agents:read. If a key is missing the required scope, the API returns:

{
  "success": false,
  "error": "InsufficientScope",
  "message": "This access key does not allow this action. Please ask your account admin to change its permissions.",
  "requiredScope": "agents:write"
}

Branch on error and read the missing scope from requiredScope. message is for people and its wording can change. See Conventions for the error shape.

Sensitive operations use explicit write, delete, or release scopes in addition to the existing role, tenant, ownership, billing, and resource-state checks.

Some scopes in the table cover modules that are not yet in the public reference, such as webhooks:*, events:read, configuration:*, whitelabel:* and dashboard:write. They are issuable and enforced today, and no published endpoint requires them. See What is not here.

Rate limits

Every request counts against per-key, per-key-and-IP and per-IP limits, and the RateLimit-* headers on each response tell you where you stand. The numbers and the headers are in Conventions.

Next steps

Quickstart makes the first request.
Conventions covers everything the endpoints share.

Developer setup

Agents

TFU Live

In-call Capabilities

Campaigns

Master agent

Phone Numbers

Voices

Projects

Calls

Contacts

Native Contacts

Native Calendar

Analytics

Billing

Manage keys

Scopes

Rate limits

Next steps

​Manage keys

​Scopes

​Rate limits

​Next steps

Manage keys

Scopes

Rate limits

Next steps