Skip to main content

​
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. That is a core requirement in ride-share (driver and rider), delivery (courier and customer), marketplace (buyer and seller), and healthcare (provider and patient) flows, where both sides must reach each other without exchanging personal contact information.

​
How it works

  1. Create a session naming the two participants (E.164 numbers) and an optional TTL (default 60 minutes, up to 24 hours).
  2. Orbit allocates a proxy number from the shared platform pool and links the session to it.
  3. Inbound messages to the proxy number are resolved to the session, matched against the participants, and forwarded to the other party with the proxy number as sender. Neither party ever sees a real number.
  4. When the session closes (explicitly or when the TTL expires), the proxy number is released back to the pool and can be reused by the next session.
Sessions that hit their TTL without an explicit close are swept by a scheduled job, and the number is released in the same sweep - so a forgotten session never locks a number permanently.

​
Create a session

The response returns the session id and the allocated proxy_number. Hand that number to both participants and route all traffic through it:
The two participants must be different numbers, otherwise the request returns a 400. ttl_minutes accepts values from 1 to 1440 (24 hours).

​
List and inspect sessions

Listing uses cursor pagination - pass limit (max 100) and follow the returned pagination.cursor for more pages.

​
Close a session

Closing a session releases its proxy number back to the pool immediately:
Only an active session can be closed; closing an already closed or expired session returns a conflict (409). You don’t need to close sessions that you let expire - the scheduled sweeper handles those.

​
Webhooks

Register a webhook endpoint subscribed to the proxy events to track the session lifecycle and forwarding:
  • 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.
See the webhook consumer guide for endpoint registration and delivery semantics.

​
Pool numbering and fairness

Proxy sessions draw from the shared platform pool, not from the one-time free trial number assigned to your organization. That means an org can run any number of concurrent sessions - one per order, ride, or listing - without exhausting a lifetime grant. A released number returns to the pool and can serve the next session.