Partner API.

The Partner API is for integration partners — software platforms that embed the KlevaDesk AI receptionist for the businesses they serve, in any vertical. It is a wholesale surface: you own the customer — the relationship, the billing, and the UI they see — and KlevaDesk is the receptionist engine behind your platform. One partner key provisions and manages many business locations: your platform sends the business profile, configuration, and onboarding data in a single enable call, and a receptionist starts answering without anyone typing anything into KlevaDesk by hand.

A note on the word: partner on this page means an integration partner. It is unrelated to the term "partner business" used in our Privacy Policy and Terms, which refers to an individual business using KlevaDesk directly.

Shape of the integration

• One partner, many businesses. Your platform holds one partner API key; every call names the business location by your own durable id. The mechanics are the same in every vertical.
• Plain HTTPS + JSON, request/response. No JSON-RPC, and no webhooks from KlevaDesk to your platform in v1 — you poll for state changes.
• The enable call is the whole onboarding. It carries the business profile, the configuration block, and onboarding data (services, staff, pricing, policy text) in one request.
• Wholesale, partner-billed. Businesses provisioned through this API never see a card form, trial banner, or checkout in KlevaDesk; plan UI points back to your platform, and they are visibly labeled as provided through the partner.
• Config ownership. Your platform writes configuration at enable time and again only through an explicit resync. After enable, the KlevaDesk app is the source of truth for tuning; a resync never silently overwrites fields the business has since changed in KlevaDesk.

Base URL: https://app.klevadesk.com/api/partner/v1 (sandbox: same host, sandbox partner key). All timestamps are RFC 3339 UTC. All bodies are JSON.

What the API does

• Provision a business onto KlevaDesk. One enable call creates (or attaches to) a KlevaDesk organization and starts acquiring a phone number for it. If the enabling owner already has a direct KlevaDesk account, nothing is taken over silently — the owner confirms the attach while signed in to KlevaDesk; asserting an email is never enough.
• Lifecycle management. Each business you provision moves through a small set of states — pending while KlevaDesk sets up the number and messaging registration, live once the receptionist is fully working (billing starts here), suspended when you pause service (calls ring the business's transfer chain, data and number kept), and deprovisioned when you remove it (a quarantine window allows full restore; after it, the number is released and the business's data is deleted, and deletion is confirmed on the status object). Any state can branch to action_required — something needs a decision or information; the status object says what, and who acts. A business in action_required keeps whatever was already working: the state describes what needs attention, not an outage.
• Runtime controls. Two controls mirror what the business's owner has inside KlevaDesk, so your UI can toggle them directly: a manual kill switch that pauses the AI (calls ring the humans instead), and a staffed-hours schedule — the weekly hours during which calls ring staff first and the AI answers the rest of the time.
• Config sync. An explicit resync is the only post-enable write of configuration and onboarding data. Fields the business has changed in KlevaDesk since enable are not overwritten; the response lists what was skipped, and overriding anyway is a deliberate, logged act visible to the owner.
• Status and health polling. A per-business status object carries the lifecycle state, the assigned number, messaging registration status, and health signals (voice, connected integrations), plus a changed-since listing for panel views. Every state or health change bumps the object's timestamp, so polling the listing is cheap.

Authentication

Every request carries a partner API key as a bearer token:

Authorization: Bearer kap_live_EXAMPLE_0000

Keys are issued and validated by KlevaAccounts, the Kleva platform's identity service, and are revealed and rotated only inside the partner portal, backed by KlevaAccounts. Key lifecycle:

• Reveal once. The plaintext key is shown exactly once, at mint or rotation. It is never in a repository, never in a message, and never echoed back by any API response.
• Rotate with overlap. Two keys may be active at once; after you reveal a new key, the old one keeps working for 24 hours, then dies. Two keys max per environment.
• Revoke now. A separate control kills a key immediately. Revocation and expiry propagate within 60 seconds while KlevaAccounts is reachable; during a KlevaAccounts outage the last successful validation may be honored for up to 15 minutes.
• Sandbox key. A separate key (kap_sandbox_...) with the same controls. Sandbox provisioning uses fake numbers, auto-approving SMS registration, and no real telephony purchases. Note: sandbox keys are not yet accepted on the live surface — a request made with one is refused with 403 sandbox_not_supported until the sandbox environment ships.
• Every key action is logged with the acting account and visible to both sides' contacts.

A missing, unknown, revoked, or expired key gets 401 invalid_key; a key without the required scope gets 403 insufficient_scope (see Errors). There is no IP allowlisting in either direction.

Quickstart

GET /me is the integration smoke test: it authenticates your key and returns who you are.

curl https://app.klevadesk.com/api/partner/v1/me \
  -H "Authorization: Bearer kap_live_EXAMPLE_0000"

{ "partner": "example-partner", "name": "Example Partner", "environment": "live" }

The response is your partner identity and the key's environment. If this call returns 200, your key, header, and base URL are all right.

Rate limits and safety

• 60 requests/min per partner key. Exceeding it returns 429 rate_limited with a Retry-After header.
• Polling budget: poll one business's status at most once per 30 seconds; the changed-since listing covers panel views.
• Idempotency: every mutating call must send Idempotency-Key: <uuid>. Same key + same body within 24 h replays the original response; same key + different body is 409 idempotency_conflict. This is what makes retrying a 5xx safe.
• Strict validation, no guessing. Phone numbers are E.164, enforced at the API — a value that does not match is refused, naming the field, and nothing is created. The same goes for an unset timezone: KlevaDesk refuses rather than run a schedule hours off. Normalizing what an admin typed is your enable UI's job.
• Suspend/deprovision safety: a business cannot be suspended or deprovisioned twice in a row without an intervening resume or re-enable, and KlevaDesk alerts the partner contacts on any deprovision of a live business.

Errors

Every error is a JSON envelope {error, message, retryable[, action, field]}:

{ "error": "phone_invalid", "field": "config.transfer_number",
  "message": "must be E.164 (e.g. +15550100100)", "retryable": false, "action": "fix_input" }

On any 5xx, retry with backoff — the Idempotency-Key makes the retry safe.

Full reference

The complete, versioned endpoint reference — every path, field, and request/response sample — is served inside the partner API itself:

curl https://app.klevadesk.com/api/partner/v1/docs.md \
  -H "Authorization: Bearer kap_live_EXAMPLE_0000"

• Authenticated with your partner key — sandbox keys included, so the reference is available from the moment you can make any call at all.
• Stable URL, Markdown, ETag'd. The document is plain Markdown at a URL that never changes; send If-None-Match and an unchanged reference answers 304. Re-fetch it to refresh.
• Built for humans and integration agents alike. Point your integration's coding agent at it directly — it always matches the version of the API your key talks to.

Becoming a partner

Partner accounts are created by invite, and keys are revealed only inside the partner portal. If you run a software platform for service businesses — in any vertical — and want to embed KlevaDesk, write to support@klevadesk.com.