## Overview The MiiTel Public API lets authorized applications retrieve and manage MiiTel tenant data, including phone-call and meeting records. Responses are limited to the authenticated account's tenant membership and permissions. **Before you start.** Obtain these values from your MiiTel administrator: - the Public API base URL for your environment, for example: - ``https://.tyo101.miitel.com`` — Tokyo environment - ``https://.jkt101.miitel.com`` — Jakarta environment - your tenant code; and - an authorized MiiTel account or supported integration credential. All resource paths begin with ``/public-api/v1``. ## Authentication **Obtain an access token.** A server-side client whose account supports password authentication can request a token as follows: ```bash curl -X POST "https://account.miitel.com/auth/v1/authenticate" \ -H "Content-Type: application/json" \ -d '{ "flow": "USER_PASSWORD", "params": {"email": "", "password": ""} }' ``` The response looks like: ```json { "auth_result": { "access_token": "", "refresh_token": "", "token_type": "Bearer", "expires_in": 3600 } } ``` Use ``auth_result.access_token`` from the response as the bearer token, and save ``auth_result.refresh_token``. If the account uses SSO or MFA, or the integration must run unattended, ask your MiiTel administrator for the supported authentication method. **Refresh an access token.** Before it expires, or right after a ``401``, exchange the refresh token for a new one by calling the same endpoint with ``"flow": "REFRESH_TOKEN"`` and ``"params": {"refresh_token": ""}``: ```json { "auth_result": { "access_token": "", "token_type": "Bearer", "expires_in": 3600 } } ``` The response may also include a new ``refresh_token`` — if so, replace the stored one. Read ``expires_in`` from each response instead of assuming a fixed lifetime. If refreshing fails, authenticate again with ``USER_PASSWORD``. > **Security:** Never place credentials or tokens in browser code, source control, logs, or support tickets. **Send your first request.** Set the values supplied for your environment, then retrieve a small page of phone-call records: ```bash export PUBLIC_API_URL="https://" export TENANT_CODE="" export ACCESS_TOKEN="" curl -X POST "${PUBLIC_API_URL}/public-api/v1/phone_calls/list" \ -H "Authorization: Bearer ${ACCESS_TOKEN}" \ -H "X-Tenant-Code: ${TENANT_CODE}" \ -H "Content-Type: application/json" \ -d '{"first": 5}' ``` Every request requires ``Authorization: Bearer ``. Send ``X-Tenant-Code: `` unless the request's host already supplies the tenant code as its leading subdomain label (as in the base-URL examples above) — when both are absent, the request fails. Send ``Content-Type: application/json`` only when the request has a JSON body. A successful response contains ``calls`` and ``page_info``. ## Choose a resource | Resource | Use it for | | --- | --- | | **Phone calls** | Parent conversations and grouped call history. A call can contain multiple legs. | | **Phone call legs** | Individual call legs, transcripts, audio, comments, tags, and analysis. | | **Meetings** | Video-meeting metadata, viewers, tags, and access settings. | | **Meeting recordings** | A meeting's individual recordings, transcripts, summaries, topics, and comments. | The operation descriptions and schemas below define the exact request fields, response fields, formats, limits, and examples. ## Pagination Most list operations use cursor pagination. | Field | Meaning | | --- | --- | | **first** | Page size — how many records to return. | | **after** | Cursor from the previous response's ``page_info.end_cursor``. Send it back unchanged to get the next page. Treat it as an opaque value — never parse or construct one. | | **offset** | Number of matching records to skip before this page. Used for old-style offset paging; on ``phone_call_legs/list`` it is always required regardless of paging style (see below). | ```json {"first": 5, "after": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"} ``` You have reached the last page when ``page_info.end_cursor`` is ``null`` — except for ``phone_calls`` and ``phone_call_legs`` lists, which are complete when the returned collection is empty. ``phone_call_legs/list`` has one more exception: it always requires ``offset`` in addition to ``after``. Send ``offset: 0`` on the first page and keep sending that same value on every later page — ``after`` is what actually advances you through the pages, not ``offset``. For any other required or optional field, follow that operation's own schema. ## Errors and retries Every error has ``{"code": "public_api.", "message": "..."}``; ``details`` is optional. Branch on ``code``, not ``message``. **Fix the request or access before retrying:** | Response | Client action | | --- | --- | | ``400``, ``413``, ``422`` | Correct the request before retrying. | | ``401`` | Obtain a valid access token. | | ``403`` | Check tenant membership, permissions, contract, and IP restrictions. | | ``404`` | Verify the resource ID and tenant. | | ``409`` | Refresh the resource and reconcile its current state. | **Retry temporary failures safely:** Every response counted against your rate limit — a ``2xx`` response as well as a ``429`` — includes ``RateLimit-Limit``, ``RateLimit-Remaining``, and ``RateLimit-Reset``. Watch ``RateLimit-Remaining`` on your normal responses to slow down before you hit ``429``. | Response | Client action | | --- | --- | | ``429`` | Wait for ``Retry-After``, add jitter, and then retry. | | ``502``, ``503``, ``504`` | Retry idempotent requests with capped exponential backoff and jitter. | > **Retry safety:** Never automatically retry a non-idempotent write unless the operation description says it is safe. **Escalate persistent failures.** After bounded retries, report a persistent ``5xx`` to your MiiTel administrator with the request timestamp (including the time zone), the HTTP method and path, the tenant code, the HTTP status, and the error ``code``. Never include the bearer token, credentials, or sensitive request data. ## Version compatibility The published OpenAPI document is the source of truth for the ``v1`` contract. Breaking changes require a new versioned API path. Compatible changes may add optional response fields or enum values, so clients should ignore unknown response fields and handle unknown enum values safely. Deprecated operations or fields are marked in OpenAPI before removal.

200Hold and unhold events for the requested phone call legs.

400The tenant could not be resolved from the request.

401Error envelope (public_api.unauthorized).

403The request is not allowed for the current tenant or access configuration.

404Error envelope (public_api.not_found).

409Error envelope (public_api.conflict).

413The request body exceeds the maximum allowed size.

422Validation Error

429Rate limit exceeded. Wait for Retry-After seconds before retrying.

502Error envelope (public_api.internal_error).

503The request could not be served right now. Please retry.

504Error envelope (public_api.request_timeout).