# Search products

Searches products by criteria with cursor-based or offset-based pagination.
**Pagination modes:**
- **Cursor-based (recommended):**
 Provide
`cursor`
 parameter. Returns
`next_cursor`

for the next page. Order is by
`products_id ASC`
.
- **Offset-based (legacy):**
 Provide
`skip`
 +
`count`
. Returns up to 2000 IDs.

**Response format:**
- Without
`?fetch=`
: returns only product IDs (lightweight).
- With
`?fetch=criteres_text,descriptions,...`
: returns hydrated product objects

with the requested related data.

**Filtering by negotiator ("suivi par"):**
Use `assigned_user_id` (an array of user IDs, even for a single one) to
filter by the negotiator in charge of the product.
**Criteria operators:**
| Operator | Description |
|  --- | --- |
| `EGAL` | Equals |
| `DIFFERENT` | Not equal |
| `SUPERIEUR` | Greater than or equal |
| `INFERIEUR` | Less than or equal |
| `CONTIENT` | Contains (multi-value text) |
| `COMPREND` | Includes (array contains) |
| `NE_COMPREND_PAS` | Does not include |

Endpoint: POST /products/search
Version: 1.6.0
Security: bearerAuth

## Security:

  - `bearerAuth` (unknown)
    http bearer opaque

## Query parameters:

  - `fetch` (array)
    Comma-separated list of additional related data to include for each product.
Only applies when results are hydrated (not for ID-only responses).
**Available values:**
- `criteres_text`
 — Text criteria values
- `criteres_number`
 — Numeric criteria values
- `criteres_fulltext`
 — Full-text criteria
- `criteres_flag`
 — Boolean criteria
- `criteres_publication_errors`
 — Criteria blocking publication
- `descriptions`
 — Web descriptions (multilingual)
- `rooms`
 — Room details
- `products_photos`
 — Photo URLs
- `customer`
 — Seller/owner contact
- `assigned_to`
 — Assigned agent
- `created_by`
 — Creator agent
- `publications`
 — Publication/distribution status
- `actions_history`
 — Action log
- `sale_agreement`
 — Related compromis
- `active_sale_agreement`
 — Active compromis only
- `log_actions`
 — Action log entries
- `live_visit`
 — Live visit data
- `scopes`
 — Permission scopes
- `statistic`
 — Statistics data
- `insee`
 — INSEE code
- `online_booking`
 — Online booking config
- `category`
 — Product category
- `themes`
 — Associated themes

## Request fields (application/json):

  - `criterias` (array)
    Filter criteria. Each item defines a condition on a product criterion.
Use `GET /criterias/product/all` to discover available criteria IDs and types.
**Note:** This field is named `criterias` on the search endpoint.
Create (`POST /products`) and update (`PATCH /products/{id}`) use `criteria` (without "s").

  - `criterias.id` (string, required)
    Criteria identifier. Accepts either the XML key (e.g. `"TypeBien"`)
or the numeric ID (e.g. `"27"`).
    Example: TypeBien

  - `criterias.operator` (string, required)
    Comparison operator.
    Enum: "EGAL", "DIFFERENT", "SUPERIEUR", "INFERIEUR", "CONTIENT", "COMPREND", "NE_COMPREND_PAS"

  - `criterias.value` (any, required)
    Criteria value. Format depends on criteria type and operator.
Can be a string or an array of strings (for `CONTIENT`/`COMPREND` operators).
    Example: Appartement

  - `keyword` (string | null)
    Free-text search. Matches against product reference, address+city,
or owner name. For numeric values, also matches price range (±10%).
    Example: Dupont

  - `model` (string | null)
    Filter by exact product reference.
    Example: REF-2025-001

  - `customer_id` (integer | null)
    Filter by owner/seller customer ID.
    Example: 789

  - `agency_id` (integer | null)
    Filter by agency ID. Must be within the authenticated site's scope.
    Example: 123

  - `assigned_user_id` (array | null)
    Filter by the negotiator(s) in charge of the product
(`products_admin_id`). Returns products assigned to any of the
given user (agent) IDs. Always an array, even for a single ID.
Use `GET /users` to discover user IDs.
    Example: [456,789]

  - `last_modified` (string | null)
    Filter products modified on or after this date.
Format: ISO 8601 (`YYYY-MM-DDTHH:mm:ss+HH:MM`).
    Example: 2026-01-01T00:00:00+01:00

  - `status_web` (boolean | null)
    Filter by web publication status:
- `true`
 — Only published products
- `false`
 — Only unpublished products

  - `hasVisit360` (boolean | null)
    Filter by 360° virtual visit availability:
- `true`
 — Only products with a virtual visit
- `false`
 — Only products without

  - `sort_type` (string | null)
    Field to sort results by:
- `id`
 — Product ID (default)
- `prix`
 — Price
- `date`
 — Last modification date
- `surface`
 — Living area
- `date_added`
 — Creation date
    Enum: "id", "prix", "date", "surface", "date_added"

  - `sort_order` (string | null)
    Sort direction. Default `desc`.
    Enum: "asc", "desc"

  - `cursor` (string | null)
    Cursor for pagination (base64-encoded last product ID from previous
response's `next_cursor`). Omit for the first page.
When `cursor` is provided, `skip`/`count` are ignored.

  - `count` (integer | null)
    Number of results per page (offset-based mode). Maximum 2000 for
ID-only responses, 100 when `?fetch=` is used. Ignored when `cursor` is provided.

## Response 200:

  - `200` (unknown)
    Search results

## Response 200 fields (application/json):

  - `data` (array)

  - `data.id` (integer)

  - `data.status` (string | null)

  - `data.price` (number | null)

  - `data.agency_id` (integer)

  - `data.model` (string | null)

  - `data.image` (string | null)

  - `data.created_at` (string | null)

  - `data.last_modified` (string | null)

  - `next_cursor` (string | null)

  - `has_more` (boolean)

## Response 403:

  - `403` (unknown)
    Access denied. The error `code` is always `FORBIDDEN`; the `message` gives the cause:
- `You do not have permission to perform this action.`
 — the access does not

hold the API pack / right required by the endpoint.
- `Insufficient scope for this request.`
 — the resource targeted by the request

(user, customer, product, agency, transaction, ...) is outside the scope of

the authenticated access.
- `Access denied for this editor.`
 /
`Your IP address has been blocked.`
 —

editor or IP restriction.

## Response 403 fields (application/json):

  - `error` (object)

  - `error.code` (string, required)

  - `error.message` (string, required)

## Response 422:

  - `422` (unknown)
    Validation failed

## Response 422 fields (application/json):

  - `error` (object)

  - `error.code` (string)
    Enum: "VALIDATION_ERROR"

  - `error.message` (string)

  - `error.details` (array)

  - `error.details.field` (string)

  - `error.details.message` (string)

## Response 403 examples:

  - `Missing API pack / right` (unknown)

  - `Resource outside the scope of the access` (unknown)

