Number Masking (Privacy Proxy)

Number masking lets two parties exchange SMS messages and calls through a shared proxy number without seeing each other’s real phone number. Ride-share (driver and rider), delivery (courier and customer), marketplace (buyer and seller), and healthcare (provider and patient) flows all share the same requirement: both sides must reach each other, and neither should walk away with the other’s personal contact information. This page is the field-level reference; for the end-to-end walkthrough (create, route, terminate, and verify with webhooks), follow the masking sessions guide.

Session lifecycle

Every masked conversation moves through four steps:

Create the session. Submit the two participants as E.164 numbers plus an optional TTL. You receive a session id and an allocated proxy number.
Pool number allocation. Orbit claims a number from the shared platform pool and binds it to the session for as long as the session is active.
Forward traffic. When a participant sends an SMS or places a call to the proxy number, Orbit matches the sender against the session’s participants and forwards to the other party with the proxy number as sender. Neither party ever sees a real number.
Close or expire. The session ends when you close it explicitly, or when its TTL elapses and the scheduled sweeper marks it expired. Either way, the proxy number returns to the pool and can serve the next session.

A forgotten session never locks a number permanently: sessions that hit their TTL without an explicit close are swept by a scheduled job, and the number is released in the same sweep.

Create a session

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

import { Devotel } from '@devotel-orbit/node';
const orbit = new Devotel({ apiKey: process.env.ORBIT_API_KEY! });

const res = await orbit.request("POST", "/proxy/sessions", {"participant_a": "+14155550100", "participant_b": "+14155550399", "ttl_minutes": 45});

from orbit_sdk import OrbitClient
client = OrbitClient.from_env()

res = client.request("POST", "/proxy/sessions", {"participant_a": "+14155550100", "participant_b": "+14155550399", "ttl_minutes": 45})

package main
import (
	"context"
	"os"
	"github.com/devotel/orbit-go/orbit"
)

func main() {
	client, err := orbit.NewClient(os.Getenv("ORBIT_API_KEY"))
	if err != nil { panic(err) }

	reqBody0 := map[string]any{"participant_a": "+14155550100", "participant_b": "+14155550399", "ttl_minutes": 45}
	var out0 map[string]any
	err = client.Request(context.Background(), "POST", "/proxy/sessions", reqBody0, nil, &out0, "")
	if err != nil { panic(err) }
}

require "orbit_sdk"
client = OrbitSdk::Client.from_env

res = client.request("POST", "/proxy/sessions", body: {"participant_a" => "+14155550100", "participant_b" => "+14155550399", "ttl_minutes" => 45})

<?php
require __DIR__.'/vendor/autoload.php';
use Devotel\Orbit\OrbitClient;
$client = OrbitClient::fromEnv();

$res = $client->request("POST", "/proxy/sessions", ['participant_a' => '+14155550100', 'participant_b' => '+14155550399', 'ttl_minutes' => 45]);

The response returns the session id and the allocated proxy_number. Hand that number to both participants and route all traffic through it:

{
  "data": {
    "session_id": "proxySession_...",
    "proxy_number": "+14155555678",
    "participant_a": "+14155550100",
    "participant_b": "+14155550399",
    "status": "active",
    "ttl_minutes": 45,
    "expires_at": "2026-08-23T12:45:00.000Z",
    "created_at": "2026-08-23T12:00:00.000Z"
  }
}

Validation on create:

Rule	Result
`participant_a` equals `participant_b`	`400 VALIDATION_ERROR` — “Participants must have different phone numbers”
`ttl_minutes` below 1 or above 1440	`400 VALIDATION_ERROR` on the `ttl_minutes` field
Either participant is not a valid E.164 number	`400 VALIDATION_ERROR` naming the field

When omitted, ttl_minutes defaults to 60.

Pick a TTL by use case

Set the TTL to the longest window in which the two parties legitimately need to reach each other, not longer. A session left open after the job completes keeps a pool number allocated and lets either party contact the other past the point your product intends.

Use case	Typical window	Suggested `ttl_minutes`	Close explicitly?
Ride-share (driver and rider)	Pickup through drop-off	30–60	Yes - close on trip completion so a finished ride cannot be recontacted
Delivery (courier and customer)	Dispatch through handoff, plus a short buffer for gate or lobby calls	60–120	Yes - close on confirmed delivery
Marketplace (buyer and seller)	A transaction or listing may span days and re-open	1440 (max) per conversation window; create a fresh session when the buyer replies later	Closing is optional - the sweeper handles expiry
Healthcare (provider and patient)	A scheduled appointment plus reminder traffic	1440, or shorter for same-day visits	Yes for same-cycle visits; let long-cycle reminder sessions expire

Two rules of thumb:

Close explicitly when your app knows the moment of completion (trip ended, delivery confirmed). The pool number is released immediately instead of waiting for the sweep.
Let the sweeper handle expiry when there is no clear completion event — a marketplace conversation that just goes quiet. The TTL is your cleanup, so size it like one.

List, inspect, and close sessions

# List sessions (optionally filter by status: active | closed | expired)
curl "https://api.orbit.devotel.io/api/v1/proxy/sessions?status=active" \
  -H "X-API-Key: dv_live_sk_..."

# Get one session
curl "https://api.orbit.devotel.io/api/v1/proxy/sessions/proxySession_..." \
  -H "X-API-Key: dv_live_sk_..."

import { Devotel } from '@devotel-orbit/node';
const orbit = new Devotel({ apiKey: process.env.ORBIT_API_KEY! });

const res0 = await orbit.request("GET", "/proxy/sessions?status=active", undefined);

const res1 = await orbit.request("GET", "/proxy/sessions/proxySession_...", undefined);

from orbit_sdk import OrbitClient
client = OrbitClient.from_env()

res0 = client.request("GET", "/proxy/sessions?status=active")

res1 = client.request("GET", "/proxy/sessions/proxySession_...")

package main
import (
	"context"
	"os"
	"github.com/devotel/orbit-go/orbit"
)

func main() {
	client, err := orbit.NewClient(os.Getenv("ORBIT_API_KEY"))
	if err != nil { panic(err) }

	var out0 map[string]any
	err = client.Request(context.Background(), "GET", "/proxy/sessions?status=active", nil, nil, &out0, "")
	if err != nil { panic(err) }

	var out1 map[string]any
	err = client.Request(context.Background(), "GET", "/proxy/sessions/proxySession_...", nil, nil, &out1, "")
	if err != nil { panic(err) }
}

require "orbit_sdk"
client = OrbitSdk::Client.from_env

res0 = client.request("GET", "/proxy/sessions?status=active")

res1 = client.request("GET", "/proxy/sessions/proxySession_...")

<?php
require __DIR__.'/vendor/autoload.php';
use Devotel\Orbit\OrbitClient;
$client = OrbitClient::fromEnv();

$res0 = $client->request("GET", "/proxy/sessions?status=active");

$res1 = $client->request("GET", "/proxy/sessions/proxySession_...");

Listing uses cursor pagination - pass limit (max 100) and follow the returned pagination.cursor for more pages. Filter by status to reconcile your order state: active sessions should map to in-flight orders, while a session your app believes is closed but reads active is a leak worth closing. Close a session to release its proxy number immediately:

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

import { Devotel } from '@devotel-orbit/node';
const orbit = new Devotel({ apiKey: process.env.ORBIT_API_KEY! });

const res = await orbit.request("DELETE", "/proxy/sessions/proxySession_...", undefined);

from orbit_sdk import OrbitClient
client = OrbitClient.from_env()

res = client.request("DELETE", "/proxy/sessions/proxySession_...")

package main
import (
	"context"
	"os"
	"github.com/devotel/orbit-go/orbit"
)

func main() {
	client, err := orbit.NewClient(os.Getenv("ORBIT_API_KEY"))
	if err != nil { panic(err) }

	var out0 map[string]any
	err = client.Request(context.Background(), "DELETE", "/proxy/sessions/proxySession_...", nil, nil, &out0, "")
	if err != nil { panic(err) }
}

require "orbit_sdk"
client = OrbitSdk::Client.from_env

res = client.request("DELETE", "/proxy/sessions/proxySession_...")

<?php
require __DIR__.'/vendor/autoload.php';
use Devotel\Orbit\OrbitClient;
$client = OrbitClient::fromEnv();

$res = $client->request("DELETE", "/proxy/sessions/proxySession_...");

Only an active session can be closed. Closing an already closed or expired session returns 409 CONFLICT, so treat a 409 on close as “already ended” rather than as a failure to retry. You do not need to close sessions you intend to let expire - the scheduled sweeper handles those and releases the number in the same pass.

Webhooks

proxy.session.created - fires when a session is created.
proxy.session.closed - fires when a session is closed.
proxy.message.forwarded - fires when an inbound message is matched to a session and forwarded to the counterparty.

Example payloads:

// proxy.session.created
{
  "session_id": "proxySession_...",
  "proxy_number": "+14155555678",
  "participant_a": "+14155550100",
  "participant_b": "+14155550399",
  "expires_at": "2026-08-23T12:45:00.000Z"
}

// proxy.session.closed
{
  "session_id": "proxySession_...",
  "proxy_number": "+14155555678",
  "closed_at": "2026-08-23T12:38:11.000Z"
}

// proxy.message.forwarded
{
  "session_id": "proxySession_...",
  "proxy_number": "+14155555678",
  "from_participant": "+14155550100",
  "to_participant": "+14155550399",
  "channel": "sms"
}

Use proxy.message.forwarded to keep your own conversation view in sync: each delivery tells you the direction the message flowed, so you can render a two-sided thread without ever storing either party’s real number as the visible sender. See the webhook consumer guide for endpoint registration, signature verification, and delivery semantics.

Worked example: a ride from dispatch to drop-off

A ride-share app masks the driver–rider channel for the lifetime of one trip. 1. Dispatch matches a driver. The app creates a 45-minute session between the driver and the rider:

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

import { Devotel } from '@devotel-orbit/node';
const orbit = new Devotel({ apiKey: process.env.ORBIT_API_KEY! });

const res = await orbit.request("POST", "/proxy/sessions", {"participant_a": "+14155550100", "participant_b": "+14155550399", "ttl_minutes": 45});

from orbit_sdk import OrbitClient
client = OrbitClient.from_env()

res = client.request("POST", "/proxy/sessions", {"participant_a": "+14155550100", "participant_b": "+14155550399", "ttl_minutes": 45})

package main
import (
	"context"
	"os"
	"github.com/devotel/orbit-go/orbit"
)

func main() {
	client, err := orbit.NewClient(os.Getenv("ORBIT_API_KEY"))
	if err != nil { panic(err) }

	reqBody0 := map[string]any{"participant_a": "+14155550100", "participant_b": "+14155550399", "ttl_minutes": 45}
	var out0 map[string]any
	err = client.Request(context.Background(), "POST", "/proxy/sessions", reqBody0, nil, &out0, "")
	if err != nil { panic(err) }
}

require "orbit_sdk"
client = OrbitSdk::Client.from_env

res = client.request("POST", "/proxy/sessions", body: {"participant_a" => "+14155550100", "participant_b" => "+14155550399", "ttl_minutes" => 45})

<?php
require __DIR__.'/vendor/autoload.php';
use Devotel\Orbit\OrbitClient;
$client = OrbitClient::fromEnv();

$res = $client->request("POST", "/proxy/sessions", ['participant_a' => '+14155550100', 'participant_b' => '+14155550399', 'ttl_minutes' => 45]);

Session status: active. A proxy.session.created webhook arrives, and the app shows both parties the proxy number +14155555678. 2. The rider texts the proxy number. The inbound message resolves to the session, the sender matches participant_b, and Orbit forwards the text to the driver with the proxy number as sender. A proxy.message.forwarded webhook records the direction. The driver replies the same way - all either side ever sees is +14155555678. 3. Drop-off completes the trip. The app closes the session:

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

import { Devotel } from '@devotel-orbit/node';
const orbit = new Devotel({ apiKey: process.env.ORBIT_API_KEY! });

const res = await orbit.request("DELETE", "/proxy/sessions/proxySession_...", undefined);

from orbit_sdk import OrbitClient
client = OrbitClient.from_env()

res = client.request("DELETE", "/proxy/sessions/proxySession_...")

package main
import (
	"context"
	"os"
	"github.com/devotel/orbit-go/orbit"
)

func main() {
	client, err := orbit.NewClient(os.Getenv("ORBIT_API_KEY"))
	if err != nil { panic(err) }

	var out0 map[string]any
	err = client.Request(context.Background(), "DELETE", "/proxy/sessions/proxySession_...", nil, nil, &out0, "")
	if err != nil { panic(err) }
}

require "orbit_sdk"
client = OrbitSdk::Client.from_env

res = client.request("DELETE", "/proxy/sessions/proxySession_...")

<?php
require __DIR__.'/vendor/autoload.php';
use Devotel\Orbit\OrbitClient;
$client = OrbitClient::fromEnv();

$res = $client->request("DELETE", "/proxy/sessions/proxySession_...");

Session status: closed. The proxy number is released back to the pool, a proxy.session.closed webhook confirms it, and neither party can reach the other afterward. 4. If the trip logic never closes — say the completion event is lost - the TTL is the backstop. At 45 minutes the sweeper marks the session expired and releases the number. The ride still ends on schedule; the close just happened later and through a different path.

Pool fairness and concurrency

Proxy sessions draw from the shared platform pool, not from the one-time free trial number assigned to your organization. There is no per-organization concurrency cap: run one session per ride, order, or listing, in parallel, without exhausting a lifetime grant. A released number - from an explicit close or a TTL sweep - returns to the pool and can be allocated to the next session, so sustained throughput scales with pool size rather than with how many sessions you have ever created.

Common errors

Status	Cause	Fix
`400 VALIDATION_ERROR`	`participant_a` and `participant_b` are the same number, `ttl_minutes` is outside 1–1440, or a participant is not E.164	Send two distinct E.164 numbers and a TTL within bounds
`404 NOT_FOUND`	The session id does not exist in your organization	Check the id from the create response; list sessions to see what exists
`409 CONFLICT`	Closing a session that is already `closed` or `expired`	Treat as already ended - do not retry the close

One race to be aware of: if your completion handler fires close to the TTL boundary, the sweeper may expire the session first and your close returns 409. That outcome is equivalent - the number is released either way - so handle a 409 on close as a successful end state.

Getting Started

Channels

Channels (Voice)

AI Agents

Campaigns

Flows

Numbers & Verify

Concepts

Features

Billing

Webhooks

Security & SSO

Compliance

Legal

Brand & press

Changelog

Number masking: keep two parties' real numbers private

Number Masking (Privacy Proxy)

Session lifecycle

Create a session

Pick a TTL by use case

List, inspect, and close sessions

Webhooks

Worked example: a ride from dispatch to drop-off

Pool fairness and concurrency

Common errors

​Number Masking (Privacy Proxy)

​Session lifecycle

​Create a session

​Pick a TTL by use case

​List, inspect, and close sessions

​Webhooks

​Worked example: a ride from dispatch to drop-off

​Pool fairness and concurrency

​Common errors

Number Masking (Privacy Proxy)

Session lifecycle

Create a session

Pick a TTL by use case

List, inspect, and close sessions

Webhooks

Worked example: a ride from dispatch to drop-off

Pool fairness and concurrency

Common errors