> ## 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 and external MCP servers) 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. 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. 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 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). message: type: string description: Human-readable description of the error. 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. 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.