Skip to content
Thirdlane

OpenAPI REST

Thirdlane REST API

Thirdlane provides a REST API with interactive documentation powered by Scalar. The API documentation is available at /apitest/openapi/ on your server, and from the Tools > OpenAPI REST menu item in Configuration Manager.

The API uses HTTP verbs and a RESTful endpoint structure. Request and response payloads are formatted as JSON. All API definitions follow the OpenAPI 3.1 specification.

What Can You Do with Thirdlane REST API

Thirdlane API allows you to create, update and delete configuration objects across 45+ endpoints, organized in two categories. The interactive reference always lists the exact, current set for your installation.

Platform Administration (global scope):

  • Organization (tenant) Management
  • Enterprise (multi-site) Management
  • Administrator Management
  • Reseller Management
  • Server and Location Management
  • DID and SIP Trunk Management
  • API Key, Webhook, and System Webhook Management

Tenant Configuration (tenant-scoped):

  • User Extensions and Dynamic Agent Management
  • Queue, Hunt Group, and Pickup Group Management
  • Inbound Routes, Outbound Routes, and Routing Condition Management
  • IVR / Voice Menu, Schedule, Feature Extension, and Office Mode Management
  • Special Endpoints and Special Mailbox Management
  • Conference Room, Company Directory, and Managed Device Management
  • Department, Emergency Location, and Tag Management
  • Click-to-Call Widget Management
  • Recordings (voice prompts), Connect Channels, Tenant Branding, and Messaging Channel Management
  • Outbound Webhook Management
  • CRM (contacts, accounts, leads, lists, custom fields, activities, tasks, campaigns, deals)
  • Migration Import (call recordings, voicemail, Music on Hold, bulk CDR)

How to Use the Interactive API Documentation

The API documentation interface provides a convenient way to explore and test the REST API.

Selecting a Tenant

For tenant-scoped operations, use the tenant selector at the top of the page to choose which tenant to work with. The selected tenant is automatically applied to all API paths.

Testing API Calls

Each endpoint includes a Test Request button that sends the request using your active Configuration Manager session. No additional authentication setup is needed when accessed from within the application.

API Categories

  • Platform Administration — Operations on global objects like tenants, servers, and administrators
  • Tenant Configuration — Operations on tenant-scoped objects like extensions, queues, and routes

How to Use Thirdlane REST API Programmatically

You can use Thirdlane REST API from applications written in any language capable of submitting HTTP requests and processing JSON. Here are examples using curl.

Authentication

API requests require authentication via Basic Authentication:

Terminal window
curl https://yourhost.yourdomain.com/api/tenants/ \
  --user username:password

Curl Example: List Tenants

This example lists all tenants the authenticated user has permission to access:

Terminal window
curl https://yourhost.yourdomain.com/api/tenants/ \
  -X GET --user username:password

Curl Example: Create a Tenant

This example creates a tenant “test1000” cloned from “thirdlane”:

Terminal window
curl https://yourhost.yourdomain.com/api/tenants/ \
  -X POST --user username:password \
  -H "Content-Type: application/json" \
  --data-binary '{
    "tenant": "test1000",
    "callerid": "14155551212",
    "emergency_callerid": "14155551313",
    "tenant_to_clone": "thirdlane",
    "tenant_limits": "1",
    "tenant_routes": "1",
    "tenant_schedules": "1",
    "tenant_menus": "1",
    "tenant_queues": "1",
    "tenant_voiceprompts": "1",
    "description": "Test tenant"
  }'

Curl Example: Create a User Extension

This example creates extension “201” for tenant “thirdlane”:

Terminal window
curl https://yourhost.yourdomain.com/api/tenants/thirdlane/extensions/ \
  -X POST --user username:password \
  -H "Content-Type: application/json" \
  --data-binary '{
    "name": "201",
    "protocol": "SIP",
    "last_name": "Last",
    "first_name": "First",
    "email": "[email protected]"
  }'

Curl Example: List Extensions for a Tenant

Terminal window
curl https://yourhost.yourdomain.com/api/tenants/thirdlane/extensions/ \
  -X GET --user username:password

Curl Example: Update an Extension

Terminal window
curl https://yourhost.yourdomain.com/api/tenants/thirdlane/extensions/201 \
  -X PUT --user username:password \
  -H "Content-Type: application/json" \
  --data-binary '{
    "callerid": "John Doe <201>",
    "email": "[email protected]"
  }'

Curl Example: Delete an Extension

Terminal window
curl https://yourhost.yourdomain.com/api/tenants/thirdlane/extensions/201 \
  -X DELETE --user username:password

Note: When using self-signed certificates, add --insecure to curl commands. Do not use this option in production environments.

Worked example: script tenant onboarding with an API key

This automates the same “onboard Acme” flow from the Tenants page, but from a shell script - and authenticates with an API key instead of an admin password, as recommended below.

1. Create an API key. In Configuration Manager go to Tools > API Keys (or POST /api/key/) and generate a key for your integration. Copy it once - you cannot read it back later. Then set it in your shell:

Terminal window
export TL_HOST=https://pbx.example.com
export TL_KEY=sk_live_xxxxxxxxxxxxxxxxxxxxxxxx

2. Create the tenant (cloned from your prototype tenant), passing the key in the X-API-Key header:

Terminal window
curl "$TL_HOST/api/tenants/" \
  -X POST -H "X-API-Key: $TL_KEY" \
  -H "Content-Type: application/json" \
  --data-binary '{
    "tenant": "acme",
    "callerid": "14155550100",
    "tenant_to_clone": "prototype",
    "tenant_menus": "1",
    "tenant_voiceprompts": "1",
    "description": "Acme Plumbing"
  }'

3. Add a user extension to the new tenant:

Terminal window
curl "$TL_HOST/api/tenants/acme/extensions/" \
  -X POST -H "X-API-Key: $TL_KEY" \
  -H "Content-Type: application/json" \
  --data-binary '{
    "name": "101",
    "protocol": "SIP",
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "[email protected]"
  }'

4. Verify by listing the tenant’s extensions. This endpoint supports pagination, so ask for a page and read the total-count header:

Terminal window
curl -i "$TL_HOST/api/tenants/acme/extensions/?limit=25&offset=0" \
  -X GET -H "X-API-Key: $TL_KEY"

The response body is the JSON array of extensions; the X-Total-Count response header tells you how many exist in total so you can loop over further pages. If the key is revoked in Tools > API Keys, every call above starts returning 401 immediately - with no impact on any human administrator’s login.

Importing historical data and media

Alongside the configuration endpoints above, a set of tenant-scoped import endpoints loads historical data and media into a tenant - call recordings, voicemail messages and greetings, Music on Hold, voice prompts, and bulk Call Detail Records (CDR). They are source-neutral and idempotent, which makes them useful both for migrating from another PBX and for one-off uploads. For example, to import a call recording with its metadata:

Terminal window
curl "$TL_HOST/api/tenants/acme/recordedcalls" \
  -X POST -H "X-API-Key: $TL_KEY" \
  -H "Content-Type: application/json" \
  --data-binary '{
    "audio_base64": "UklGR...",
    "when": "2026-05-01T14:03:00Z",
    "type": "extension",
    "src": "2025551234",
    "dst": "1001",
    "duration": 42,
    "external_id": "src-rec-55231"
  }'

See the Data Migration and Import guide for the full endpoint reference, timestamp and audio-format rules, reload batching, and a complete worked example.

Best practices

  • Prefer API keys over embedding a username and password. An API key can be scoped and revoked without changing an administrator’s login, and keeps admin credentials out of scripts and CI pipelines.
  • Always use HTTPS with a valid certificate in production. --insecure disables certificate verification and exposes credentials - use it only against a local test box with a self-signed cert.
  • Grant the least privilege that gets the job done. Authenticate as an account whose permissions match the task; a tenant-scoped integration does not need platform-administration rights.
  • Handle pagination and errors. List endpoints support limit/offset and return total-count headers; check HTTP status codes and the error field rather than assuming success.
  • Automate against the spec. Generate client code from the downloadable OpenAPI spec so your integration stays in step with field changes.