Skip to main content

​
Endpoint

FieldValue
MethodGET
API roothttps://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

ParameterTypeRequiredDescription
querystringNoFree-text search across name, phone, last seen location, reporter name, age, address, province, and notes.
limitnumberNoMaximum number of results. Defaults to 100; maximum is 1000.
genderstringNoFilter by Male or Female.
statusstringNoFilter by Lost, Found, or Delivered.
eventIdstringNoEvent ULID. If omitted by an API client, the current open event is used.
idGtstringNoReturn people with an ID greater than this ULID. Useful for cursor-style paging.
idLtstringNoReturn people with an ID less than this ULID. Useful for cursor-style paging.
createdBystringNoFilter by creator user ULID. Usually for internal use.

​
Request logic

Taeh applies the request in this order:
  1. Authenticates the API client key.
  2. Verifies the key has the people:read scope.
  3. If eventId is missing, finds the current open event and limits results to it.
  4. Applies optional filters: query, gender, status, createdBy, idGt, and idLt.
  5. Sorts by newest person first.
  6. 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

FieldTypeDescription
idstringPerson ULID.
createdAtdatetimeCreation time derived from the ULID.
createdBystringUser ULID that created the record.
serialnumberDatabase serial number.
fullnamestringPerson name.
agestringAge text.
genderstringMale or Female.
statusstringLost, Found, or Delivered.
lastSeenAtstringLast seen location or description.
phoneNumberstringReporter or contact phone number.
reporterNamestringName of the reporting person.
photoIdstring | nullUploaded photo ULID, if available.
photoUrlstring | nullPublic photo URL, if available.
stationIdstring | nullAssigned station ULID.
stationNamestring | nullAssigned station name.
stationPhonestring | nullAssigned station phone number.
deliveredTostring | nullPerson or place the found person was delivered to.
provincestringProvince.
addressstring | nullAddress or detailed location.
latitudenumber | nullLatitude, if recorded.
longitudenumber | nullLongitude, if recorded.
notesstring | nullAdditional notes.

​
Errors

StatusMeaning
401Missing or invalid API client key.
403API 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.