Search People

curl --request POST \
  --url https://api.ishlabs.io/api/v1/workspaces/{workspace_id}/people/search \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "archived": false,
  "generation_job_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "pagination": {
    "after": "<string>",
    "limit": 25
  },
  "rule": {},
  "search": "<string>"
}
'

import requests

url = "https://api.ishlabs.io/api/v1/workspaces/{workspace_id}/people/search"

payload = {
    "archived": False,
    "generation_job_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "pagination": {
        "after": "<string>",
        "limit": 25
    },
    "rule": {},
    "search": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    archived: false,
    generation_job_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    pagination: {after: '<string>', limit: 25},
    rule: {},
    search: '<string>'
  })
};

fetch('https://api.ishlabs.io/api/v1/workspaces/{workspace_id}/people/search', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.ishlabs.io/api/v1/workspaces/{workspace_id}/people/search",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'archived' => false,
    'generation_job_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'pagination' => [
        'after' => '<string>',
        'limit' => 25
    ],
    'rule' => [
        
    ],
    'search' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

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

func main() {

	url := "https://api.ishlabs.io/api/v1/workspaces/{workspace_id}/people/search"

	payload := strings.NewReader("{\n  \"archived\": false,\n  \"generation_job_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"pagination\": {\n    \"after\": \"<string>\",\n    \"limit\": 25\n  },\n  \"rule\": {},\n  \"search\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.ishlabs.io/api/v1/workspaces/{workspace_id}/people/search")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"archived\": false,\n  \"generation_job_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"pagination\": {\n    \"after\": \"<string>\",\n    \"limit\": 25\n  },\n  \"rule\": {},\n  \"search\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.ishlabs.io/api/v1/workspaces/{workspace_id}/people/search")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"archived\": false,\n  \"generation_job_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"pagination\": {\n    \"after\": \"<string>\",\n    \"limit\": 25\n  },\n  \"rule\": {},\n  \"search\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "has_more": true,
  "items": [
    {
      "created_at": "2023-11-07T05:31:56Z",
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "name": "<string>",
      "owner": "self",
      "updated_at": "2023-11-07T05:31:56Z",
      "accessibility_profile": {},
      "archived_at": "2023-11-07T05:31:56Z",
      "avatar_url": "<string>",
      "bio": "<string>",
      "city": "<string>",
      "country": "<string>",
      "date_of_birth": "2023-12-25",
      "education_level": "less_than_secondary",
      "employment_status": "employed_full_time",
      "external_id": "<string>",
      "gender": "male",
      "generation_job_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "household": "single",
      "income_level": "lower",
      "interests": [
        "<string>"
      ],
      "locale_type": "urban",
      "occupation": "<string>",
      "occupation_code": "<string>",
      "type": "ai",
      "workspace_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
    }
  ],
  "next_cursor": "<string>"
}

{
  "detail": "<string>",
  "request_id": "<string>",
  "docs_url": "<string>"
}

{
  "detail": "<string>",
  "request_id": "<string>",
  "docs_url": "<string>"
}

{
  "detail": "<string>",
  "request_id": "<string>",
  "docs_url": "<string>"
}

{
  "detail": [
    {
      "detail": "<string>",
      "error": "<string>",
      "error_code": "<string>",
      "errors": [
        {
          "loc": [
            "<string>"
          ],
          "msg": "<string>",
          "type": "<string>",
          "allowed_values": [
            "<unknown>"
          ],
          "input": "<string>"
        }
      ],
      "retryable": true,
      "status": 123,
      "suggestions": [
        "<string>"
      ]
    }
  ]
}

{
  "detail": "<string>",
  "request_id": "<string>",
  "docs_url": "<string>"
}

API reference

Search People

Find people by their attributes, using a boolean rule tree.

Searches the same pool the list endpoint serves (your workspace’s people plus the platform library), and returns the same paginated envelope.

The rule tree

A rule is a single node. A node is either a leaf or a group, never both:

A leaf tests one attribute: {"field": {"source": ..., "key": ...}, "operator": ..., "value": ...}. Copy source and key from the attribute’s filter block in GET .../people/schema; that endpoint is the authoritative vocabulary, and an attribute or operator it does not list is refused with a 422 rather than matching nothing.
A group combines nodes: {"op": "and" | "or" | "not", "conditions": [...]}.

Boolean semantics, exactly

A group’s op applies to its OWN conditions and to nothing else. and matches a person satisfying every condition in that group; or matches a person satisfying at least one; not takes exactly one condition and matches people who do not satisfy it. Groups nest, so a group inside another group is evaluated on its own first and its result is then one input to the parent’s operator. There is no precedence to remember and no implicit combination anywhere: two conditions are only ever joined by the op of the group holding them.

A worked example

“Nurses in Sweden, plus teachers in Norway” is two AND-groups joined by an OR. Note that the country is repeated in both groups: the outer or does not distribute over anything, so a condition placed outside the groups would not apply to either.

{
  "rule": {
    "op": "or",
    "conditions": [
      {"op": "and", "conditions": [
        {"field": {"source": "demographic", "key": "occupation"},
         "operator": "eq", "value": "nurse"},
        {"field": {"source": "demographic", "key": "country"},
         "operator": "eq", "value": "Sweden"}
      ]},
      {"op": "and", "conditions": [
        {"field": {"source": "demographic", "key": "occupation"},
         "operator": "eq", "value": "teacher"},
        {"field": {"source": "demographic", "key": "country"},
         "operator": "eq", "value": "Norway"}
      ]}
    ]
  },
  "pagination": {"limit": 25}
}

Testing whether an attribute is set

is_not_null matches people who have a value for an attribute, and is_null matches people who do not. Reach for these rather than comparing against an empty string: an attribute nobody filled in holds no value at all, and it satisfies no ordinary comparison, not even a negated one.

Limits, and how a rule is refused

A rule may nest groups at most 2 levels deep, hold at most 15 conditions in any one group, and 25 in total.

Both refusals are a 422 carrying an error_kind, and they have different fixes:

search_rule_too_complex: past one of those caps. The detail names the offending count and the limit. Combining values with in costs one condition instead of one per value, and is the usual fix.
search_rule_invalid: the tree is malformed, or it names an attribute, source or operator this API does not publish. The detail names the offender, and GET .../people/schema is the vocabulary it was checked against.

A malformed request BODY (rather than a bad rule) is the ordinary validation 422 with the field-level envelope, which is why this operation’s 422 documents either shape.

Saved segments

Segments live in the ish app and are not exposed here. A segment IS a rule, so the way to use one is to send its rule as the rule on this request: that is how the ish console itself applies them.

POST

api

workspaces

{workspace_id}

people

Search People

curl --request POST \
  --url https://api.ishlabs.io/api/v1/workspaces/{workspace_id}/people/search \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "archived": false,
  "generation_job_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "pagination": {
    "after": "<string>",
    "limit": 25
  },
  "rule": {},
  "search": "<string>"
}
'

import requests

url = "https://api.ishlabs.io/api/v1/workspaces/{workspace_id}/people/search"

payload = {
    "archived": False,
    "generation_job_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "pagination": {
        "after": "<string>",
        "limit": 25
    },
    "rule": {},
    "search": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    archived: false,
    generation_job_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    pagination: {after: '<string>', limit: 25},
    rule: {},
    search: '<string>'
  })
};

fetch('https://api.ishlabs.io/api/v1/workspaces/{workspace_id}/people/search', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.ishlabs.io/api/v1/workspaces/{workspace_id}/people/search",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'archived' => false,
    'generation_job_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'pagination' => [
        'after' => '<string>',
        'limit' => 25
    ],
    'rule' => [
        
    ],
    'search' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

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

func main() {

	url := "https://api.ishlabs.io/api/v1/workspaces/{workspace_id}/people/search"

	payload := strings.NewReader("{\n  \"archived\": false,\n  \"generation_job_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"pagination\": {\n    \"after\": \"<string>\",\n    \"limit\": 25\n  },\n  \"rule\": {},\n  \"search\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.ishlabs.io/api/v1/workspaces/{workspace_id}/people/search")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"archived\": false,\n  \"generation_job_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"pagination\": {\n    \"after\": \"<string>\",\n    \"limit\": 25\n  },\n  \"rule\": {},\n  \"search\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.ishlabs.io/api/v1/workspaces/{workspace_id}/people/search")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"archived\": false,\n  \"generation_job_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"pagination\": {\n    \"after\": \"<string>\",\n    \"limit\": 25\n  },\n  \"rule\": {},\n  \"search\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "has_more": true,
  "items": [
    {
      "created_at": "2023-11-07T05:31:56Z",
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "name": "<string>",
      "owner": "self",
      "updated_at": "2023-11-07T05:31:56Z",
      "accessibility_profile": {},
      "archived_at": "2023-11-07T05:31:56Z",
      "avatar_url": "<string>",
      "bio": "<string>",
      "city": "<string>",
      "country": "<string>",
      "date_of_birth": "2023-12-25",
      "education_level": "less_than_secondary",
      "employment_status": "employed_full_time",
      "external_id": "<string>",
      "gender": "male",
      "generation_job_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "household": "single",
      "income_level": "lower",
      "interests": [
        "<string>"
      ],
      "locale_type": "urban",
      "occupation": "<string>",
      "occupation_code": "<string>",
      "type": "ai",
      "workspace_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
    }
  ],
  "next_cursor": "<string>"
}

{
  "detail": "<string>",
  "request_id": "<string>",
  "docs_url": "<string>"
}

{
  "detail": "<string>",
  "request_id": "<string>",
  "docs_url": "<string>"
}

{
  "detail": "<string>",
  "request_id": "<string>",
  "docs_url": "<string>"
}

{
  "detail": [
    {
      "detail": "<string>",
      "error": "<string>",
      "error_code": "<string>",
      "errors": [
        {
          "loc": [
            "<string>"
          ],
          "msg": "<string>",
          "type": "<string>",
          "allowed_values": [
            "<unknown>"
          ],
          "input": "<string>"
        }
      ],
      "retryable": true,
      "status": 123,
      "suggestions": [
        "<string>"
      ]
    }
  ]
}

{
  "detail": "<string>",
  "request_id": "<string>",
  "docs_url": "<string>"
}

Authorizations

Authorization

string

header

required

Workspace API key as a bearer token: Authorization: Bearer ish_sk_live_.... Keys are workspace-scoped machine principals minted in Settings > Developers (shown once at mint). Scopes: sessions:run (create a session, submit turns, close), sessions:read (read the session and its decision trace), environments:read and environments:write (manage the workspace's registered environments), tasks:read and tasks:write (manage the workspace's registered tasks), people:read and people:write (the people the workspace can run a session for), and usage:read (the workspace's own consumption, spend limits and rate-limit budgets). A key is minted with sessions:run, sessions:read, and tasks:read by default; every other scope must be requested, people:read and usage:read included. An ish user access token also works on the same header for personal scripts.

Path Parameters

workspace_id

string<uuid>

required

Body

application/json

A capped rule-tree query over the workspace's reachable people.

Unknown keys are rejected rather than ignored: a typo in a filter that silently widened the result set would be indistinguishable from a match.

archived

boolean

default:false

false (the default) searches live people; true searches the archive instead. The two sets are disjoint, so this selects which one you are searching rather than widening the search.

generation_job_id

string<uuid> | null

Restrict to the people one generation job produced. Reads its own writes: a person is visible here the moment the job records them.

owner

enum<string> | null

Restrict to one owner. Omitted returns both, which is the set you can open a session for.

Available options:

self,

platform

pagination

PublicPersonSearchPagination · object

Keyset pagination, in the body because the query is.

Show child attributes

rule

Rule · object | null

A boolean tree of filters. See the endpoint description for the grammar, the caps, and a worked example.

string | null

Case-insensitive substring match on the person's name.

Maximum string length: 200

Response

Successful Response

A keyset-paginated page of people.

Ordered created_at DESC, id DESC, the same order and the same envelope as the session list, so one pagination helper in an SDK drives both.

has_more

boolean

required

True when more people exist beyond this page.

items

PublicPersonResponse · object[]

required

Show child attributes

next_cursor

string | null

required

Opaque keyset cursor for the next page (pass as after); null on the final page.

Get started

Core concepts

Guides

API reference

Versioning and changes

Search People

The rule tree

Boolean semantics, exactly

A worked example

Testing whether an attribute is set

Limits, and how a rule is refused

Saved segments

Authorizations

Path Parameters

Body

Response