> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs.taeh.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Search people

> Search lost, found, and delivered people using a Taeh API client key.

## 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:

```http theme={null}
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.

```bash theme={null}
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:

```http theme={null}
Authorization: Bearer orion_live_<keyId>_<secret>
```

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

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

## 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:

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`.

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

## cURL example

```bash theme={null}
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

```bash theme={null}
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:

```json theme={null}
[]
```

Each matching record has this shape:

```json theme={null}
[
    {
        "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`.

```bash theme={null}
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.