curl -X POST "https://api.orbit.devotel.io/api/v1/personalization/slots" \
  -H "Authorization: Bearer $SESSION_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "slot": "hero-banner",
    "segment_label": "at_risk",
    "content": "<h2>We kept your cart warm</h2><p>Finish checkout today and take 15% off.</p>",
    "cta_url": "https://shop.example.com/cart",
    "cta_text": "Resume checkout",
    "variant": "b",
    "priority": 40,
    "active": true,
    "metadata": { "experiment": "winback-q3" }
  }'

{
  "data": [
    {
      "id": "perso_01h4wka9fq",
      "slot": "hero-banner",
      "segment_label": "at_risk",
      "content": "<h2>We kept your cart warm</h2><p>Finish checkout today and take 15% off.</p>",
      "cta_url": "https://shop.example.com/cart",
      "cta_text": "Resume checkout",
      "variant": "b",
      "priority": 40,
      "active": true,
      "metadata": { "experiment": "winback-q3" },
      "created_at": "2026-08-25T10:00:00Z",
      "updated_at": "2026-08-25T10:04:00Z"
    }
  ],
  "meta": {
    "request_id": "req_slot_list",
    "timestamp": "2026-08-25T10:05:00Z",
    "pagination": {
      "cursor": null,
      "has_more": false
    }
  }
}

curl -X POST "https://api.orbit.devotel.io/api/v1/personalization/slots" \
  -H "Authorization: Bearer $SESSION_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "slot": "hero-banner",
    "segment_label": "at_risk",
    "content": "<h2>We kept your cart warm</h2><p>Finish checkout today and take 15% off.</p>",
    "cta_url": "https://shop.example.com/cart",
    "cta_text": "Resume checkout",
    "variant": "b",
    "priority": 40,
    "active": true,
    "metadata": { "experiment": "winback-q3" }
  }'

{
  "data": [
    {
      "id": "perso_01h4wka9fq",
      "slot": "hero-banner",
      "segment_label": "at_risk",
      "content": "<h2>We kept your cart warm</h2><p>Finish checkout today and take 15% off.</p>",
      "cta_url": "https://shop.example.com/cart",
      "cta_text": "Resume checkout",
      "variant": "b",
      "priority": 40,
      "active": true,
      "metadata": { "experiment": "winback-q3" },
      "created_at": "2026-08-25T10:00:00Z",
      "updated_at": "2026-08-25T10:04:00Z"
    }
  ],
  "meta": {
    "request_id": "req_slot_list",
    "timestamp": "2026-08-25T10:05:00Z",
    "pagination": {
      "cursor": null,
      "has_more": false
    }
  }
}

Personalization API

A two-sided surface:

Dashboard side (/api/v1/personalization/slots, this page) — owners and admins define content slots, variants, and rules.
SDK side (/sdk/personalize) — the customer’s website JS fetches the right variant for a given visitor / contact at runtime.

This page documents the dashboard side. Base path: /api/v1/personalization Authentication: Session JWT (owner / admin role).

Method	Path	Purpose
`GET`	`/api/v1/personalization/slots`	List slots
`POST`	`/api/v1/personalization/slots`	Create a slot
`GET`	`/api/v1/personalization/slots/{id}`	Get a slot
`PATCH`	`/api/v1/personalization/slots/{id}`	Update a slot
`DELETE`	`/api/v1/personalization/slots/{id}`	Delete a slot
`GET`	`/api/v1/personalization/slots/{slot}/preview`	Preview slot output for a sample contact

List slots

GET /api/v1/personalization/slots Page through every variant configured for the tenant, ordered by id. Filter with slot (exact placement key) and segment_label (one of the eight platform segments; an unrecognized label is ignored rather than failing the query). meta.pagination.cursor is the token for the next page — pass it back as cursor; has_more: false and a null cursor mean you have reached the end.

curl "https://api.orbit.devotel.io/api/v1/personalization/slots?slot=hero-banner&limit=25" \
  -H "Authorization: Bearer $SESSION_JWT"

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/personalization/slots?slot=hero-banner&limit=25",
  { headers: { Authorization: `Bearer ${process.env.SESSION_JWT}` } },
);
const page = await res.json();
console.log(page.data, page.meta.pagination);

import os
import requests

res = requests.get(
    "https://api.orbit.devotel.io/api/v1/personalization/slots",
    headers={"Authorization": f"Bearer {os.environ['SESSION_JWT']}"},
    params={"slot": "hero-banner", "limit": 25},
)
print(res.json()["data"], res.json()["meta"]["pagination"])

package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/personalization/slots?slot=hero-banner&limit=25", nil)
	req.Header.Set("Authorization", "Bearer "+os.Getenv("SESSION_JWT"))
	res, _ := http.DefaultClient.Do(req)
	body, _ := io.ReadAll(res.Body)
	fmt.Println(string(body))
}

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/personalization/slots?slot=hero-banner&limit=25')
req = Net::HTTP::Get.new(uri)
req['Authorization'] = "Bearer #{ENV['SESSION_JWT']}"
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/personalization/slots?slot=hero-banner&limit=25');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'Authorization: Bearer ' . getenv('SESSION_JWT'),
]);
echo curl_exec($ch);

{
  "data": [
    {
      "id": "perso_01h4wka9fq",
      "slot": "hero-banner",
      "segment_label": "at_risk",
      "content": "<h2>We kept your cart warm</h2><p>Finish checkout today and take 15% off.</p>",
      "cta_url": "https://shop.example.com/cart",
      "cta_text": "Resume checkout",
      "variant": "b",
      "priority": 40,
      "active": true,
      "metadata": { "experiment": "winback-q3" },
      "created_at": "2026-08-25T10:00:00Z",
      "updated_at": "2026-08-25T10:04:00Z"
    }
  ],
  "meta": {
    "request_id": "req_slot_list",
    "timestamp": "2026-08-25T10:05:00Z",
    "pagination": {
      "cursor": null,
      "has_more": false
    }
  }
}

Create a slot variant

POST /api/v1/personalization/slots A variant is keyed on slot + segment_label + variant, and only one active variant may exist per combination — creating a duplicate returns 409, so edit or deactivate the existing one first. Omit segment_label to define the default content every visitor sees when no segment-specific variant matches. content accepts formatting HTML; scripts, iframes, and inline event handlers are rejected with 422 because the SDK injects the markup into your site.

curl -X POST "https://api.orbit.devotel.io/api/v1/personalization/slots" \
  -H "Authorization: Bearer $SESSION_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "slot": "hero-banner",
    "segment_label": "at_risk",
    "content": "<h2>We kept your cart warm</h2><p>Finish checkout today and take 15% off.</p>",
    "cta_url": "https://shop.example.com/cart",
    "cta_text": "Resume checkout",
    "variant": "b",
    "priority": 40,
    "active": true,
    "metadata": { "experiment": "winback-q3" }
  }'

{
  "data": {
    "id": "perso_01h4wka9fq",
    "slot": "hero-banner",
    "segment_label": "at_risk",
    "content": "<h2>We kept your cart warm</h2><p>Finish checkout today and take 15% off.</p>",
    "cta_url": "https://shop.example.com/cart",
    "cta_text": "Resume checkout",
    "variant": "b",
    "priority": 40,
    "active": true,
    "metadata": { "experiment": "winback-q3" },
    "created_at": "2026-08-25T10:00:00Z",
    "updated_at": "2026-08-25T10:00:00Z"
  },
  "meta": {
    "request_id": "req_slot_001",
    "timestamp": "2026-08-25T10:00:00Z"
  }
}

Update variants and rules

PATCH /api/v1/personalization/slots/{id} Partial update — send only the fields you want to change; at least one is required. Omitted fields keep their stored values. Set active: false to stop serving a variant without deleting it; priority is the tie-breaker when several variants match the same visitor (highest wins).

curl -X PATCH "https://api.orbit.devotel.io/api/v1/personalization/slots/perso_01h4wka9fq" \
  -H "Authorization: Bearer $SESSION_JWT" \
  -H "Content-Type: application/json" \
  -d '{ "priority": 80, "active": false }'

{
  "data": {
    "id": "perso_01h4wka9fq",
    "slot": "hero-banner",
    "segment_label": "at_risk",
    "priority": 80,
    "active": false,
    "updated_at": "2026-08-25T10:04:00Z"
  },
  "meta": {
    "request_id": "req_slot_002",
    "timestamp": "2026-08-25T10:04:00Z"
  }
}

Get a slot

GET /api/v1/personalization/slots/{id} Fetch one variant by id before you edit it. Returns the full row; a 404 means no variant with that id exists on this tenant.

curl "https://api.orbit.devotel.io/api/v1/personalization/slots/perso_01h4wka9fq" \
  -H "Authorization: Bearer $SESSION_JWT"

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/personalization/slots/perso_01h4wka9fq",
  { headers: { Authorization: `Bearer ${process.env.SESSION_JWT}` } },
);
const slot = await res.json();
console.log(slot.data);

import os
import requests

res = requests.get(
    "https://api.orbit.devotel.io/api/v1/personalization/slots/perso_01h4wka9fq",
    headers={"Authorization": f"Bearer {os.environ['SESSION_JWT']}"},
)
print(res.json()["data"])

package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/personalization/slots/perso_01h4wka9fq", nil)
	req.Header.Set("Authorization", "Bearer "+os.Getenv("SESSION_JWT"))
	res, _ := http.DefaultClient.Do(req)
	body, _ := io.ReadAll(res.Body)
	fmt.Println(string(body))
}

require 'net/http'

uri = URI('https://api.orbit.devotel.io/api/v1/personalization/slots/perso_01h4wka9fq')
req = Net::HTTP::Get.new(uri)
req['Authorization'] = "Bearer #{ENV['SESSION_JWT']}"
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/personalization/slots/perso_01h4wka9fq');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'Authorization: Bearer ' . getenv('SESSION_JWT'),
]);
echo curl_exec($ch);

{
  "data": {
    "id": "perso_01h4wka9fq",
    "slot": "hero-banner",
    "segment_label": "at_risk",
    "content": "<h2>We kept your cart warm</h2><p>Finish checkout today and take 15% off.</p>",
    "cta_url": "https://shop.example.com/cart",
    "cta_text": "Resume checkout",
    "variant": "b",
    "priority": 40,
    "active": true,
    "metadata": { "experiment": "winback-q3" },
    "created_at": "2026-08-25T10:00:00Z",
    "updated_at": "2026-08-25T10:04:00Z"
  },
  "meta": {
    "request_id": "req_slot_get",
    "timestamp": "2026-08-25T10:06:00Z"
  }
}

Delete a slot

DELETE /api/v1/personalization/slots/{id} Permanently delete one variant. The SDK stops serving it immediately and falls back to the next matching active variant for that slot, or to the page’s own markup when none is left. Set active: false instead when you may want it back. Returns 204 with no body.

curl -X DELETE "https://api.orbit.devotel.io/api/v1/personalization/slots/perso_01h4wka9fq" \
  -H "Authorization: Bearer $SESSION_JWT"

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/personalization/slots/perso_01h4wka9fq",
  {
    method: "DELETE",
    headers: { Authorization: `Bearer ${process.env.SESSION_JWT}` },
  },
);
console.log(res.status); // 204

import os
import requests

res = requests.delete(
    "https://api.orbit.devotel.io/api/v1/personalization/slots/perso_01h4wka9fq",
    headers={"Authorization": f"Bearer {os.environ['SESSION_JWT']}"},
)
print(res.status_code)  # 204

package main

import (
	"fmt"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("DELETE", "https://api.orbit.devotel.io/api/v1/personalization/slots/perso_01h4wka9fq", nil)
	req.Header.Set("Authorization", "Bearer "+os.Getenv("SESSION_JWT"))
	res, _ := http.DefaultClient.Do(req)
	fmt.Println(res.Status)
}

require 'net/http'

uri = URI('https://api.orbit.devotel.io/api/v1/personalization/slots/perso_01h4wka9fq')
req = Net::HTTP::Delete.new(uri)
req['Authorization'] = "Bearer #{ENV['SESSION_JWT']}"
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.code  # "204"

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/personalization/slots/perso_01h4wka9fq');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'Authorization: Bearer ' . getenv('SESSION_JWT'),
]);
curl_exec($ch);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE);  // 204

204 No Content — the variant is deleted; no response body.

Runtime fetching is via the SDK endpoint

The slot definitions above are what the SDK serves. At runtime the embedded website JS calls /sdk/personalize (unauthenticated, project-keyed) with the visitor’s slot keys and segment context, and Orbit returns the winning variant per slot — your page then injects the returned markup. The dashboard-side endpoints on this page never carry that traffic; the SDK path is cached and rate-limited for page-view volume. Preview any slot for a sample contact before shipping it with GET /api/v1/personalization/slots/{slot}/preview.

Preview a slot before you ship it

GET /api/v1/personalization/slots/{slot}/preview This is the endpoint the POST/PATCH examples above point toward. Where /sdk/personalize is public (unauthenticated, keyed by the website project key, called by every visitor’s browser once per page view), the preview endpoint is private: an admin call you make from the dashboard or from curl with a session JWT, before you activate a variant. It runs the same resolution the SDK would — highest-priority active variant for the requested segment, falling back to the slot’s segment-less default — but against the slot definitions as configured, with no live page, no visitor, and no impression recorded.

Query parameter	Type	Purpose
`segment_label`	string (optional)	Segment to resolve as (`champion`, `high_value_engaged`, `engaged`, `new`, `passive`, `at_risk`, `dormant`, `lost`). Omit it to preview the default content every unmatched visitor gets. An unrecognized label degrades to “no segment filter” rather than failing, so a stale segment name never hides a live variant.

The response echoes what was resolved: data.slot restates the slot key, data.requested_segment is the segment that was applied (or null), and data.resolved is the winning variant row — slot, segment_label, content, cta_url, cta_text, variant. data.resolved is null when no active variant matches; that is the exact condition under which the public SDK returns nothing and your page keeps the markup it already has, so a null here is a preview of “visitors see the default page,” not an error.

cURL

curl "https://api.orbit.devotel.io/api/v1/personalization/slots/hero-banner/preview?segment_label=at_risk" \
  -H "Authorization: Bearer $SESSION_JWT"

Node.js

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/personalization/slots/hero-banner/preview?segment_label=at_risk",
  { headers: { Authorization: `Bearer ${process.env.SESSION_JWT}` } },
);
const preview = await res.json();
console.log(preview.data.resolved);

Python

import os
import requests

res = requests.get(
    "https://api.orbit.devotel.io/api/v1/personalization/slots/hero-banner/preview",
    headers={"Authorization": f"Bearer {os.environ['SESSION_JWT']}"},
    params={"segment_label": "at_risk"},
)
print(res.json()["data"]["resolved"])

package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/personalization/slots/hero-banner/preview?segment_label=at_risk", nil)
	req.Header.Set("Authorization", "Bearer "+os.Getenv("SESSION_JWT"))
	res, _ := http.DefaultClient.Do(req)
	body, _ := io.ReadAll(res.Body)
	fmt.Println(string(body))
}

Ruby

require 'net/http'

uri = URI('https://api.orbit.devotel.io/api/v1/personalization/slots/hero-banner/preview?segment_label=at_risk')
req = Net::HTTP::Get.new(uri)
req['Authorization'] = "Bearer #{ENV['SESSION_JWT']}"
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/personalization/slots/hero-banner/preview?segment_label=at_risk');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'Authorization: Bearer ' . getenv('SESSION_JWT'),
]);
echo curl_exec($ch);

{
  "data": {
    "slot": "hero-banner",
    "requested_segment": "at_risk",
    "resolved": {
      "slot": "hero-banner",
      "segment_label": "at_risk",
      "content": "<h2>We kept your cart warm</h2><p>Finish checkout today and take 15% off.</p>",
      "cta_url": "https://shop.example.com/cart",
      "cta_text": "Resume checkout",
      "variant": "b"
    }
  },
  "meta": {
    "request_id": "req_slot_preview",
    "timestamp": "2026-09-08T09:00:00Z"
  }
}

Because the data the preview returns is the same variant object /sdk/personalize hands to a real visitor, the trace stays one-to-one: set segment_label to the segment you targeted, read data.resolved.variant and data.resolved.content, and that is the variant and markup that segment will see after you flip the variant active — checked end to end without a real visitor firing an impression.

Status	`error.code`	When you see it
`401`	`UNAUTHORIZED`	Missing or expired session JWT — authenticate again.
`403`	`INSUFFICIENT_PERMISSIONS`	Your session’s role is below the read floor the route enforces; ask an owner or admin.
`404`	`NOT_FOUND`	When you addressed the preview by a slot label there is no definition for — resolve the slot once via `GET /api/v1/personalization/slots` first and use the slot key from the row.

A mismatch you should treat as a signal: the 200 above ships with data.resolved: null when nothing matches, which means the SDK will serve no markup for that segment — fix the slot or the segment label, don’t debug the visitor’s page.

Using the SDKs

The Node SDK wraps this page’s surface as orbit.personalization.* — create a slot variant with a full body, then preview what the SDK would resolve for a visitor segment. Python reaches the endpoints through the generic client.request() escape hatch; Go, Ruby, and PHP use plain HTTP clients (no SDK dependency) against the same endpoints:

curl -X POST "https://api.orbit.devotel.io/api/v1/personalization/slots" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"slot":"hero-banner","name":"Hero banner","variants":[{"segment_id":"at_risk","content":{"cta":"Resume checkout"},"weight":100}],"active":true}'

import { Orbit } from "@devotel-orbit/node";

const orbit = new Orbit({ apiKey: process.env.ORBIT_API_KEY! });

const created = await orbit.personalization.createSlot({
  slot: "hero-banner",
  name: "Hero banner",
  variants: [
    { segment_id: "at_risk", content: { cta: "Resume checkout", headline: "We kept your cart warm" }, weight: 100 },
  ],
  active: true,
});
const slotId = created.data.id;

// Preview the winning variant for a given visitor context before shipping it
const preview = await orbit.personalization.previewSlot("hero-banner", { segment_label: "at_risk" });
console.log(preview.data.resolved?.variant, preview.data.resolved?.content);

from orbit_sdk import OrbitClient

client = OrbitClient.from_env()  # reads ORBIT_API_KEY

created = client.request("POST", "/personalization/slots", json_body={
    "slot": "hero-banner",
    "name": "Hero banner",
    "variants": [
        {"segment_id": "at_risk", "content": {"cta": "Resume checkout"}, "weight": 100},
    ],
    "active": True,
})
preview = client.request("GET", "/personalization/slots/hero-banner/preview?segment_label=at_risk")
resolved = preview["data"]["resolved"]  # the variant dict, or None when nothing matches

package main

import (
	"bytes"
	"fmt"
	"net/http"
	"os"
)

func main() {
	body := []byte(`{"slot":"hero-banner","name":"Hero banner","variants":[{"segment_id":"at_risk","content":{"cta":"Resume checkout"},"weight":100}],"active":true}`)
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/personalization/slots", bytes.NewBuffer(body))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	res, _ := http.DefaultClient.Do(req)
	fmt.Println(res.Status)
}

require 'net/http'
require 'json'

body = {
  slot: "hero-banner",
  name: "Hero banner",
  variants: [{ segment_id: "at_risk", content: { cta: "Resume checkout" }, weight: 100 }],
  active: true
}.to_json

uri = URI('https://api.orbit.devotel.io/api/v1/personalization/slots')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = body
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/personalization/slots');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"slot":"hero-banner","name":"Hero banner","variants":[{"segment_id":"at_risk","content":{"cta":"Resume checkout"},"weight":100}],"active":true}');
echo curl_exec($ch);

The Python SDK is core-scope — it wraps the 8 core resources (messaging, voice, contacts, campaigns, verify, numbers) and reaches this page’s surface through the generic client.request() escape hatch above. See the Python SDK. Returns the typed ApiResponse envelope. See the SDK index at SDK quickstart.

API Reference

All Endpoints

Personalization API: web SDK content slot definitions

Personalization API

List slots

Create a slot variant

Update variants and rules

Get a slot

Delete a slot

Runtime fetching is via the SDK endpoint

Preview a slot before you ship it

Using the SDKs

See also

​Personalization API

​List slots

​Create a slot variant

​Update variants and rules

​Get a slot

​Delete a slot

​Runtime fetching is via the SDK endpoint

​Preview a slot before you ship it

​Using the SDKs

​See also

Personalization API

List slots

Create a slot variant

Update variants and rules

Get a slot

Delete a slot

Runtime fetching is via the SDK endpoint

Preview a slot before you ship it

Using the SDKs

See also