# Search mandates

Searches mandates in the mandate register (registre des mandats) with
cursor-based pagination. Results are ordered by `mandat_id` descending.
The mandate register must be enabled for the site
(`MODULE_REGISTRE_MANDATS`) and the authenticated scope must include at
least one agency, otherwise the request is rejected.
Use `include` to load additional related data.

Endpoint: GET /mandates
Version: 1.6.0
Security: bearerAuth

## Security:

  - `bearerAuth` (unknown)
    http bearer opaque

## Query parameters:

  - `per_page` (integer)
    Number of results per page. Maximum 200, default 50.

  - `cursor` (string)
    Cursor for pagination (from a previous response's `meta.next_cursor`).

  - `include` (string)
    Comma-separated list of additional relations to include.
**Available values:** `amendments`.

  - `status` (string)
    Filter by one or more mandate statuses (comma-separated).
**Allowed values:** `cancel`, `reserved`, `original_sans_saisi`,
`fax_receive`, `saisi`, `waiting`, `original_receive`, `ended`.

  - `status_web` (boolean)
    Filter on the web publication status.

  - `type` (string)
    Mandate type (referential C124), e.g. `exclusif`, `simple`.

  - `form` (string)
    Mandate form (referential criterion 1914), e.g. `Vente`, `Recherche`,
`Location`, `Negociation`, `Gestion`.

  - `card_id` (integer)
    Professional card ID.

  - `card_number` (string)
    Professional card number.

  - `number` (string)
    Mandate number.

  - `created_from` (string)
    Filter mandates created on or after this date (ISO 8601).

  - `created_to` (string)
    Filter mandates created on or before this date (ISO 8601).

  - `agency_id` (integer)
    Filter by agency (manufacturer) ID, within the authenticated scope.

  - `user_id` (integer)
    Filter by negotiator (agent) ID.

  - `principal_id` (integer)
    Filter by principal (mandant) ID.

  - `product_type` (string)
    Filter by product type.

  - `product_model` (string)
    Filter by product model/reference.

  - `product_id` (integer)
    Filter by product ID.

  - `profile_id` (integer)
    Filter by profile ID.

## Response 200:

  - `200` (unknown)
    Paginated list of mandates

## Response 200 fields (application/json):

  - `data` (array)

  - `data.id` (integer)
    Mandate ID.
    Example: 12345

  - `data.order_number` (integer | null)
    Sequential order number of the mandate.

  - `data.number` (string | null)
    Mandate number.

  - `data.created_at` (string | null)
    Creation date.

  - `data.start_date` (string | null)
    Start date of the mandate.

  - `data.limit_date` (string | null)
    Deadline date (date butoir).

  - `data.term_date` (string | null)
    Term/expiry date (date échéance).

  - `data.sign_place` (string | null)
    Place of signature.

  - `data.form` (string | null)
    Mandate form (Vente, Recherche, Location, Negociation, Gestion).

  - `data.type` (string | null)
    Mandate type (exclusif, simple).

  - `data.status` (string | null)
    Mandate status.

  - `data.agency` (object)
    Agency the mandate belongs to.

  - `data.agency.id` (integer | null)

  - `data.agency.name` (string | null)

  - `data.card` (object)
    Professional card.

  - `data.card.id` (integer | null)

  - `data.card.number` (string | null)

  - `data.principal` (object)
    Principal (mandant).

  - `data.principal.id` (integer | null)

  - `data.principal.gender` (string | null)

  - `data.principal.first_name` (string | null)

  - `data.principal.last_name` (string | null)

  - `data.principal.location` (object)

  - `data.principal.location.address` (string | null)

  - `data.principal.location.zip_code` (string | null)

  - `data.principal.location.city` (string | null)

  - `data.principal.phone` (string | null)

  - `data.principal.email` (string | null)

  - `data.customers_associate` (integer | null)
    ID of the associated customer, if any.

  - `data.product` (object)
    Property attached to the mandate.

  - `data.product.id` (integer | null)

  - `data.product.model` (string | null)

  - `data.product.type` (string | null)

  - `data.product.price` (number | null)

  - `data.product.description` (string | null)

  - `data.product.area` (number | null)

  - `data.product.fees` (number | null)
    Total fees (honoraires).

  - `data.product.seller_fees` (number | null)
    Seller fees (honoraires vendeur).

  - `data.product.buyer_fees` (number | null)
    Buyer fees (honoraires acquéreur).

  - `data.original_products_id` (integer | null)
    ID of the original product, if the mandate was transferred.

  - `data.comment` (string | null)

  - `data.user` (object)
    Negotiator (agent) in charge.

  - `data.user.id` (integer | null)

  - `data.user.name` (string | null)

  - `data.amendment_of` (integer | null)
    ID of the parent mandate when this entry is an amendment.

  - `data.is_amendment` (boolean)
    Whether this mandate is an amendment (avenant).

  - `data.root_mandate` (object | null)
    Root mandate reference when applicable.

  - `data.amendments` (array | null)
    List of amendments. Loaded with `include=amendments`.

  - `meta` (object)
    Pagination metadata for cursor-based listings.

  - `meta.per_page` (integer)
    Number of items returned per page.
    Example: 50

  - `meta.next_cursor` (string | null)
    Cursor to pass in the next request to fetch the next page.
Null when there is no next page.
    Example: eyJpZCI6MTIzfQ==

  - `meta.prev_cursor` (string | null)
    Cursor for the previous page. Null on first page.

  - `links` (object)
    Ready-to-use links for cursor-based navigation.

  - `links.next` (string | null)
    URL of the next page, or null.

  - `links.prev` (string | null)
    URL of the previous page, or null.

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

