Mettre à jour une candidature

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ètre	Type	Requis	Description
`id`	integer	Oui	Identifiant de la candidature

Query Parameters

Paramètre	Type	Requis	Description
`apiKey`	string	Oui	Votre clé API
`status`	string	Non	Nouveau statut de la candidature (voir liste ci-dessous)
`lostReason`	string	Non	Raison de perte. Pris en compte lorsque `status=candidate.status.lost`
`archive`	string	Non	`"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)

Valeur	Description
`candidate.status.demande`	Non traitée (statut initial)
`candidate.status.relance1`	Relancé 1x
`candidate.status.relance2`	Relancé 2x
`candidate.status.interesse`	Intéressé
`candidate.status.maybe`	À l’étude
`candidate.status.ok`	Acceptée
`candidate.status.ko`	Refusée
`candidate.status.cancel`	Désistement (archive automatiquement la candidature)
`candidate.status.notinsearch`	Ne cherche plus
`candidate.status.lost`	Perdu (utilisable avec `lostReason`)

Mandants / prospects vendeurs

Valeur	Description
`candidate.status.contacte`	Prospect contacté
`candidate.status.estimEnvoye`	Estimation envoyée
`candidate.status.attDoc`	En attente de document
`candidate.status.mandatEnv`	Mandat envoyé
`candidate.status.mandatSigne`	Mandat signé
`candidate.status.lost`	Perdu

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 HTTP	Code Flatbay	Cause
403	`NOAPIKEY`	Le paramètre `apiKey` est manquant
400	`BADPARAMS`	L’identifiant de la candidature est manquant
403	`CANDIDATENOTINYOURGROUP`	La candidature ciblée n’appartient pas à un établissement de votre groupe

​Endpoint

​Description

​Paramètres

​Path Parameter

​Query Parameters

​Valeurs possibles pour status

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

​Mandants / prospects vendeurs

​Valeurs suggérées pour lostReason

​Exemples de requête

​Réponse

​Codes d’erreur