Search

Global search — worked samples

One POST replaces the N parallel per-surface searches a client would otherwise fan out itself: the query is multiplexed against every product pillar in a single request, and the response comes back ranked across all of them. This is the endpoint behind the dashboard’s global search palette — use it the same way when building a custom search widget.

Request fields

Field	Type	Notes
`query`	string	Required. 1–200 characters.
`pillars`	array of enum	Optional. Any of `contacts`, `conversations`, `tickets`, `agents`, `calls`, `numbers`, `segments` (max 8 entries). Omit (or send `[]`) to query every pillar; send a subset to scope the search.
`per_pillar_limit`	integer	Optional. 1–10, default 5. Caps how many matches each pillar returns.
`static_match_count`	integer	Optional. 0–100, default 0. The count of non-pillar matches your client already rendered for this query (page, setting, or help-article shortcuts); folded into the recorded result count so successful searches are not mis-counted as zero-result. Palette callers should always send it.

Multi-pillar query across all seven pillars

curl -X POST "https://api.orbit.devotel.io/api/v1/search/global" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "ady",
    "pillars": ["contacts", "conversations", "tickets", "agents", "calls", "numbers", "segments"],
    "per_pillar_limit": 5,
    "static_match_count": 2
  }'

const res = await fetch("https://api.orbit.devotel.io/api/v1/search/global", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.ORBIT_API_KEY!,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    query: "ady",
    pillars: [
      "contacts",
      "conversations",
      "tickets",
      "agents",
      "calls",
      "numbers",
      "segments",
    ],
    per_pillar_limit: 5,
    static_match_count: 2,
  }),
});
const body = await res.json();
for (const hit of body.data.results) {
  console.log(hit.pillar, hit.title, hit.href, hit.score);
}

import os, requests

r = requests.post(
    "https://api.orbit.devotel.io/api/v1/search/global",
    headers={"X-API-Key": os.environ["ORBIT_API_KEY"]},
    json={
        "query": "ady",
        "pillars": ["contacts", "conversations", "tickets", "agents", "calls", "numbers", "segments"],
        "per_pillar_limit": 5,
        "static_match_count": 2,
    },
)
for hit in r.json()["data"]["results"]:
    print(hit["pillar"], hit["title"], hit["href"])

package main

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

func main() {
	payload, _ := json.Marshal(map[string]interface{}{
		"query": "ady",
		"pillars": []string{
			"contacts", "conversations", "tickets", "agents", "calls", "numbers", "segments",
		},
		"per_pillar_limit":  5,
		"static_match_count": 2,
	})
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/search/global", bytes.NewReader(payload))
	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.StatusCode)
}

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/search/global')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {
  query: 'ady',
  pillars: %w[contacts conversations tickets agents calls numbers segments],
  per_pillar_limit: 5,
  static_match_count: 2,
}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
JSON.parse(res.body)['data']['results'].each { |hit| puts "#{hit['pillar']}: #{hit['title']}" }

<?php
$payload = json_encode([
  'query' => 'ady',
  'pillars' => ['contacts', 'conversations', 'tickets', 'agents', 'calls', 'numbers', 'segments'],
  'per_pillar_limit' => 5,
  'static_match_count' => 2,
]);
$ch = curl_init('https://api.orbit.devotel.io/api/v1/search/global');
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, $payload);
$body = json_decode(curl_exec($ch), true);
foreach ($body['data']['results'] as $hit) {
  echo $hit['pillar'] . ': ' . $hit['title'] . PHP_EOL;
}

200

{
  "data": {
    "query": "ady",
    "results": [
      {
        "id": "agt_01K2N8Q3Z7R4",
        "pillar": "agents",
        "title": "Adyen Routing Agent",
        "subtitle": "Routes Adyen payment-support calls to the billing queue",
        "href": "/agents/agt_01K2N8Q3Z7R4",
        "score": 2
      },
      {
        "id": "cnt_8bTcQ4PaXwE2",
        "pillar": "contacts",
        "title": "Adya Sharma",
        "subtitle": "adya.sharma@example.com",
        "href": "/audience/contacts/cnt_8bTcQ4PaXwE2",
        "score": 1
      }
    ],
    "by_pillar": {
      "agents": [
        {
          "id": "agt_01K2N8Q3Z7R4",
          "pillar": "agents",
          "title": "Adyen Routing Agent",
          "subtitle": "Routes Adyen payment-support calls to the billing queue",
          "href": "/agents/agt_01K2N8Q3Z7R4",
          "score": 2
        }
      ],
      "contacts": [
        {
          "id": "cnt_8bTcQ4PaXwE2",
          "pillar": "contacts",
          "title": "Adya Sharma",
          "subtitle": "adya.sharma@example.com",
          "href": "/audience/contacts/cnt_8bTcQ4PaXwE2",
          "score": 1
        }
      ]
    },
    "counts": {
      "contacts": 1,
      "conversations": 0,
      "tickets": 0,
      "agents": 1,
      "calls": 0,
      "numbers": 0,
      "segments": 0
    },
    "partial": ["conversations"],
    "search_analytics_id": "searchAnalytics_9f2c7a1b4e"
  },
  "meta": {
    "request_id": "req_4c2b11a0",
    "timestamp": "2026-09-11T10:00:00.000Z"
  }
}

Reading the response

Each entry in results[] — and in the per-pillar buckets under by_pillar — carries:

id — the entity’s own id, so client-render keys stay stable.
pillar — one of the seven pillar buckets above; drives the icon and group heading.
title — the headline label (a contact name, an agent name, a number).
subtitle — an optional muted secondary label (for a contact, the email or phone).
href — a locale-relative dashboard path; prepend /${locale} before navigating.
score — per-pillar relevance: exact match > prefix match > substring match. Use it as the flat-sort tiebreaker across pillars.

Render either the flat, pre-sorted results array or the grouped by_pillar map (keys are only the pillars that returned at least one match). counts reports the match tally for every pillar, including zero, which is what powers a “1 result in Contacts” summary line. partial names the pillars whose sub-query failed — e.g. a transient database error on one resolver — so the client can show a discreet “couldn’t search conversations” hint next to the pillars that did succeed. partial is empty on a fully successful fan-out. search_analytics_id is the row this query recorded for search analytics, or null when the write was de-duped. Save it and report the row the user picks with POST /api/v1/search-analytics/click — that click attribution is what makes the search-analytics click-through panel non-zero. See the Search Analytics API for the click endpoint and the reporting reads that back-fill those panels.

Scoped palette query — worked round trip

A palette opened on one surface rarely needs all seven pillars. Scope the fan-out with pillars and tighten per_pillar_limit so the response stays small enough to render per keystroke:

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/search/global" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "ady",
    "pillars": ["contacts", "conversations"],
    "per_pillar_limit": 3,
    "static_match_count": 1
  }'

200

{
  "data": {
    "query": "ady",
    "results": [
      {
        "id": "cnt_8bTcQ4PaXwE2",
        "pillar": "contacts",
        "title": "Adya Sharma",
        "subtitle": "adya.sharma@example.com",
        "href": "/audience/contacts/cnt_8bTcQ4PaXwE2",
        "score": 1
      },
      {
        "id": "cnv_5dR7wX2mNqK1",
        "pillar": "conversations",
        "title": "Adyen chargeback thread",
        "subtitle": "Open · billing queue",
        "href": "/inbox/conversations/cnv_5dR7wX2mNqK1",
        "score": 1
      }
    ],
    "by_pillar": {
      "contacts": [
        {
          "id": "cnt_8bTcQ4PaXwE2",
          "pillar": "contacts",
          "title": "Adya Sharma",
          "subtitle": "adya.sharma@example.com",
          "href": "/audience/contacts/cnt_8bTcQ4PaXwE2",
          "score": 1
        }
      ],
      "conversations": [
        {
          "id": "cnv_5dR7wX2mNqK1",
          "pillar": "conversations",
          "title": "Adyen chargeback thread",
          "subtitle": "Open · billing queue",
          "href": "/inbox/conversations/cnv_5dR7wX2mNqK1",
          "score": 1
        }
      ]
    },
    "counts": {
      "contacts": 1,
      "conversations": 1
    },
    "partial": [],
    "search_analytics_id": "searchAnalytics_2c8d91f0ab"
  },
  "meta": {
    "request_id": "req_search_scope01",
    "timestamp": "2026-10-15T09:10:00.000Z"
  }
}

Hits carry the same fields as the all-pillar sample above (id, pillar, title, subtitle, href, score); by_pillar and counts cover only the pillars you asked for, and partial stays empty on a fully successful fan-out. static_match_count and the zero-result trap. The analytics row recorded for every query stores its result count as the pillar matches returned plus the static_match_count you sent. In the round trip above the palette rendered one client-side shortcut and the pillars returned two hits, so the query records as three results. Leave static_match_count out and a search that matched only your static shortcuts records zero — and lands in the Search Analytics zero-result panel even though the user found what they needed and clicked it. That is exactly the miscount the field exists to prevent: send the number of shortcuts your client actually rendered for the query, every time. The same call through the Python SDK’s generic client, for teams on a SDK version that does not ship a dedicated search resource yet:

Python

import os
from orbit_sdk import OrbitClient

client = OrbitClient.from_api_key(os.environ["ORBIT_API_KEY"])
body = client.request(
    "POST",
    "/api/v1/search/global",
    json_body={
        "query": "ady",
        "pillars": ["contacts", "conversations"],
        "per_pillar_limit": 3,
        "static_match_count": 1,
    },
)
for hit in body["data"]["results"]:
    print(hit["pillar"], hit["title"], hit["href"])

Errors worth branching on

Class	Meaning	Branch
401 `UNAUTHORIZED`	no authenticated user or key behind the call	Surface; fix the credential — a retry changes nothing.
422 `VALIDATION_ERROR`	the body failed the schema: empty or over-200-char `query`, unrecognized pillar, or a limit outside 1–10	Fix the field `error.details` names, then resend.

422

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid global search body",
    "status": 422,
    "details": { "field": "query", "value": "", "expected": "string of 1-200 characters" }
  },
  "meta": {
    "request_id": "req_search422a",
    "timestamp": "2026-10-15T09:12:00.000Z"
  }
}

An over-long query (201+ characters) answers with this same envelope and details.field: "query"; an unrecognized pillar name lands with details.field: "pillars". There is no dedicated query_too_long code to match against: branch on the 422 plus error.details.field. And because the endpoint takes free text with no operator grammar, there is likewise no operator_not_supported rejection to handle — special characters are matched literally, never rejected.

401

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authenticated user required",
    "status": 401
  },
  "meta": {
    "request_id": "req_search401a",
    "timestamp": "2026-10-15T09:12:00.000Z"
  }
}

API Reference

All Endpoints

Global search — worked samples

Request fields

Multi-pillar query across all seven pillars

Reading the response

Scoped palette query — worked round trip

Errors worth branching on

​Global search — worked samples

​Request fields

​Multi-pillar query across all seven pillars

​Reading the response

​Scoped palette query — worked round trip

​Errors worth branching on

Global search — worked samples

Request fields

Multi-pillar query across all seven pillars

Reading the response

Scoped palette query — worked round trip

Errors worth branching on