API access

VoiceBooker provides programmatic API access for integrating with other applications and automating workflows such as usage retrieval, bot deployment, and CI/CD pipeline integration.

Base URL

For the VoiceBooker production instance, use:

https://voicebooker.de/app/api/v1

Authentication

Create an API token for the business in VoiceBooker and send it with every request. The API accepts either of these headers:

Authorization: Bearer <your-api-token>

or:

X-API-Token: <your-api-token>

Keep the token private. It determines the business context for the request; the endpoints do not accept an arbitrary business ID to establish access.

Export a bot

GET /exportBots/{botId} exports a bot that belongs to the business associated with the API token. The response contains the bot definition and its stages and can be used as input for /importBots.

Optional query parameters:

pretty=true returns a human-readable HJSON document.
nt=true returns the nested-text representation.

curl --get 'https://voicebooker.de/app/api/v1/exportBots/<bot-id>' \
  --header 'Authorization: Bearer <your-api-token>' \
  --data-urlencode 'pretty=true'

Example response:

{
  "name": "Reception assistant",
  "id": "kqrmxaveli",
  "stages": [
    {
      "name": "Welcome",
      "id": "mavotirenu",
      "linkId": "qeluzanopi",
      "template": false,
      "prompt": "Welcome the caller.",
      "tools": [],
      "functions": [],
      "settings": {},
      "stageConfig": [],
      "x": 0,
      "y": 0,
      "order": 0,
      "instanceSettings": {}
    }
  ],
  "settings": {},
  "wizard": {}
}

POST /importBots imports a bot definition into the business associated with the API token. Send the exported object as the contents parameter. JSON objects can be sent directly; HJSON content can be sent by setting filename to a name ending in .hjson.

The optional flags are:

overwriteBotStages=true replaces the existing bot with the same name.
overwriteTemplates=true imports template stages instead of reusing existing templates.
replaceBotStages=true updates the bot identified by the exported id rather than creating a new bot.

curl --request POST \
  --url https://voicebooker.de/app/api/v1/importBots \
  --header 'Authorization: Bearer <your-api-token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "filename": "reception-assistant.json",
    "contents": {"name": "Reception assistant", "settings": {}, "stages": []},
    "overwriteBotStages": false,
    "overwriteTemplates": false,
    "replaceBotStages": false
  }'

Example response:

{
  "id": "vexorimaku",
  "name": "Reception assistant",
  "settings": {},
  "invisible": false
}

Place outbound calls

You can place an outbound call by sending a POST request to:

https://voicebooker.de/app/api/v1/makeCall

Use the following headers:

Content-Type: application/json
Token: <your-api-token>

Example request:

{
  "dest": "+49-351-123456789",
  "botId": "kqrmxaveli",
  "sipAccountId": "lupenakori",
  "ringTimeout": 25,
  "startTimeout": 10,
  "state": {
    "customerId": "zpjwletodo"
  }
}

Parameter	Description
`dest`	Number to call in E.164 format.
`botId`	Bot used for the call.
`sipAccountId`	SIP account used to place the call. Its number is shown to the callee.
`ringTimeout`	Seconds to ring before cancelling when nobody answers. Default: 30 seconds.
`startTimeout`	Seconds to wait before the bot starts speaking, allowing the callee to speak first.
`state`	Data that can be passed to webhooks or API calls during the call, such as a customer ID.

The REST API returns a callId, which can be used with webhooks triggered when the call succeeds or fails:

{
  "callId": "xavurimeto"
}

Retrieve usage

GET /usage returns call and chat session usage for the authenticated business and its available partner businesses.

Without a businessId, the response contains usage for all businesses in that scope. Use businessId to retrieve usage for one business, and use start and end to filter by the session creation time.

curl --get https://voicebooker.de/app/api/v1/usage \
  --header 'X-API-Token: <your-api-token>' \
  --data-urlencode 'businessId=zpjwletodo' \
  --data-urlencode 'start=2026-01-01T00:00:00Z' \
  --data-urlencode 'end=2026-02-01T00:00:00Z'

start is inclusive and end is inclusive. Date-time values should be parseable ISO 8601 values. The businessId must be returned by /partnerClients or belong to the authenticated business; using a business outside the token's scope returns 403 Forbidden.

Each usage item contains:

Field	Type	Description
`id`	string	Call-session ID.
`businessId`	string	Business ID.
`botId`	string	Bot ID.
`isCall`	boolean	`true` for a phone call, `false` for another session type.
`direction`	string	`inbound` or `outbound`.
`phoneNumberCaller`	string	Caller number, when available.
`phoneNumberCallee`	string	Called number, when available.
`duration`	integer	Session duration in seconds. Returns `0` when no call detail duration is available.
`costs`	number	Recorded session cost.
`start`	string	Session creation timestamp, returned as a JSON date-time value.

Example response:

[
  {
    "id": "xavurimeto",
    "businessId": "zpjwletodo",
    "botId": "kqrmxaveli",
    "isCall": true,
    "direction": "inbound",
    "phoneNumberCaller": "+491701234567",
    "phoneNumberCallee": "+49301234567",
    "duration": 184,
    "costs": 0.46,
    "start": "2026-01-15T10:30:00.000Z"
  }
]

List partner businesses

For reseller and partner integrations, GET /partnerClients returns the visible businesses connected to the authenticated partner business. The returned business IDs can be passed to the businessId filter on the usage endpoint.

curl --request GET \
  --url https://voicebooker.de/app/api/v1/partnerClients \
  --header 'Authorization: Bearer <your-api-token>'

The response is an array of business objects.

Example response:

[
  {
    "id": "zpjwletodo",
    "name": "Example Partner Business",
    "city": "Berlin",
    "country": "DE"
  }
]

OpenAPI specification

The following OpenAPI 3.1 document describes these APIs. For bot, usage, and partner endpoints, bearerAuth and apiToken are alternatives. The outbound-call endpoint uses the Token header.

openapi: 3.1.0
info:
  title: VoiceBooker Partner API
  version: 1.0.0
  description: Retrieve partner businesses and usage for the business associated with an API token.
servers:
  - url: https://voicebooker.de/app/api/v1
    description: VoiceBooker production API
tags:
  - name: Partner access
    description: APIs for partner and reseller integrations.
paths:
  /exportBots/{botId}:
    get:
      tags: [Partner access]
      operationId: exportBot
      summary: Export a bot
      description: Exports a bot belonging to the business associated with the API token.
      security:
        - bearerAuth: []
        - apiToken: []
      parameters:
        - name: botId
          in: path
          required: true
          description: Bot ID to export.
          schema: {type: string}
        - name: pretty
          in: query
          schema: {type: boolean, default: false}
        - name: nt
          in: query
          schema: {type: boolean, default: false}
      responses:
        '200':
          description: Exported bot definition.
          content:
            application/json:
              schema: {$ref: '#/components/schemas/BotExport'}
        '401': {$ref: '#/components/responses/Unauthorized'}
        '403': {description: The bot does not belong to the business associated with the token.}
  /importBots:
    post:
      tags: [Partner access]
      operationId: importBot
      summary: Import a bot
      description: Imports a bot definition into the business associated with the API token.
      security:
        - bearerAuth: []
        - apiToken: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [contents]
              properties:
                filename: {type: string}
                contents: {oneOf: [{type: object}, {type: string}]}
                overwriteBotStages: {type: boolean, default: false}
                overwriteTemplates: {type: boolean, default: false}
                replaceBotStages: {type: boolean, default: false}
      responses:
        '200':
          description: Imported bot.
          content:
            application/json:
              schema: {type: object, properties: {id: {type: string}, name: {type: string}}}
        '401': {$ref: '#/components/responses/Unauthorized'}
  /makeCall:
    post:
      tags: [Partner access]
      operationId: makeOutboundCall
      summary: Place an outbound call
      description: Starts an outbound call using the selected bot and SIP account.
      security:
        - tokenAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [dest, botId, sipAccountId]
              properties:
                dest: {type: string, description: Destination number in E.164 format.}
                botId: {type: string}
                sipAccountId: {type: string}
                ringTimeout: {type: integer, default: 30}
                startTimeout: {type: integer, default: 0}
                state: {type: object, additionalProperties: true}
      responses:
        '200':
          description: Outbound call started.
          content:
            application/json:
              schema: {type: object, properties: {callId: {type: string}}}
        '401': {$ref: '#/components/responses/Unauthorized'}
  /usage:
    get:
      tags: [Partner access]
      operationId: listUsage
      summary: Retrieve usage
      description: Returns usage for the authenticated business and its available partner businesses, optionally filtered to one business and a date range.
      security:
        - bearerAuth: []
        - apiToken: []
      parameters:
        - name: businessId
          in: query
          required: false
          description: Business ID. It must be the authenticated business or an available partner business.
          schema:
            type: string
        - name: start
          in: query
          required: false
          description: Inclusive lower bound for the session creation timestamp.
          schema:
            type: string
            format: date-time
        - name: end
          in: query
          required: false
          description: Inclusive upper bound for the session creation timestamp.
          schema:
            type: string
            format: date-time
      responses:
        '200':
          description: Usage records.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UsageRecord'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: The requested business is outside the token's scope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /partnerClients:
    get:
      tags: [Partner access]
      operationId: listPartnerClients
      summary: List partner businesses
      description: Returns visible businesses connected to the business associated with the API token.
      security:
        - bearerAuth: []
        - apiToken: []
      responses:
        '200':
          description: A list of partner businesses.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PartnerBusiness'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  securitySchemes:
    tokenAuth:
      type: apiKey
      in: header
      name: Token
      description: Send the API token in `Token: <token>`.
    bearerAuth:
      type: http
      scheme: bearer
      description: Send the API token in `Authorization: Bearer <token>`.
    apiToken:
      type: apiKey
      in: header
      name: X-API-Token
      description: Send the API token in `X-API-Token: <token>`.
  schemas:
    BotExport:
      type: object
      properties:
        name: {type: string}
        id: {type: string}
        stages: {type: array, items: {type: object}}
        settings: {type: object}
        wizard: {type: object}
    PartnerBusiness:
      type: object
      description: Business data returned by the partner-business endpoint. Additional fields may be returned as the business model evolves.
      additionalProperties: true
      properties:
        id:
          type: string
          description: Business ID.
        name:
          type: string
    UsageRecord:
      type: object
      required: [id, businessId, botId, isCall, direction, duration, costs, start]
      properties:
        id: {type: string, description: Call-session ID.}
        businessId: {type: string, description: Business ID.}
        botId: {type: string, nullable: true, description: Bot ID.}
        isCall: {type: boolean}
        direction: {type: string, enum: [inbound, outbound]}
        phoneNumberCaller: {type: string, nullable: true}
        phoneNumberCallee: {type: string, nullable: true}
        duration: {type: integer, minimum: 0, description: Duration in seconds.}
        costs: {type: number, format: double}
        start: {type: string, format: date-time}
    Error:
      type: object
      properties:
        error:
          type: string
          example: Invalid businessId
  responses:
    Unauthorized:
      description: The API token is missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

HTTP errors

401 Unauthorized: the API token is missing or does not match an API key.
403 Forbidden: the requested businessId is not the authenticated business or an available partner business.

API access

On this page