Build interpreting into your own systems

1. Create a Remoto business account at /register/agency (or sign in) and set up your business profile under Your Business.
2. Open Your Business → API & Webhooks and create a test key. Test keys work immediately against the sandbox: every endpoint, real response shapes and real webhooks, but no interpreter is rung and nothing is billed.
3. When you are ready for real calls, fill in Request live access on the same page: what you are building, the call types you need, expected volume. Remoto reviews it, usually within one business day, and emails you the decision (it also shows on that page and in GET /me).
4. Once approved, the business owner or an admin creates a live key. Live calls are billed to your business: to the card on the owner account by default, or monthly on invoice if Remoto has agreed invoice terms with you. GET /me shows live_access and billing.

Phone systems and call centres can also send calls straight to Remoto over SIP, with no API calls at all. Write to [email protected] for a SIP trunk; those calls then appear in GET /calls and the call.* webhooks.

Call the API with your key as a bearer token:

curl https://www.proz.com/remoto/api/v1/me \
  -H "Authorization: Bearer rmk_test_..."

{
  "object": "api_key_context",
  "api_version": "2026-09-29",
  "livemode": false,
  "key": { "id": "3fJ9kQ2mX8aB", "name": "Staging", "mode": "test" },
  "business": { "id": "66f…", "name": "Example Health", "live_access": "requested", "billing": "card", ... }
}

Base URL: https://www.proz.com/remoto/api/v1. All requests and responses are JSON over HTTPS. Timestamps are ISO 8601 in UTC. Money is a decimal amount with an ISO 4217 currency. Language codes are ISO 639 (eng, ara, spa, urd …).

Your user needs an interpreter now — a patient in a telehealth visit, a customer on your support chat. One request gives you a join_url. Open it for your user in a new tab, a redirect, or your mobile app's in-app browser (it cannot be embedded in an iframe). Nobody is rung until your user presses Connect on that page, so an interpreter never waits in an empty room.

1. POST /call-requests → status: "waiting" with a join_url. Optionally check GET /availability first and show the price.
2. Your user opens the link and connects → ringing (webhook call_request.ringing). Remoto rings the online interpreters for the pair, within your interpreter-sourcing setting (your own roster first or only, if you have one).
3. First interpreter to accept → accepted (webhook call_request.accepted with the interpreter). Your user is put straight into the call room — video or audio, with the interpreter.
4. The call ends and is settled → completed (webhook call_request.completed, whose data.object.call carries duration, billed seconds and cost).
5. No answer within ring_timeout_seconds, nobody available, or your user gives up → missed with an end_reason. Create a new request to try again.

curl https://www.proz.com/remoto/api/v1/call-requests \
  -H "Authorization: Bearer $REMOTO_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: visit-5521-interp" \
  -d '{
    "language_pair": { "source": "eng", "target": "spa" },
    "call_type": "video",
    "client_name": "Maria Lopez",
    "external_reference": "visit-5521",
    "metadata": { "clinic": "north", "visit_id": "5521" }
  }'

{
  "id": "6710c2…",
  "object": "call_request",
  "livemode": true,
  "status": "waiting",
  "language_pair": { "source": "eng", "target": "spa", "code": "eng_spa" },
  "call_type": "video",
  "client_name": "Maria Lopez",
  "external_reference": "visit-5521",
  "metadata": { "clinic": "north", "visit_id": "5521" },
  "join_url": "https://proz.com/remoto/connect/Xk3…",
  "join_expires_at": "2026-10-13T15:02:11.000Z",
  "ring_timeout_seconds": 120,
  "interpreter": null,
  "call_id": null,
  ...
}

Parameters

The call request object

Track progress with webhooks (recommended) or by polling GET /call-requests/{id} every few seconds. POST /call-requests/{id}/cancel withdraws a request that is still waiting or ringing; once it is accepted the call is happening and you get 409. The join_url is the credential for that one call — send it only to your user. A user who drops can reopen it to rejoin while the call is live.

Billing. Billing starts when the interpreter and your user are both connected; ring time is free. The rate is your wholesale or business rate card for the pair if Remoto has set one, otherwise the Remoto platform rate — the same rate GET /availability returns.

Prefer your own interface over the hosted join page? Load the Remoto Call script and draw the call yourself: your buttons, your layout, your brand. Remoto supplies the interpreter, the media connection and the minute tracking. Interpreters still answer in Remoto as usual.

1. Your server creates the request with POST /call-requests and passes only its client_secret to the browser (never your API key).
2. Your page loads the script, calls start() to ring, shows your own recording notice and calls acceptRecordingConsent(), then join() when the status becomes accepted.
3. The script plays the interpreter's audio, renders video into the <video> elements you pass, reconnects after network drops, and reports presence to Remoto. Billing runs only while both your user and the interpreter are in the call; Remoto also checks the room itself, so billing never depends on your page alone.

<video id="interpreter" autoplay playsinline></video>
<video id="me" autoplay playsinline muted></video>
<button id="connect">Get an interpreter</button>
<button id="hangup">End call</button>

<script src="https://www.proz.com/remoto/sdk/remoto-call.js"></script>
<script>
  // clientSecret comes from YOUR server: POST /v1/call-requests → client_secret
  const call = RemotoCall.create({ clientSecret: CLIENT_SECRET });

  call.on("status", async (s) => {
    showStatus(s.status);                       // waiting | ringing | accepted | completed | missed | cancelled
    if (s.status === "accepted") {
      await call.join({
        remoteVideo: document.getElementById("interpreter"),
        localVideo: document.getElementById("me"),
      });
    }
  });
  call.on("interpreter", (i) => showInterpreter(i.name));
  call.on("connection", (c) => showConnection(c)); // joining | joined | reconnecting | left
  call.on("ended", (e) => showEnded(e.reason));
  call.on("error", (err) => console.warn(err.code, err.message));

  document.getElementById("connect").onclick = async () => {
    if (!confirm("This session may be recorded for quality and compliance. Continue?")) return;
    await call.acceptRecordingConsent();
    await call.start({ name: "Maria Lopez" });
  };
  document.getElementById("hangup").onclick = () => call.hangUp();
</script>

Scheduled calls embed the same way: use the booking's client_secret (from POST /scheduled-calls). There is nothing to ring, so skip start() and call watch() to keep the status fresh. The status is waiting until an interpreter is confirmed and accepted after. joinable turns true 30 minutes before startsAt; join any time after that. Before then, join() fails with too_early.

Errors carry a code: consent_required, not_accepted, too_early, call_closed, sandbox (test-key requests have no media room: the status lifecycle and webhooks are simulated, but join() is refused), not_found.

The script is about 125 KB gzipped and works in current Chrome, Edge, Firefox and Safari (desktop and mobile). Pages must be served over HTTPS for camera and microphone access. Calls placed this way have audio/video only. Recording settings follow your account; adding a second interpreter, dialling a phone number in and live captions are available in the hosted join page.

For appointments: book a time, Remoto finds and confirms an interpreter, and your user joins at the time through the booking's join_url (no Remoto account). Nobody is picked up front: Remoto invites matching interpreters (within your sourcing setting) and the first to accept confirms it — you get scheduled_call.confirmed. start_time must be at least 15 minutes ahead. Live bookings need invoice terms on your business or a verified payment method on the owner account (otherwise 402).

curl https://www.proz.com/remoto/api/v1/scheduled-calls \
  -H "Authorization: Bearer $REMOTO_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: booking-8841" \
  -d '{
    "language_pair": { "source": "eng", "target": "ara" },
    "start_time": "2026-10-20T09:00:00Z",
    "duration_minutes": 30,
    "call_type": "video",
    "client_name": "Ahmed Saleh",
    "notes": "Cardiology follow-up",
    "external_reference": "booking-8841"
  }'

{
  "id": "66fa0c…",
  "object": "scheduled_call",
  "livemode": true,
  "status": "pending",
  "language_pair": { "source": "eng", "target": "ara", "code": "eng_ara" },
  "start_time": "2026-10-20T09:00:00.000Z",
  "duration_minutes": 30,
  "call_type": "video",
  "client_name": "Ahmed Saleh",
  "join_url": "https://proz.com/remoto/join/9f3c…",
  "external_reference": "booking-8841",
  "origin": "api",
  "interpreter": null,
  ...
}

Parameters: language_pair (required), start_time (required), duration_minutes (5–480, default 60), call_type (audio | video, default audio), notes (shown to the interpreter, ≤ 2000 chars), client_name, external_reference, metadata, and client_email with notify_client: true if you want Remoto to email your user the confirmation and reminders (off by default — you own the conversation).

POST /scheduled-calls/{id}/cancel with an optional reason cancels a booking that has not started. If an interpreter is already confirmed, the late-cancellation policy may charge a fee; the response returns cancellation_fee.

Send your key in the Authorization: Bearer header (or X-Api-Key). Keys look like rmk_live_… or rmk_test_…. Treat them like passwords: server-side only, never in a browser or mobile app.

• Hashed at rest, shown once. We store only a SHA-256 hash of each key. If you lose one, rotate or create a new key.
• Rotation with grace. Rotating issues a replacement immediately; the old key keeps working for 24 hours so you can redeploy without downtime. Revoking is immediate.
• Who can create keys. Live keys need approved live access, and can be created or rotated only by the business owner or an admin. Team members with settings access can create test keys. If Remoto suspends live access, live keys stop with 403 live_access_not_approved while test keys keep working.
• Test vs live. Test keys read your real data but never ring or book anyone: see Testing. Live keys place real calls with real interpreters.
• Tenant isolation. The business is taken from the key alone — no endpoint accepts a business id — so a key can never read or write another business's data.
• Rate limits. 120 requests per minute per key, counted separately in each Remoto data centre, so treat 120 as the budget even if you occasionally get more through. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset; over the limit you get 429 with Retry-After. Repeated failed authentication from one IP is also throttled.
• Audit log. Every request made with your keys — including rejected ones — is logged with time, key id, method, path, status and IP, and is visible in the dashboard for 90 days.
• Idempotency. Send an Idempotency-Key header (8–128 chars) on POST /call-requests and POST /scheduled-calls; a retried request with the same key returns the original object (header Idempotent-Replayed: true) instead of creating a second one.
• Join links. A join_url admits whoever holds it to that one call. Hand it only to your user, over HTTPS, and do not log it in analytics.

Errors use one shape, with a request id you can quote to support:

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_start_time",
    "message": "start_time must be an ISO 8601 date-time",
    "param": "start_time"
  }
}
// Response header:  Remoto-Request-Id: req_3b1c…

Types: authentication_error (401), permission_error (403), invalid_request_error (400/402), not_found (404), rate_limit_error (429), api_error (500). A language code Remoto does not support is a 400 with code: "unknown_language".

Availability

Who could take a call right now, counted exactly the way a call placed now would ring: your interpreter sourcing setting applies (roster-only businesses see only their live roster unless coverage fallback is on), and pass client_idto apply a portal client's team rules. The rate is your wholesale rate group when your account has wholesale pricing (with its billing increment and minimum), else your client rate card for the pair, else the Remoto platform rate. Pass call_type=opi (default) or vri for the phone or video price. Up to 20 pairs per request with pairs=.

curl "https://www.proz.com/remoto/api/v1/availability?pairs=eng_ara,ara_urd" -H "Authorization: Bearer $REMOTO_KEY"

{
  "object": "list",
  "data": [
    {
      "object": "availability",
      "language_pair": { "source": "eng", "target": "ara", "code": "eng_ara", "label": "English ↔ Arabic" },
      "available_now": true,
      "interpreters_online": 7,
      "roster_interpreters_online": 2,
      "interpreters_total": 412,
      "sourcing": "roster_first",
      "rate": { "amount": 1.5, "currency": "USD", "unit": "minute", "source": "business_rate_card" },
      "checked_at": "2026-09-29T14:02:11.000Z"
    }
  ]
}

Call logs and usage

GET /calls returns connected calls and missed rings together, newest first. Filters: from, to (default: last 30 days, max 366), status (all, completed, missed, cancelled), channel (phone_line, video, audio), limit (≤ 100). Page with starting_after=<next_cursor> while has_more is true.

curl "https://www.proz.com/remoto/api/v1/calls?channel=phone_line&from=2026-09-01T00:00:00Z&limit=100" \
  -H "Authorization: Bearer $REMOTO_KEY"

GET /usage?from=&to= totals completed calls (billed seconds and minutes, cost per currency) by language pair, channel and UTC day, plus missed counts. Test calls are excluded.

GET /phone-lines lists your Phone Line accounts: account number, dial-in number, speed-dial pairs, operator-fallback pair, and the SIP trunks that route your PBX into the line (SIP URI, auth mode, allowed IPs, digest username, per-pair extensions). IVR PINs and SIP passwords are never returned by the API. Send your own call id in the X-Remoto-Ref SIP header and it comes back as phone_line.partner_ref on the call and its webhooks, so you can reconcile against your CDRs.

Phone Line calls carry everything a telecom partner needs to reconcile: when ringing started, when the interpreter picked up, pickup seconds, billed seconds, whether the operator fallback or an added interpreter was used, and the cost.

{
  "id": "call-5c1e…",
  "object": "call",
  "channel": "phone_line",
  "status": "completed",
  "language_pair": { "source": "eng", "target": "ara", "code": "eng_ara" },
  "requested_at": "2026-09-29T08:00:03.000Z",
  "answered_at": "2026-09-29T08:00:41.000Z",
  "ended_at": "2026-09-29T08:14:12.000Z",
  "answer_seconds": 38,
  "duration_seconds": 811,
  "billed_seconds": 811,
  "operator_fallback_used": true,
  "requested_language_pair": { "source": "ara", "target": "urd", "code": "ara_urd" },
  "added_interpreters": [
    { "interpreter": { "id": "5512", "name": "A. Khan" },
      "language_pair": { "source": "ara", "target": "urd", "code": "ara_urd" },
      "billed_seconds": 640, "cost": 12.8 }
  ],
  "added_interpreter_used": true,
  "cost": {
    "amount": 33.08, "currency": "USD", "rate_per_minute": 1.5,
    "breakdown": { "interpreting": 20.28, "added_interpreters": 12.8, "recording": 0, "phone_dialout": 0 },
    "billed_to": "business", "payment_status": "succeeded", "agency_earnings": null
  },
  "phone_line": { "account_number": "4821", "caller_number_masked": "+9*******4512",
                  "sip_trunk_id": "66fb…", "partner_ref": "3cx-call-000123",
                  "leg": { "answered_at": "…", "ended_at": "…", "billable_seconds": 809, "hangup_cause": "normal_clearing" } },
  "missed_reason": null
}

Add endpoints under API & Webhooks and pick the events you want (none = all). Each endpoint gets its own signing secret (whsec_…), shown once. Use Send test to fire a signed sample of any event at your endpoint: its data.object has exactly the shape of a real event (fake ids, livemode: false). A new endpoint starts receiving live events within a minute.

POST /your/webhook HTTP/1.1
Content-Type: application/json
User-Agent: Remoto-Webhooks/2026-09-29
Remoto-Signature: t=1790690000,v1=5f2b…c9
Remoto-Event-Id: evt_call_completed_call_5c1e…
Remoto-Event-Type: call.completed
Remoto-Delivery-Id: 66fa…

{
  "id": "evt_call_completed_call_5c1e…",
  "object": "event",
  "type": "call.completed",
  "api_version": "2026-09-29",
  "created": "2026-09-29T08:14:20.000Z",
  "livemode": true,
  "business_id": "66f…",
  "data": { "object": { "id": "call-5c1e…", "object": "call", ... } }
}

• Respond 2xx quickly, then do the work asynchronously. An attempt fails if your server sends nothing for 10 seconds or has not finished responding within 15 seconds. Redirects are not followed.
• Retries: a failed delivery is retried after 1 min, 5 min, 30 min, 2 h, 8 h and 24 h (7 attempts), then marked failed. You can resend any delivery from the dashboard.
• Deduplicate on id. An event is delivered at least once; the same transition always has the same event id, built from the event type and the object id with anything other than letters, digits and _ turned into _ (for example evt_call_completed_call_5c1e…, evt_sc_confirmed_66fa…_1234, evt_cr_accepted_6710…). Dashboard test events get a random id.
• An on-demand request fires its call_request.* events and also the generic call events — call.missed for a ring nobody answered, call.completed for a connected call. Subscribe to whichever fits; most integrations need only call_request.*.
• Ordering is not guaranteed — e.g. confirmed can arrive before created. Use data.object.status and created, or re-fetch the object.
• Check livemode: test-key bookings and dashboard tests send livemode: false.
• Webhook URLs must be public https:// addresses.

Remoto-Signature is t=<unix seconds>,v1=<hex>, where v1 is HMAC-SHA256 of <t>.<raw request body> keyed with your endpoint secret. Compute it over the raw bytes (before JSON parsing), compare in constant time, and reject timestamps more than 5 minutes old to block replays.

const crypto = require("crypto");
const express = require("express");
const app = express();

app.post("/remoto/webhooks", express.raw({ type: "application/json" }), (req, res) => {
  const header = req.get("Remoto-Signature") || "";
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const t = Number(parts.t);
  if (!t || Math.abs(Date.now() / 1000 - t) > 300) return res.status(400).send("stale");

  const expected = crypto
    .createHmac("sha256", process.env.REMOTO_WEBHOOK_SECRET)
    .update(`${t}.${req.body.toString("utf8")}`)
    .digest("hex");
  const given = Buffer.from(parts.v1 || "", "hex");
  const ok = given.length === 32 && crypto.timingSafeEqual(Buffer.from(expected, "hex"), given);
  if (!ok) return res.status(400).send("bad signature");

  const event = JSON.parse(req.body.toString("utf8"));
  // …queue event.id for processing, dedupe on event.id…
  res.sendStatus(200);
});

import hashlib, hmac, os, time
from flask import Flask, request, abort

app = Flask(__name__)
SECRET = os.environ["REMOTO_WEBHOOK_SECRET"].encode()

@app.post("/remoto/webhooks")
def remoto_webhook():
    raw = request.get_data()  # raw bytes
    parts = dict(p.split("=", 1) for p in request.headers.get("Remoto-Signature", "").split(","))
    t = int(parts.get("t", "0"))
    if abs(time.time() - t) > 300:
        abort(400)
    expected = hmac.new(SECRET, f"{t}.".encode() + raw, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(expected, parts.get("v1", "")):
        abort(400)
    event = request.get_json()
    # ...dedupe on event["id"], process asynchronously...
    return "", 200

<?php
$raw = file_get_contents('php://input');
parse_str(str_replace(',', '&', $_SERVER['HTTP_REMOTO_SIGNATURE'] ?? ''), $parts);
$t = (int)($parts['t'] ?? 0);
if (abs(time() - $t) > 300) { http_response_code(400); exit; }
$expected = hash_hmac('sha256', $t . '.' . $raw, getenv('REMOTO_WEBHOOK_SECRET'));
if (!hash_equals($expected, $parts['v1'] ?? '')) { http_response_code(400); exit; }
$event = json_decode($raw, true);
// ...dedupe on $event['id']...
http_response_code(200);

Everything can be built and tested with a test key before Remoto approves live access:

• POST /call-requests returns a real join_url. Open it and press Connect: the request goes ringing, is acceptedby "Sandbox Interpreter" about 6 seconds later and completed about 30 seconds after connecting (keep the page open; it drives the simulation) — firing the same call_request.* webhooks (livemode: false). No call room opens and nothing is billed. Test the other paths with POST /call-requests/{id}/cancel and by letting a link expire (join_expires_in_minutes: 5).
• POST /scheduled-calls validates everything and returns a simulated booking with a scheduled_call.created webhook.
• Send test on a webhook endpoint fires a signed sample of any event type, including every call_request.* event.
• Real calls, free: request a test-call allowanceon the API & Webhooks page. Once Remoto grants it (you get an email), send "test_call": true on POST /call-requestswith your live key: the call rings only Remoto's designated test interpreters, runs the real media and webhooks, and nothing is billed. Each call uses one test call from the allowance.

This is API version 2026-09-29, returned on /me and in every event. We add fields and event types without notice; we never remove or rename fields within a version. Build your parsers to ignore unknown fields.

Questions or a new integration? Quote the Remoto-Request-Id header and write to [email protected].