> ## Documentation Index
> Fetch the complete documentation index at: https://docs.famulor.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect an integration

> Connect an account of a native integration (a booking, shop or property system) as an agent tool. Pass the integration id in the path and the connection values that integration asks for in `fields`, for example an account id and an API key. The credentials are checked at the vendor before the tool is created. The tool starts with the read operations enabled; write operations such as bookings and orders stay off until you enable them by updating the tool. Access details such as Wi-Fi and door codes follow the sharing settings of the connection and stay behind a second check of the caller. Secret values are never returned. Unknown integration ids answer 404 and list the available ones. An integration that is not enabled for your platform answers 403. Required scope: assistants:write. Requires an admin-level credential.



## OpenAPI

````yaml /api-reference/openapi.json post /tools/integrations/{provider}
openapi: 3.1.0
info:
  title: Famulor API
  version: 1.0.0
  description: >-
    REST API for Famulor. Authenticate with an API key (`fam_...`, created under
    **Settings → API Keys**) or an OAuth 2.0 access token (`fam_at_...`) as a
    Bearer token.


    Every response uses a consistent envelope: `{ "data": ... , "meta": { ... }
    }` on success and `{ "error": { "code", "message" } }` on failure. List
    endpoints paginate with `?limit=` (default 50, max 200) and `?offset=`;
    `meta.pagination.total` carries the total match count.


    REST operations require API Access through the workspace plan or a recurring
    add-on. Without it, regular operations return `403 api_access_required`. The
    invoice-payment and billing-portal operations remain available with a valid
    `billing:write` credential after a failed plan payment so an authorized
    owner, admin, or billing member can recover billing.


    The same customer-facing capabilities are available as MCP tools at
    `https://app.famulor.io/mcp` (Model Context Protocol, streamable HTTP) using
    the same credentials, scopes, and workspace access. MCP availability is
    controlled separately by Connect AI / MCP, not by API Access.
servers:
  - url: https://app.famulor.io/api/v1
    description: Hosted platform.
  - url: https://{domain}/api/v1
    description: White-label tenant domain — same paths, tenant branding.
    variables:
      domain:
        default: app.famulor.io
        description: Your white-label tenant domain.
security:
  - bearerAuth: []
tags:
  - name: Account
    description: Self-inspection of the calling credential.
  - name: Migrations
    description: Preview and import data from supported legacy platforms.
  - name: Assistants
    description: Create and manage voice assistants.
  - name: Tools
    description: >-
      Reusable tools (HTTP APIs, external MCP servers and actions of connected
      apps) assistants can call mid-conversation.
  - name: Voices
    description: Browse the text-to-speech voice library.
  - name: Calls
    description: Start outbound calls and read call history, transcripts and recordings.
  - name: History
    description: Unified conversation history across calls, messaging and assistant emails.
  - name: Campaigns
    description: Outbound calling campaigns with a compliant power dialer.
  - name: Leads
    description: Manage Audience contacts across campaigns, channels and Call QA metrics.
  - name: Segments
    description: >-
      Saved, dynamic lead filters — reusable audience definitions used for
      Audience search and campaign lead assignment.
  - name: Suppression
    description: Cross-channel marketing opt-outs and active workspace suppression records.
  - name: Callbacks
    description: >-
      Scheduled callbacks booked by the Schedule callback tool across voice,
      chat, and email.
  - name: Phone Numbers
    description: Marketplace numbers and customer-provided numbers.
  - name: Famulor Loop
    description: >-
      Personal business-phone access, directory, presence, devices, and Loop
      call recents.
  - name: SIP Trunks
    description: Bring your own SIP provider and numbers.
  - name: Carrier Connections
    description: Connect a supported carrier account and import its existing phone numbers.
  - name: Knowledge Bases
    description: RAG knowledge bases and documents for assistants.
  - name: Settings
    description: Workspace-level settings such as caller-memory defaults.
  - name: Billing
    description: Balance and transaction ledger of the API key's workspace.
  - name: Automations
    description: >-
      Native workspace automations — list, create, update, trigger. Requires
      Automations in the workspace plan.
  - name: Milian Missions
    description: Recurring jobs that Milian runs unattended on schedule.
  - name: Integrations
    description: >-
      Calendar integrations (Cal.com, Calendly, Acuity Scheduling, Google
      Calendar, Outlook, native booking engine). Assign them to assistants to
      provide availability and booking tools, plus provider-supported
      appointment lookup, cancellation, and rescheduling.
  - name: Bookings
    description: >-
      Native booking engine — event types with weekly availability, public
      booking pages at /book/{workspace}/{slug}, and the bookings they produce.
  - name: Dashboards
    description: >-
      Custom analytics dashboards, reusable widgets, and tenant-scoped
      performance analytics. Requires Custom dashboards in the workspace plan.
  - name: Catalog
    description: >-
      Read-only platform catalogs — available models, supported assistant
      languages, and prompt templates.
  - name: Simulations
    description: Assistant simulation tests (plan-gated).
  - name: Versions
    description: Assistant configuration version history.
  - name: Caller IDs
    description: Outbound caller ID verification.
  - name: Widgets
    description: Web widget connectors.
  - name: Messaging
    description: >-
      Telegram, Slack, and Messenger text bots linked to assistants (Chat SDK).
      Includes conversation delay, inactivity end, and conversation-ended
      webhooks.
  - name: QA
    description: Cohort AI Quality Assurance runs over call transcripts.
  - name: White Label
    description: >-
      Manage white-label customer accounts, defaults, credit transfers and
      customer plan offers. Each endpoint documents its required scope and
      workspace eligibility.
  - name: API Keys
    description: >-
      Self-service API keys for the calling workspace or a same-brand workspace
      where the credential's user is owner/admin. A key can only mint further
      keys with a scope subset of its own.
  - name: Workspaces
    description: >-
      List visible workspaces, create an additional workspace for the key owner,
      and mint a dedicated credential for a selected owner/admin workspace.
  - name: SMS
    description: Outbound SMS from workspace phone numbers.
  - name: Milian
    description: >-
      Ask Milian, the AI co-worker in your workspace, and start voice sessions
      with it.
  - name: Translation
    description: >-
      Live translation sessions that interpret a conversation between two
      languages.
  - name: Shopify
    description: Native Shopify app store connections, assistant tools and activity.
  - name: Avatars
    description: Private custom avatars and widget avatar selection.
  - name: Webhook Subscriptions
    description: >-
      Signed workspace event subscriptions, independent of existing
      destinations.
paths:
  /tools/integrations/{provider}:
    post:
      tags:
        - Tools
      summary: Connect an integration
      description: >-
        Connect an account of a native integration (a booking, shop or property
        system) as an agent tool. Pass the integration id in the path and the
        connection values that integration asks for in `fields`, for example an
        account id and an API key. The credentials are checked at the vendor
        before the tool is created. The tool starts with the read operations
        enabled; write operations such as bookings and orders stay off until you
        enable them by updating the tool. Access details such as Wi-Fi and door
        codes follow the sharing settings of the connection and stay behind a
        second check of the caller. Secret values are never returned. Unknown
        integration ids answer 404 and list the available ones. An integration
        that is not enabled for your platform answers 403. Required scope:
        assistants:write. Requires an admin-level credential.
      operationId: connectIntegration
      parameters:
        - name: provider
          in: path
          required: true
          schema:
            type: string
            pattern: ^[a-z][a-z0-9_]{1,23}$
          description: >-
            Integration id in lower case, for example hostaway. The
            documentation page of each integration names its id.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - fields
              properties:
                fields:
                  type: object
                  additionalProperties:
                    type: string
                  description: >-
                    Connection values by field key. Which keys an integration
                    takes is listed on its documentation page. Secret values
                    (API keys, secrets) are never returned.
                name:
                  type: string
                  description: >-
                    Unique tool name, using letters, numbers and underscores.
                    Defaults to the integration id.
                caller_recognition:
                  type: boolean
                  description: >-
                    Look the caller up in the connected system before the
                    conversation, so the assistant can greet them by name.
                    Defaults to true for integrations that can recognise
                    callers; `true` is rejected for integrations that cannot.
                    Voice calls use the caller's number; WhatsApp and SMS
                    conversations use the contact's number; email uses a
                    verified sender address.
      responses:
        '201':
          description: Created. Secret values are masked.
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    $ref: '#/components/schemas/UserTool'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  schemas:
    UserTool:
      type: object
      description: >-
        A reusable tool of the account. Secret values inside `config` (auth
        values, header values, Browser Use login password and authenticator key)
        are always masked as `•••`.
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
          description: >-
            Tool name — doubles as the LLM function name (letters, digits, `_`,
            `-`).
        description:
          type: string
          description: Human/LLM-readable description of what the tool does.
        type:
          type: string
          enum:
            - mcp
            - api
            - builtin
          description: >-
            `api` = HTTP API tool, `mcp` = external MCP server, `builtin` =
            built-in capability (call transfer, warm call transfer, end call,
            DTMF, keypad collection, Cal.com scheduling, assistant transfer).
        config:
          type: object
          description: >-
            Type-specific configuration (URL, method, parameters, auth). Secret
            values are masked.
        is_active:
          type: boolean
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        nativeIntegration:
          type: string
          enum:
            - shopify
          readOnly: true
          description: >-
            Verified native integration owning this tool; present only for
            native Shopify tools.
        app_action:
          oneOf:
            - $ref: '#/components/schemas/AppActionToolSummary'
            - type: 'null'
          readOnly: true
          description: >-
            The app action this tool runs; null for other tools. Change an app
            action tool with `PATCH /tools/app-actions/{toolId}`; `PATCH
            /tools/{id}` only changes its name and whether it is active.
    AppActionToolSummary:
      type: object
      description: The app action behind a tool.
      required:
        - app
        - app_name
        - action
        - action_name
        - connection_id
        - risk
        - confirmation
        - status
        - update_available
      properties:
        app:
          type: string
          description: App ID.
        app_name:
          type: string
        action:
          type: string
          description: Action ID.
        action_name:
          type: string
        connection_id:
          type: string
          format: uuid
        risk:
          $ref: '#/components/schemas/AppActionRisk'
        confirmation:
          type: string
          enum:
            - ask_first
            - none
          description: >-
            Whether the assistant asks the customer before an action changes
            data.
        status:
          type: string
          enum:
            - ok
            - needs_attention
          description: >-
            `needs_attention`: the connection must be reconnected or the action
            changed. The tool does not run until it is fixed.
        update_available:
          type: boolean
          description: >-
            A newer version of the action exists. The tool keeps using its saved
            version.
    ErrorEnvelope:
      type: object
      description: Error envelope returned by every /api/v1 endpoint on failure.
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              enum:
                - unauthorized
                - forbidden
                - api_access_required
                - not_found
                - invalid_request
                - rate_limited
                - conflict
                - telephony_configuration_error
                - telephony_unavailable
                - destination_forbidden
                - internal_error
                - service_unavailable
                - verification_address_required
                - bundle_address_missing
              description: >-
                Stable, machine-readable error code. `service_unavailable` is
                returned by POST /bookings and GET
                /booking-event-types/{id}/slots specifically when the
                availability engine could not be reached (see
                AvailabilityOrProtectionUnavailable).
                `verification_address_required` and `bundle_address_missing` are
                returned by POST /phone-numbers when the verification behind the
                number has no address (see the operation description).
            message:
              type: string
              description: Human-readable description of the error.
            reason:
              type: string
              description: >-
                Optional, more specific and stable reason for this error, for
                example `plan_required`, `read_only_role` or `missing_scope`.
                Branch on `code` first: `reason` is only present on some errors,
                and new values may be added. Campaign operations use
                `attestation_required` (400, `compliance_attestation` missing on
                launch), `launch_required` (400, a sequence campaign was never
                launched; launch it or start it with `compliance_attestation`),
                `sequence_changed` (409, the sequence changed after
                `sequence_hash` was taken), `campaign_sequences_unavailable`
                (403, the plan does not include Campaign sequences),
                `campaign_extension_unavailable` (503 `service_unavailable`, the
                campaign feature is not available yet) and `analytics_timeout`
                (504 `service_unavailable`, the campaign analytics took too
                long; choose a shorter period).
            hint:
              type: string
              description: >-
                Optional recovery advice that is safe to show to the end user,
                for example which settings page to open.
    AppActionRisk:
      type: string
      enum:
        - read
        - write
        - destructive
      description: >-
        What the action does in the app: `read` only reads, `write` changes
        data, `destructive` deletes data. Actions that delete data cannot be
        used as tools yet.
  responses:
    BadRequest:
      description: Invalid request body or parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          example:
            error:
              code: invalid_request
              message: '"to_number" is required (E.164 format, e.g. +4930123456).'
    Unauthorized:
      description: Missing, invalid, expired or revoked API key / access token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          example:
            error:
              code: unauthorized
              message: Invalid API key.
    Forbidden:
      description: >-
        The credential lacks the required scope or role, or the workspace does
        not have the required capability.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          examples:
            scopeDenied:
              summary: Required scope is missing
              value:
                error:
                  code: forbidden
                  message: >-
                    This API key is missing the required scope
                    "assistants:write".
            apiAccessRequired:
              summary: API Access is not available
              value:
                error:
                  code: api_access_required
                  message: >-
                    API Access is not available for this workspace. Review
                    Settings → Plan.
    NotFound:
      description: Resource not found (or it belongs to another workspace).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          example:
            error:
              code: not_found
              message: Assistant not found
    RateLimited:
      description: Too many requests. Retry after the indicated delay.
      headers:
        Retry-After:
          description: Seconds to wait before retrying.
          schema:
            type: integer
            minimum: 1
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          example:
            error:
              code: rate_limited
              message: Too many requests. Retry after the indicated delay.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
      description: >-
        API key (`fam_...`, created under **Settings → API Keys**) or an OAuth
        2.0 access token (`fam_at_...`). REST operations also require API Access
        for the credential's workspace. Keys can be restricted to scopes such as
        `assistants:read`, `calls:write`, `campaigns:write`, `automations:read`,
        `dashboards:read`, `dashboards:write`, `leads:write`, `segments:write`,
        `loop:read`, `loop:write`, `phone_numbers:write`, `sip_trunks:write`,
        `knowledge:write`, `voices:read`, `billing:read`, `billing:write`,
        `settings:write`, `platform:read`, `platform:write`; a `*:write` scope
        implies the matching `*:read`. Automation and dashboard endpoints also
        accept the legacy `calls:*` scope. Keys without scope restrictions have
        full access within the workspace's available capabilities.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.