> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Data placement and residency

> One answer to 'where does my data live': tenant isolation is the WHERE boundary, the residency pin is the WHERE-GEOGRAPHICALLY choice, and region-of-compute covers API ingress and voice media — and how to read all three before you certify a posture.

# 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](/concepts/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](/concepts/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](/compliance/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](/concepts/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](/concepts/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](/compliance/posture-overview): 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](/concepts/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.

<Note>
  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.
</Note>

## Cross-references

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