Telroi API

Build voice, OTP, speech and CRM features on Telroi over one REST API.

Developer quickstart

Make your first API request in minutes. Send a voice OTP with a single call.

fetch("https://app.telroi.ai/v1/otp", {
  method: "POST",
  headers: {
    "Authorization": "Bearer tlr_live_xxx",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "to": "+15551234567"
  })
})
  .then((res) => res.json())
  .then((data) => console.log(data));

Base URLv1

Capabilities

Build voice verification, speech and calling into your product over one REST API.

OTP

Voice OTP

Deliver one-time passcodes over a phone call. OTP-only, with operator-set length, expiry and frequency.

TTS · STT

Speech

Text-to-speech synthesis and speech-to-text transcription via simple endpoints.

Voice

Voice calls

Place and manage calls programmatically across your provisioned numbers.

Start building

Send a voice OTPPlace a call that reads a one-time code aloud Synthesize speechTurn text into natural-sounding audio Transcribe audioConvert recorded speech into text Place a callOriginate outbound voice calls via the API

Authentication

Authenticate every request with a secret API key in the Authorization header. Create keys in your dashboard under Developers.

cURL

curl https://app.telroi.ai/v1/numbers \
  -H "Authorization: Bearer tlr_live_xxx"

live tlr_live_ keys hit live infrastructure and bill your wallet. test tlr_test_ keys run in sandbox — calls are simulated, nothing is charged, and OTP code 000000 always verifies. Keep secret keys server-side.

Errors & rate limits

Telroi uses conventional HTTP status codes: 2xx success, 4xx a request problem, 5xx a Telroi-side error. Every error body has the same shape.

Error

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or revoked API key"
  }
}

HTTP status code summary

Code	Description
`200`	OK — the request succeeded.
`201`	Created — a resource was created (e.g. an OTP was placed).
`400`	Bad Request — a parameter is missing or invalid. See the error code in the body.
`401`	Unauthorized — no valid API key was provided. Send it as a Bearer token.
`403`	Forbidden — the key is valid but lacks the required scope (e.g. otp:write).
`404`	Not Found — the resource or endpoint doesn't exist.
`405`	Method Not Allowed — wrong HTTP method for this endpoint.
`422`	Unprocessable Entity — the body is well-formed but failed validation.
`429`	Too Many Requests — a rate limit was exceeded. Check the retry guidance.
`5xx`	Server Error — something went wrong on Telroi's end. These are rare.

Error codes

When a request fails, the body contains an error.code you can branch on:

Error code	HTTP	Meaning
`invalid`	`400`	A required field is missing or malformed (e.g. a non-E.164 destination number).
`unauthorized`	`401`	The API key is missing, revoked, or not recognized.
`forbidden`	`403`	The key lacks the scope this endpoint needs (otp:write, speech:write, etc.).
`rate_limited`	`429`	Too many OTP requests for this destination number. Respect the cooldown, hourly and daily caps; retry after the indicated delay.
`otp_failed`	`502`	The OTP call could not be placed by the configured voice vendor.
`speech_failed`	`502`	Text-to-speech or speech-to-text processing failed at the configured vendor.

Rate limits

The Voice OTP endpoint is rate-limited per destination number by the operator policy (cooldown, hourly and daily caps). Exceeding a limit returns 429 with a rate_limited code.