> ## Documentation Index
> Fetch the complete documentation index at: https://developers.avest.fr/llms.txt
> Use this file to discover all available pages before exploring further.

# Rechercher des transactions (paginé)

> Recherche paginée de transactions (`sale`, `acquisition`, `rental`) avec leurs contacts associés.

La clé contenant les résultats varie selon `{transaction}` : `sales`, `acquisitions` ou `rentals`. Taille de page fixe : 100 documents. Pas de `total` retourné — itérer jusqu'à `hasMore: false`. `page` max : 100 (soit 10 000 documents cumulés).

Aucun paramètre autre que ceux listés n'est accepté → `400`. Si `search` est fourni sans `sortField`, l'ordre par défaut est la pertinence (pas `createdAt`). Le numéro de mandat (`mandate.referenceNumber`) n'est pas indexé : passer par `GET /external-integration/sale?customId=...` si vous avez le customId métier. Les champs non renseignés sont absents de la réponse (pas `null`). Endpoint en lecture seule.



## OpenAPI

````yaml /openapi.yaml get /external-integration/{transaction}/search
openapi: 3.1.0
info:
  title: Avest External Integration API
  version: 1.0.0
  description: >-
    API d'intégration externe Avest. Permet de rechercher des contacts et des
    collaborateurs, de récupérer des transactions (ventes, acquisitions,
    locations) et de créer/mettre à jour des transactions avec déduplication
    automatique.


    Tous les endpoints requièrent un token LinkedAPI (scope
    `externalIntegration`) dont la clé doit avoir un `agencyGroup` configuré.
    Les données sont strictement limitées au périmètre autorisé du token :
    aucune fiche hors `agencyGroup` n'est jamais retournée.
servers:
  - url: https://api.avest.fr/v1
    description: API de production Avest
security:
  - linkedApiToken: []
tags:
  - name: Contacts
    description: Recherche et récupération de contacts.
  - name: Users
    description: Récupération des collaborateurs (annuaire).
  - name: Transactions
    description: Récupération et recherche de ventes, acquisitions et locations.
  - name: Lead generation
    description: Création / mise à jour de transactions (ventes, acquisitions, locations).
  - name: Matches
    description: Récupération et recherche de rapprochements (matches vente / acquisition).
  - name: Activities
    description: Récupération et création des activités liées à un document.
  - name: Ads
    description: Récupération et recherche d'annonces (listings publiques).
  - name: Key
    description: Type de la clé API et méthodes qu'elle autorise.
  - name: Agencies
    description: Découverte des agences accessibles par la clé.
  - name: Shift planning
    description: >-
      Planning de permanence d'une agence, semaine par semaine. Écriture
      réservée aux clés autorisées en écriture.
paths:
  /external-integration/{transaction}/search:
    get:
      tags:
        - Transactions
      summary: Rechercher des transactions (paginé)
      description: >-
        Recherche paginée de transactions (`sale`, `acquisition`, `rental`) avec
        leurs contacts associés.


        La clé contenant les résultats varie selon `{transaction}` : `sales`,
        `acquisitions` ou `rentals`. Taille de page fixe : 100 documents. Pas de
        `total` retourné — itérer jusqu'à `hasMore: false`. `page` max : 100
        (soit 10 000 documents cumulés).


        Aucun paramètre autre que ceux listés n'est accepté → `400`. Si `search`
        est fourni sans `sortField`, l'ordre par défaut est la pertinence (pas
        `createdAt`). Le numéro de mandat (`mandate.referenceNumber`) n'est pas
        indexé : passer par `GET /external-integration/sale?customId=...` si
        vous avez le customId métier. Les champs non renseignés sont absents de
        la réponse (pas `null`). Endpoint en lecture seule.
      operationId: searchTransactions
      parameters:
        - $ref: '#/components/parameters/TransactionType'
        - name: search
          in: query
          required: false
          description: >-
            Texte libre. Minimum 3 caractères. Recherche sur nom / téléphone /
            email / adresse / customId. Les mots vides FR (`de`, `la`, `le`...)
            ne sont pas pris en compte.
          schema:
            type: string
            minLength: 3
        - $ref: '#/components/parameters/Page'
        - name: sortField
          in: query
          required: false
          description: Champ de tri. Défaut `createdAt`.
          schema:
            type: string
            enum:
              - createdAt
              - updatedAt
              - stepUpdatedAt
            default: createdAt
        - name: sortOrder
          in: query
          required: false
          description: >-
            Ordre de tri. Défaut `desc`. S'envoie avec `sortField` : seul, il
            est refusé (`400`).
          schema:
            type: string
            enum:
              - asc
              - desc
            default: desc
        - name: step
          in: query
          required: false
          description: >-
            Filtre sur l'étape. Valeurs autorisées selon le type : sale (`STK`,
            `TRN`, `ARC`, `PQUL`, `QUL`, `CNV`, `RDV`, `DLV`, `MND`, `TARC`,
            `OFR`, `AGT`, `MTG`, `SLD`) ; acquisition (`AQUL`, `ASRC`, `ANGT`,
            `AOFR`, `ACLS`, `AARC`) ; rental (`RQUL`, `RCNV`, `RRDV`, `RDLV`,
            `RMDT`, `RARC`, `RMAR`, `RRTD`, `RRTM`). Répétable → logique « OU ».
          style: form
          explode: true
          schema:
            type: array
            items:
              type: string
        - name: owner
          in: query
          required: false
          description: >-
            Filtre sur l'utilisateur Avest responsable du dossier (ObjectId).
            Répétable → logique « OU ».
          style: form
          explode: true
          schema:
            type: array
            items:
              type: string
        - name: tags
          in: query
          required: false
          description: >-
            Filtre sur un tag de la fiche (ObjectId). `acquisition` et `rental`
            uniquement (non supporté sur `sale` → `400`). Répétable → logique «
            OU ».
          style: form
          explode: true
          schema:
            type: array
            items:
              type: string
      responses:
        '200':
          description: >-
            Liste paginée de transactions. La clé `sales` / `acquisitions` /
            `rentals` dépend du type demandé.
          headers:
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimit-Limit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimit-Remaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimit-Reset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchTransactionsResponse'
              examples:
                sale:
                  summary: sale/search
                  value:
                    success: true
                    sales:
                      - id: 6a044cba8db14b3fbd015208
                        customId: BCOU2162
                        agency: 66cc91d475c9fac35c86ed80
                        agencyGroup: 66cc8a8e75c9fac35c6ecd73
                        step: MND
                        status: awaitingLaunch
                        project: B
                        property:
                          mainType: apartment
                          developmentType: old
                          size: 65
                          floor: 3
                          isCollectiveOwnership: true
                          addressData:
                            streetNumber: '3'
                            route: Avenue Reille
                            postalCode: '75014'
                            city: Paris
                            country: France
                            countryCode: FR
                            formattedAddress: 3 Av. Reille, 75014 Paris, France
                        mandate:
                          price: 252000
                          sellPrice: 240000
                          agencyCommission: 12000
                          type: notExclusive
                          referenceNumber: '1729'
                          feeResponsibility: seller
                          commissionPercentage: 4.76
                          commissionType: value
                          mandateDuration: 3
                          maxMandateDuration: 12
                        timeline:
                          mandateSignatureDate: '2026-05-13T14:59:03.596Z'
                        owner:
                          id: 6939530d9200187f19a2707d
                          firstName: Florian
                          lastName: PUJO
                          picture: >-
                            https://cdn.avest.fr/attachment/user/696e2f1adff893e4465d15b3
                        mainContact: 6a044cadd494814278d1fb84
                        contacts:
                          - id: 6a044cadd494814278d1fb84
                            firstName: Olivier
                            lastName: BOYER
                            title: mr
                            isIndividual: true
                            contactDetails:
                              - type: email
                                data: olivier.boyer@example.fr
                              - type: phone
                                data: '+33660598726'
                        createdAt: '2026-05-13T10:04:42.139Z'
                    page: 1
                    limit: 100
                    hasMore: true
                acquisition:
                  summary: acquisition/search
                  value:
                    success: true
                    acquisitions:
                      - id: 6a04a0aed4948142783f8cdf
                        customId: AABZJ7515
                        agency: 66cc92295f84c9b212dab7ef
                        agencyGroup: 66cc8a8e75c9fac35c6ecd73
                        step: AQUL
                        project: buyer
                        activityLevel: hot
                        propertiesTypes:
                          - apartment
                        priceRange:
                          high: 197000
                        sizeRange:
                          low: 51
                        roomRange:
                          low: 2
                        purpose: secondaryResidence
                        areas:
                          - type: postalCode
                            postalCode: '31000'
                            countryCode: FR
                          - type: postalCode
                            postalCode: '31400'
                            countryCode: FR
                        owner: null
                        mainContact: 6a04a0acd4948142783f8909
                        contacts:
                          - id: 6a04a0acd4948142783f8909
                            firstName: Yannick
                            lastName: BERGOUGNOUX
                            isIndividual: true
                            contactDetails:
                              - type: phone
                                data: '+33670567683'
                              - type: email
                                data: yan.bergou@example.fr
                        createdAt: '2026-05-13T16:02:54.888Z'
                    page: 1
                    limit: 100
                    hasMore: true
                rental:
                  summary: rental/search
                  value:
                    success: true
                    rentals:
                      - id: 69fcb723ac44aa882a150bbc
                        customId: REBZJ7515
                        agency: 6937f7389200187f198aaa07
                        agencyGroup: 66cc8a8e75c9fac35c6ecd73
                        step: RQUL
                        project: OTR
                        type: longTerm
                        property:
                          mainType: apartment
                          developmentType: old
                          size: 24.79
                          floor: 2
                          rooms: 2
                          bedrooms: 1
                          addressData:
                            streetNumber: '21'
                            route: Rue des Salines
                            postalCode: '87500'
                            city: Saint-Yrieix-la-Perche
                            country: France
                            countryCode: FR
                            formattedAddress: 21 Rue Des Salines, 87500 Saint-Yrieix-la-Perche
                        owner:
                          id: 693fd8823b8b4059ba4ea468
                          firstName: Imogen
                          lastName: RUSSEL
                        mainContact: 694a6a2fbe34c245521ce681
                        contacts:
                          - id: 694a6a2fbe34c245521ce681
                            firstName: Raphael
                            lastName: LORENZI
                            isIndividual: true
                            contactDetails:
                              - type: email
                                data: raph.lorenzi@example.fr
                        createdAt: '2026-05-07T16:00:35.683Z'
                    page: 1
                    limit: 100
                    hasMore: true
                vide:
                  summary: Aucun résultat
                  value:
                    success: true
                    sales: []
                    page: 1
                    limit: 100
                    hasMore: false
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
components:
  parameters:
    TransactionType:
      name: transaction
      in: path
      required: true
      description: Type de transaction.
      schema:
        type: string
        enum:
          - acquisition
          - sale
          - rental
    Page:
      name: page
      in: query
      required: false
      description: Page 1-indexée. Défaut `1`. Max `100`.
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 1
  headers:
    RateLimit-Limit:
      description: Nombre de requêtes autorisées dans la fenêtre courante.
      schema:
        type: integer
    RateLimit-Remaining:
      description: Requêtes restantes dans la fenêtre courante.
      schema:
        type: integer
    RateLimit-Reset:
      description: Secondes avant la réinitialisation de la fenêtre.
      schema:
        type: integer
    Retry-After:
      description: Secondes à attendre avant de réessayer (présent sur les réponses `429`).
      schema:
        type: integer
  schemas:
    SearchTransactionsResponse:
      type: object
      description: >-
        La clé contenant les résultats (`sales` / `acquisitions` / `rentals`)
        dépend du type demandé.
      properties:
        success:
          type: boolean
          const: true
        sales:
          type: array
          items:
            $ref: '#/components/schemas/SaleRead'
        acquisitions:
          type: array
          items:
            $ref: '#/components/schemas/AcquisitionRead'
        rentals:
          type: array
          items:
            $ref: '#/components/schemas/RentalRead'
        page:
          type: integer
        limit:
          type: integer
          description: >-
            Taille de page (fixe, non paramétrable). ⚠️ Ce champ s'appelle
            `limit` ici, mais `pageSize` sur `/activities` et `/ad/search` —
            deux noms pour la même chose, historique et conservé pour ne pas
            casser les intégrations existantes.
        hasMore:
          type: boolean
    SaleRead:
      type: object
      description: >-
        Vente en lecture. `id`, `customId`, `agency`, `agencyGroup`, `step`,
        `createdAt`, `updatedAt`, `stepUpdatedAt`, `owner` et `mainContact` sont
        toujours présents (si la vente existe). Les autres champs sont absents
        s'ils ne sont pas renseignés.
      properties:
        id:
          $ref: '#/components/schemas/ObjectId'
        customId:
          type: string
        agency:
          $ref: '#/components/schemas/ObjectId'
        agencyGroup:
          $ref: '#/components/schemas/ObjectId'
        step:
          type: string
          description: Étape courante (`QUL`, `CNV`, `RDV`, `MND`, `ARC`, etc.).
        createdAt:
          type: string
          description: Date de création (ISO 8601).
        updatedAt:
          type: string
          description: >-
            Date de dernière modification (ISO 8601). Combiné à
            `sortField=updatedAt` sur `/search`, permet de ne resynchroniser que
            les ventes modifiées depuis votre dernier passage.
        stepUpdatedAt:
          type: string
          description: Date du dernier changement d'étape (ISO 8601).
        owner:
          $ref: '#/components/schemas/Owner'
        mainContact:
          oneOf:
            - $ref: '#/components/schemas/ObjectId'
            - type: 'null'
          description: ObjectId du vendeur principal. `null` si aucun contact lié.
        status:
          type: string
        state:
          type: string
        project:
          type: string
        parsingCustomId:
          type: string
        property:
          $ref: '#/components/schemas/PropertyRead'
        mandate:
          $ref: '#/components/schemas/SaleMandateRead'
        offer:
          type: object
          additionalProperties: true
        timeline:
          $ref: '#/components/schemas/Timeline'
        fieldValue:
          $ref: '#/components/schemas/Range'
        onlineValue:
          $ref: '#/components/schemas/Range'
        contacts:
          type: array
          description: >-
            Présent dans la réponse de recherche (`/search`). Le premier élément
            correspond au `mainContact`.
          items:
            $ref: '#/components/schemas/Contact'
    AcquisitionRead:
      type: object
      description: >-
        Acquisition en lecture. `id`, `customId`, `agency`, `agencyGroup`,
        `step`, `createdAt`, `updatedAt`, `stepUpdatedAt`, `owner` et
        `mainContact` sont toujours présents (si l'acquisition existe). Les
        autres champs sont absents s'ils ne sont pas renseignés.
      properties:
        id:
          $ref: '#/components/schemas/ObjectId'
        customId:
          type: string
        agency:
          $ref: '#/components/schemas/ObjectId'
        agencyGroup:
          $ref: '#/components/schemas/ObjectId'
        step:
          type: string
          description: Étape courante de l'acquisition.
          enum:
            - AQUL
            - ASRC
            - ANGT
            - AOFR
            - ACLS
            - AARC
        createdAt:
          type: string
        updatedAt:
          type: string
          description: Date de dernière modification (ISO 8601).
        stepUpdatedAt:
          type: string
          description: Date du dernier changement d'étape (ISO 8601).
        owner:
          $ref: '#/components/schemas/Owner'
        mainContact:
          oneOf:
            - $ref: '#/components/schemas/ObjectId'
            - type: 'null'
        project:
          type: string
          description: Projet (`buyer`, `buyerSeller`, `buyerOwner`, ...).
        activityLevel:
          type: string
          enum:
            - hot
            - warm
            - cold
            - mandate
        propertiesTypes:
          type: array
          items:
            type: string
        areas:
          type: array
          items:
            $ref: '#/components/schemas/Area'
        priceRange:
          $ref: '#/components/schemas/Range'
        sizeRange:
          $ref: '#/components/schemas/Range'
        roomRange:
          $ref: '#/components/schemas/Range'
        bedroomRange:
          $ref: '#/components/schemas/Range'
        floorRange:
          $ref: '#/components/schemas/Range'
        fieldRange:
          $ref: '#/components/schemas/Range'
        elevator:
          type: string
        outdoor:
          type: string
        parking:
          type: string
        pool:
          type: string
        lastFloor:
          type: string
        groundFloor:
          type: string
        bikeShed:
          type: boolean
        mortgageType:
          type: string
          enum:
            - relay
            - standard
            - none
        mortgage:
          type: boolean
        purpose:
          type: string
          enum:
            - primaryResidence
            - secondaryResidence
            - businessPremise
            - investment
            - propertyTrade
        mandate:
          type: object
          additionalProperties: true
        parsingCustomId:
          type: string
        contacts:
          type: array
          description: Présent dans la réponse de recherche (`/search`).
          items:
            $ref: '#/components/schemas/Contact'
    RentalRead:
      type: object
      description: >-
        Location en lecture. `id`, `customId`, `agency`, `agencyGroup`, `step`,
        `createdAt`, `updatedAt`, `stepUpdatedAt`, `owner` et `mainContact` sont
        toujours présents (si la location existe). Les autres champs sont
        absents s'ils ne sont pas renseignés.
      properties:
        id:
          $ref: '#/components/schemas/ObjectId'
        customId:
          type: string
        agency:
          $ref: '#/components/schemas/ObjectId'
        agencyGroup:
          $ref: '#/components/schemas/ObjectId'
        step:
          type: string
          description: Étape courante (`RQUL`, `RCNV`, `RVST`, `RBAIL`, `ROCC`, ...).
        createdAt:
          type: string
        updatedAt:
          type: string
          description: Date de dernière modification (ISO 8601).
        stepUpdatedAt:
          type: string
          description: Date du dernier changement d'étape (ISO 8601).
        owner:
          $ref: '#/components/schemas/Owner'
        mainContact:
          oneOf:
            - $ref: '#/components/schemas/ObjectId'
            - type: 'null'
        type:
          type: string
          description: '`longTerm`, `furnishedRental`, `seasonal`, ...'
        project:
          type: string
        property:
          $ref: '#/components/schemas/PropertyRead'
        mandate:
          type: object
          additionalProperties: true
        timeline:
          $ref: '#/components/schemas/Timeline'
        fieldValue:
          $ref: '#/components/schemas/Range'
        onlineValue:
          $ref: '#/components/schemas/Range'
        fieldQuote:
          $ref: '#/components/schemas/Range'
        onlineQuote:
          $ref: '#/components/schemas/Range'
        currentValue:
          type: number
        parsingCustomId:
          type: string
        contacts:
          type: array
          description: Présent dans la réponse de recherche (`/search`).
          items:
            $ref: '#/components/schemas/Contact'
    ErrorResponse:
      type: object
      required:
        - success
        - message
      properties:
        success:
          type: boolean
          const: false
        errorCode:
          type: string
          description: >-
            Code stable, présent sur certaines erreurs seulement (par exemple
            `VISIT_DATE_REQUIRED`, `CONTACT_DELETED`). À préférer à `message`
            pour reconnaître une erreur.
        message:
          type: string
    RateLimitErrorResponse:
      type: object
      required:
        - success
        - message
      properties:
        success:
          type: boolean
          const: false
        message:
          type: string
          example: Rate limit exceeded
        retryAfter:
          type: integer
          description: Secondes avant de pouvoir réessayer.
    ObjectId:
      type: string
      description: Identifiant Mongo (24 caractères hexadécimaux).
      pattern: ^[a-fA-F0-9]{24}$
      example: 618a35a36d932054e195ca0a
    Owner:
      type: object
      nullable: true
      description: Utilisateur Avest responsable du dossier. `null` si non attribué.
      properties:
        id:
          $ref: '#/components/schemas/ObjectId'
        firstName:
          type: string
        lastName:
          type: string
        picture:
          type: string
          description: URL de la photo (optionnelle).
    PropertyRead:
      type: object
      description: >-
        Bien immobilier tel que retourné en lecture. Seuls les champs renseignés
        sont présents ; cette liste n'est pas exhaustive.
      properties:
        mainType:
          type: string
          description: 'Ex: `apartment`, `house`, `field`, `building`, `parking`, etc.'
        developmentType:
          type: string
          enum:
            - old
            - new
        size:
          type: number
        floor:
          type: integer
        lastFloor:
          type: integer
        lotsNumbers:
          type: string
        rooms:
          type: integer
        bedrooms:
          type: integer
        bathrooms:
          type: integer
        toilets:
          type: integer
        kitchenType:
          type: string
        isCollectiveOwnership:
          type: boolean
        collectiveMonthlyCost:
          type: number
        numberOfLots:
          type: integer
        heatingType:
          type: string
        heatingEnergyType:
          type: string
        DPENumber:
          type: string
        DPEEnergyValue:
          type: number
        DPEEnergyTag:
          $ref: '#/components/schemas/DPETag'
        DPEGESValue:
          type: number
        DPEGESTag:
          $ref: '#/components/schemas/DPETag'
        DPEDate:
          type: string
        availabilityDate:
          type: string
        propertyTaxResponsibility:
          type: string
          enum:
            - owner
            - tenant
          description: >-
            Taxe foncière à la charge du bailleur (`owner`) ou du preneur
            (`tenant`). Bien professionnel.
        vatRegime:
          type: string
          enum:
            - subject
            - exempt
          description: Bien professionnel soumis (`subject`) ou non (`exempt`) à la TVA.
        addressData:
          $ref: '#/components/schemas/AddressData'
      additionalProperties: true
    SaleMandateRead:
      type: object
      description: >-
        Mandat de vente, renseigné à partir de l'étape `MND`. Avant, l'objet
        peut être présent avec seulement `mandateHistory`.
      properties:
        price:
          type: number
          description: Prix affiché honoraires inclus (HAI), calculé automatiquement.
        sellPrice:
          type: number
          description: Net vendeur.
        agencyCommission:
          type: number
          description: Montant des honoraires.
        feeResponsibility:
          type: string
          enum:
            - seller
            - buyer
            - both
        commissionPercentage:
          type: number
        commissionType:
          type: string
          enum:
            - value
            - percentage
        sellerAgencyCommission:
          type: number
          description: >-
            Part vendeur des honoraires, renseignée seulement en charge `both`.
            La part acquéreur vaut `agencyCommission` moins cette part.
        sellerAgencyCommissionPercentage:
          type: number
          description: >-
            Part vendeur en %, sur la même base que `commissionPercentage`,
            renseignée seulement en charge `both`.
        type:
          type: string
          enum:
            - exclusive
            - semiExclusive
            - notExclusive
        referenceNumber:
          type: string
        mandateDuration:
          type: integer
        maxMandateDuration:
          type: integer
        expirationDate:
          type: string
        mandateHistory:
          type: array
          description: >-
            Historique des modifications du net vendeur, des honoraires et du
            type de mandat. Vide si le mandat n'a jamais été modifié.
          items:
            type: object
            additionalProperties: true
            properties:
              date:
                type: string
                description: Date de la modification (ISO 8601).
              changes:
                type: array
                items:
                  type: object
                  additionalProperties: true
                  properties:
                    field:
                      type: string
                    from: {}
                    to: {}
    Timeline:
      type: object
      description: Dates clés du dossier (uniquement les dates renseignées).
      properties:
        mandateSignatureDate:
          type: string
        agreementDate:
          type: string
        agreementExpirationDate:
          type: string
        offerDate:
          type: string
        mortgageDeadline:
          type: string
        closingDate:
          type: string
        estimationDate:
          type: string
        estimationStartAt:
          type: string
        estimationEndAt:
          type: string
    Range:
      type: object
      description: Fourchette de valeurs.
      properties:
        low:
          type: number
        high:
          type: number
    Contact:
      type: object
      description: >-
        Contact. `firstName` / `lastName` si `isIndividual: true` ;
        `commercialName` / `corporateName` si entreprise (`isIndividual:
        false`).
      properties:
        id:
          $ref: '#/components/schemas/ObjectId'
        title:
          type: string
          enum:
            - mr
            - mme
        firstName:
          type: string
        lastName:
          type: string
        commercialName:
          type: string
        corporateName:
          type: string
        isIndividual:
          type: boolean
        contactDetails:
          type: array
          items:
            $ref: '#/components/schemas/ContactDetail'
    Area:
      type: object
      properties:
        type:
          type: string
          enum:
            - postalCode
            - inseeCode
            - departmentCode
            - geometry
        postalCode:
          type: string
        inseeCode:
          type: string
        countryCode:
          type: string
          description: Code pays ISO 3166-1 alpha-2.
        addresses:
          type: array
          items:
            type: object
            additionalProperties: true
        geometry:
          type: object
          additionalProperties: true
          description: Polygone GeoJSON, si `type = geometry`.
        center:
          type: object
          additionalProperties: true
          description: >-
            Centre d'une zone tracée en cercle dans Avest (GeoJSON `Point`), si
            `type = geometry`.
        radius:
          type: number
          description: Rayon de ce cercle, en km.
    DPETag:
      type: string
      enum:
        - A
        - B
        - C
        - D
        - E
        - F
        - G
    AddressData:
      type: object
      description: Adresse splittée.
      properties:
        streetNumber:
          type: string
        route:
          type: string
        city:
          type: string
        postalCode:
          type: string
        country:
          type: string
        countryCode:
          type: string
          description: Code pays ISO 3166-1 alpha-2.
        formattedAddress:
          type: string
        department:
          type: string
        region:
          type: string
    ContactDetail:
      type: object
      properties:
        type:
          type: string
          enum:
            - email
            - phone
        data:
          type: string
      required:
        - type
        - data
  responses:
    BadRequest:
      description: >-
        Requête invalide. Le champ `message` précise la cause (paramètre
        manquant, invalide, mutuellement exclusif, clé de query inconnue,
        `LinkedAPI agencyGroup is required`, etc.).


        Les exemples ci-dessous sont **illustratifs et non exhaustifs** : les
        messages réellement renvoyés dépendent de la route. En particulier, le
        rejet des clés de query inconnues n'est appliqué que par `/contact`,
        `/contacts`, `/user`, `/users` et `/{transaction}/search`.


        La plupart des messages de validation sont préfixés par le contexte qui
        les émet, sous la forme `"<Contexte> : <message>"`. **Ne faites jamais
        de correspondance exacte sur `message`** : basez-vous sur le code HTTP
        et traitez `message` comme du texte destiné au diagnostic.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            unParametreRequis:
              value:
                success: false
                message: One of phone, email, or search is required
            exclusif:
              value:
                success: false
                message: Provide exactly one of phone, email, or search
            queryInconnue:
              value:
                success: false
                message: 'Unsupported query parameter: foo'
            telephoneInvalide:
              value:
                success: false
                message: Invalid phone number
            emailInvalide:
              value:
                success: false
                message: Invalid email
            searchTropCourt:
              value:
                success: false
                message: search must be at least 3 characters
            pageHorsLimites:
              value:
                success: false
                message: page must be <= 100
            agencyGroupManquant:
              value:
                success: false
                message: LinkedAPI agencyGroup is required
    Unauthorized:
      description: >-
        Token invalide. Renvoyé quand le header `Authorization: Bearer` est
        présent mais que sa valeur n'est pas un token exploitable (malformé,
        signature invalide, valeur vide) — `message` vaut alors `Invalid bearer
        token`.


        Un token bien formé mais qui ne correspond plus à aucune clé (révoquée
        ou régénérée) donne aussi un `401`, avec le message `Not authorized to
        access this resource`.


        L'absence du header, une clé en lecture seule et une IP non autorisée
        renvoient un `403`, pas un `401`.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            tokenInvalide:
              value:
                success: false
                message: Invalid bearer token
            cleInconnue:
              value:
                success: false
                message: Not authorized to access this resource
    Forbidden:
      description: >-
        Accès refusé. Trois causes donnent **exactement la même réponse** (même
        code, même `message`) :


        1. le header `Authorization` est absent ;

        2. la clé est en **lecture seule** et la requête est un `POST` ou un
        `PATCH` (voir le guide Authentification) ;

        3. la clé est en mode **sécurisé** et l'IP d'appel, lue dans
        `X-Real-IP`, n'est pas celle autorisée.


        Sur les routes d'écriture, un document lié hors du périmètre de la clé
        renvoie également ce `403`.


        Un `403` sur vos seules écritures alors que vos lectures passent = clé
        en lecture seule.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            message: Not authorized to access this resource
    TooManyRequests:
      description: >-
        Limite de débit dépassée : limite de la route (par groupe d'agences et
        par chemin) ou limite globale (200 requêtes / 10 s par clé, `message`
        `Too many requests, please try again later`).
      headers:
        Retry-After:
          $ref: '#/components/headers/Retry-After'
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimit-Limit'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimit-Remaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimit-Reset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RateLimitErrorResponse'
          example:
            success: false
            message: Rate limit exceeded
            retryAfter: 27
  securitySchemes:
    linkedApiToken:
      type: http
      scheme: bearer
      description: >-
        Token LinkedAPI avec scope `externalIntegration`. La clé doit avoir un
        `agencyGroup` configuré (sinon `400 LinkedAPI agencyGroup is required`).
        Fourni via l'en-tête `Authorization: Bearer {linkedAPI_token}`. Si la
        clé a `secure === true`, l'IP appelante doit être whitelistée (en-tête
        `X-Real-IP`), sinon `403 Not authorized to access this resource`.


        La clé porte aussi un **niveau d'accès** : en lecture seule, elle
        n'autorise que les `GET` ; un `POST` ou un `PATCH` renvoie alors `403
        Not authorized to access this resource`, soit la même réponse qu'une
        requête sans en-tête `Authorization`. Voir le guide Authentification.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.