---
title: "Search workers accessible to the calling company"
method: POST
path: "/public/worker/v1/search-workers"
tags: ["Worker"]
---

# Search workers accessible to the calling company

`POST /public/worker/v1/search-workers`

## Request

- Base URL: `https://api.maqqie.app` (the document declares no server; this is the origin it was published from)
- URL: `https://api.maqqie.app/public/worker/v1/search-workers`
- Auth: OAuth 2
  - Client credentials
  - Token URL: `https://maqqie.app/auth/realms/maqqie/protocol/openid-connect/token`
- TypeScript: <https://skmtc.dev/maqqie/apis/maqqie-public-api/docs/public/worker/v1/search-workers/post.ts> (a function with typed inputs; its response is checked against the schema)

Returns a paged list of workers visible to the calling company.

A worker is visible when the calling company either added the worker, or has any non-deleted
and non-aborted order with the worker (as company or intermediary). Workers outside this
access scope are never returned.

The optional `search` term is matched case-insensitively against both the worker's full name
(first + middle + last) and email address; a worker matches when either contains the term.
When `search` is omitted, all accessible workers are returned.

## Request body

- SearchWorkersRequestV1
  - `search` string: Optional free-text term, matched case-insensitively against both the worker's full name (first + middle + last) and email address. A worker matches when either contains the term. When omitted, all accessible workers are returned.
  - `page` PageRequestV1: Generic paging request parameters, reusable across public API endpoints. If omitted, defaults are number=0, size=25.
    - `number` integer: Zero-based page index.
    - `size` integer: Number of items per page. No maximum is enforced — callers running automated bulk fetches may request larger pages.

## Response `200`

Successfully retrieved a page of workers.

- SearchWorkersResponseV1
  - `workers` WorkerSummaryV1[], required
    - `workerId` string, uuid, required: The unique id of the worker.
    - `fullName` string, required: The worker's full name (first + middle + last, blanks collapsed).
    - `emailAddress` string, email, required: The worker's email address.
  - `page` PageV1, required: Generic paging metadata returned alongside a page of results, reusable across public API endpoints.
    - `number` integer, required: Zero-based index of the returned page.
    - `size` integer, required: The requested page size. The last page may contain fewer items.
    - `totalElements` integer, required: Total number of items matching the query across all pages.
    - `totalPages` integer, required: Total number of pages available for the query.

## Other responses

- `401`: The request did not contain credentials identifying the caller, or the provided credentials were invalid.
- `403`: The caller is not allowed to use this endpoint.

## Changes

- **2026-09-29** `f9510f3f4b22`: 2 breaking, 4 info
  - the request's body type changed from no type to `object`
  - the response's body type changed from no type to `object` for status `200`
  - added the new optional request property `page`
  - added the new optional request property `search`
  - …2 more
- **2026-09-29** `3352b56bb8fe`: 4 breaking, 2 warning
  - the request's body type changed from `object` to no type
  - the response's body type changed from `object` to no type for status `200`
  - removed the required property `page` from the response with the `200` status
  - removed the required property `workers` from the response with the `200` status
  - …2 more
- **2026-09-16** `ccf9834e5006`: 2 breaking, 4 info
  - the request's body type changed from no type to `object`
  - the response's body type changed from no type to `object` for status `200`
  - added the new optional request property `page`
  - added the new optional request property `search`
  - …2 more
- **2026-09-15** `8085d4c1ab80`: 4 breaking, 2 warning
  - the request's body type changed from `object` to no type
  - the response's body type changed from `object` to no type for status `200`
  - removed the required property `page` from the response with the `200` status
  - removed the required property `workers` from the response with the `200` status
  - …2 more
- …earlier changes not shown

[Operation history](https://skmtc.dev/maqqie/apis/maqqie-public-api/changes/public/worker/v1/search-workers/post.md)

---

[API](https://skmtc.dev/maqqie/apis/maqqie-public-api.md) - [All operations](https://skmtc.dev/maqqie/apis/maqqie-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/maqqie/apis/maqqie-public-api/revisions/13ed331da2b2?raw)