> ## Documentation Index > Fetch the complete documentation index at: https://docs.teamfollowup.ai/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > Use the public API base URL: https://api.teamfollowup.ai/api. > Authenticate public API requests with Authorization: Bearer YOUR_API_KEY. > Use product-owned terms: agents, campaigns, projects (GoHighLevel sub-accounts), contacts, calls, outcomes, skills, cadences, phone numbers. > Scope requests by locationId rather than projectName. > Read the guide linked from each API reference group before recommending an endpoint. # Get contact > Read one contact from the platform, scoped by locationId. Use include=calls to expand its call history. The record reports the latest recorded outcome; that is distinct from the current CRM do-not-call flag. No CRM profile is edited by this read. Required API key scope: `contacts:read`. ## OpenAPI ````yaml /openapi.yaml get /api/contacts/{contactId} openapi: 3.1.0 info: title: TFUAI Server API version: 1.0.0 description: >- API reference for the TFUAI SaaS server. All published endpoints are mounted under `/api`. Responses use a standard envelope: `{ "success": true, ... }` on success and `{ "success": false, "error": "..." }` on failure. Product API modules are being launched module by module. This spec currently exposes only contracted public modules. Authenticate public API requests with an API key in the `Authorization` header: `Authorization: Bearer YOUR_API_KEY`. servers: - url: https://api.teamfollowup.ai description: Production API origin. Public API paths are under /api. security: [] tags: - name: Agents description: >- Build the conversation: identity and settings, script, lead context and split testing. - name: Analytics description: >- Understand call volume, pickup, booking and transfer metrics within the selected reporting scope. - name: Billing description: >- Balances, spend, purchases and sub-account rebilling. Reference and guides only; the builder chatbot has no billing playbook. - name: Calls description: >- Review completed calls, recordings, transcripts and campaign run history; distinguish observation from placing a new call. - name: Campaigns description: >- Configure what starts calls, who is eligible, calling windows, caller IDs, activation and the actions that follow each outcome. What runs after a call lands: for each outcome (booked, opted out, asked for a callback…), an ordered chain of actions — tag the contact, move a pipeline stage, send an SMS, book an appointment. Stored as a graph: `nodes` are the actions, `edges` say what follows what, and `dispositionEntries` maps each outcome to the node its chain starts at. **Pick the narrowest endpoint that does the job.** | To | Call | | | --- | --- | --- | | See what fires per outcome | `GET .../workflow?view=summary` | Reads as plain text, no graph walking | | Add steps to an outcome | `POST .../outcomes/{outcome}/nodes` | Server derives node ids, edge ids, handles, layout | | Change a message, tag or setting | `PATCH .../workflow` | Merges; carries no graph, so it cannot damage one | | Remove one step | `DELETE .../nodes/{nodeId}` | Also re-links the chain around it | | Author or replace the whole graph | `PUT .../workflow` | Replaces everything you send | `PUT` is the only one that can re-wire, position nodes, build an `if`, save an unconfigured draft, or copy a whole workflow — and the only one that can overwrite a change someone else made after you read it. Use it when you are genuinely authoring the graph, and send `expectedVersion` when you do. For everything else the narrower endpoints are both easier and safer. - name: Contacts description: >- Find contacts and their calls, manage do-not-call status and identify internal contacts excluded from reporting. - name: In-call Capabilities description: >- Configure actions and instructions the agent uses during a live call: booking, transfers, lookups and custom skills. - name: Master agent description: >- Run a shared agent and campaign across linked projects; manage inheritance, local bindings, synchronization and rollout readiness. - name: Native Calendar description: >- The diary of a sub-account with no CRM: its bookable calendars, the free slots they offer, and the appointments on them. Availability is computed per request against live bookings and is never cached, because a cached slot is one somebody else has already taken. - name: Native Contacts description: >- The people a sub-account with no CRM calls, and the fields it keeps on them. This is the system of record for those contacts: there is nowhere else they exist. A sub-account with a CRM keeps its contacts there and every operation here answers 400 for it. - name: Phone Numbers description: >- Find and manage caller IDs, assign numbers to campaigns and understand connected Twilio numbers. - name: Projects description: >- Understand project ownership, inspect configuration and validate the local resources used by a campaign. - name: TFU Live description: >- Build one TFU Live agent with its Brain, Voice and equipped actions; connect it through shared Campaigns. - name: Voices description: >- Browse the voice catalogue and select a voice; configure speech and listening behavior in Agents. paths: /api/contacts/{contactId}: get: tags: - Contacts summary: Get contact description: >- Read one contact from the platform, scoped by locationId. Use include=calls to expand its call history. The record reports the latest recorded outcome; that is distinct from the current CRM do-not-call flag. No CRM profile is edited by this read. Required API key scope: `contacts:read`. operationId: get-contact parameters: - name: contactId in: path required: true schema: type: string minLength: 1 description: >- The contactId returned by List contacts. For contacts without one, use an encoded international phone number and idType=phone. This is not the list row id. - name: locationId in: query required: true description: >- The project location ID. Contact identity is always scoped to this project. schema: type: string minLength: 1 - name: idType in: query required: false description: >- Use phone only when identifying a contact by its international phone number. schema: type: string enum: - contact - phone default: contact - name: include in: query required: false description: Optional related information. Omit for just the contact. schema: type: string enum: - calls responses: '200': description: Contact details. content: application/json: schema: $ref: '#/components/schemas/ContactDetailResponse' example: success: true data: id: 64f2a8c8a2b3c4d5e6f7a8b9 _id: 64f2a8c8a2b3c4d5e6f7a8b9 phoneNumber: '+14155551234' leadName: Alex Morgan projectName: Acme Clinic dateAdded: '2026-07-08T16:00:00.000Z' callCount: 3 contactId: contact_123 locationId: loc_9f7a123 crm: ghl leadId: null kommoSubdomain: null ghlWhitelabelDomain: null isInternal: false nextScheduledCall: nextCallTime: '2026-07-09T14:30:00.000Z' cadenceStep: 1 disposition: type: appointment label: Appointment color: green '400': description: Invalid parameters or unsupported fields. content: application/json: schema: $ref: '#/components/schemas/ContactsErrorResponse' example: success: false error: VALIDATION code: VALIDATION message: locationId is required. '401': description: Authentication required. content: application/json: schema: $ref: '#/components/schemas/ContactsErrorResponse' example: success: false error: UNAUTHORIZED code: UNAUTHORIZED message: Unauthorized '403': description: Required role, API scope, or project access is missing. content: application/json: schema: $ref: '#/components/schemas/ContactsErrorResponse' example: success: false error: FORBIDDEN code: FORBIDDEN message: Access denied to this project '404': description: Contact not found in the selected project. content: application/json: schema: $ref: '#/components/schemas/ContactsErrorResponse' example: success: false error: NOT_FOUND code: NOT_FOUND message: Contact not found in the selected project. '409': description: A phone number matches multiple contacts. Use a contact ID. content: application/json: schema: $ref: '#/components/schemas/ContactsErrorResponse' example: success: false error: AMBIGUOUS_CONTACT code: AMBIGUOUS_CONTACT message: A phone number matches multiple contacts. Use a contact ID. '429': $ref: '#/components/responses/RateLimited' '500': description: The contact could not be read or updated. content: application/json: schema: $ref: '#/components/schemas/ContactsErrorResponse' example: success: false error: INTERNAL_ERROR code: INTERNAL_ERROR message: The contact could not be read. security: - ApiKeyAuth: [] x-codeSamples: - lang: bash label: cURL source: |- curl --request GET \ --url https://api.teamfollowup.ai/api/contacts/{contactId} \ --header 'Authorization: Bearer YOUR_API_KEY' components: schemas: ContactDetailResponse: type: object required: - success - data properties: success: const: true data: type: object additionalProperties: false required: - id - phoneNumber - leadName - projectName - dateAdded - callCount - contactId - locationId - crm - leadId - kommoSubdomain - ghlWhitelabelDomain - isInternal - nextScheduledCall - disposition properties: id: type: string example: 64f2a8c8a2b3c4d5e6f7a8b9 _id: type: string description: Legacy alias of `id`. example: 64f2a8c8a2b3c4d5e6f7a8b9 phoneNumber: type: string example: '+14155551234' leadName: type: - string - 'null' example: Alex Morgan projectName: type: string example: Acme Clinic dateAdded: type: - string - 'null' format: date-time example: '2026-07-08T16:00:00.000Z' callCount: type: integer minimum: 0 example: 3 contactId: type: - string - 'null' example: contact_123 locationId: type: - string - 'null' description: >- The sub-account this contact belongs to. On a sub-account with a CRM it is also what builds the deep link to the contact there. example: loc_9f7a123 crm: type: - string - 'null' description: >- Which system holds this contact: a connected CRM, or `native` when the sub-account keeps its contacts on the platform. example: ghl leadId: type: - string - 'null' description: CRM lead id (Kommo). Null for GHL contacts. example: null kommoSubdomain: type: - string - 'null' description: Kommo tenant subdomain used to build the Kommo deep link. example: null ghlWhitelabelDomain: type: - string - 'null' description: >- Host serving the agency's white-labelled GoHighLevel (e.g. 'app.example.com'). Null when the agency uses the shared default host. example: null isInternal: type: boolean description: >- True when this contact is marked as one of your own test leads, Its calls are left out of the dashboard's performance figures but kept in the cost figures. example: false nextScheduledCall: anyOf: - $ref: '#/components/schemas/ContactsScheduledCall' - type: 'null' disposition: anyOf: - $ref: '#/components/schemas/ContactsOutcome' - type: 'null' calls: $ref: '#/components/schemas/ContactsCallsData' ContactsErrorResponse: type: object additionalProperties: {} required: - success - error properties: success: type: boolean error: type: string example: Access denied to this project code: type: string example: FORBIDDEN message: type: string example: Access denied to this project ContactsScheduledCall: type: object additionalProperties: false required: - nextCallTime - cadenceStep properties: nextCallTime: type: - string - 'null' format: date-time example: '2026-07-09T14:30:00.000Z' cadenceStep: type: - integer - 'null' example: 1 ContactsOutcome: type: object additionalProperties: {} required: - type - label - color properties: type: $ref: '#/components/schemas/ContactsOutcomeType' id: type: string example: disp_123 _id: type: string description: Legacy alias of `id`. example: disp_123 label: type: string example: Appointment color: type: string example: green date: type: string example: '2026-07-08T16:15:00.000Z' duration: type: - number - 'null' example: 184 dateCreated: type: string example: '2026-07-08T16:15:00.000Z' dateScheduled: type: string example: '2026-07-09' requestedDateTime: type: string example: '2026-07-09T15:00:00.000Z' calendarName: type: - string - 'null' example: Main Calendar dateOfAppointment: type: string example: '2026-07-11' timeOfAppointment: type: string example: 10:30 AM dayOfWeek: type: string example: Saturday stageBooked: type: - string - 'null' example: Consultation status: type: string example: Successful tag: type: string description: >- The GoHighLevel tag the call applied. Present only when `type` is `tagged`, an outcome only a sub-account with GoHighLevel can record. example: quoted ContactsCallsData: type: object additionalProperties: false required: - contact - calls - dispositionSummary properties: contact: type: object additionalProperties: false required: - phoneNumber - locationId - projectName properties: phoneNumber: type: string example: '+14155551234' locationId: type: - string - 'null' description: >- Project location id the lookup was scoped to, echoed back from the request. example: loc_9f7a123 projectName: type: - string - 'null' example: Acme Clinic calls: type: array items: $ref: '#/components/schemas/ContactsCallRecord' spend: type: object additionalProperties: false required: - calls description: >- What this contact has cost so far, in the viewer-safe channel the call list uses. properties: calls: type: - number - 'null' description: >- Total cost of every call to the contact, not only the calls listed. null when no call is costed yet. example: 6.54 dispositionSummary: $ref: '#/components/schemas/ContactsDispositionSummary' ApiError: type: object description: Standard error envelope returned by the API. properties: success: type: boolean example: false error: type: string description: Short machine-readable error code. example: Unauthorized message: type: string description: Human-readable explanation of the error. example: Authentication required. required: - success - error ContactsOutcomeType: type: string enum: - killSwitch - callBack - appointment - liveTransfer - failedTransfer - tagged example: appointment ContactsCallRecord: type: object additionalProperties: false required: - id - callId - date - dateTime - leadName - phoneNumber - direction - status - duration - agent - callSummary - projectName - recordingUrl - disposition properties: id: type: string example: 64f2a8c8a2b3c4d5e6f7a8c0 _id: type: string description: Legacy alias of `id`. example: 64f2a8c8a2b3c4d5e6f7a8c0 callId: type: - string - 'null' example: call_123 date: type: string example: '2026-07-08' dateTime: type: string format: date-time example: '2026-07-08T16:12:00.000Z' leadName: type: - string - 'null' example: Alex Morgan phoneNumber: type: string example: '+14155551234' direction: type: string example: outbound status: type: string example: completed duration: type: integer minimum: 0 example: 184 agent: type: string example: Front Desk Agent callSummary: type: string example: Alex asked for available appointment times. projectName: type: string example: Acme Clinic recordingUrl: type: - string - 'null' example: https://media.example.test/recordings/call_123.mp3 cost: type: - number - 'null' description: >- Cost of this call at your account's rate, or null while the call is still being costed. example: 2.18 disposition: anyOf: - $ref: '#/components/schemas/ContactsOutcome' - type: 'null' ContactsDispositionSummary: type: object additionalProperties: false required: - killSwitch - callBack - appointment - liveTransfer - tagged - total properties: killSwitch: type: integer minimum: 0 example: 0 callBack: type: integer minimum: 0 example: 1 appointment: type: integer minimum: 0 example: 0 liveTransfer: type: integer minimum: 0 example: 0 tagged: type: integer minimum: 0 example: 0 total: type: integer minimum: 0 example: 1 responses: RateLimited: description: Rate limit exceeded. content: application/json: schema: $ref: '#/components/schemas/ApiError' securitySchemes: ApiKeyAuth: type: http scheme: bearer bearerFormat: API key description: 'Send your API key as `Authorization: Bearer YOUR_API_KEY`.' ````