Heimster Telephony API

openapi: 3.2.0
info:
  title: Heimster Telephony API
  version: '2026-11-11'
  description: 'GENERATED FROM DOCUMENTATION by API Evangelist on 2026-11-11: 38 operation(s) read from 1 public documentation page(s) (each operation names its page in x-source). This is not the provider''s published contract; Heimster has published no machine-readable contract that the pipeline could find. Engine: local.'
  x-evidence-tiers:
    code-example: 1
    documentation: 37
    pages-with-code: 1
    pages-read: 1
  x-generated-from: documentation
  x-provenance: generated
  x-authored-by: API Evangelist
  x-generated: '2026-11-11'
  x-generator: generate-contract-from-docs.py
  x-engine: local
  x-sources:
  - https://heimster.ch/developers
security:
- bearer: []
tags:
- name: Telephony
paths:
  /api/v1/telephony/calls:
    post:
      operationId: post_api_v1_telephony_calls
      tags:
      - Telephony
      summary: Heimster API · Heimster
      x-source: https://heimster.ch/developers
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiV1TelephonyCallsRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostApiV1TelephonyCallsResponse'
      x-evidence:
        kind: documentation
  /api/v1/telephony/contacts:
    post:
      operationId: post_api_v1_telephony_contacts
      tags:
      - Telephony
      summary: Heimster API · Heimster
      x-source: https://heimster.ch/developers
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiV1TelephonyContactsRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostApiV1TelephonyContactsResponse'
      x-evidence:
        kind: documentation
  /api/v1/telephony/lookup:
    get:
      operationId: get_api_v1_telephony_lookup
      tags:
      - Telephony
      summary: Look up a caller
      x-source: https://heimster.ch/developers
      parameters:
      - name: number
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetApiV1TelephonyLookupResponse'
      x-evidence:
        kind: documentation
components:
  schemas:
    GetApiV1TelephonyLookupResponse:
      type: object
      properties:
        found:
          type: boolean
        number:
          type: string
        count:
          type: integer
        contact:
          type: object
        matches:
          type: array
        url:
          type: string
    PostApiV1TelephonyContactsResponse:
      type: object
      properties:
        found:
          type: boolean
        contact.id:
          type: string
        contact.firstName:
          type: string
        contact.lastName:
          type: string
        contact.name:
          type: string
        contact.company:
          type: string
        contact.email:
          type: string
        contact.phone:
          type: string
        contact.phoneE164:
          type: string
        contact.url:
          type: string
        contact.owner:
          type: object
        contact.entityType:
          type: string
        url:
          type: string
    PostApiV1TelephonyCallsResponse:
      type: object
      properties:
        activityId:
          type: string
        result:
          type: string
        contactId:
          type: string
        contactCreated:
          type: boolean
        agentId:
          type: string
        taskId:
          type: string
    PostApiV1TelephonyCallsRequest:
      type: object
      properties:
        callId:
          type: string
          description: The phone system's call id (idempotency key). Derived from agent + number + start when missing.
        number:
          type: string
          description: The external number.
        direction:
          type: string
          description: in | out (also inbound / outbound).
        status:
          type: string
          description: answered | missed.
        callType:
          type: string
          description: Alternatively 3CX's Inbound | Outbound | Missed | Notanswered.
        start:
          type: string
          description: 'Call start: ISO-8601 or epoch milliseconds (default now).'
        duration:
          type: string
          description: Talk time in seconds or hh:mm:ss.
        agentEmail:
          type: string
          description: E‑mail of the agent (a member of your organisation).
        agent:
          type: string
          description: Extension of the agent («Durchwahl»).
        contactId:
          type: string
          description: The contact, when already known (e.g. from the lookup).
        createContact:
          type: boolean
          description: Create a minimal contact for an unknown number (default false).
        name:
          type: string
          description: Caller name for a created contact.
        note:
          type: string
          description: Note stored with the call.
      required:
      - number
    PostApiV1TelephonyContactsRequest:
      type: object
      properties:
        number:
          type: string
          description: Phone number (number or email required).
        firstName:
          type: string
        lastName:
          type: string
        email:
          type: string
        company:
          type: string
        agentEmail:
          type: string
          description: Becomes the contact's owner when it is a member.
        agent:
          type: string
          description: Or the owner's extension.
      required:
      - number
  securitySchemes:
    bearer:
      type: http
      scheme: bearer