Famulor Phone Numbers API
Rufnummern suchen, kaufen, konfigurieren und freigeben.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/famulor-io:famulor-io-phone-numbers-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: Famulor Phone Numbers API
summary: REST API für AI-Assistenten, Anrufe, Konversationen, Leads und omnichannel Kundenkommunikation.
description: 'Die Famulor Produkt-API unter `https://app.famulor.de/api`. Damit steuerst du
AI-Assistenten, startest und liest Anrufe, verwaltest Leads und Kampagnen,
versendest SMS und WhatsApp-Nachrichten, pflegst Wissensdatenbanken und
automatisierst Prozesse.
## Authentifizierung
Alle Endpunkte erwarten einen API-Key als Bearer-Token:
```
Authorization: Bearer YOUR_API_KEY
```
Den Key erstellst du in deinem Account unter im
Bereich API-Keys. Der Key wird nur einmal angezeigt.
## Webhooks
Famulor sendet Ereignisse (Post-Call, Conversation Ended, Read Receipts) an
deine URL. Die Payloads stehen im Abschnitt `webhooks` dieser Spec.
Diese Datei wird aus der offiziellen Dokumentation generiert:'
version: 1.0.0
contact:
name: Famulor Support
email: sales@famulor.io
url: https://www.famulor.io/support
license:
name: Proprietary
url: https://www.famulor.io/terms
termsOfService: https://www.famulor.io/terms
servers:
- url: https://app.famulor.de/api
description: Production
security:
- BearerAuth: []
tags:
- name: Phone Numbers
description: Rufnummern suchen, kaufen, konfigurieren und freigeben.
paths:
/user/phone-numbers/{id}:
delete:
tags:
- Phone Numbers
summary: Release Phone Number
operationId: releasePhoneNumber
description: 'Releases a phone number and cancels its subscription
Docs
Gilt auch für: **Delete SIP Trunk** (Docs).'
externalDocs:
description: Release Phone Number
url: https://docs.famulor.io/api-v1/phone-numbers/release
parameters:
- name: id
in: path
required: true
description: The unique identifier of the phone number to release
schema:
type: integer
responses:
'200':
description: OK
content:
application/json:
examples:
subscription-cancelled:
summary: Subscription Cancelled
value:
message: Phone number released successfully. It will be removed at the end of the billing period.
immediately-deleted:
summary: Immediately Deleted
value:
message: Phone number deleted successfully.
schema:
type: object
properties:
message:
type: string
description: Success message indicating the release status
additionalProperties: true
'400':
description: Already Scheduled
content:
application/json:
example:
error: Phone number is already scheduled for release.
'401':
$ref: '#/components/responses/Unauthorized'
'404':
description: Not Found
content:
application/json:
example:
error: Phone number not found.
'422':
$ref: '#/components/responses/ValidationError'
'500':
description: Error
content:
application/json:
example:
error: Failed to release phone number. Please try again or contact support.
put:
tags:
- Phone Numbers
summary: Update Phone Number
operationId: updatePhoneNumber
description: 'Update a phone number''s nickname
Docs'
externalDocs:
description: Update Phone Number
url: https://docs.famulor.io/api-v1/phone-numbers/update
parameters:
- name: id
in: path
required: true
description: The unique identifier of the phone number to update
schema:
type: integer
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
nickname:
type: string
description: A short label for the phone number. Maximum 50 characters. Send `null` or an empty string to clear it.
responses:
'200':
description: Response
content:
application/json:
example:
message: Phone number updated successfully.
data:
id: 1
phone_number: '+14155551234'
nickname: Sales line
country_code: US
type: normal
schema:
type: object
properties:
message:
type: string
description: Success message
data:
type: object
description: The updated phone number
properties:
id:
type: integer
description: The unique identifier of the phone number
phone_number:
type: string
description: The phone number in E.164 format
nickname:
type: string
description: The phone number's nickname (or `null` if not set)
country_code:
type: string
description: The ISO 3166-1 alpha-2 country code
type:
type: string
description: 'The type of phone number: `normal`, `sip`, or `caller_id`'
additionalProperties: true
additionalProperties: true
'401':
$ref: '#/components/responses/Unauthorized'
'404':
description: Not Found
content:
application/json:
example:
error: Phone number not found.
'422':
description: Validation Error
content:
application/json:
example:
message: The nickname must not exceed 50 characters.
errors:
nickname:
- The nickname must not exceed 50 characters.
/user/phone-numbers/all:
get:
tags:
- Phone Numbers
summary: List Phone Numbers
operationId: listPhoneNumbers
description: 'Retrieves all phone numbers of the authenticated user
Docs'
externalDocs:
description: List Phone Numbers
url: https://docs.famulor.io/api-v1/phone-numbers/list
responses:
'200':
description: Success
content:
application/json:
example:
data:
- id: 1
phone_number: '+49155551234'
nickname: Sales line
country_code: DE
type: normal
type_label: Dedicated Number
sms_capable: true
region: us1
has_active_subscription: true
created_at: '2025-01-07T10:30:00.000000Z'
- id: 2
phone_number: '+442071234567'
nickname: null
country_code: GB
type: normal
type_label: Dedicated Number
sms_capable: false
region: us1
has_active_subscription: true
created_at: '2025-01-05T14:20:00.000000Z'
schema:
type: object
properties:
data:
type: array
description: Array of phone number objects
items:
type: object
properties:
id:
type: integer
description: The unique identifier of the phone number
phone_number:
type: string
description: The phone number in E.164 format (e.g. +49155551234)
nickname:
type:
- string
- 'null'
description: A short, human-friendly label for the number (or `null` if not set)
country_code:
type: string
description: The ISO 3166-1 alpha-2 country code (e.g. DE, GB, AU)
type:
type: string
description: 'The type of phone number: `normal`, `sip` or `caller_id`'
type_label:
type: string
description: Human-readable label for the phone number type
sms_capable:
type: boolean
description: Whether the phone number can send and receive SMS
region:
type: string
description: The region where the phone number was provisioned
has_active_subscription:
type: boolean
description: Whether the phone number has an active subscription
created_at:
type: string
description: ISO 8601 timestamp of when the phone number was purchased
additionalProperties: true
additionalProperties: true
'401':
$ref: '#/components/responses/Unauthorized'
'422':
$ref: '#/components/responses/ValidationError'
/user/phone-numbers/purchase:
post:
tags:
- Phone Numbers
summary: Purchase Phone Number
operationId: purchasePhoneNumber
description: 'Purchase a dedicated phone number in Famulor via API. Acquire local, mobile or toll-free numbers for inbound or outbound AI voice agent calls.
Docs'
externalDocs:
description: Purchase Phone Number
url: https://docs.famulor.io/api-v1/phone-numbers/purchase
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
phone_number:
type: string
description: The phone number to purchase in E.164 format (e.g. +14155551234). Must be a number returned by the Search endpoint.
required:
- phone_number
responses:
'201':
description: Created
content:
application/json:
example:
message: Phone number purchased successfully.
data:
id: 123
phone_number: '+14155551234'
country_code: US
type: normal
sms_capable: true
schema:
type: object
properties:
message:
type: string
description: Success message
data:
type: object
description: The details of the purchased phone number
properties:
id:
type: integer
description: The unique identifier of the phone number
phone_number:
type: string
description: The phone number in E.164 format
country_code:
type: string
description: The ISO country code
type:
type: string
description: The phone number type (always `normal` for purchased numbers)
sms_capable:
type: boolean
description: Whether the number supports SMS
additionalProperties: true
additionalProperties: true
'400':
description: Bad Request
content:
application/json:
examples:
already-in-use:
summary: Already In Use
value:
error: This phone number is already in use.
not-available:
summary: Not Available
value:
error: This phone number is not available for purchase. Please search for available numbers first.
'401':
$ref: '#/components/responses/Unauthorized'
'402':
description: Payment Required
content:
application/json:
examples:
no-payment-method:
summary: No Payment Method
value:
error: No payment method found. Please add a payment method to your account.
payment-failed:
summary: Payment Failed
value:
error: Payment failed. Please update your payment method.
'422':
description: Invalid Format
content:
application/json:
example:
error: Unable to parse phone number. Please provide a valid E.164 format number.
'500':
description: Provider Error
content:
application/json:
example:
error: Failed to purchase phone number from provider. Please contact support.
/user/phone-numbers/search:
get:
tags:
- Phone Numbers
summary: Search Available Phone Numbers
operationId: searchAvailablePhoneNumbers
description: 'Searches for available phone numbers that can be purchased
Docs'
externalDocs:
description: Search Available Phone Numbers
url: https://docs.famulor.io/api-v1/phone-numbers/search
parameters:
- name: country_code
in: query
required: false
description: The ISO 3166-1 alpha-2 country code to search in (e.g. DE, GB, AU, CA)
schema:
type: string
default: DE
- name: contains
in: query
required: false
description: Filters phone numbers containing specific digits (numeric characters only, maximum 10 digits)
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
examples:
success:
summary: Success
value:
data:
- phone_number: '+14155551234'
phone_number_formatted: +1 415-555-1234
country_code: US
price: 3.99
stripe_price_id: price_1PkA4dBXoZOzqQuAsvGvVJTZ
address_requirements: none
sms_capable: true
- phone_number: '+14155555678'
phone_number_formatted: +1 415-555-5678
country_code: US
price: 3.99
stripe_price_id: price_1PkA4dBXoZOzqQuAsvGvVJTZ
address_requirements: none
sms_capable: false
empty-response:
summary: Empty Response
value:
data: []
schema:
type: object
properties:
data:
type: array
description: Array of available phone numbers
items:
type: object
properties:
phone_number:
type: string
description: The phone number in E.164 format
phone_number_formatted:
type: string
description: The phone number formatted for display
country_code:
type: string
description: The ISO country code
price:
type: number
description: Monthly rental price in USD
stripe_price_id:
type: string
description: The Stripe price ID for billing
address_requirements:
type: string
description: 'Address requirements for this number: `none`, `local`, `foreign` or `inventory`'
sms_capable:
type: boolean
description: Whether the number supports SMS
additionalProperties: true
additionalProperties: true
'401':
$ref: '#/components/responses/Unauthorized'
'422':
$ref: '#/components/responses/ValidationError'
components:
responses:
ValidationError:
description: Die Anfrage ist inhaltlich ungültig.
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
example:
message: The given data was invalid.
errors:
phone_number:
- The phone number field is required.
Unauthorized:
description: Fehlender oder ungültiger API-Key.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
message: Unauthenticated.
schemas:
ValidationError:
type: object
properties:
message:
type: string
errors:
type: object
description: Feldname → Liste der Fehlermeldungen.
additionalProperties:
type: array
items:
type: string
Error:
type: object
properties:
message:
type: string
description: Menschenlesbare Fehlermeldung.
error:
type: string
description: Fehlerkennung, sofern gesetzt.
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: 'API-Key als Bearer-Token: `Authorization: Bearer YOUR_API_KEY`. Key erstellen unter https://app.famulor.de.'
externalDocs:
description: Famulor API-Dokumentation
url: https://docs.famulor.io/api-v1/introduction