> ## 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.

# Review a customer managed plan

> Requires live owner/admin membership in the calling credential’s reseller workspace. Existing managed agreements can still be reviewed and ended after Whitelabel entitlement ends; assigning or replacing a plan requires the entitlement. Operates only on that reseller’s customer workspaces, including when the acting user is a platform administrator. Returns the current assignment, available plans, included services, and credit funding requirements. Required scope: platform:read.



## OpenAPI

````yaml /api-reference/openapi.json get /platform/users/{user_id}/plan
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:
  /platform/users/{user_id}/plan:
    get:
      tags:
        - White Label
      summary: Review a customer managed plan
      description: >-
        Requires live owner/admin membership in the calling credential’s
        reseller workspace. Existing managed agreements can still be reviewed
        and ended after Whitelabel entitlement ends; assigning or replacing a
        plan requires the entitlement. Operates only on that reseller’s customer
        workspaces, including when the acting user is a platform administrator.
        Returns the current assignment, available plans, included services, and
        credit funding requirements. Required scope: platform:read.
      operationId: getPlatformUserPlan
      parameters:
        - name: user_id
          in: path
          required: true
          description: Customer user UUID.
          schema:
            type: string
            description: Customer user UUID.
            format: uuid
        - name: workspace_id
          in: query
          description: >-
            Customer workspace UUID. Required when the customer workspace cannot
            be selected unambiguously.
          schema:
            type: string
            description: Customer workspace UUID.
            format: uuid
      responses:
        '200':
          description: Managed plan overview.
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    $ref: '#/components/schemas/ManagedPlanOverview'
                additionalProperties: false
        '400':
          description: Invalid fields or an ambiguous customer workspace.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: >-
            Missing scope, API Access, Whitelabel entitlement, or live reseller
            owner/admin authority.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '404':
          description: Customer, workspace or plan not found within this reseller.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '409':
          description: >-
            Stale version, changed funding quote, conflicting request ID,
            unsupported plan, or an existing checkout subscription. Refresh the
            overview before submitting a new change.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          description: Plan management or its dependencies are temporarily unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      security:
        - bearerAuth: []
components:
  schemas:
    ManagedPlanOverview:
      type: object
      required:
        - workspace_id
        - workspace_name
        - wallet_credits
        - voice_credits_per_minute
        - customer_plan_credits
        - current
        - plans
        - blocked_reason
        - auto_topup
      properties:
        workspace_id:
          type: string
          description: Selected customer workspace.
          format: uuid
        workspace_name:
          type: string
          description: Selected customer workspace name.
        wallet_credits:
          type: number
          description: Available reseller funding balance in credits.
        voice_credits_per_minute:
          type: number
          description: Credits consumed per equivalent voice minute.
          exclusiveMinimum: 0
        customer_plan_credits:
          type: number
          description: Customer credits remaining from the managed plan.
          minimum: 0
        current:
          anyOf:
            - $ref: '#/components/schemas/ManagedPlanSummary'
            - type: 'null'
          description: Current managed plan, or null when none exists.
        plans:
          type: array
          items:
            $ref: '#/components/schemas/ManagedPlanOffer'
          description: >-
            Available and unavailable reseller offers with their funding
            details.
        blocked_reason:
          type:
            - string
            - 'null'
          description: Reason plan management is blocked, or null.
        auto_topup:
          type: object
          required:
            - enabled
            - has_saved_card
            - amount_cents
            - currency
            - decimal_digits
            - consent_token
          properties:
            enabled:
              type: boolean
              description: Whether reseller auto-top-up is enabled.
            has_saved_card:
              type: boolean
              description: Whether a usable saved card exists.
            amount_cents:
              type: number
              description: Configured auto-top-up charge in minor currency units.
              minimum: 0
            currency:
              type: string
              description: Currency of the configured top-up amount.
            decimal_digits:
              type: integer
              minimum: 0
              maximum: 4
              description: >-
                Decimal precision of the top-up currency. Divide amount_cents by
                10 to this power for the display amount.
            consent_token:
              type: string
              pattern: ^[a-f0-9]{64}$
              description: >-
                Opaque fingerprint of the displayed auto-top-up settings. Pass
                it as auto_topup_consent_token whenever shortage_policy is
                auto_topup, including when automatic top-up is already enabled.
            paused_reason:
              type:
                - string
                - 'null'
              enum:
                - card_declined
                - unpaid_invoice
                - null
              description: >-
                Why the reseller's automatic top-up is paused, or null.
                card_declined: switched off after declined card payments until a
                manual top-up, another card or switching it on again.
                unpaid_invoice: switched off because an invoice is unpaid, until
                it is switched on again.
          additionalProperties: false
      additionalProperties: false
    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.
    ManagedPlanSummary:
      type: object
      required:
        - plan_id
        - plan_name
        - version
        - billing_interval
        - monthly_credits
        - addon_credits
        - retail_price_cents
        - currency
        - period_start
        - period_end
        - next_refill_at
        - reserve_credits
        - refundable_credits
        - shortage_policy
        - ends_at
        - last_error
        - included_addons
      properties:
        plan_id:
          type: string
          description: Assigned plan identifier.
          format: uuid
        plan_name:
          type: string
          description: Assigned plan name.
        version:
          type: integer
          minimum: 1
          description: Concurrency version; pass this as expected_version for changes.
        billing_interval:
          type: string
          description: Funding interval.
          enum:
            - monthly
            - yearly
        monthly_credits:
          type: number
          description: Included monthly credit allowance.
          minimum: 0
        addon_credits:
          type: number
          description: Included-service funding for the current period in credits.
          minimum: 0
        retail_price_cents:
          type: number
          description: >-
            Customer-facing retail price for the funding period in hundredths of
            the displayed currency (divide by 100).
          minimum: 0
        currency:
          type: string
          description: Retail price currency.
        period_start:
          type: string
          description: Current funded period start.
          format: date-time
        period_end:
          type: string
          description: Current funded period end.
          format: date-time
        next_refill_at:
          type: string
          description: Next monthly allowance delivery date.
          format: date-time
        reserve_credits:
          type: number
          description: Credits reserved for future monthly allowances.
          minimum: 0
        refundable_credits:
          type: number
          description: >-
            Unused credits currently eligible to return to the reseller when
            changing or ending the plan.
          minimum: 0
        shortage_policy:
          type: string
          description: >-
            Renewal behavior when reseller funds are insufficient. Funding is
            retried hourly; if renewal stays unfunded for three days after the
            term ends, the managed plan ends, unused funded credits return to
            the reseller wallet and the customer falls back to the free plan.
          enum:
            - wait
            - auto_topup
        ends_at:
          type:
            - string
            - 'null'
          description: Optional scheduled end; null means no end date.
          format: date-time
        last_error:
          type:
            - string
            - 'null'
          description: Most recent actionable renewal issue, or null.
        included_addons:
          type: array
          description: >-
            Included services retained from the funded agreement, independent of
            subsequent catalog changes.
          items:
            type: object
            required:
              - name
              - quantity
            properties:
              name:
                type: string
                description: Included service name.
              quantity:
                type: number
                description: Included quantity.
                minimum: 0
            additionalProperties: false
      additionalProperties: false
    ManagedPlanOffer:
      type: object
      required:
        - id
        - name
        - is_active
        - currency
        - price_monthly_cents
        - price_yearly_cents
        - monthly_credits
        - included_minutes
        - extra_minute_cost_cents
        - monthly_addon_credits
        - yearly_addon_credits
        - included_addons
        - limits
        - unavailable_reason
        - monthly_quote_token
        - yearly_quote_token
      properties:
        id:
          type: string
          description: Plan identifier.
          format: uuid
        name:
          type: string
          description: Plan name.
        is_active:
          type: boolean
          description: >-
            Whether this offer is visible to customers for self-service
            purchase; hidden offers can still be managed.
        currency:
          type: string
          description: Currency of the customer-facing retail prices.
        price_monthly_cents:
          type: number
          description: >-
            Customer-facing monthly retail price in hundredths of the displayed
            currency (divide by 100).
          minimum: 0
        price_yearly_cents:
          type:
            - number
            - 'null'
          description: >-
            Customer-facing yearly retail price in hundredths of the displayed
            currency (divide by 100); null when yearly billing is unavailable.
          minimum: 0
        monthly_credits:
          type: number
          description: Included credit allowance delivered each month.
          minimum: 0
        included_minutes:
          type: number
          description: >-
            Equivalent included voice minutes at the displayed credit
            conversion.
          minimum: 0
        extra_minute_cost_cents:
          type: number
          description: >-
            Customer-facing additional minute price in hundredths of the
            displayed currency (divide by 100).
          minimum: 0
        monthly_addon_credits:
          type: number
          description: Credits needed to fund included services for a monthly period.
          minimum: 0
        yearly_addon_credits:
          type:
            - number
            - 'null'
          description: >-
            Credits needed to fund included services for a yearly period; null
            when unavailable.
          minimum: 0
        included_addons:
          type: array
          description: Services and capacity included in this offer.
          items:
            type: object
            required:
              - name
              - quantity
            properties:
              name:
                type: string
                description: Included service name.
              quantity:
                type: number
                description: Included quantity.
                minimum: 0
            additionalProperties: false
        limits:
          type: object
          description: >-
            Plan limits and included feature access. A numeric limit of -1 means
            unlimited; 0 means unavailable.
          additionalProperties:
            type:
              - number
              - boolean
        unavailable_reason:
          type:
            - string
            - 'null'
          description: Reason this offer cannot currently be assigned, or null.
        monthly_quote_token:
          type:
            - string
            - 'null'
          pattern: ^[a-f0-9]{64}$
          description: >-
            Opaque acceptance token for the reviewed monthly offer. Pass as
            quote_token when assigning this interval; null when unavailable.
        yearly_quote_token:
          type:
            - string
            - 'null'
          pattern: ^[a-f0-9]{64}$
          description: >-
            Opaque acceptance token for the reviewed yearly offer. Pass as
            quote_token when assigning this interval; null when unavailable.
      additionalProperties: false
  responses:
    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.
    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.