Conventions

Everything on this page applies to every published endpoint. The endpoint pages assume you know it.

Base URL and authentication

https://api.teamfollowup.ai/api

Paths in the reference already include the /api prefix. Every request carries an API key as a bearer token:

Authorization: Bearer YOUR_API_KEY

Keys, scopes and the InsufficientScope error are covered in Authentication. Requests authenticated with an API key do not use CSRF tokens. CSRF protection applies to browser dashboard sessions only.

Response envelope

Success:

{ "success": true, "data": { } }

The payload key is data on most endpoints and a named field on some, such as agents, voices or contacts. The endpoint page shows which. Failure:

{
  "success": false,
  "error": "NotFound",
  "message": "We couldn't find that. It may have been moved or deleted."
}

Every error answers in this shape:

Field	Sent	What it is
`error`	Always	A stable code for what went wrong, from the table below or the endpoint’s page. Branch on this. The same failure always answers with the same code.
`message`	Always	One plain sentence for a person: what happened and what to do next. Show it, never parse it. Its wording can change.
`errors`	When specific fields were refused	One `{ field, code, message }` per field to fix. `field` is where the value sits in your request, as a dotted path. `code` is stable, `message` is for a person.
`details`	Sometimes	Data your code may need to act on the failure, such as ids or limits. Never text.
`ref`	When the failure was on our side	Quote it to support so they can find the request. It matches the `x-request-id` response header.

Some errors add fields of their own, such as requiredScope on InsufficientScope, or workflowId and stepId on a TFU Live workflow refusal. Some endpoints also repeat the code in a top-level code field, kept for integrations built before error always held one. The reference lists these on each endpoint. Requests made with an API key or through an OAuth app, MCP included, always get message in English. People using the dashboard get it in their own language. error never changes with the language.

If you read a sentence from `error`

Five modules used to put a sentence in error: Native Calendar, Native Contacts, Contacts, TFU Live, and the power dialer operations under Campaigns. They now put a code there, like every other module, and the sentence is in message. If your integration shows error to people, show message instead. If it matches the words, match the code. Contacts and the power dialer also sent the code in a separate code field. Read it from error now: code is no longer sent there. TFU Live still sends code, with the same value as error. See the Changelog.

Which id to use

Most resources have more than one identifier. They are not interchangeable.

You want to name	Send	Not
A project (one sub-account, with its contacts in GoHighLevel or here)	`locationId`	`projectName`. It is a display label that can be renamed. Name-only project selections return `400`; send `locationId` or `locationIds`.
A project on the `/api/v2/projects` endpoints	The project record `id` in the path	`locationId`, which those paths do not take.
An agent	Its `id`, for example `agent_8a488fcfa8fdbf8ce8ad5ccc45`	The `agentId` on a campaign is the same value seen from the campaign’s side.
A campaign	`campaignId`	The campaign’s `name`.
A split-test variant	`agentVariantId` as a filter, `variantAgentId` in split-test paths	Either one alone: a variant only means something inside its `campaignId`.
A contact	`contactId`, or `phoneNumber` in E.164	Assuming a `contactId` is always there.
A call	`id` for `GET /api/call-history/{callId}`, `callId` for `GET /api/call-history/by-call-id/{callId}`	Mixing them. Two ids, two lookups.
A queued lead in the power dialer	`queueId`	The contact id. One contact can have been queued more than once.

A contact’s contactId is the GoHighLevel contact id on a sub-account with a CRM, and the native contact id, which starts with nct_, on one that keeps its contacts here. It can be absent altogether, so key on the phone number and treat the id as optional. See Agencies, projects and sub-accounts for the three project identifiers in detail.

Phone numbers

Numbers travel in E.164 with a leading +, for example +14155550100. In a URL path the + must be percent-encoded as %2B:

DELETE /api/agent-builder/phone-numbers/%2B14155550100

Dates and times

Date filters (dateFromUTC, dateToUTC) accept a UTC timestamp with Z or an offset, or a plain YYYY-MM-DD. A plain date covers that whole day.
A plain date is a UTC day unless you also send tz, an IANA zone name such as America/Los_Angeles or Asia/Kolkata. With it, the day runs from midnight in that zone to the next midnight there, so a day when the clocks change is 23 or 25 hours long. GET /api/call-history and GET /api/contacts take tz, and the window on their response gives the UTC instants the filter used.
tz changes plain dates only. A timestamp is the exact moment it names, with or without tz.
A missing or unknown tz is not an error: plain dates stay UTC days. So does a bare offset such as +05:30, because an offset does not follow daylight saving. Send the zone name.
A timestamp without a zone is rejected with 400 rather than read as server time.
Timestamps in responses are ISO 8601 in UTC, for example 2026-09-05T14:03:22.000Z.
Analytics windows are inclusive calendar days. See Metrics and how they are calculated.

Pagination and sorting

Paged list endpoints take page (from 1) and limit, and return a pagination object with page, limit, total and totalPages. Sorting is not uniform, and the reference shows which form each endpoint takes:

Calls: sort as field.direction, for example dateTime.desc.
Contacts: sortBy and sortOrder (asc or desc).

Idempotency

Most operations are not idempotent. Repeating a create after a timeout can create twice. Read the current state back before retrying a write. These operations accept an Idempotency-Key header. Send a unique value per logical request and a retry with the same key returns the original result:

Create agent
Clone agent
Add actions to an outcome
Add split variant, which marks the replay with idempotentReplay: true
Every Billing change, which marks the replay with idempotentReplay: true. Link a Stripe customer requires it as well, because it links the sub-accounts one at a time. The three that charge a card require it: Buy a plan, Charge a sub-account and Enable rebilling with a charge. A declined card is an answer too: the retry replays that decline rather than reaching the card again, so once the card is fixed, use a new key. If an attempt ends without a known outcome, the key is spent: buying a plan answers IDEMPOTENCY_OUTCOME_UNKNOWN until you check the billing and use a new key.

Concurrency tokens

Documents that are edited while they run carry a version. Send it back on every write. If someone saved in between, the write is refused with 409 and you reload instead of overwriting them.

Resource	Read	Send back as
Campaign workflow	`version`	`expectedVersion`
Agent skills	`version`	`expectedVersion`
Split test	`revision`	`revision`

Legacy aliases

Some responses carry an older spelling beside the canonical field. Same value. Build on the canonical name.

Canonical	Alias	Where
`active` (campaign live state)	`isActive`	Campaign reads. Note that Get agent returns the agent’s state as `isActive` while List agents returns it as `active`.
`dialing`	`type`	Campaign reads.
`s2lDelaySeconds`	`s2lDelayMinutes`	Campaign `config`. When both are present, seconds wins.
`agentType` and `capabilities`	`system`	Campaign reads. `system` is the legacy template the campaign was cloned from, not what the agent can do. See Campaign types and capabilities.

Deprecated routes carry a Deprecation response header (RFC 9745) and are marked in the reference. Removals are announced in the Changelog.

Status codes

Status	Meaning
`400`	Validation failed or the request is malformed.
`401`	Missing, invalid or revoked credential.
`402`	The agency’s effective billing access does not permit this request.
`403`	Authenticated but not permitted: role, tenant boundary, or missing scope.
`404`	Not found, or not visible to this credential.
`409`	The change conflicts with current state, a concurrency token is stale, or a billing gate refused a paid action.
`422`	The request is well formed, but a value or the state it depends on cannot be accepted.
`429`	Rate limited.
`500`	Unexpected server error.
`502`	An upstream provider refused the request.
`503`	An upstream provider is unavailable.

Error codes

The codes shared across published endpoints, grouped by what to do about them. Each endpoint’s page lists the codes specific to it. A few codes have two spellings, an older one kept so existing integrations keep working, and the reference shows which one each endpoint returns. If you handle one, handle both.

Code	Status	Means
`Unauthorized`, `InvalidApiKey`, `InvalidAccessToken`	`401`	No usable credential. Check the header and that the key or OAuth token is not revoked or expired.
`AccessSubscriptionRequired`	`402`	The agency needs software access restored. Review billing access in the dashboard.
`InsufficientScope`	`403`	The key lacks the scope named in `requiredScope`.
`Forbidden`, `FORBIDDEN`	`403`	Permitted credential, wrong tenant, role or resource. A role refusal does not name the role it needs.
`AccessDenied`	`403`	The project or resource is outside this credential’s agency.
`ApiKeyNotAllowed`	`403`	This operation is done signed in to the dashboard, not with an API key.
`ValidationFailed`	`400`, `422`	One or more fields need fixing. `errors` lists each one.
`VALIDATION`	`400`	A field is missing or malformed, on the endpoints that always answered with this code. When it names fields, `errors` lists each one.
`BadRequest`	`400`	The request shape is wrong in a way that is not one field.
`MalformedIdentifier`	`400`	An id in the path is not in the right format. Check it was copied whole.
`NotFound`, `NOT_FOUND`	`404`	The resource does not exist or is not yours.
`Conflict`, `CONFLICT`	`409`	State conflict, stale token, or a billing gate. Read the current state before retrying.
`IN_USE`	`409`	The resource is attached to something live and cannot be removed yet.
`GHL_NOT_CONNECTED`	`409`	The project has never been connected to GoHighLevel.
`SUBACCOUNT_DISCONNECTED`	`409`	The GoHighLevel connection stopped working. Reconnect the project.
`SYNC_FAILED`	`502`	Saved here, not on the voice provider. `sync.status` reads `error` until retried.
`VoiceProviderUnavailable`	`502`	The voice provider refused to start a session. Nothing is wrong with the agent.
`PROVIDER_UNAVAILABLE`	`503`	A provider-backed search could not be served. Retry shortly.
`TooManyRequests`, `RateLimited`	`429`	Rate limited. Read the `RateLimit-*` headers and wait.
`Internal`, `InternalError`	`500`	Our fault. Retry once, then report it to support with the `ref`.
`ServiceUnavailable`, `QueryTimeout`	`502`, `503`	A dependency or a slow read did not answer in time. Retry shortly.

Integration states are explained in GoHighLevel resources.

Billing access

AccessSubscriptionRequired can block reads as well as writes. Changing API key scopes does not resolve it. Effective software access is separate from the provider’s subscription status and the wallet’s recorded balance. An approved billing exemption does not change resource ownership, user roles or API key scopes. It also does not cancel an existing provider subscription or erase billing history.

Rate limits

Limits are per minute and the defaults are below. The headers on every response are authoritative, so build on them rather than on this table.

Limit	Default	Applies to
Per API key	300 requests	Every request made with that key.
Per API key and source IP	120 requests	The same key from one address.
Per source IP	1000 requests	Every request to `/api`, with or without a key.
Write endpoints, per source IP	500 requests	Endpoints that change state.
Bulk endpoints, per source IP	200 requests	Endpoints that act on many records at once.
Billing charges, per API key	10 requests	The three Billing operations that charge a card; 5 from one address. Retry a `429` with the same `Idempotency-Key`.

Every response carries the standard draft rate-limit headers:

Header	Meaning
`RateLimit-Limit`	The limit for the window that is closest to being exhausted.
`RateLimit-Remaining`	Requests left in that window.
`RateLimit-Reset`	Seconds until the window resets.

When a limit is exceeded the API returns 429 with TooManyRequests and the standard envelope. Wait RateLimit-Reset seconds and retry. Spread bulk work across the window rather than bursting at the top of the minute.

Authentication for keys and scopes.
Glossary for every term and field used in these docs.

Developer setup

Agents

TFU Live

In-call Capabilities

Campaigns

Master agent

Phone Numbers

Voices

Projects

Calls

Contacts

Native Contacts

Native Calendar

Analytics

Billing

Base URL and authentication

Response envelope

If you read a sentence from `error`

Which id to use

Phone numbers

Dates and times

Idempotency

Concurrency tokens

Legacy aliases

Status codes

Error codes

Billing access

Rate limits

​Base URL and authentication

​Response envelope

​If you read a sentence from error

​Which id to use

​Phone numbers

​Dates and times

​Pagination and sorting

​Idempotency

​Concurrency tokens

​Legacy aliases

​Status codes

​Error codes

​Billing access

​Rate limits

​Related

Base URL and authentication

Response envelope

If you read a sentence from `error`

Which id to use

Phone numbers

Dates and times

Pagination and sorting

Idempotency

Concurrency tokens

Legacy aliases

Status codes

Error codes

Billing access

Rate limits

Related