Number Masking (Proxy) API

Connect Party A to Party B via a third “proxy” number — both sides call or text the proxy and the platform forwards to the other end. Used by marketplaces and ride-share apps where the buyer and seller shouldn’t see each other’s real phone number. Base path: /api/v1/proxy Authentication: API key (X-API-Key) or session JWT. Session create/close requires the owner, admin, or developer role.

Using the SDKs

import { Orbit } from "@devotel-orbit/node";

const orbit = new Orbit({ apiKey: process.env.ORBIT_API_KEY! });

const res = await orbit.proxy.listSessions();

Python (same call via the SDK’s escape hatch):

from orbit_sdk import OrbitClient

client = OrbitClient.from_env()  # reads ORBIT_API_KEY

res = client.request("GET", "/proxy")

The Python SDK is core-scope — it wraps the 8 core resources (messaging, voice, contacts, campaigns, verify, numbers) and reaches everything else through the generic client.request() escape hatch above. See the Python SDK. Returns the typed ApiResponse envelope. See the SDK index at SDK quickstart.

Sessions

A session is the active mapping. While the session is open, calls and SMS to the proxy number from either participant are forwarded to the other.

Method	Path	Purpose
`POST`	`/api/v1/proxy/sessions`	Create a session (claim a proxy number)
`GET`	`/api/v1/proxy/sessions`	List sessions (cursor-paginated, filter by `status`)
`GET`	`/api/v1/proxy/sessions/{id}`	Get a session
`DELETE`	`/api/v1/proxy/sessions/{id}`	Close a session (release the number)

ttl_minutes is optional (integer 1–1440, defaults to 60). When the TTL elapses the session expires, the proxy number is released back to the pool, and inbound traffic to it stops forwarding. Texting the proxy counts toward messaging usage; voice legs count toward voice usage.

Create a session

curl -X POST https://api.orbit.devotel.io/api/v1/proxy/sessions \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "participant_a": "+14155551111",
    "participant_b": "+14155552222",
    "ttl_minutes": 60
  }'

201 response — store session_id, proxy_number, and expires_at:

{
  "data": {
    "session_id": "pxy_c8f1a2e3b4d5468ba1c9e2f3d4a5b6c7",
    "proxy_number": "+13107774455",
    "participant_a": "+14155551111",
    "participant_b": "+14155552222",
    "status": "active",
    "ttl_minutes": 60,
    "expires_at": "2026-08-25T14:00:00.000Z",
    "created_at": "2026-08-25T13:00:00.000Z"
  },
  "meta": {
    "request_id": "req_01HXZ1QW2DK3T9VYV4N9CSB0B1",
    "timestamp": "2026-08-25T13:00:00.012Z"
  }
}

List sessions

curl "https://api.orbit.devotel.io/api/v1/proxy/sessions?status=active&limit=25" \
  -H "X-API-Key: dv_live_sk_your_key_here"

status filters to active, closed, or expired. Pagination is cursor-based — pass next_cursor from meta.pagination back as cursor.

Get a session

curl https://api.orbit.devotel.io/api/v1/proxy/sessions/pxy_c8f1a2e3b4d5468ba1c9e2f3d4a5b6c7 \
  -H "X-API-Key: dv_live_sk_your_key_here"

Returns the session row: id, participant_a, participant_b, proxy_number, status, ttl_minutes, expires_at, closed_at, created_at, updated_at.

Close a session

Close early when the trip or transaction ends — this releases the number immediately rather than waiting for TTL expiry.

curl -X DELETE https://api.orbit.devotel.io/api/v1/proxy/sessions/pxy_c8f1a2e3b4d5468ba1c9e2f3d4a5b6c7 \
  -H "X-API-Key: dv_live_sk_your_key_here"

200 response:

{
  "data": {
    "id": "pxy_c8f1a2e3b4d5468ba1c9e2f3d4a5b6c7",
    "participant_a": "+14155551111",
    "participant_b": "+14155552222",
    "proxy_number": "+13107774455",
    "status": "closed",
    "ttl_minutes": 60,
    "expires_at": "2026-08-25T14:00:00.000Z",
    "closed_at": "2026-08-25T13:42:10.500Z",
    "created_at": "2026-08-25T13:00:00.000Z",
    "updated_at": "2026-08-25T13:42:10.500Z"
  },
  "meta": {
    "request_id": "req_01HXZ4SDR9A2M8PVCQRW2JH0D2",
    "timestamp": "2026-08-25T13:42:10.533Z"
  }
}

Closing an already-closed or expired session returns 409 CONFLICT (see Errors below).

Webhooks

Register the proxy event types on your webhook endpoint to follow the session lifecycle. Every delivery carries an id (evt_…), type, and data — and an HMAC signature header for verification.

`proxy.session.created`

{
  "id": "evt_6b2c1e45f8a94d3bb0a2c4e6f1d3b5a7",
  "type": "proxy.session.created",
  "created_at": "2026-08-25T13:00:00.045Z",
  "data": {
    "session_id": "pxy_c8f1a2e3b4d5468ba1c9e2f3d4a5b6c7",
    "proxy_number": "+13107774455",
    "participant_a": "+14155551111",
    "participant_b": "+14155552222",
    "expires_at": "2026-08-25T14:00:00.000Z"
  }
}

`proxy.message.forwarded`

Fired once per successful forward — this is what you listen for to mirror the ride-share conversation in your own UI (when Party A texts or calls the proxy, the platform forwards to Party B and fires this event):

{
  "id": "evt_4d8e2a1c3b5f406aa7e9d1f2a3b4c5d6",
  "type": "proxy.message.forwarded",
  "created_at": "2026-08-25T13:07:22.110Z",
  "data": {
    "session_id": "pxy_c8f1a2e3b4d5468ba1c9e2f3d4a5b6c7",
    "proxy_number": "+13107774455",
    "from_participant": "+14155551111",
    "to_participant": "+14155552222",
    "channel": "sms"
  }
}

The event fires only when the forward succeeded — an inbound message to an expired session, an unknown sender, or a delivery failure produces no event. Message bodies are not included in the payload.

`proxy.session.closed`

{
  "id": "evt_9a7d3c2b1e4f405bb8c6d5a4e3f2b1a0",
  "type": "proxy.session.closed",
  "created_at": "2026-08-25T13:42:10.533Z",
  "data": {
    "session_id": "pxy_c8f1a2e3b4d5468ba1c9e2f3d4a5b6c7",
    "proxy_number": "+13107774455",
    "closed_at": "2026-08-25T13:42:10.500Z"
  }
}

POST /proxy/sessions — rider and driver numbers, ttl_minutes: 90. Store session_id, proxy_number, expires_at.
Show both parties the proxy number as the contact for the trip.
The rider texts the proxy. The platform forwards the message to the driver from the proxy number and fires proxy.message.forwarded. The driver replies to the proxy; same flow in reverse.
When the trip ends, DELETE /proxy/sessions/{id} to close the session and release the number. If you never close it, the session expires at expires_at, releases the number, and any later inbound traffic to it is ignored.

The carrier’s inbound traffic to the proxy number arrives at POST /api/v1/proxy/inbound — internal, signed for carrier use; do not call it from your integration.

SDKs

The Node SDK (@devotel/sdk-node) covers /proxy: orbit.proxy.createSession(...), orbit.proxy.listSessions({ status, limit, cursor }), orbit.proxy.getSession(id), orbit.proxy.closeSession(id), plus iterSessions() for auto-pagination. See the SDK reference for the exact doctype signatures — the API contract above is authoritative (participant_a, participant_b, ttl_minutes). If you need a straight-HTTP fallback:

const ORBIT_API = "https://api.orbit.devotel.io";
const KEY = process.env.ORBIT_API_KEY; // dv_live_sk_…

async function createProxySession(participantA, participantB, ttlMinutes = 60) {
  const res = await fetch(`${ORBIT_API}/api/v1/proxy/sessions`, {
    method: "POST",
    headers: { "X-API-Key": KEY, "Content-Type": "application/json" },
    body: JSON.stringify({
      participant_a: participantA,
      participant_b: participantB,
      ttl_minutes: ttlMinutes,
    }),
  });
  const json = await res.json();
  if (!res.ok) throw new Error(`${json.error.code}: ${json.error.message}`);
  return json.data; // { session_id, proxy_number, expires_at, ... }
}

Errors

All errors ship the same envelope:

{
  "error": { "code": "VALIDATION_ERROR", "message": "Invalid proxy session input", "status": 422, "details": { "issues": [ { "field": "participant_a", "message": "Invalid E.164 phone number" } ] } },
  "meta": { "request_id": "req_01HXZ6T9ABCD4ZPW7FG2MX0Y", "timestamp": "2026-08-25T13:01:00.700Z" }
}

Outcome	HTTP	Error code	Notes
Non-E.164 `participant_a` / `participant_b`	`422`	`VALIDATION_ERROR`	`details.issues` lists the failing field
`ttl_minutes` outside 1–1440	`422`	`VALIDATION_ERROR`	must be an integer (whole seconds not allowed)
`participant_a` equals `participant_b`	`400`	`VALIDATION_ERROR`	both parties must differ
Unknown session id on get/close	`404`	`NOT_FOUND`	—
Close an already-closed or expired session	`409`	`CONFLICT`	`error.message` includes the current status

Note: an expired session is not a 4xx — a GET on an expired session still returns 200 with status: "expired"; closing it after expiry is the 409 case. Inbound traffic to an expired (or released) proxy number is ignored after TTL, so the only signal that masking has lapsed is the expired status on the row.

API Reference

All Endpoints

Number Masking (Proxy) API

Number Masking (Proxy) API

Using the SDKs

Sessions

Create a session

List sessions

Get a session

Close a session

Webhooks

`proxy.session.created`

`proxy.message.forwarded`

`proxy.session.closed`

SDKs

Errors

​Number Masking (Proxy) API

​Using the SDKs

​Sessions

​Create a session

​List sessions

​Get a session

​Close a session

​Webhooks

​proxy.session.created

​proxy.message.forwarded

​proxy.session.closed

​End-to-end sequence (ride-share)

​SDKs

​Errors

Number Masking (Proxy) API

Using the SDKs

Sessions

Create a session

List sessions

Get a session

Close a session

Webhooks

`proxy.session.created`

`proxy.message.forwarded`

`proxy.session.closed`

End-to-end sequence (ride-share)

SDKs

Errors