---
title: "Search whitelabel clients"
method: POST
path: "/api/whitelabel-clients/search"
tags: ["whitelabel_clients"]
---

# Search whitelabel clients

`POST /api/whitelabel-clients/search`

## Request

- Base URL: `https://beta.getsales.io/id/v1`
- URL: `https://beta.getsales.io/id/v1/api/whitelabel-clients/search`
- Auth: HTTP bearer and API key in header `Team-SID`

Who registered on the team's brands: one row per client user, newest first. include user for the account, teams for the workspaces the client owns with their gate and the share the reseller allocated (the targets of create_subscription_allocation and open_whitelabel_client_workspace). counts.groups.registered gives the 7d, 30d and 90d registration counters; page_size 0 returns them alone.

Contract:
- MCP tool `search_whitelabel_clients`, registry package `mcp.id/whitelabel_clients`, mount `id.partner`.
- Operation `search`, response envelope `search`.
- Flags: read only.

## Request body

- SearchWhitelabelClientsRequest: Request body of `search_whitelabel_clients`.
  - `filter` object: Field filters, ANDed: {field: {eq | ne | in | nin | gte | lte | gt | lt | is_null}}; q inside it is free text. Omit for every row.
    - `sid` object: Client sid(s).
      - `eq` string
      - `in` string[]
    - `whitelabel_sid` object: One brand's registrations.
      - `eq` string
      - `in` string[]
    - `user_sid` object: Is this account a client, and of which brand.
      - `eq` string
      - `in` string[]
    - `created_at` object: Registration window.
      - `gte` string
      - `lte` string
      - `gt` string
      - `lt` string
  - `include` string[]: Relations to attach to every item; omit for the bare rows.
  - `sort` object: One column and its direction; omit for the default order.
    - `field` 'created_at', required: The column to order by.
    - `direction` 'asc' | 'desc': asc or desc; default desc.
  - `page_size` integer: 0..500, default 50; 0 = counts only, 1 = the first row.
  - `cursor` string, nullable: pagination.next_cursor of the previous page.

## Response `200`

`search` success envelope.

- SearchWhitelabelClientsResponse
  - `success` true, required
  - `operation` 'search', required
  - `items` object[], required
    - `item` object, required
      - `sid` string, required: Client sid (id_wc_...).
      - `whitelabel_sid` string, required: The brand the client registered on (id_wl_...).
      - `user_sid` string, required: The client's account (us_mb_...); one brand per user.
      - `created_at` string, nullable, required: ISO 8601 UTC: the registration moment.
    - `included` object, required
      - `user` object: The client's user row (UserDomain).
      - `teams` object[]: The workspaces the client OWNS (TeamDomain rows), with the derived gate and the limits the reseller allocated.
  - `pagination` object, required
    - `next_cursor` string, nullable, required
    - `has_more` boolean, required
    - `total_count` integer, nullable, required
  - `applied_filters` object, required
  - `includes` string[], required
  - `meta` object, required
    - `trace_id` string, required: UUID v7; same 128-bit value as the X-Trace-Id header.
    - `span_id` string, required: 16 hex chars, root span of this request.
    - `timestamp` string, required: ISO 8601 UTC (Y-m-dTH:i:sZ), response time.
    - `duration_ms` integer, required: Server-side wall clock.
    - `team_sid` string, nullable: The team this call ran in (the token team, or the team_sid override). Null when unauthenticated; absent from pre-2026-08-20 backends.
    - `actor_type` string, nullable: user | agent | api_key | system. Null when unauthenticated; absent from pre-2026-08-20 backends.
  - `counts` object
    - `total_count` number, required: Clients matching the filter.
    - `groups` object, required
      - `registered` object: Registrations over the same scope in the last 7d, 30d and 90d.

## Other responses

- `4XX`: MCP error envelope. `error.code` is one of validation_failed, nothing_to_update, not_found, relation_not_found, invalid_transition, limit_exceeded, payment_required, duplicate_rejected, conflict, delete_blocked, unauthorized, forbidden, rate_limited, not_implemented.
- `5XX`: MCP error envelope with `error.code` internal_error or service_unavailable.

---

[API](https://skmtc.dev/getsales/apis/getsales-public-contract-gs-service-id.md) - [All operations](https://skmtc.dev/getsales/apis/getsales-public-contract-gs-service-id/llms.txt) - [OpenAPI document](https://skmtc.dev/getsales/apis/getsales-public-contract-gs-service-id/revisions/95e48541fe85?raw)