Segments API

Segments endpoints exposed by the Devotel CPaaS API Base path: /api/v1 Endpoint count: 2

Build a segment from a natural-language description (AI)

POST /api/v1/contacts/segments/autopilot

Translate a natural-language audience description into structured Orbit segment rules and return them together with a live preview match-count and sample contacts, in a single round-trip. The proposed rules are constrained to the segmentation engine’s allowlisted fields, validated with a dry-run before the preview, and returned in both the dashboard’s flat rule shape and the normalised FilterAst the engine consumes. Requires the contacts:write scope (owner / admin / developer). Returns 503 SERVICE_UNAVAILABLE when the AI backend is not configured for the platform; callers should fall back to the manual segment builder.

string

required

Natural-language description of the audience to build (e.g. “customers in Germany who opened an email in the last 30 days”). The handler asks the LLM to translate it into structured segment rules constrained to the segmentation engine’s allowlisted fields.

integer

Maximum number of sample contacts returned in preview.sample_contacts. Keeps the payload bounded — the dashboard renders only the first 10.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/contacts/segments/autopilot" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "description": "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/contacts/segments/autopilot', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "description": "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/contacts/segments/autopilot", headers=headers, json={
  "description": "string"
})
print(r.json())

package main

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

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/contacts/segments/autopilot", bytes.NewBuffer([]byte(`{
  "description": "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/contacts/segments/autopilot')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {
  "description": "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/contacts/segments/autopilot');
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
{
  "description": "string"
}
JSON);
echo curl_exec($ch);

Export an ad-hoc audience as CSV

POST /api/v1/segments/export.csv

Resolve an ad-hoc audience — an unsaved segment filter AST, the same shape the segment builder and POST /api/v1/segments/auto-suggest produce — live against the tenant’s contacts and download the matched rows as an RFC-4180 CSV attachment, without first persisting or materialising a segment. PII columns (phone, email) honour the caller’s role + reveal context. Requires the contacts:write scope (owner / admin / developer). Hard-capped at 50,000 rows; a truncated export sets the X-Export-Truncated: true response header. The saved-segment equivalent is GET /api/v1/contacts/segments/{id}/export.csv.

object

required

The audience definition — the same FilterAst the segment builder and auto-suggest speak (a single condition or a nested AND/OR group). Validated server-side against the field allowlist + depth cap.

integer

Optional row cap below the 50,000-row hard ceiling (e.g. for a quick sample). Clamped server-side.

string

Optional filename stem for the download. Sanitised so it cannot break the Content-Disposition header.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/segments/export.csv" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "filters": {}
}'

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/segments/export.csv', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "filters": {}
}),
})
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/segments/export.csv", headers=headers, json={
  "filters": {}
})
print(r.json())

package main

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

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/segments/export.csv", bytes.NewBuffer([]byte(`{
  "filters": {}
}`)))
	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/segments/export.csv')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {
  "filters": {}
}.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/segments/export.csv');
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
{
  "filters": {}
}
JSON);
echo curl_exec($ch);

API Reference

All Endpoints

Segments API

Segments API

Build a segment from a natural-language description (AI)

Export an ad-hoc audience as CSV

​Segments API

​Build a segment from a natural-language description (AI)

​Export an ad-hoc audience as CSV

Segments API

Build a segment from a natural-language description (AI)

Export an ad-hoc audience as CSV