Personalization API

Personalization endpoints exposed by the Devotel CPaaS API Base path: /api/v1/personalization/slots Endpoint count: 7

List personalization slots

GET /api/v1/personalization/slots

List the personalization 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. Use it to populate the personalization table in the dashboard or to audit which content the web SDK can render. A segment_label the platform does not recognise is treated as no filter, so a renamed segment still returns every variant instead of failing the page.

string

Return only variants for this slot key (exact match), e.g. hero-banner.

string

Return only variants targeted at this segment (champion, high_value_engaged, engaged, new, passive, at_risk, dormant, lost). Unrecognised values are ignored.

string

Page token — pass meta.pagination.cursor from the previous response to fetch the next page.

integer

Number of variants per page (1–100).

string (enum: true|false)

Sandbox opt-in for Clerk-session-authenticated requests. Set to true to route the call through the test-mode pipeline: no real provider delivery, no credits deducted, response meta.test_mode: true. Ignored for live API keys (dv_live_sk_*) — server-to-server clients must use a test-prefixed key (dv_test_sk_*) to exercise sandbox. Test-prefixed keys unconditionally enable sandbox regardless of this header.

cURL

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

Node.js

import { Orbit } from '@devotel-orbit/node'

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

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

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.get("https://api.orbit.devotel.io/api/v1/personalization/slots", headers=headers)
print(r.json())

package main

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

func main() {
	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/personalization/slots", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))

	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/personalization/slots')
req = Net::HTTP::Get.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']


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');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),

]);

echo curl_exec($ch);

{
  "data": [
    {}
  ],
  "meta": {}
}

Get a personalization slot

GET /api/v1/personalization/slots/{id}

Fetch a single personalization slot variant by id, including its content, CTA link and label, target segment, variant name, priority, active flag and metadata. Use it to hydrate the edit form before an update. Returns 404 when no variant with that id exists in this tenant.

string

required

Slot-variant id (perso_ + 32 hex characters), as returned by create or list.

string (enum: true|false)

cURL

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

Node.js

import { Orbit } from '@devotel-orbit/node'

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

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

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.get("https://api.orbit.devotel.io/api/v1/personalization/slots/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3", headers=headers)
print(r.json())

package main

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

func main() {
	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/personalization/slots/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))

	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/personalization/slots/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3')
req = Net::HTTP::Get.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']


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/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),

]);

echo curl_exec($ch);

{
  "data": {},
  "meta": {}
}

Report lift for a personalization slot

GET /api/v1/personalization/slots/{slot}/lift

Compare two variants of a slot on the traffic each one actually received and report which converts better. Pass the baseline arm as variant_a — use __default__ to make the segment’s untagged fallback content the baseline, the closest this feature has to a holdout — the variant under test as variant_b, and the event name that counts as a conversion. Impressions come from the personalization events the web and mobile SDKs already send on every render, so nothing new has to be instrumented. The report returns each arm’s impressions, conversions and conversion rate, the absolute and relative lift, a 95% confidence interval, a z-score, a p-value and whether the difference is significant. state is no_traffic while neither arm has been served and collecting while only one has, and the statistical fields stay null until both arms have traffic. A segment_label the platform does not recognise is treated as no filter.

string

required

Slot key to report on, e.g. hero-banner.

string

required

Baseline arm — a variant name, or __default__ for the segment’s untagged default content.

string

required

Treatment arm — the variant under test. Must differ from variant_a, otherwise the request is rejected.

string

required

Name of the SDK event that counts as a conversion, e.g. clicked_cta or purchase.

string

Report only on visitors in this segment (champion, high_value_engaged, engaged, new, passive, at_risk, dormant, lost). Unrecognised values are ignored.

integer

Lookback window in days (1–365).

string (enum: true|false)

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/personalization/slots/{slot}/lift" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel-orbit/node'

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

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

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.get("https://api.orbit.devotel.io/api/v1/personalization/slots/{slot}/lift", headers=headers)
print(r.json())

package main

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

func main() {
	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/personalization/slots/{slot}/lift", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))

	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/personalization/slots/{slot}/lift')
req = Net::HTTP::Get.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']


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/{slot}/lift');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),

]);

echo curl_exec($ch);

{
  "data": {},
  "meta": {}
}

Preview a personalization slot

GET /api/v1/personalization/slots/{slot}/preview

Resolve a slot exactly as the public SDK endpoint would for a visitor in a given segment, without publishing anything or loading a live page. The highest-priority active variant targeted at segment_label wins; when none matches, the slot’s segment-less default is used. Use it to check a new variant before you activate it.

string

required

Slot key to resolve, e.g. hero-banner.

string

Segment to preview as (champion, high_value_engaged, engaged, new, passive, at_risk, dormant, lost). Omit it to preview the default content; unrecognised values are treated the same way.

string (enum: true|false)

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/personalization/slots/{slot}/preview" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel-orbit/node'

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

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

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.get("https://api.orbit.devotel.io/api/v1/personalization/slots/{slot}/preview", headers=headers)
print(r.json())

package main

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

func main() {
	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/personalization/slots/{slot}/preview", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))

	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/personalization/slots/{slot}/preview')
req = Net::HTTP::Get.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']


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/{slot}/preview');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),

]);

echo curl_exec($ch);

{
  "data": {},
  "meta": {}
}

Create a personalization slot

POST /api/v1/personalization/slots

Define the content the web SDK renders into a slot (for example hero-banner or cart-empty) for one audience segment. 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, inline event handlers and javascript: or non-image data: URLs are rejected with 422 because the SDK injects the markup into your site. Owner or admin only.

string

Stripe-style idempotency token. Pass a stable, client-generated value (1-255 chars) to dedupe retries on transient timeouts. The same key+credential+path replays the original response for 24h on 2xx (5min on 4xx, 30s on 5xx). Returns 409 if a concurrent request with the same key is already in flight; replayed responses include the Idempotency-Replay: true response header.

string (enum: true|false)

string

required

Slot key the SDK asks for on the page — lowercase letters, digits, hyphen or underscore.

Audience segment this variant targets. Leave null for the default content shown to everyone else.

string

required

Markup or text rendered into the slot (up to 5,000 characters). Formatting HTML only — scripts, iframes and inline event handlers are rejected.

string | null

Destination the call to action links to (http or https), if any.

string | null

Label for the call-to-action button or link.

string | null

Variant name for A/B testing (for example b). Report on it with the slot lift endpoint.

integer

Tie-breaker when several variants match the same visitor — highest wins. Defaults to 0.

boolean

Whether the SDK may serve this variant. Defaults to true.

object | null

Free-form key/value data stored alongside the variant.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/personalization/slots" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "slot": "string",
  "content": "string"
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/personalization/slots', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "slot": "string",
  "content": "string"
}),
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
headers["Content-Type"] = "application/json"
r = requests.post("https://api.orbit.devotel.io/api/v1/personalization/slots", headers=headers, json={
  "slot": "string",
  "content": "string"
})
print(r.json())

package main

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

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/personalization/slots", bytes.NewBuffer([]byte(`{
  "slot": "string",
  "content": "string"
}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require '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 = {
  "slot": "string",
  "content": "string"
}.to_json
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');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
{
  "slot": "string",
  "content": "string"
}
JSON);
echo curl_exec($ch);

{
  "data": {},
  "meta": {}
}

Update a personalization slot

PATCH /api/v1/personalization/slots/{id}

Update a personalization slot variant in place — send only the fields you want to change; at least one is required. Omitted fields keep their stored values, so editing the copy never silently re-ranks a variant or brings a paused one back. Set active to false to stop serving a variant without deleting it. Updated content is re-checked against the same markup rules as create. Owner or admin only; returns 404 when no variant with that id exists in this tenant.

string

required

Slot-variant id (perso_ + 32 hex characters), as returned by create or list.

string (enum: true|false)

string

Move the variant to a different slot key.

Retarget the variant at another segment, or null for the default content.

string

Replacement markup or text for the slot.

string | null

New call-to-action destination (http or https), or null to clear.

string | null

New call-to-action label, or null to clear.

string | null

New variant name, or null to clear.

integer

New tie-breaker rank (0–100) — highest wins.

boolean

Set false to stop serving the variant, true to resume.

object | null

Replacement free-form key/value data.

cURL

curl -X PATCH "https://api.orbit.devotel.io/api/v1/personalization/slots/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/personalization/slots/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3', {
  method: 'PATCH',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
headers["Content-Type"] = "application/json"
r = requests.patch("https://api.orbit.devotel.io/api/v1/personalization/slots/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3", headers=headers, json={})
print(r.json())

package main

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

func main() {
	req, _ := http.NewRequest("PATCH", "https://api.orbit.devotel.io/api/v1/personalization/slots/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3", bytes.NewBuffer([]byte(`{}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/personalization/slots/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3')
req = Net::HTTP::Patch.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {}.to_json
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/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PATCH');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
{}
JSON);
echo curl_exec($ch);

{
  "data": {},
  "meta": {}
}

Delete a personalization slot

DELETE /api/v1/personalization/slots/{id}

Permanently delete a personalization slot variant. The SDK stops serving it immediately and falls back to the next matching active variant for that slot, or to the markup already on your page when none is left. Deactivate the variant instead when you may want it back. Owner or admin only; returns 404 when no variant with that id exists in this tenant.

string

required

Slot-variant id (perso_ + 32 hex characters), as returned by create or list.

string (enum: true|false)

cURL

curl -X DELETE "https://api.orbit.devotel.io/api/v1/personalization/slots/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/personalization/slots/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3', {
  method: 'DELETE',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
headers["Content-Type"] = "application/json"
r = requests.delete("https://api.orbit.devotel.io/api/v1/personalization/slots/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3", headers=headers, json={})
print(r.json())

package main

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

func main() {
	req, _ := http.NewRequest("DELETE", "https://api.orbit.devotel.io/api/v1/personalization/slots/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3", bytes.NewBuffer([]byte(`{}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/personalization/slots/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3')
req = Net::HTTP::Delete.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {}.to_json
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/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
{}
JSON);
echo curl_exec($ch);

Response: 204 No Content

API Reference

All Endpoints

Personalization API

Personalization API

List personalization slots

Get a personalization slot

Report lift for a personalization slot

Preview a personalization slot

Create a personalization slot

Update a personalization slot

Delete a personalization slot

​Personalization API

​List personalization slots

​Get a personalization slot

​Report lift for a personalization slot

​Preview a personalization slot

​Create a personalization slot

​Update a personalization slot

​Delete a personalization slot

Personalization API

List personalization slots

Get a personalization slot

Report lift for a personalization slot

Preview a personalization slot

Create a personalization slot

Update a personalization slot

Delete a personalization slot