Accueil

Documentation

API Scorimmo

Faites remplir ses critères à l'acheteur, recevez-les dans votre logiciel, puis classez les fiches de vos recherches selon ces critères. L'affichage reste entièrement de votre côté.

Aperçu

Le parcours, de bout en bout :

  1. Le courtier clique sur la fiche d'un projet (ou d'un prospect : Scorimmo n'a pas besoin de savoir lequel). Votre logiciel appelle POST /criteria-links avec votre identifiant pour cet élément (external_ref). Scorimmo y rattache un jeu de critères et renvoie un lien.
  2. L'acheteur ouvre le lien — sans compte ni mot de passe, le jeton est dans l'URL. Il répond au questionnaire, ou décrit sa recherche avec ses mots : texte, PDF ou message vocal. Il envoie.
  3. Les critères sont générés et vous parviennent par webhook (criteria_set.updated). Vous les affichez ; le courtier les modifie avec les routes /criteria-sets.
  4. Une recherche dans votre logiciel envoie le jeu de critères et les fiches (jusqu'à 100) à POST /analyses/batch. Les scores et leur détail reviennent dans la réponse, au fil de l'eau, ou par webhook fiche par fiche.
  • Toutes les routes sont sous /v1/partner. L'adresse de l'API vous est communiquée avec votre jeton.
  • Requêtes et réponses en JSON (Content-Type: application/json), UTF-8.
  • Les montants et surfaces sont exprimés dans la devise et l'unité du marché de votre contrat (ex. : CAD et pi² au Québec, EUR et m² en France).
  • Les messages d'erreur (detail) sont rédigés en français.
MéthodeRouteUsage
GET/accountcontrat, marché, consommation du mois
GET/criteria-schemachamps, mesures et types de lieux utilisables
PUT/webhookvotre point de réception (secret renvoyé une fois)
GET/webhookle webhook configuré
DELETE/webhookle retirer
POST/webhook/testenvoyer un ping signé, voir le résultat
GET/webhook/deliveriesenvois récents (?status=failed)
GET/webhook/deliveries/{id}un envoi, avec son contenu
POST/webhook/deliveries/{id}/retryrenvoyer
POST/criteria-linksun lien pour l'acheteur (crée le jeu au besoin)
GET/criteria-links/{link_id}où en est ce lien
GET/criteria-sets?external_ref=…vos jeux, avec leurs critères
GET/criteria-sets/{id}un jeu
PUT/criteria-sets/{id}/criteriaremplacer toute la liste
POST/criteria-sets/{id}/criteriaajouter un critère
PATCH/criteria-sets/{id}/criteria/{critere}modifier un critère
DELETE/criteria-sets/{id}/criteria/{critere}retirer un critère
DELETE/criteria-sets/{id}supprimer un jeu (libère une place)
POST/analyses/batchanalyser 1 à 100 fiches
GET/analyses/batches/{batch_id}relire le résultat d'une recherche
GET/criteria-sets/{id}/listings?listing_ref=…dernier score enregistré de chaque fiche
GET/criteria-sets/{id}/listings/{fiche}dernier score d'une fiche, avec le détail

Authentification

Chaque requête porte le jeton de votre société dans l'en-tête :

Authorization: Bearer smk_live_…
  • Le jeton vous est remis une seule fois, à sa création. Scorimmo n'en conserve qu'une empreinte et ne peut pas vous le renvoyer.
  • Traitez-le comme un mot de passe : coffre de secrets, appels depuis vos serveurs uniquement, jamais dans du code exécuté par le navigateur.
  • Plusieurs jetons peuvent coexister (production, recette), chacun révocable séparément. Un jeton révoqué est refusé dès la requête suivante (401).
  • Le lien envoyé à l'acheteur, lui, ne porte aucun jeton d'API : seulement un jeton propre à ce lien, qui ne donne accès qu'au formulaire de ce jeu de critères.

Contrat et limites

Votre contrat fixe un marché, un périmètre géographique et des quotas. Vous pouvez les lire à tout moment, avec votre consommation du mois :

GET /v1/partner/account

{
  "company": "Votre société",
  "market": {
    "id": "quebec", "currency": "CAD", "currency_symbol": "$",
    "area_unit": "sqft", "area_label": "pi²", "locale": "fr-CA", …
  },
  "perimeter_zones": "montreal:45.40,-73.98,45.71,-73.47",
  "requests_per_minute": 60,
  "max_photos": 12,
  "batch_max_listings": 100,
  "webhook_configured": true,
  "usage": {
    "period": "2026-10",
    "analyses_used": 312, "analyses_limit": 1000, "analyses_remaining": 688,
    "criteria_sets": 17, "criteria_sets_limit": 50
  }
}
LimiteEffet quand elle est atteinte
Analyses par mois (mois civil UTC)429 sur POST /analyses/batch jusqu'au 1er du mois suivant
Nombre de jeux de critères409 sur POST /criteria-links pour un nouvel external_ref ; supprimez un jeu pour libérer une place
Requêtes par minute429 avec Retry-After: 60
Périmètre géographiqueune fiche située hors zone est refusée (403 dans rejected) — non décomptée
Photos par ficheles suivantes sont ignorées, avec un avertissement dans le résultat

perimeter_zones liste les zones couvertes, chacune sous la forme nom:lat_sud,lon_ouest,lat_nord,lon_est, séparées par ;.

Webhook

Scorimmo vous pousse les critères générés et, si vous le demandez, les résultats de vos recherches. Déclarez une adresse HTTPS (port 443, adresse publique) :

PUT /v1/partner/webhook

{ "url": "https://crm.example.com/hooks/scorimmo" }

→ 200
{
  "url": "https://crm.example.com/hooks/scorimmo",
  "secret": "whsec_4kQ…",          // renvoyé une seule fois (et à chaque rotation)
  "secret_hint": "whsec_4kQ9…",
  "events": ["criteria_set.updated", "criteria_set.generation_failed",
             "analysis.completed", "analysis.failed", "batch.completed"]
}

Le secret sert à signer chaque envoi. Il n'est renvoyé qu'à sa création et quand vous demandez "rotate_secret": true ; changer d'URL le conserve.

Ce que vous recevez

POST https://crm.example.com/hooks/scorimmo
Content-Type: application/json; charset=utf-8
Scorimmo-Event: criteria_set.updated
Scorimmo-Delivery: 0b6f2c1e-…            // identique à chaque nouvel essai : dédoublonnez dessus
Scorimmo-Timestamp: 1792681445
Scorimmo-Signature: v1=5f1d0c…

{ "id": "0b6f2c1e-…", "type": "criteria_set.updated",
  "created_at": "2026-10-22T15:04:05Z", "data": { … } }
ÉvénementQuand
criteria_set.updatedl'acheteur a envoyé ; ses critères sont dans le jeu
criteria_set.generation_failedrien d'exploitable n'a pu être tiré de l'envoi ; l'acheteur peut compléter et renvoyer
analysis.completedune fiche d'une recherche, notée, avec son détail
analysis.failedune fiche n'a pas pu être notée (non décomptée)
batch.completedune recherche livrée par webhook est terminée
pingenvoyé par POST /webhook/test

Vérifier la signature

Scorimmo-Signature vaut v1= suivi du HMAC-SHA256, en hexadécimal, de {Scorimmo-Timestamp}.{corps brut} avec votre secret. Calculez-le sur les octets reçus, avant toute analyse du JSON, comparez en temps constant, et refusez un horodatage de plus de 5 minutes.

Node.js
import crypto from "node:crypto";

// rawBody : les octets reçus, AVANT tout JSON.parse
function isFromScorimmo(rawBody, headers, secret) {
  const timestamp = headers["scorimmo-timestamp"];
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;   // rejeu
  const expected = "v1=" + crypto.createHmac("sha256", secret)
    .update(`${timestamp}.`).update(rawBody).digest("hex");
  const received = headers["scorimmo-signature"] ?? "";
  return expected.length === received.length &&
    crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(received));
}

Livraison et nouveaux essais

  • Toute réponse 2xx vaut accusé de réception. Répondez vite (moins de 10 s) et traitez ensuite : un délai dépassé compte comme un échec.
  • Sinon (autre code, délai, connexion refusée), nouvel essai après 10 s, 1 min, 5 min, 30 min et 2 h. Après le 6e essai, l'envoi passe en failed et reste consultable. Les redirections ne sont pas suivies.
  • Scorimmo-Delivery est identique à chaque essai : un même envoi peut arriver deux fois, dédoublonnez sur cet identifiant.
  • L'ordre n'est pas garanti : chaque événement porte ce qu'il concerne (criteria_id, external_ref, batch_id).
GET /v1/partner/webhook/deliveries?status=failed

[
  { "delivery_id": "0b6f2c1e-…", "event": "analysis.completed", "status": "failed",
    "attempts": 6, "last_status_code": 503, "last_error": "HTTP 503",
    "created_at": "2026-10-22T15:04:05", "delivered_at": null, "next_attempt_at": null }
]

POST /v1/partner/webhook/deliveries/0b6f2c1e-…/retry     → 202

Lien de critères

Quand le courtier clique sur votre bouton, demandez un lien pour l'élément concerné. Le premier appel pour un external_ref crée son jeu de critères ; les suivants le réutilisent et renvoient chacun un nouveau lien.

POST /v1/partner/criteria-links

{
  "external_ref": "projet-4812",      // votre identifiant : un projet, un prospect…
  "name": "Projet condo Plateau",     // facultatif, jamais montré à l'acheteur
  "expiry_days": 30                   // 1 à 180
}

→ 201
{
  "link_id": "7b1e…",
  "criteria_id": "sc-3f9a0c21b7e44d12",
  "external_ref": "projet-4812",
  "status": "pending",
  "url": "https://scorimmo.ca/q/kY3…",     // renvoyée une seule fois
  "expires_at": "2026-11-21T15:04:05",
  "source": null, "error": null
}
  • Affichez url au courtier : il l'ouvre lui-même ou l'envoie à l'acheteur. Elle n'est renvoyée qu'une fois — pour la réafficher plus tard, demandez un nouveau lien.
  • Les liens déjà envoyés restent valables jusqu'à leur expiration. Le dernier envoi reçu, par n'importe lequel d'entre eux, l'emporte.
  • La page ne révèle ni le courtier, ni le nom du jeu, ni votre identifiant.

Ce que voit l'acheteur

Deux façons de répondre, au choix, chacune enregistrée au fil de la saisie :

  • Le questionnaire du marché de votre contrat : budget, surface, pièces, étage, proximités, trajets — dans la langue du jeu de questions.
  • Ses propres mots : un texte libre, un PDF (une analyse des besoins, par exemple) ou un message vocal enregistré sur la page ou envoyé en fichier (m4a, mp3, wav, webm…, 14 Mo au maximum). Un fichier est d'abord converti en texte, que l'acheteur relit et corrige avant d'envoyer.

À l'envoi, le lien passe en processing le temps de générer les critères (quelques secondes), puis en applied — ou failed, avec la raison dans error. L'acheteur peut compléter et renvoyer tant que le lien est valable : chaque envoi régénère les critères.

GET /v1/partner/criteria-links/7b1e…

{ "link_id": "7b1e…", "criteria_id": "sc-3f9a0c21b7e44d12", "external_ref": "projet-4812",
  "status": "applied",            // pending → processing → applied | failed
  "source": "audio",              // questionnaire | text | pdf | audio
  "submitted_at": "2026-10-22T15:03:51", "applied_at": "2026-10-22T15:04:05",
  "url": null, "error": null, … }
Le webhook vous informe au moment où ça se produit ; GET /criteria-links/{id} sert à rattraper un envoi manqué.

Critères reçus et modifiés

Les critères générés remplacent ceux du jeu, puis vous sont envoyés avec ce que l'acheteur a dit, pour que le courtier voie l'un à côté de l'autre :

criteria_set.updated
{
  "id": "0b6f2c1e-…",
  "type": "criteria_set.updated",
  "created_at": "2026-10-22T15:04:05Z",
  "data": {
    "criteria_set": {
      "criteria_id": "sc-3f9a0c21b7e44d12",
      "external_ref": "projet-4812",
      "name": "Projet condo Plateau",
      "exclusions": [
        { "id": "prix_max", "label": "Prix > 650 000 $", "is_exclusion": true, "points": 0,
          "evaluations": [{ "method": "reso_field", "params": { "field": "list_price", "op": "gt", "value": 650000 } }] }
      ],
      "scored_criteria": [
        { "id": "metro_10", "label": "Métro à moins de 10 min à pied", "points": 10, … },
        …
      ],
      "total_points_possible": 35,
      "updated_at": "2026-10-22T15:04:05"
    },
    "link_id": "7b1e…",
    "source": "questionnaire",                  // questionnaire | text | pdf | audio
    "submitted_at": "2026-10-22T15:03:51",
    "answers": [                                // questionnaire : ce que l'acheteur a répondu
      { "key": "budget", "question": "Quel prix vous conviendrait ?", "answer": "excellent 550 000 $, acceptable 600 000 $, limite 650 000 $" }
    ],
    "brief": null,                              // texte, PDF ou audio : le texte dont les critères sont tirés
    "unmapped": ["près d'une bonne école"],   // demandé, mais aucun critère ne peut le vérifier
    "rejected": []
  }
}
ChampContenu
criteria_setle jeu complet, tel qu'il est maintenant (même forme que GET /criteria-sets/{id})
sourcequestionnaire, text, pdf ou audio
answersquestionnaire : chaque question et la réponse, en clair
brieftexte, PDF ou audio : le texte dont les critères ont été tirés (corrigé par l'acheteur)
unmappedce que l'acheteur a demandé et qu'aucun critère ne sait vérifier — à montrer au courtier
rejectedcritères proposés puis écartés parce qu'inévaluables, avec la raison
criteria_set.generation_failed
{
  "type": "criteria_set.generation_failed",
  "data": { "criteria_id": "sc-3f9a0c21b7e44d12", "external_ref": "projet-4812",
            "link_id": "7b1e…", "source": "text",
            "error": "La description est trop courte pour en tirer des critères." }
}

Modifier les critères

Le courtier ajuste le jeu dans votre écran ; enregistrez avec les routes ci-dessous. Ces modifications ne déclenchent pas de webhook (elles viennent de vous). Le plus simple : renvoyer la liste complète.

PUT /v1/partner/criteria-sets/sc-3f9a0c21b7e44d12/criteria

{
  "criteria": [
    { "id": "prix_max", "label": "Prix > 650 000 $", "is_exclusion": true,
      "evaluations": [{ "method": "reso_field",
        "params": { "field": "list_price", "op": "gt", "value": 650000 } }] },

    { "id": "surface_900", "label": "Plus de 900 pi²", "points": 5,
      "evaluations": [{ "method": "reso_field",
        "params": { "field": "living_area", "op": "gt", "value": 900 } }] },

    { "id": "metro_10", "label": "Métro à moins de 10 min à pied", "points": 10,
      "evaluations": [{ "method": "signal",
        "params": { "signal": "metro_walk_minutes", "op": "lte", "value": 10, "radius_m": 3000 } }] },

    { "id": "travail_30", "label": "Moins de 30 min du bureau en transport", "points": 8,
      "evaluations": [{ "method": "signal",
        "params": { "signal": "commute_minutes", "destination": "1000 rue De La Gauchetière O, Montréal",
                    "mode": "transit", "op": "lte", "value": 30 } }] },

    { "id": "cuisine_renovee", "label": "Cuisine rénovée", "points": 10,
      "evaluations": [{ "method": "llm", "params": { "inputs": ["description", "photos"] } }] }
  ]
}
MéthodeRouteUsage
GET/criteria-sets?external_ref=…le jeu rattaché à votre identifiant
GET/criteria-sets/{id}un jeu, avec tous ses critères
PUT/criteria-sets/{id}/criteriaremplacer toute la liste
POST/criteria-sets/{id}/criteriaajouter un critère
PATCH/criteria-sets/{id}/criteria/{critere}modifier un critère
DELETE/criteria-sets/{id}/criteria/{critere}retirer un critère
DELETE/criteria-sets/{id}l'élément n'existe plus chez vous : libère une place
GET/criteria-schemachamps, mesures et types de lieux, pour construire l'éditeur

Anatomie d'un critère

ChampRôle
ididentifiant stable, a-z 0-9 _, 2 à 64 caractères, unique dans le jeu
labellibellé affiché, jusqu'à 300 caractères
is_exclusiontrue = rédhibitoire : s'il est vrai, la fiche est éliminée. Le libellé décrit donc le problème (« Prix > 650 000 $ », « Rez-de-chaussée »), jamais le souhait.
pointspoids d'un critère noté : de 1 (petit plus) à 10 (priorité de l'acheteur), jamais plus. Toujours 0 pour une exclusion.
definitionprécision optionnelle, lue par l'IA
categoryregroupement optionnel pour votre affichage
evaluationsune ou plusieurs façons d'y répondre ; la première qui donne une réponse est retenue

Trois méthodes d'évaluation

Le moteur exécute les méthodes de la moins coûteuse à la plus coûteuse et s'arrête dès qu'une exclusion est confirmée.

  1. reso_field — comparaison exacte sur un champ de la fiche. Paramètres field, op (gt, gte, lt, lte, eq) et value.
  2. signal — une mesure sur l'emplacement. Paramètres signal, op, value, et ceux propres à la mesure (rayon, type de lieu, adresse de destination…).
  3. llm — jugé par l'IA. Paramètre inputs : ["description"] (par défaut), ["photos"] ou les deux.

Champs de la fiche (reso_field)

ChampContenu
list_priceprix affiché
living_areasurface habitable, dans l'unité du marché
rooms_totalnombre de pièces
bedrooms_totalchambres
bathrooms_total_integersalles de bain
year_builtannée de construction
entry_levelétage (0 = rez-de-chaussée)
lot_size_areasurface du terrain
association_feefrais de copropriété, ramenés au mois
tax_annual_amounttaxes foncières annuelles
monthly_taxes_and_feestaxes et frais de copropriété, par mois
energy_class_rankclasse énergétique (DPE) : A = 1 … G = 7
ghg_class_rankclasse climat (GES) : A = 1 … G = 7

Mesures sur l'emplacement (signal)

MesureCe qu'elle renvoie
metro_walk_minutesminutes à pied jusqu'à la station de métro la plus proche
grocery_walk_minutesminutes à pied jusqu'à l'épicerie la plus proche
place_walk_minutesminutes à pied jusqu'au lieu le plus proche d'un type donné (école, parc, pharmacie…)
place_countnombre de lieux d'un type donné dans un rayon
commercial_density_countdensité de commerces et restaurants autour du bien
commute_minutesdurée du trajet vers une adresse (destination), en voiture, transport, vélo ou à pied (mode)
osm_nearest_distance_mdistance en mètres à l'élément OpenStreetMap le plus proche (littoral, plage, parc, gare…)
osm_countnombre d'éléments OpenStreetMap dans un rayon
air_quality_indexindice de qualité de l'air
pollen_indexindice pollinique
roof_sunshine_hoursheures d'ensoleillement annuelles du toit
roof_solar_potential_kwhpotentiel solaire du toit
elevation_maltitude
La liste exacte des champs, mesures et types de lieux disponibles pour votre marché, avec leurs paramètres, est renvoyée par GET /v1/partner/criteria-schema. C'est la référence à utiliser pour construire un éditeur de critères.

Recherche de fiches

Quand le courtier lance une recherche pour l'élément, envoyez son jeu de critères (le criteria_id, ou votre external_ref) et les fiches trouvées, jusqu'à 100. Elles sont analysées en parallèle et partagent ce qui peut l'être (même immeuble, même rue).

POST /v1/partner/analyses/batch

{
  "criteria_id": "sc-3f9a0c21b7e44d12",   // ou "external_ref": "projet-4812"
  "properties": [ { "ListingKey": "A-1042", … }, … ],   // 1 à 100 fiches
  "format": "auto",                        // auto | reso | mlsconnect
  "delivery": "response"                   // ou "webhook"
}

Format des fiches

  • "format": "reso" — une fiche aux noms de champs RESO Data Dictionary (ListingKey, ListPrice, LivingArea, BedroomsTotal, Latitude, Longitude, PublicRemarks, Media…).
  • Votre format natif — si votre flux n'est pas au format RESO, nous mettons en place un adaptateur qui lit vos fiches telles que votre système les produit.
  • "format": "auto" (par défaut) reconnaît le format tout seul.
{
  "ListingKey": "A-1042",
  "ListPrice": 549000,
  "LivingArea": 842,
  "BedroomsTotal": 2,
  "BathroomsTotalInteger": 1,
  "EntryLevel": 3,
  "Latitude": 45.5343, "Longitude": -73.5812,
  "PublicRemarks": "Condo lumineux au 3e étage, cuisine refaite en 2024…",
  "Media": [ { "MediaURL": "https://…/1.jpg" }, { "MediaURL": "https://…/2.jpg" } ]
}

Les coordonnées sont nécessaires pour vérifier le périmètre et pour toutes les mesures d'emplacement. Les photos sont lues dans l'ordre, jusqu'à la limite de votre contrat.

Trois façons de recevoir les résultats

RequêteCe qui revient
delivery: "response" (défaut)tout le résultat à la fin, dans la réponse
idem + Accept: application/x-ndjsonune ligne par fiche dès qu'elle est prête, puis le résultat complet
delivery: "webhook"202 immédiatement ; chaque fiche arrive en analysis.completed, puis batch.completed

Le résultat d'une fiche

Le même objet partout — réponse, flux, webhook : le score, une phrase prête à afficher, et dans result le détail de chaque critère.

{
  "index": 3,
  "listing_ref": "A-1042",
  "analysis_id": "5d0c…",
  "excluded": false,
  "exclusion_reasons": [],
  "score": 86, "score_min": 86, "score_max": 86,
  "summary": "4 critères remplis sur 5 : Métro à moins de 10 min à pied, Cuisine rénovée, Moins de 30 min du bureau en transport et 1 autre. Manque : Plus de 900 pi².",
  "cached": false, "billed": true,
  "warnings": [],
  "result": {
    "score": 86,
    "disqualified": false,
    "disqualifying_reasons": [],
    "total_points_earned": 30, "total_points_possible": 35,
    "points_unevaluated": 0,
    "breakdown": [
      { "id": "surface_900", "label": "Plus de 900 pi²", "is_exclusion": false,
        "points_possible": 5, "points_earned": 0, "passed": false,
        "methods": ["reso_field"], "resolved_by": "reso_field", "note": "living_area=842 (gt 900)" },
      { "id": "metro_10", "label": "Métro à moins de 10 min à pied", "is_exclusion": false,
        "points_possible": 10, "points_earned": 10, "passed": true,
        "methods": ["signal"], "resolved_by": "signal", "note": "station la plus proche à 6 min à pied" },
      { "id": "cuisine_renovee", "label": "Cuisine rénovée", "is_exclusion": false,
        "points_possible": 10, "points_earned": 10, "passed": true,
        "methods": ["llm"], "resolved_by": "llm", "inputs_used": ["description", "photos"],
        "note": "« cuisine refaite en 2024 », comptoirs de quartz visibles en photo 2" },
      …
    ],
    "unevaluated_criteria": [],
    "skipped_criteria": [],
    "explanation": "…",
    "llm_explanation": "…"
  }
}
ChampSignification
score0 à 100 : points obtenus ÷ points des critères notés effectivement évalués. 0 si la fiche est éliminée.
excludedune exclusion est vraie ; les libellés sont dans exclusion_reasons
score_min/ score_max : le score si les critères non vérifiables échouaient / réussissaient. score est toujours entre les deux ; égaux quand tout a été vérifié.
summaryune phrase : ce qui écarte la fiche, ou les critères remplis les plus importants et ce qui manque
result.breakdown[]chaque critère : passed (true / false, ou null si la donnée manque), points, resolved_by (la méthode qui a répondu) et note (la valeur ou l'élément sur lequel repose le verdict)
result.unevaluated_criteriacritères dont l'information n'existe pas ; ils sortent du calcul
result.skipped_criteriacritères non calculés parce que la fiche était déjà éliminée
result.llm_explanationl'explication rédigée par l'IA, quand elle a participé
warningspoints d'attention sur la fiche (position approximative, location plutôt que vente, photos ignorées…)
cachedrésultat réutilisé, non décompté (voir plus bas)

Dans la réponse

→ 200
{
  "batch_id": "9f2c…",
  "criteria_id": "sc-3f9a0c21b7e44d12",
  "external_ref": "projet-4812",
  "delivery": "response",
  "total": 42,
  "complete": true,
  "excluded": [ { "listing_ref": "A-0977", "exclusion_reasons": ["Prix > 650 000 $"], "result": { … }, … } ],
  "ranking":  [ { "listing_ref": "A-1042", "score": 86, "summary": "…", "result": { … }, … }, … ],
  "rejected": [ { "index": 7, "listing_ref": null, "status": 422, "detail": "Propriété illisible : …" } ],
  "failed":   [ { "index": 12, "listing_ref": "A-1101", "status": 502, "detail": "…" } ],
  "usage": { "analyses_used": 351, "analyses_limit": 1000, … }
}
ChampSignification
rankingles fiches retenues, de la meilleure à la moins bonne (score, puis score_max)
excludedles fiches écartées par une exclusion
rejectedrefusées sans frais : illisible (422), hors périmètre (403), en double dans la requête (409)
failedanalyse échouée de notre côté (502) : non décomptée, à renvoyer
completefalse si la recherche a été interrompue avant la fin

Au fil de l'eau

Avec Accept: application/x-ndjson, un objet JSON par ligne. Les lignes listing arrivent dans l'ordre où les analyses se terminent ; index est la position de la fiche dans properties.

POST /v1/partner/analyses/batch
Accept: application/x-ndjson

{"type":"batch","batch_id":"9f2c…","criteria_id":"sc-3f9a…","external_ref":"projet-4812","total":42,"accepted":41,"to_analyse":38,"rejected":[{"index":7,"listing_ref":null,"status":422,"detail":"…"}]}
{"type":"listing","index":3,"listing_ref":"A-1042","score":86,"summary":"…","result":{ … }, …}
{"type":"listing","index":0,"listing_ref":"A-0977","excluded":true,"exclusion_reasons":["Prix > 650 000 $"],"score":0, …}
{"type":"listing_error","index":12,"listing_ref":"A-1101","status":502,"detail":"…"}
…
{"type":"result","result":{ …le corps de la réponse non diffusée… }}
JavaScript
const res = await fetch(`${API}/v1/partner/analyses/batch`, {
  method: "POST",
  headers: { Authorization: `Bearer ${TOKEN}`, "Content-Type": "application/json",
             Accept: "application/x-ndjson" },
  body: JSON.stringify({ criteria_id, properties }),
});
if (!res.ok) throw new Error((await res.json()).detail);   // 404, 422, 429… : pas de flux

const reader = res.body.getReader();
const decoder = new TextDecoder();
let buffer = "";
for (;;) {
  const { value, done } = await reader.read();
  if (done) break;
  buffer += decoder.decode(value, { stream: true });
  let nl;
  while ((nl = buffer.indexOf("\n")) >= 0) {
    const event = JSON.parse(buffer.slice(0, nl));
    buffer = buffer.slice(nl + 1);
    if (event.type === "listing") showListing(event);          // score + détail, dès qu'il est prêt
    if (event.type === "listing_error") showFailed(event);
    if (event.type === "result") return event.result;          // classement final
    if (event.type === "error") throw new Error(event.detail);
  }
}
Les erreurs connues avant le début (404, 422, 429…) restent des réponses HTTP ordinaires, sans flux. Fermer la connexion en cours de route abandonne les analyses restantes, non décomptées ; celles qui sont terminées restent enregistrées.

Par webhook

POST /v1/partner/analyses/batch

{ "criteria_id": "sc-3f9a0c21b7e44d12", "properties": [ … ], "delivery": "webhook" }

→ 202
{
  "batch_id": "9f2c…", "criteria_id": "sc-3f9a0c21b7e44d12", "external_ref": "projet-4812",
  "delivery": "webhook",
  "total": 42, "accepted": 41, "to_analyse": 38, "cached": 3,
  "rejected": [ { "index": 7, "status": 422, "detail": "…" } ],
  "usage": { … }
}
{
  "type": "analysis.completed",
  "data": {
    "batch_id": "9f2c…", "criteria_id": "sc-3f9a0c21b7e44d12", "external_ref": "projet-4812",
    "listing": { "index": 3, "listing_ref": "A-1042", "score": 86, "summary": "…",
                 "result": { "breakdown": [ … ], … }, … }
  }
}

{ "type": "analysis.failed",
  "data": { "batch_id": "9f2c…", …, "index": 12, "listing_ref": "A-1101", "status": 502, "detail": "…" } }

{ "type": "batch.completed",
  "data": { "batch_id": "9f2c…", "complete": true, "total": 42,
            "ranking": [ { "listing_ref": "A-1042", "score": 86, "result": null, … }, … ],
            "excluded": [ … ], "rejected": [ … ], "failed": [ … ], "usage": { … } } }
  • Chaque fiche arrive avec son détail complet. batch.completed récapitule le classement sans répéter les détails (result: null).
  • Une recherche interrompue par un redémarrage de notre côté se termine par batch.completed avec complete: false : renvoyez les fiches que vous n'avez pas reçues — celles déjà analysées sont rejouées gratuitement.
  • GET /analyses/batches/{batch_id} relit à tout moment le résultat d'une recherche, détail compris.

Scores déjà calculés

Chaque analyse est conservée. Quand le courtier ouvre une fiche, ou qu'une liste affiche des fiches déjà notées pour ce jeu, lisez le dernier score enregistré plutôt que de relancer une analyse — c'est gratuit. stale: true signale que les critères ont changé depuis : le score n'est plus à jour, relancez une recherche pour le rafraîchir.

GET /v1/partner/criteria-sets/sc-3f9a0c21b7e44d12/listings/A-1042

→ 200
{
  "listing_ref": "A-1042", "analysis_id": "5d0c…",
  "score": 86, "score_min": 86, "score_max": 86, "excluded": false,
  "summary": "…",
  "created_at": "2026-10-22T15:12:40",
  "batch_id": "9f2c…",
  "stale": false,             // true : les critères ont changé depuis cette analyse
  "result": { "breakdown": [ … ], … }
}

GET /v1/partner/criteria-sets/sc-3f9a0c21b7e44d12/listings?listing_ref=A-1042&listing_ref=A-0977

→ 200
[ { "listing_ref": "A-1042", "score": 86, "summary": "…", "stale": false, "result": null, … },
  { "listing_ref": "A-0977", "score": 0, "excluded": true, "stale": false, "result": null, … } ]
MéthodeRouteUsage
GET/criteria-sets/{id}/listings/{fiche}dernier score d'une fiche, avec le détail de chaque critère (404 si jamais analysée)
GET/criteria-sets/{id}/listings?listing_ref=…dernier score de chaque fiche nommée (ou de toutes, les plus récentes d'abord) ; details=true pour inclure le détail

Votre géocodage (facultatif)

Si votre système connaît déjà la position exacte du bien ou ses lieux proches, joignez-les à la fiche sous scorimmo_geo : Scorimmo s'en sert au lieu de les rechercher.

{
  "ListingKey": "A-1042", "ListPrice": 549000, …,
  "scorimmo_geo": {
    "latitude": 45.53431, "longitude": -73.58124,
    "precision": "rooftop",            // "rooftop" | "street" | "approximate"
    "places": [
      { "type": "subway_station", "name": "Laurier", "walk_minutes": 6 },
      { "type": "supermarket", "name": "IGA", "latitude": 45.5351, "longitude": -73.5838 },
      { "type": "park", "name": "Parc Laurier", "distance_m": 420 }
    ]
  }
}
  • Les coordonnées remplacent celles de la fiche (sauf precision: "approximate").
  • Chaque lieu de places a un type du vocabulaire place_types et au moins un de : walk_minutes (pris tel quel), distance_m (à vol d'oiseau, le temps de marche en est estimé) ou ses coordonnées.
  • Un scorimmo_geo mal formé est ignoré, avec un avertissement.

Ce qui est décompté

  • Une analyse décomptée = une fiche analysée dans une recherche.
  • Ré-analyse gratuite pendant 24 h : la même fiche, avec les mêmes données, analysée avec le même jeu de critères dans les 24 h est rejouée (cached: true, billed: false). Les champs purement administratifs (dates de mise à jour…) n'y changent rien ; une modification du prix, de la surface, de la description, des photos ou des critères déclenche une nouvelle analyse.
  • Tout ou rien : si le quota restant ne couvre pas toutes les fiches à analyser d'une recherche, rien n'est lancé (429).
  • Jamais décompté : une fiche hors périmètre, illisible ou en double, une analyse qui échoue de notre côté, les liens de critères, la génération des critères et la lecture des fichiers de l'acheteur, la lecture des scores enregistrés.

Erreurs

Toutes les erreurs ont la forme {"detail": "message"}.

HTTP/1.1 429 Too Many Requests
Retry-After: 60

{ "detail": "Trop de requêtes : 60 par minute au maximum." }
CodeSignification
401jeton absent, invalide ou révoqué
403compte désactivé
404jeu, critère, lien, envoi ou recherche introuvable (ou appartenant à une autre société)
409limite de jeux atteinte, identifiant de critère déjà utilisé, ou aucun webhook configuré
422données invalides : critère inévaluable, URL de webhook refusée, plus de 100 fiches, criteria_id et external_ref ensemble
429quota mensuel insuffisant, ou trop de requêtes par minute (voir Retry-After)

Exemple complet

bash
API=https://…            # adresse communiquée avec votre jeton
TOKEN=smk_live_…
H=(-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json")

# 0. une fois : votre webhook (gardez le secret renvoyé)
curl -s -X PUT $API/v1/partner/webhook "${H[@]}" \
  -d '{"url":"https://crm.example.com/hooks/scorimmo"}' | jq -r .secret

# 1. le courtier clique : un lien pour le projet 4812
curl -s -X POST $API/v1/partner/criteria-links "${H[@]}" \
  -d '{"external_ref":"projet-4812","name":"Projet condo Plateau"}' | jq -r .url

# 2. l'acheteur remplit le lien → criteria_set.updated arrive sur votre webhook

# 3. une recherche : les fiches, classées, avec le détail
curl -s -X POST $API/v1/partner/analyses/batch "${H[@]}" \
  -d "{\"external_ref\":\"projet-4812\",\"properties\":$(cat fiches.json)}" \
  | jq '.ranking[] | {listing_ref, score, summary}'