Search people

Endpoint

Field	Value
Method	`GET`
API root	`https://api.taeh.org/people`
Path	`/people`

What you must send

Every request must include a valid API client key:

Authorization: Bearer orion_live_<keyId>_<secret>

The key must have the people:read scope. For a basic search, send at least one search parameter such as query, limit, or a filter. If you do not send eventId, Taeh searches inside the current open event automatically.

curl -G "https://api.taeh.org/people" \
  -H "Authorization: Bearer orion_live_<keyId>_<secret>" \
  --data-urlencode "query=ahmed" \
  --data-urlencode "limit=20"

Authentication

Use an API client key in the Authorization header:

Authorization: Bearer orion_live_<keyId>_<secret>

The API client key must include the people:read scope.

When an API client calls this endpoint without an eventId, results are automatically limited to the current open event.

Query parameters

Parameter	Type	Required	Description
`query`	`string`	No	Free-text search across name, phone, last seen location, reporter name, age, address, province, and notes.
`limit`	`number`	No	Maximum number of results. Defaults to `100`; maximum is `1000`.
`gender`	`string`	No	Filter by `Male` or `Female`.
`status`	`string`	No	Filter by `Lost`, `Found`, or `Delivered`.
`eventId`	`string`	No	Event ULID. If omitted by an API client, the current open event is used.
`idGt`	`string`	No	Return people with an ID greater than this ULID. Useful for cursor-style paging.
`idLt`	`string`	No	Return people with an ID less than this ULID. Useful for cursor-style paging.
`createdBy`	`string`	No	Filter by creator user ULID. Usually for internal use.

Request logic

Taeh applies the request in this order:

Authenticates the API client key.
Verifies the key has the people:read scope.
If eventId is missing, finds the current open event and limits results to it.
Applies optional filters: query, gender, status, createdBy, idGt, and idLt.
Sorts by newest person first.
Applies pagination using idGt, idLt, and limit.

If no current event is open and you do not send eventId, the API returns 200 OK with an empty array.

cURL example

curl -G "https://api.taeh.org/people" \
  -H "Authorization: Bearer orion_live_<keyId>_<secret>" \
  --data-urlencode "query=ahmed" \
  --data-urlencode "limit=20"

Example with filters

curl -G "https://api.taeh.org/people" \
  -H "Authorization: Bearer orion_live_<keyId>_<secret>" \
  --data-urlencode "query=baghdad" \
  --data-urlencode "gender=Male" \
  --data-urlencode "status=Lost" \
  --data-urlencode "limit=50"

Success response

Returns 200 OK with an array of people. If no people match the filters, the API returns an empty array:

[]

Each matching record has this shape:

[
    {
        "id": "01JZQ2V9S3XQW8Q8T4K8X9P7W1",
        "createdAt": "2026-07-08T12:30:00+00:00",
        "createdBy": "01JZQ2T5PNR4A58S7A7B6M60F2",
        "serial": 125,
        "fullname": "Ahmed Ali",
        "age": "12",
        "gender": "Male",
        "status": "Lost",
        "lastSeenAt": "Gate 4",
        "phoneNumber": "07701234567",
        "reporterName": "Ali Hassan",
        "photoId": null,
        "photoUrl": null,
        "updatedBy": null,
        "updatedByName": null,
        "stationId": "01JZQ2TB8X7H5ZJYQ2XQ7Z8R2A",
        "stationName": "Main Station",
        "stationPhone": "07700000000",
        "deliveredTo": null,
        "province": "Baghdad",
        "address": "Near the main entrance",
        "latitude": 33.3152,
        "longitude": 44.3661,
        "notes": "Wearing a blue shirt"
    }
]

Response fields

Field	Type	Description
`id`	`string`	Person ULID.
`createdAt`	`datetime`	Creation time derived from the ULID.
`createdBy`	`string`	User ULID that created the record.
`serial`	`number`	Database serial number.
`fullname`	`string`	Person name.
`age`	`string`	Age text.
`gender`	`string`	`Male` or `Female`.
`status`	`string`	`Lost`, `Found`, or `Delivered`.
`lastSeenAt`	`string`	Last seen location or description.
`phoneNumber`	`string`	Reporter or contact phone number.
`reporterName`	`string`	Name of the reporting person.
`photoId`	`string \| null`	Uploaded photo ULID, if available.
`photoUrl`	`string \| null`	Public photo URL, if available.
`stationId`	`string \| null`	Assigned station ULID.
`stationName`	`string \| null`	Assigned station name.
`stationPhone`	`string \| null`	Assigned station phone number.
`deliveredTo`	`string \| null`	Person or place the found person was delivered to.
`province`	`string`	Province.
`address`	`string \| null`	Address or detailed location.
`latitude`	`number \| null`	Latitude, if recorded.
`longitude`	`number \| null`	Longitude, if recorded.
`notes`	`string \| null`	Additional notes.

Errors

Status	Meaning
`401`	Missing or invalid API client key.
`403`	API client key does not have the `people:read` scope.

Pagination

For simple pagination, use limit and idLt.

curl -G "https://api.taeh.org/people" \
  -H "Authorization: Bearer orion_live_<keyId>_<secret>" \
  --data-urlencode "limit=100" \
  --data-urlencode "idLt=<lastId>"

For cursor-style pagination, use idLt with the last id returned from the previous page because results are ordered from newest to oldest.

Overview

People

Reference

Search people

Endpoint

What you must send

Authentication

Query parameters

Request logic

cURL example

Example with filters

Success response

Response fields

Errors

​Endpoint

​What you must send

​Authentication

​Query parameters

​Request logic

​cURL example

​Example with filters

​Success response

​Response fields

​Errors

​Pagination

Endpoint

What you must send

Authentication

Query parameters

Request logic

cURL example

Example with filters

Success response

Response fields

Errors

Pagination