Overview
The Buluthat API lets you integrate your existing software (CRM, ERP, e-commerce, help desk) with your cloud PBX: click-to-call, call control, queue management, blocklist, audio files, auto call campaigns, voice assistant tasks and voice verification codes.
All endpoints are plain HTTP; responses are JSON. Use it from any language with an HTTP client.
Base address: https://api.buluthat.com/api/
Authentication
All endpoints the same the API key uses. The key in the panel Account and Support > API Keys from the page, generated by the account administrator; bt_ starts with and is shown only once, at the moment it is generated.
The key is sent in the header with every request:
Authorization: Bearer bt_xxxxxxxxAuthorization if the header cannot be set X-Api-Key: bt_xxxxxxxx is also accepted. The key in the URL (?key=) is disabled for new keys.
Each key is tied to a single customer account and accesses only that account's data. In the key scope is defined:
| Scope | Endpoints |
|---|---|
call | Call management, queues, agent statuses |
autocall | Auto call (for compatibility with older integrations it also opens the voice assistant, voice OTP and call endpoints) |
voicebot | Voice assistant |
voice_otp | Voice verification code |
sms | SMS API |
Out-of-scope request 403 scope_denied, modules closed on your account 403 module_disabled returns. To the key allowed IP list, expiry date and mandatory HMAC request signature can be defined; all API Security on the page.
Do not use your key on the browser side (JavaScript); always call from your own server. If you think it has leaked, choose "Renew key > Close the old one immediately" in the panel and the old one becomes invalid instantly.
Request format
- Read operations
GET, operations that changePOST(in audio filesPUT/DELETE). - POST body
application/jsonorapplication/x-www-form-urlencodedmay be. - Action on integration endpoints
actionis selected with the parameter (?action=create_campaign). - Timestamps are Turkish time (
2026-09-18 10:12:03). - Phone numbers
05xxxxxxxxx,5xxxxxxxxxor905xxxxxxxxxis accepted in the formats; it is returned normalized in responses.
Response format
Integration endpoints (autocall, voicebot, voice_otp) always return an envelope:
{ "ok": true, "data": { } }{ "ok": false, "error": "Kampanya bulunamadı.", "code": "campaign_not_found" }PBX endpoints (begin_call, queues, blocked_numbers…) speak with HTTP status codes: on success 200 OK and the result in the body (JSON array or plain text), on error 4xx and a Turkish error message in the body.
Error codes
| HTTP | code | Meaning |
|---|---|---|
| 400 | validation_failed | Field validation failed; the message explains the reason |
| 401 | missing_token / invalid_token / token_expired | The key is missing, invalid or expired |
| 401 | query_key_disabled / signature_* | The key came in the URL or the signature could not be verified (API Security) |
| 403 | module_disabled / scope_denied / ip_not_allowed | Module is off, scope is insufficient or the IP is not allowed |
| 404 | *_not_found | No such record or it belongs to another customer |
| 405 | method_not_allowed | GET received for an operation that requires POST |
| 422 | (endpoint-specific) | Business rule rejection: quota, duration, no line, etc. |
| 413 | payload_too_large | The request body exceeds 5 MB |
| 429 | rate_limited / ip_locked | Rate limit exceeded or the IP is temporarily locked due to too many failed attempts |
| 503 | db_unavailable | Temporary service issue; try again shortly |
Rate limits
| Limit | Default |
|---|---|
| Per key | 120 requests per minute (can be lowered in the key settings) |
| Total of all keys of the account | 600 requests per minute |
| Agent statuses | plus 2 requests per minute (prefer a webhook for live status) |
Auto call add_leads | 5.000 records in a single request |
In responses X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset headers arrive. On excess 429 Too Many Requests and Retry-After header is returned. In every response X-Request-Id share the value in support tickets.
Test environment
There is no separate sandbox; try it with a test extension and a small campaign in your account. Auto call campaigns status: "draft" create with and results/summary you can call the endpoints even without data. In the voice verification code, send to your own number; billing follows your package rules.
Version and changes
Endpoints are kept backward compatible; new fields are added, and the names and types of existing fields do not change. A field to be removed is announced in the panel and on this page at least 90 days in advance.
Help
If you get stuck during integration, open a ticket in the Support Center inside the panel under "Integration / API"; attach your sample request/response and we will look at it together.