​
Endpoint

POST /api/candidate/:id?apiKey=xxxxx
Il faudra que l’équipe Flatbay vous fournisse une clé API pour utiliser cette route.

​
Description

Cette route permet de mettre à jour une candidature existante :
  • Changer son statut (status) — avec gestion automatique de l’archivage selon le statut, mise à jour du timestamp statusAt, et écriture dans l’historique des changements de statut.
  • Renseigner une raison de perte (lostReason) — typiquement utilisée avec status=candidate.status.lost.
  • Archiver / désarchiver explicitement la candidature (archive).
Le changement de statut déclenche également les webhooks de type candidate_status configurés sur le groupe et rafraîchit les compteurs du bien associé.

​
Paramètres

​
Path Parameter

ParamètreTypeRequisDescription
idintegerOuiIdentifiant de la candidature

​
Query Parameters

ParamètreTypeRequisDescription
apiKeystringOuiVotre clé API
statusstringNonNouveau statut de la candidature (voir liste ci-dessous)
lostReasonstringNonRaison de perte. Pris en compte lorsque status=candidate.status.lost
archivestringNon"1" pour archiver la candidature, "0" pour la désarchiver
Au moins un des trois paramètres status, lostReason ou archive doit être fourni pour que la requête ait un effet.

​
Valeurs possibles pour status

​
Candidatures locataires / acheteurs (cas le plus fréquent)

ValeurDescription
candidate.status.demandeNon traitée (statut initial)
candidate.status.relance1Relancé 1x
candidate.status.relance2Relancé 2x
candidate.status.interesseIntéressé
candidate.status.maybeÀ l’étude
candidate.status.okAcceptée
candidate.status.koRefusée
candidate.status.cancelDésistement (archive automatiquement la candidature)
candidate.status.notinsearchNe cherche plus
candidate.status.lostPerdu (utilisable avec lostReason)

​
Mandants / prospects vendeurs

ValeurDescription
candidate.status.contacteProspect contacté
candidate.status.estimEnvoyeEstimation envoyée
candidate.status.attDocEn attente de document
candidate.status.mandatEnvMandat envoyé
candidate.status.mandatSigneMandat signé
candidate.status.lostPerdu

​
Valeurs suggérées pour lostReason

lostReason accepte n’importe quelle chaîne libre. Pour rester compatible avec les filtres internes Flatbay, privilégier l’une des valeurs suivantes :
  • candidate.lostReason.outofarea — Hors secteur
  • candidate.lostReason.notresponse — Sans réponse
  • candidate.lostReason.otheretablissement — Parti chez un confrère
  • candidate.lostReason.treatmenttoolong — Traitement trop long
  • candidate.lostReason.pricetoohigh — Prix trop élevé

​
Exemples de requête

Mettre une candidature en statut « Intéressé » : 
POST /api/candidate/12345?apiKey=xxxxx&status=candidate.status.interesse
Marquer une candidature comme perdue avec une raison : 
POST /api/candidate/12345?apiKey=xxxxx&status=candidate.status.lost&lostReason=candidate.lostReason.pricetoohigh
Archiver une candidature sans changer son statut : 
POST /api/candidate/12345?apiKey=xxxxx&archive=1

​
Réponse

{
  "status": "ok"
}

​
Codes d’erreur

Code HTTPCode FlatbayCause
403NOAPIKEYLe paramètre apiKey est manquant
400BADPARAMSL’identifiant de la candidature est manquant
403CANDIDATENOTINYOURGROUPLa candidature ciblée n’appartient pas à un établissement de votre groupe