> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.client-p.pylote.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Recuperer les freelances

> Endpoint principal. Retourne les freelances modifies depuis `modifiedTime`, pagines.

Les freelances sont retournes au format [JSON Resume](https://jsonresume.org/schema/)
enrichi avec les metadonnees Pylote (`meta`).

**Recommandation** : pour une premiere synchronisation, utilisez `modifiedTime=0`
pour recuperer tous les freelances, puis stockez le timestamp de la derniere
synchronisation pour les appels suivants.




## OpenAPI

````yaml /openapi.yaml get /freelances
openapi: 3.1.0
info:
  title: Pylote Client API
  version: 1.0.4
  description: >
    API de distribution des profils freelances Pylote.


    Permet aux clients (recruteurs, integrateurs, partenaires) de recuperer

    les freelances depuis la base Pylote, gerer les whitelist recruteurs

    et tracker les consultations de profils.


    Les profils sont retournes au format [JSON
    Resume](https://jsonresume.org/schema/)

    enrichi avec les metadonnees Pylote (disponibilite, TJM, mobilites,
    competences).


    ## Engagements clients


    En utilisant cette API, vous vous engagez a :

    1. **Tracker les consultations** de profils via `POST
    /partners/{slug}/events` (contractuel)

    2. **Supprimer les profils** dont le `status` est `deleted` de votre base

    3. **Ne jamais exposer** les emails personnels des freelances (utiliser les
    emails proxy Pylote)


    ## Protection des donnees


    Les donnees sont transformees avant distribution :

    - Les emails personnels sont remplaces par des **emails proxy**
    (`@freelance.pylote.io`)

    - Le champ `personalEmail` est un **hash SHA-256** (pour dedoublonnage,
    jamais l'email en clair)

    - Les URLs LinkedIn et CV passent par `hive.pylote.io` (tracking watermarke)

    - Les identifiants (`meta.id`) sont **chiffres** (AES-256-CBC) et opaques
  contact:
    name: Pylote
    url: https://pylote.io
    email: contact@pylote.io
servers:
  - url: https://client-p.pylote.io
    description: Production
  - url: https://client-pp.pylote.io
    description: Preprod
security:
  - apiKey: []
tags:
  - name: Freelances
    description: >
      Endpoints principaux pour recuperer les profils freelances.

      Les profils sont au format JSON Resume enrichi avec les metadonnees
      Pylote.
  - name: Partners
    description: >
      Endpoints pour les partenaires de distribution (ex: Agrega).

      Gestion de la whitelist recruteurs et **tracking obligatoire** des
      consultations de profils.
  - name: Integration
    description: |
      Endpoints pour les integrateurs (ex: BoondManager).
      Gestion des sous-clients et de leurs whitelist recruteurs.
  - name: Sandbox
    description: >
      Endpoints de test avec donnees anonymisees. Aucune cle API requise.

      Utilisez la sandbox pour valider votre integration avant de passer en
      production.
  - name: Admin
    description: >-
      Endpoints d'administration (cache, debug). Requiert un flag admin sur la
      cle API.
  - name: Health
    description: Health check de l'API et de ses dependances externes
paths:
  /freelances:
    get:
      tags:
        - Freelances
      summary: Recuperer les freelances
      description: >
        Endpoint principal. Retourne les freelances modifies depuis
        `modifiedTime`, pagines.


        Les freelances sont retournes au format [JSON
        Resume](https://jsonresume.org/schema/)

        enrichi avec les metadonnees Pylote (`meta`).


        **Recommandation** : pour une premiere synchronisation, utilisez
        `modifiedTime=0`

        pour recuperer tous les freelances, puis stockez le timestamp de la
        derniere

        synchronisation pour les appels suivants.
      operationId: getFreelances
      parameters:
        - name: modifiedTime
          in: query
          required: true
          description: >
            Timestamp Unix (en secondes). Seuls les freelances modifies apres
            cette date sont retournes.

            Utilisez `0` pour tout recuperer.
          schema:
            type: integer
          example: 1712089295
        - name: page
          in: query
          required: true
          description: Numero de page (commence a 1)
          schema:
            type: integer
            minimum: 1
          example: 1
        - name: limit
          in: query
          required: true
          description: Nombre de freelances par page (max 1000)
          schema:
            type: integer
            maximum: 1000
          example: 50
        - name: showDeleted
          in: query
          required: false
          description: Inclure les freelances supprimes (default `true`)
          schema:
            type: boolean
            default: true
      responses:
        '200':
          description: Liste paginee de freelances
          content:
            application/json:
              schema:
                type: object
                properties:
                  freelances:
                    type: array
                    items:
                      $ref: '#/components/schemas/JsonResume'
                  infos:
                    $ref: '#/components/schemas/PaginationInfos'
        '400':
          description: Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
        '401':
          description: Cle API manquante
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
        '403':
          description: Cle API invalide
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenError'
components:
  schemas:
    JsonResume:
      type: object
      properties:
        basics:
          $ref: '#/components/schemas/Basics'
        work:
          type: array
          items:
            $ref: '#/components/schemas/Work'
        education:
          type: array
          items:
            $ref: '#/components/schemas/Education'
        certificates:
          type: array
          items:
            $ref: '#/components/schemas/Certificate'
        skills:
          type: array
          items:
            $ref: '#/components/schemas/Skill'
        languages:
          type: array
          items:
            $ref: '#/components/schemas/Language'
        meta:
          $ref: '#/components/schemas/Meta'
        volunteer:
          type: array
          items: {}
        awards:
          type: array
          items: {}
        publications:
          type: array
          items: {}
        interests:
          type: array
          items: {}
        references:
          type: array
          items: {}
        projects:
          type: array
          items: {}
    PaginationInfos:
      type: object
      properties:
        total:
          type: integer
          description: Nombre total de freelances correspondant aux criteres
          example: 1234
        page:
          type: integer
          description: Page actuelle
          example: 1
        limit:
          type: integer
          description: Nombre de freelances par page
          example: 50
        totalPages:
          type: integer
          description: Nombre total de pages
          example: 25
    ValidationError:
      type: object
      properties:
        error:
          type: string
          example: Validation failed
        message:
          type: string
          example: '"modifiedTime" is required'
    UnauthorizedError:
      type: object
      properties:
        statusCode:
          type: integer
          example: 401
        message:
          type: string
          example: Missing x-api-key header
    ForbiddenError:
      type: object
      properties:
        statusCode:
          type: integer
          example: 403
        message:
          type: string
          example: Invalid API key
    Basics:
      type: object
      properties:
        name:
          type: string
          description: Prenom et nom du freelance
          example: Jean Dupont
        label:
          type: string
          description: Titre professionnel
          example: Developpeur Full Stack
        image:
          type: string
          description: URL de l'avatar (vide si non renseigne)
          example: ''
        email:
          type: string
          description: Email proxy Pylote (jamais l'email personnel)
          example: dupont.j@freelance.pylote.io
        phone:
          type: string
          example: ''
        url:
          type: string
          description: >
            URL du profil LinkedIn du freelance, passant par le proxy
            `hive.pylote.io`.

            Contient un watermark (IP encodee) pour le suivi des consultations.

            Ne partagez pas cette URL en dehors de votre plateforme.
          example: https://hive.pylote.io/linkedin/ldp9kOK_xyz123/pk_client?t=dGVzdA
        summary:
          type: string
          description: Description du freelance (similaire LinkedIn), si renseignee
          example: 10 ans d'experience en dev web, specialise React et Node.js
        location:
          $ref: '#/components/schemas/Location'
        profiles:
          type: array
          items:
            $ref: '#/components/schemas/Profile'
    Work:
      type: object
      properties:
        name:
          type: string
          description: Nom de l'entreprise
          example: Capgemini
        position:
          type: string
          example: Lead Developer
        startDate:
          type: string
          format: date
        endDate:
          type: string
          format: date
        summary:
          type: string
    Education:
      type: object
      properties:
        institution:
          type: string
          example: Ecole 42
        area:
          type: string
        studyType:
          type: string
          example: Master
        startDate:
          type: string
          format: date
        endDate:
          type: string
          format: date
    Certificate:
      type: object
      properties:
        name:
          type: string
          example: AWS Solutions Architect
        issuer:
          type: string
          example: Amazon Web Services
        url:
          type: string
        startDate:
          type: string
          format: date
    Skill:
      type: object
      properties:
        name:
          type: string
          example: React
        level:
          type: string
          example: Senior
        keywords:
          type: array
          items:
            type: string
    Language:
      type: object
      properties:
        language:
          type: string
          example: Francais
        fluency:
          type: string
          example: Langue maternelle
    Meta:
      type: object
      properties:
        id:
          type: string
          description: >
            Identifiant unique du freelance. C'est un identifiant **chiffre**
            (AES-256-CBC),

            opaque pour le client. Utilisez-le tel quel pour indexer les
            freelances dans votre base

            et pour les references dans `POST /partners/{slug}/events`.
          example: ldp9kOK_xyz123
        status:
          type: string
          enum:
            - completed
            - deleted
          description: |
            - `completed` : profil actif et complet
            - `deleted` : profil a supprimer de votre base
        createdAt:
          type: string
          format: date-time
          description: Date de creation du profil
        updatedAt:
          type: string
          format: date-time
          description: Derniere modification du profil par le freelance
        personalEmail:
          type: string
          description: >
            Hash SHA-256 de l'email personnel du freelance, sale avec un secret
            Pylote.

            Sert **exclusivement au dedoublonnage** : si deux profils ont le
            meme hash,

            c'est le meme freelance. Vous ne pouvez pas retrouver l'email a
            partir du hash.
        firstName:
          type: string
          example: Jean
        lastName:
          type: string
          example: Dupont
        freelance:
          $ref: '#/components/schemas/MetaFreelance'
    Location:
      type: object
      description: Lieu de residence du freelance, si renseigne
      properties:
        address:
          type: string
          description: 'Format : Ville, Pays'
          example: Paris, France
        postalCode:
          type: string
          example: '75001'
        city:
          type: string
          example: Paris
        countryCode:
          type: string
          description: Code ISO du pays
          example: FR
        region:
          type: string
          example: Ile-de-France
    Profile:
      type: object
      properties:
        username:
          type: string
        network:
          type: string
          example: LinkedIn
        url:
          type: string
    MetaFreelance:
      type: object
      properties:
        available:
          type: boolean
          description: Le freelance est-il disponible ?
        availabilityDate:
          type: string
          description: Date de disponibilite (format libre, ex. "01/06/2026")
        rate:
          type: string
          description: |
            Taux journalier moyen (TJM).
            C'est une **string**, pas un nombre. Peut contenir du texte libre.
            Exemples : "450", "400-500", "Negociable", "".
          example: '450'
        seniority:
          type: string
          description: Niveau d'experience
          enum:
            - ''
            - Junior (0-2 ans)
            - Confirme (3-6 ans)
            - Senior (7-10 ans)
            - Expert (10+ ans)
        professions:
          type: array
          description: Metiers du freelance (referentiel Pylote)
          items:
            type: string
          example:
            - Developpeur Back-End
            - DevOps
        openToCdi:
          type: boolean
          description: Le freelance est-il ouvert au CDI ?
        vehicle:
          type: boolean
          description: Le freelance est-il vehicule ?
        preferences:
          $ref: '#/components/schemas/Preferences'
    Preferences:
      type: object
      properties:
        missionDuration:
          type: array
          description: Durees de mission acceptees
          items:
            type: string
            enum:
              - < 3 mois
              - 3 a 6 mois
              - 6 a 12 mois
              - '> 12 mois'
          example:
            - 3 a 6 mois
            - 6 a 12 mois
        remoteWork:
          type: array
          description: Preferences de teletravail
          items:
            type: string
            enum:
              - Sur site
              - Hybride
              - Full remote
          example:
            - Hybride
            - Full remote
        daysPerWeek:
          type: array
          description: Jours par semaine disponibles
          items:
            type: string
            enum:
              - '1'
              - '2'
              - '3'
              - '4'
              - '5'
          example:
            - '4'
            - '5'
        workAreas:
          type: array
          description: Zones de mobilite du freelance
          items:
            $ref: '#/components/schemas/WorkArea'
    WorkArea:
      type: object
      description: >
        Zone de mobilite. Le type determine quels champs sont presents.

        Les mobilites peuvent etre en France, Belgique, Suisse, Luxembourg ou
        Andorre.
      properties:
        type:
          type: string
          enum:
            - ville
            - departement
            - region
            - pays
        code:
          type: string
          description: Code unique du lieu (deprecated, utiliser les champs specifiques)
          deprecated: true
        label:
          type: string
          description: Label du lieu (deprecated, utiliser les champs specifiques)
          deprecated: true
        cityZipCode:
          type: string
          description: Code postal (type `ville` uniquement)
          example: '75001'
        cityName:
          type: string
          description: Nom de la ville (type `ville` uniquement)
          example: Paris
        departmentCode:
          type: string
          description: Code du departement (types `ville` et `departement`)
          example: '75'
        departmentName:
          type: string
          description: Nom du departement
          example: Paris
        regionCode:
          type: string
          description: Code de la region (absent pour type `pays`)
          example: '11'
        regionName:
          type: string
          description: Nom de la region (absent pour type `pays`)
          example: Ile-de-France
        countryCode:
          type: string
          description: Code ISO du pays
          example: FR
        countryName:
          type: string
          description: Nom du pays
          example: France
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: >
        Cle API fournie par Pylote. Inclure dans le header `x-api-key` de chaque
        requete.


        Exemple : `x-api-key: votre-cle-api`

````