Skip to main content

​
Data placement and residency

“Where does my data live?” sounds like one question. On Orbit it is three, each answered by a different control with a different scope:
  1. Where — which database holding is my data in? Tenant isolation: schema-per-tenant, the hard boundary that separates your data from every other organization’s data.
  2. Where geographically — in which region do my bytes rest and get processed? The residency pin: your org-level, tenant-owned region choice.
  3. Region of compute — which region handles the traffic in flight? API ingress processing plus the voice media plane (recordings, voicemail, live media).
A buyer answering a questionnaire — or a registrar auditing your posture — needs all three, and this page is the single concept that consults them. Each individual control has its own page (linked section by section); this page binds them into one model with one worked read flow.

​
Section 1 — The split: WHERE vs WHERE-GEOGRAPHICALLY vs REGION-OF-COMPUTE

WHERE — tenant-schema isolation. Every organization’s working data lives in its own PostgreSQL schema, and the API resolves which schema a request belongs to server-side from your API key — never from a client-supplied tenant_id. Isolation is unconditional: it holds with no pin set, and it cannot be widened or relaxed by configuration. The full mechanism — the public catalog vs. per-tenant schema split, the request-resolution chain, and sibling-subaccount ownership gating — is Tenant isolation. WHERE-GEOGRAPHICALLY — the residency pin. Within your already-isolated schema, you choose which geographic region your data is pinned to. That choice is a tenant-owned control: you set it, you enforce it, you lock it, and you document it — the platform records and reports it, the decision is yours. The messaging data plane projects this pin into a read next to sender pools and messaging services; the full control — region catalog, advisory vs. enforced pins, and the composed storedAndProcessedInRegion verdict — is Messaging data residency. REGION-OF-COMPUTE — API ingress and voice media. Two compute axes sit alongside the storage story. First, API ingress: the region your API requests are actually processed in, compared against your pin and reported per request on the messaging residency read’s api_region block. Second, voice: call recordings, voicemail, and live media follow a separate workspace voice-region pin, because voice media runs on its own region-pinned media plane. The voice control, its in-region guarantee, and its retention behavior are Voice data residency. The three axes are complementary, never substitutes: isolation answers whose boundary protects the data, the residency pin answers which region it rests in, and the compute axes answer which region handles it in flight. Isolation is the precondition that gives a pin content — a region choice is only meaningful once your data is already separated from everyone else’s.

​
Section 2 — The two answers a buyer or registrar actually needs

When a questionnaire or a register entry asks “where is our data?”, two concrete verdicts answer it, and both are tenant-readable: Messaging — the storedAndProcessedInRegion verdict. Read GET /v1/messaging/data-residency and take two fields: pinnedRegion (the enforced region, or null when nothing is enforced) and storedAndProcessedInRegion — true only when the pin is enforced and targets the region where message bytes genuinely rest and are processed today. The platform stores and processes message data in the EU, so an enforced EU pin reads true; any other pin reads false and reports the gap rather than implying a guarantee. The api_region block on the same read adds the compute axis: whether the API pod processing your requests coincides with your pinned region (inRegion) and whether the region-pinned ingress endpoint is serving today (targetApiEndpointLive). Voice — the workspace voice-region verdict. Recordings, voicemail, and live media do not follow the org pin; they follow the workspace voice-region pin. Read GET /v1/voice/regions/preferred and take two fields: preferred — your saved setting (auto, eu, or us) — and resolved, the region your calls actually land in right now. When preferred is explicit the two match; when it is auto, resolved is where auto-selection currently maps you, which is not a residency answer you can certify against a fixed region. A register entry that names only one of these two answers is half a posture — messaging data and voice data are covered by separate controls, and neither covers the other.

​
Section 3 — The read + lock flow: advisory pin → enforced pin → RESIDENCY_LOCKED guard

The residency control has a deliberate three-step posture, documented in full on Messaging data residency:
  1. Advisory pin. PUT /v1/compliance/data-residency with enforced: false records your intent against a region. This is the right state while a region is in preview — enforcement of a preview region is refused (409 RESIDENCY_REGION_UNAVAILABLE) because the platform will not claim an at-rest guarantee it cannot keep, but the advisory pin registers where your data needs to land.
  2. Enforced pin. PUT /v1/compliance/data-residency with enforced: true on an available region — the EU is the one region live today. An enforced EU pin also flips storedAndProcessedInRegion on the messaging read to true.
  3. Locked pin. POST /v1/compliance/data-residency/lock gates the pin behind a deliberate unlock. From this point any further region change is refused with 409 RESIDENCY_LOCKED until you call .../unlock first — the guard that keeps data already written under the pin from being silently re-homed, and the state a register entry should reference if the recorded posture must not drift.
Every write above requires an owner or admin API key and lands in your audit log.

​
Section 4 — Multi-brand organizations: one pin per org

The residency pin is set per organization, and one pin covers every messaging data plane of that org at once — there is no per-channel or per-sender knob to keep in sync. A family of subaccounts under one reseller parent cannot share an org pin, and the reason is the tenant-isolation boundary: a subaccount is a separate org with its own row in the organizations catalog, not a namespace inside the parent’s residency config. The parent’s pin configures the parent’s org. Each subaccount’s pin is set independently on that subaccount’s own compliance surface, and each org’s audit log records who set its own pin. A multi-brand operator answers a register entry per org — read each org’s messaging endpoint, never assume the parent’s pin projects onto the children. (Sibling subaccounts do share the parent’s tenant schema — that is the isolation side of the boundary, gated by org ownership per Tenant isolation. Sharing a schema does not share a residency pin; the two settings live in different layers precisely so one boundary cannot silently widen the other.)

​
Section 5 — Worked posture: read before you certify

Residency is one of the tenant-owned controls in your compliance posture: Orbit provides the surface, you own the decision and its documentation. Before you certify a workspace’s residency posture in a register or answer a questionnaire, walk this checklist (it mirrors Section 5 of Messaging data residency, extended with the voice and lock axes):
  1. Read the messaging endpoint (GET /v1/messaging/data-residency) and check pinnedRegion, enforced, and storedAndProcessedInRegion. A false storedAndProcessedInRegion means either the pin is advisory-only or it targets a region where message data does not rest and get processed today — resolve which before you certify.
  2. Check the api_region block on the same read if you care about where API calls are processed, not only where data rests. inRegion: false or targetApiEndpointLive: false tells you the request path is still cross-region even when the at-rest story is settled.
  3. Read the voice workspace region (GET /v1/voice/regions/preferred) and check preferred and resolved. auto is not a certifiable residency answer — pin an explicit region if the register entry names one, and remember that a region change affects new calls only: recordings already written stay where they were stored.
  4. Check the lock state if you rely on the pin as a frozen answer. An unlocked enforced pin can still be moved by an owner or admin; lock it if the register entry must not drift, and cite the 409 RESIDENCY_LOCKED guard as the freeze mechanism.
  5. Record the plain-language notes the endpoints return per plane — they are written for exactly this register entry, so quote them rather than paraphrasing.
The residency surfaces are placement-policy reads and writes. They perform no outbound traffic of their own and gate no sending — configure them deliberately and document the reading you settle on.

​
Cross-references

  • Tenant isolation — the hard schema-per-tenant boundary (the WHERE) that a residency pin composes with.
  • Messaging data residency — the org-level pin, the composed verdict, and the lock flow in full (the WHERE-GEOGRAPHICALLY).
  • Voice data residency — the workspace voice-region pin for recordings, voicemail, and live media (the voice compute axis).
  • Data residency overview — the map of which surface answers which channel’s residency question.
  • Compliance posture overview — where tenant-owned residency controls fit in your overall posture.