​

Pin, lock, and run a governed data-residency migration

​

The org-wide pin surface, and what it does not cover

​

Step order: read → pin → verify → lock

​

The four refusal codes, walked in the sequence

​

When the per-plane reads need explicit confirmation

​

The governed migration sequence

1. Announce and document. Record the reason for the migration, the target region, and the sign-off (customer contract, regulatory driver, or procurement change) before any API call. The unlock and re-pin will land in the audit log on both sides; the officer’s written justification is the only narrative between them.
2. Unlock the pin. POST /compliance/data-residency/unlock with a { "notes": "…" } body naming the reason. The call records the change only — it performs no data movement and wires no carrier. That distinction is load-bearing for audit: the surface records policy, and the audit log reads as a governance ledger.
3. Re-pin the target. PUT the new region with enforced: true and a justification that names the migration. Same-region enforcement (enforced: true → enforced: true) is also allowed on a locked pin if you ever need to refresh the justification without unlocking.
4. Run the data-plane migration out-of-band. Moving bytes between regions is a service-operations step, not part of this surface — contact Devotel to schedule it. Until the bytes move, the planes that do not follow the pin report the gap honestly in the matrix (residentRegion stays on the actual store region and the plane’s note says so).
5. Re-lock. POST /compliance/data-residency/lock with notes referencing the migration ticket. Re-read the GET and confirm data.config.locked: true and data.config.region now name the new boundary — the sequence ends in the state you want, not the state the unlock left behind.

​

Worked cURL for each step

export BASE="https://api.orbit.devotel.io/api/v1"
export KEY="X-API-Key: dv_live_sk_..."

curl -s -H "$KEY" "$BASE/compliance/data-residency"

curl -X PUT "$BASE/compliance/data-residency" \
  -H "$KEY" -H "Content-Type: application/json" \
  -d '{
    "region": "eu",
    "enforced": true,
    "justification": "EU umbrella customer — GDPR Art. 44 boundary contract"
  }'

curl -s -H "$KEY" "$BASE/compliance/data-residency"

curl -X POST "$BASE/compliance/data-residency/lock" \
  -H "$KEY" -H "Content-Type: application/json" \
  -d '{ "notes": "Freeze EU boundary ahead of ISO27001 renewal audit." }'

# 1. Unlock (audited governance event — records the change only)
curl -X POST "$BASE/compliance/data-residency/unlock" \
  -H "$KEY" -H "Content-Type: application/json" \
  -d '{ "notes": "Governed migration: uk → eu per customer contract amendment 2026-03" }'

# 2. Re-pin the target region (still enforced)
curl -X PUT "$BASE/compliance/data-residency" \
  -H "$KEY" -H "Content-Type: application/json" \
  -d '{
    "region": "eu",
    "enforced": true,
    "justification": "Customer contract amendment 2026-03 — migrate from UK nest to EU umbrella"
  }'

# 3. Confirm the new posture before re-locking
curl -s -H "$KEY" "$BASE/compliance/data-residency"

# 4. Re-lock — audit the lock with the migration ticket reference
curl -X POST "$BASE/compliance/data-residency/lock" \
  -H "$KEY" -H "Content-Type: application/json" \
  -d '{ "notes": "Re-lock after UK→EU migration ticket MIG-2026-031 complete." }'

# Messaging plane read — check storedAndProcessedInRegion
curl -s -H "$KEY" "$BASE/messaging/data-residency"

# CDP plane read — the four-ingest-surface matrix
curl -s -H "$KEY" "$BASE/cdp/data-residency"

​

See also

• Data residency overview — which surface answers which channel’s residency question, including the messaging subprocessor answer.
• Voice data residency — the workspace voice-region pin that covers recordings, voicemail, and live media. Set beside the org-wide pin; never instead of it.
• Messaging data residency — the concept behind GET /messaging/data-residency and the composed storedAndProcessedInRegion verdict.
• Troubleshooting: RESIDENCY_* errors — the reference for each refusal code and what to bundle for support.
• Data placement and residency — the WHERE-isolation vs. WHERE-geographic vs. region-of-compute concept this pin composes with.