Personalization

Worked personalization samples

The endpoint list below documents every operation’s parameters; this overlay walks a slot the way a tenant’s frontend actually uses it: list the slots → read one variant → update it → handle the duplicate-variant conflict. Success envelopes are { data, meta }, error envelopes { error, meta } — see How to read a worked sample. The platform accepts both a sandbox (dv_test_sk_*) key and a live key; the write paths (create/update/delete) require owner or admin, while the list/get/preview paths are just read. Every response carries meta.request_id. Quote it when you report a slot serving the wrong variant — support traces the routing end-to-end from the request id and the recompute tick.

1. List personalization slots

GET /api/v1/personalization/slots returns the slot variants configured for this tenant, ordered by id and paginated with a cursor. Filter by slot to inspect a single placement or by segment_label to see what one audience is served. An unknown segment label is treated as no filter, so a renamed segment still returns a row.

curl -X GET \
  "https://api.orbit.devotel.io/api/v1/personalization/slots?slot=hero-banner" \
  -H "X-API-Key: dv_test_sk_YOUR_KEY"

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/personalization/slots?slot=hero-banner",
  {
    headers: { "X-API-Key": process.env.ORBIT_API_KEY! },
  },
);
console.log(await res.json());

200

{
  "data": {
    "slots": [
      {
        "id": "slot_8fb2d1b7c00c4ec9",
        "slot": "hero-banner",
        "segment_label": "enterprise",
        "content": "<h1>Welcome back</h1><p>Your plan includes priority support.</p>",
        "cta_url": "https://brand.example/billing",
        "cta_text": "Open billing",
        "variant": "control",
        "priority": 0,
        "active": true
      }
    ],
    "pagination": { "cursor": null, "has_more": false }
  },
  "meta": {
    "request_id": "req_psn_list",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

2. Read one variant

GET /api/v1/personalization/slots/{id} returns a single slot variant: content, CTA link and label, target segment, variant name, priority, active flag, and metadata. Use it to hydrate the slot edit form before a PATCH.

curl -X GET \
  "https://api.orbit.devotel.io/api/v1/personalization/slots/slot_8fb2d1b7c00c4ec9" \
  -H "X-API-Key: dv_test_sk_YOUR_KEY"

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/personalization/slots/slot_8fb2d1b7c00c4ec9",
  {
    headers: { "X-API-Key": process.env.ORBIT_API_KEY! },
  },
);
console.log(await res.json());

3. Update a variant’s copy

PATCH /api/v1/personalization/slots/{id} is the in-place update the sdk/personalize endpoint draws from — send only the fields you are changing. An omitted field keeps its stored value, so a copy edit never silently re-ranks a variant or re-enables a stopped one. Set active: false to stop serving a variant without deleting the row.

curl -X PATCH \
  "https://api.orbit.devotel.io/api/v1/personalization/slots/slot_8fb2d1b7c00c4ec9" \
  -H "X-API-Key: dv_test_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "content": "<h1>Welcome back</h1><p>Priority support is now on your plan.</p>",
  "cta_text": "Manage billing"
}'

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/personalization/slots/slot_8fb2d1b7c00c4ec9",
  {
    method: "PATCH",
    headers: {
      "X-API-Key": process.env.ORBIT_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      content:
        "<h1>Welcome back</h1><p>Priority support is now on your plan.</p>",
      cta_text: "Manage billing",
    }),
  },
);
console.log(await res.json());

200

{
  "data": {
    "id": "slot_8fb2d1b7c00c4ec9",
    "slot": "hero-banner",
    "content": "<h1>Welcome back</h1><p>Priority support is now on your plan.</p>",
    "cta_text": "Manage billing",
    "priority": 0,
    "active": true
  },
  "meta": {
    "request_id": "req_psn_update",
    "timestamp": "2026-08-26T12:01:00.000Z"
  }
}

content is re-checked on update against the same HTML rules as create — script execution, iframes, and event handlers are rejected.
priority 0–100 ranks variants inside one (slot, segment_label, variant) tuple; an update that leaves priority untouched never re-materializes it to the schema default.

4. Errors

Errors follow the { error, meta } envelope. Two failures every admin hits: 409 — duplicate variant. The triple (slot, segment_label, variant) must be unique. Creators hitting this should PATCH the existing row instead of POSTing a new one. 422 — rejected markup. The sanitizer rejected the content, or the update body was empty:

422

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Personalization content rejected: inline scripts are blocked.",
    "status": 422
  },
  "meta": {
    "request_id": "req_psn_err",
    "timestamp": "2026-08-26T12:02:00.000Z"
  }
}

API Reference

All Endpoints

Worked personalization samples

1. List personalization slots

2. Read one variant

3. Update a variant’s copy

4. Errors

​Worked personalization samples

​1. List personalization slots

​2. Read one variant

​3. Update a variant’s copy

​4. Errors

Worked personalization samples

1. List personalization slots

2. Read one variant

3. Update a variant’s copy

4. Errors