Overview
The flow, end to end:
- The broker clicks on a project (or a prospect — Scorimmo does not need to know which). Your software calls
POST /criteria-linkswith your id for that record (external_ref). Scorimmo files a criteria set under it and returns a link. - The buyer opens the link — no account, no password; the token is in the URL. They answer the questionnaire, or describe their search in their own words: text, PDF or voice note. They send it.
- The criteria are generated and reach you by webhook (
criteria_set.updated). You display them; the broker edits them through the/criteria-setsroutes. - A search in your software sends the criteria set and the listings (up to 100) to
POST /analyses/batch. Scores and their details come back on the response, as they finish, or by webhook listing by listing.
- Every route lives under
/v1/partner. The API address is provided along with your token. - Requests and responses are JSON (
Content-Type: application/json), UTF-8. - Amounts and areas are in the currency and unit of your contract's market (e.g.
CADand sq ft in Quebec,EURand m² in France). - Error messages (
detail) are written in French.
| Method | Route | Purpose |
|---|---|---|
| GET | /account | contract, market, this month's usage |
| GET | /criteria-schema | fields, measures and place types available |
| PUT | /webhook | your endpoint (secret returned once) |
| GET | /webhook | the configured webhook |
| DELETE | /webhook | remove it |
| POST | /webhook/test | send a signed ping, see the outcome |
| GET | /webhook/deliveries | recent deliveries (?status=failed) |
| GET | /webhook/deliveries/{id} | one delivery, with its payload |
| POST | /webhook/deliveries/{id}/retry | send it again |
| POST | /criteria-links | a link for the buyer (creates the set if needed) |
| GET | /criteria-links/{link_id} | where that link stands |
| GET | /criteria-sets?external_ref=… | your sets, with their criteria |
| GET | /criteria-sets/{id} | one set |
| PUT | /criteria-sets/{id}/criteria | replace the whole list |
| POST | /criteria-sets/{id}/criteria | add a criterion |
| PATCH | /criteria-sets/{id}/criteria/{criterion} | edit a criterion |
| DELETE | /criteria-sets/{id}/criteria/{criterion} | remove a criterion |
| DELETE | /criteria-sets/{id} | delete a set (frees a slot) |
| POST | /analyses/batch | score 1 to 100 listings |
| GET | /analyses/batches/{batch_id} | read a search's outcome again |
| GET | /criteria-sets/{id}/listings?listing_ref=… | latest stored score of each listing |
| GET | /criteria-sets/{id}/listings/{listing} | one listing's latest score, with details |
Authentication
Every request carries your company's token in the header:
Authorization: Bearer smk_live_…- The token is handed to you once, when it is created. Scorimmo only keeps a fingerprint of it and cannot send it again.
- Treat it like a password: secret vault, calls from your servers only, never in code running in the browser.
- Several tokens can coexist (production, staging), each revocable on its own. A revoked token is refused from the next request on (
401). - The link sent to the buyer carries no API token: only a token of its own, which opens nothing but that criteria set's form.
Contract and limits
Your contract sets a market, a geographic perimeter and quotas. You can read them at any time, along with this month's usage:
GET /v1/partner/account
{
"company": "Your company",
"market": {
"id": "quebec", "currency": "CAD", "currency_symbol": "$",
"area_unit": "sqft", "area_label": "sq ft", "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
}
}| Limit | What happens when it is reached |
|---|---|
| Analyses per month (UTC calendar month) | 429 on POST /analyses/batch until the 1st of the next month |
| Number of criteria sets | 409 on POST /criteria-links for a new external_ref; delete a set to free a slot |
| Requests per minute | 429 with Retry-After: 60 |
| Geographic perimeter | a listing outside it is refused (403 in rejected) — not counted |
| Photos per listing | the rest are ignored, with a warning in the result |
perimeter_zones lists the covered areas, each as name:south_lat,west_lon,north_lat,east_lon, separated by ;.
Webhook
Scorimmo pushes the generated criteria to you and, if you ask for it, your searches' results. Register an HTTPS address (port 443, public address):
PUT /v1/partner/webhook
{ "url": "https://crm.example.com/hooks/scorimmo" }
→ 200
{
"url": "https://crm.example.com/hooks/scorimmo",
"secret": "whsec_4kQ…", // returned only once (and on each rotation)
"secret_hint": "whsec_4kQ9…",
"events": ["criteria_set.updated", "criteria_set.generation_failed",
"analysis.completed", "analysis.failed", "batch.completed"]
}The secret signs every delivery. It is only returned when created and when you ask for "rotate_secret": true; changing the URL keeps it.
What you receive
POST https://crm.example.com/hooks/scorimmo
Content-Type: application/json; charset=utf-8
Scorimmo-Event: criteria_set.updated
Scorimmo-Delivery: 0b6f2c1e-… // the same on every retry: deduplicate on it
Scorimmo-Timestamp: 1792681445
Scorimmo-Signature: v1=5f1d0c…
{ "id": "0b6f2c1e-…", "type": "criteria_set.updated",
"created_at": "2026-10-22T15:04:05Z", "data": { … } }| Event | When |
|---|---|
criteria_set.updated | the buyer sent their answer; their criteria are in the set |
criteria_set.generation_failed | nothing usable came out of it; the buyer can add detail and send again |
analysis.completed | one listing of a search, scored, with its details |
analysis.failed | one listing could not be scored (not counted) |
batch.completed | a search delivered by webhook is over |
ping | sent by POST /webhook/test |
Verifying the signature
Scorimmo-Signature is v1= followed by the hex HMAC-SHA256 of {Scorimmo-Timestamp}.{raw body} with your secret. Compute it over the bytes received, before parsing the JSON, compare in constant time, and refuse a timestamp more than 5 minutes old.
import crypto from "node:crypto";
// rawBody: the bytes received, BEFORE any JSON.parse
function isFromScorimmo(rawBody, headers, secret) {
const timestamp = headers["scorimmo-timestamp"];
if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false; // replay
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));
}Delivery and retries
- Any
2xxresponse is an acknowledgement. Answer fast (under 10 s) and process afterwards: a timeout counts as a failure. - Otherwise (another status, a timeout, a refused connection) it is retried after 10 s, 1 min, 5 min, 30 min and 2 h. After the 6th attempt the delivery is
failedand stays listed. Redirects are not followed. Scorimmo-Deliveryis the same on every attempt: one delivery may arrive twice, deduplicate on it.- Order is not guaranteed: every event carries what it is about (
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 → 202Criteria link
When the broker clicks your button, ask for a link for that record. The first call for an external_ref creates its criteria set; later ones reuse it and each returns a new link.
POST /v1/partner/criteria-links
{
"external_ref": "projet-4812", // your id: a project, a prospect…
"name": "Plateau condo project", // optional, never shown to the buyer
"expiry_days": 30 // 1 to 180
}
→ 201
{
"link_id": "7b1e…",
"criteria_id": "sc-3f9a0c21b7e44d12",
"external_ref": "projet-4812",
"status": "pending",
"url": "https://scorimmo.ca/q/kY3…", // returned only once
"expires_at": "2026-11-21T15:04:05",
"source": null, "error": null
}- Show
urlto the broker: they open it themselves or send it to the buyer. It is returned only once — to show it again later, ask for a new link. - Links already sent stay valid until they expire. The last submission received, through any of them, wins.
- The page reveals neither the broker, nor the set's name, nor your id.
What the buyer sees
Two ways to answer, their choice, each saved as they type:
- The questionnaire of your contract's market: budget, size, rooms, floor, nearby places, commutes — in the question set's language.
- Their own words: free text, a PDF (a needs analysis, say) or a voice note recorded on the page or sent as a file (m4a, mp3, wav, webm…, 14 MB at most). A file is first turned into text, which the buyer reads and corrects before sending.
On submit the link goes processing while the criteria are generated (a few seconds), then applied — or failed, with the reason in error. The buyer can add to it and send again as long as the link is valid: each submission regenerates the criteria.
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, … }GET /criteria-links/{id} is there to catch up on a missed delivery.Criteria received and edited
The generated criteria replace the set's, then are sent to you with what the buyer said, so the broker can see both side by side:
{
"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": "Plateau condo project",
"exclusions": [
{ "id": "prix_max", "label": "Price > $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": "Metro within a 10-min walk", "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: what the buyer answered
{ "key": "budget", "question": "What price would suit you?", "answer": "excellent $550,000, acceptable $600,000, limit $650,000" }
],
"brief": null, // text, PDF or audio: the text the criteria came from
"unmapped": ["near a good school"], // asked for, but no criterion can check it
"rejected": []
}
}| Field | Content |
|---|---|
criteria_set | the whole set as it now stands (same shape as GET /criteria-sets/{id}) |
source | questionnaire, text, pdf or audio |
answers | questionnaire: each question and the answer, readable |
brief | text, PDF or audio: the text the criteria came from (as corrected by the buyer) |
unmapped | what the buyer asked for that no criterion can check — worth showing the broker |
rejected | criteria drafted then dropped because they could not be evaluated, with why |
{
"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." }
}Editing the criteria
The broker adjusts the set in your screen; save it with the routes below. These edits do not trigger a webhook (they come from you). The simplest is to send the full list back.
PUT /v1/partner/criteria-sets/sc-3f9a0c21b7e44d12/criteria
{
"criteria": [
{ "id": "prix_max", "label": "Price > $650,000", "is_exclusion": true,
"evaluations": [{ "method": "reso_field",
"params": { "field": "list_price", "op": "gt", "value": 650000 } }] },
{ "id": "surface_900", "label": "Over 900 sq ft", "points": 5,
"evaluations": [{ "method": "reso_field",
"params": { "field": "living_area", "op": "gt", "value": 900 } }] },
{ "id": "metro_10", "label": "Metro within a 10-min walk", "points": 10,
"evaluations": [{ "method": "signal",
"params": { "signal": "metro_walk_minutes", "op": "lte", "value": 10, "radius_m": 3000 } }] },
{ "id": "travail_30", "label": "Under 30 min to the office by transit", "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": "Renovated kitchen", "points": 10,
"evaluations": [{ "method": "llm", "params": { "inputs": ["description", "photos"] } }] }
]
}| Method | Route | Purpose |
|---|---|---|
| GET | /criteria-sets?external_ref=… | the set filed under your id |
| GET | /criteria-sets/{id} | one set, with all its criteria |
| PUT | /criteria-sets/{id}/criteria | replace the whole list |
| POST | /criteria-sets/{id}/criteria | add a criterion |
| PATCH | /criteria-sets/{id}/criteria/{criterion} | edit a criterion |
| DELETE | /criteria-sets/{id}/criteria/{criterion} | remove a criterion |
| DELETE | /criteria-sets/{id} | the record is gone on your side: frees a slot |
| GET | /criteria-schema | fields, measures and place types, to build the editor |
Anatomy of a criterion
| Field | Role |
|---|---|
id | stable id, a-z 0-9 _, 2 to 64 characters, unique within the set |
label | displayed label, up to 300 characters |
is_exclusion | true = dealbreaker: if it holds, the listing is ruled out. The label therefore names the problem ("Price > $650,000", "Ground floor"), never the wish. |
points | weight of a scored criterion: from 1 (a small bonus) to 10 (a top priority for the buyer), never more. Always 0 for an exclusion. |
definition | optional clarification, read by the AI |
category | optional grouping for your display |
evaluations | one or more ways to answer it; the first that gives an answer is kept |
Three evaluation methods
The engine runs methods from cheapest to most expensive and stops as soon as an exclusion is confirmed.
reso_field— exact comparison on a listing field. Parametersfield,op(gt,gte,lt,lte,eq) andvalue.signal— a measure of the location. Parameterssignal,op,value, and those specific to the measure (radius, place type, destination address…).llm— judged by the AI. Parameterinputs:["description"](default),["photos"]or both.
Listing fields (reso_field)
| Field | Content |
|---|---|
list_price | asking price |
living_area | living area, in the market's unit |
rooms_total | number of rooms |
bedrooms_total | bedrooms |
bathrooms_total_integer | bathrooms |
year_built | year built |
entry_level | floor (0 = ground floor) |
lot_size_area | lot size |
association_fee | condo fees, per month |
tax_annual_amount | annual property taxes |
monthly_taxes_and_fees | taxes and condo fees, per month |
energy_class_rank | energy class (EPC): A = 1 … G = 7 |
ghg_class_rank | climate class (GHG): A = 1 … G = 7 |
Location measures (signal)
| Measure | What it returns |
|---|---|
metro_walk_minutes | walking minutes to the nearest metro station |
grocery_walk_minutes | walking minutes to the nearest grocery store |
place_walk_minutes | walking minutes to the nearest place of a given type (school, park, pharmacy…) |
place_count | number of places of a given type within a radius |
commercial_density_count | density of shops and restaurants around the property |
commute_minutes | travel time to an address (destination), by car, transit, bike or on foot (mode) |
osm_nearest_distance_m | distance in metres to the nearest OpenStreetMap feature (coastline, beach, park, station…) |
osm_count | number of OpenStreetMap features within a radius |
air_quality_index | air quality index |
pollen_index | pollen index |
roof_sunshine_hours | annual sunshine hours on the roof |
roof_solar_potential_kwh | the roof's solar potential |
elevation_m | elevation |
GET /v1/partner/criteria-schema. Use it as the reference to build a criteria editor.Scoring a search
When the broker runs a search for the record, send its criteria set (the criteria_id, or your external_ref) and the listings found, up to 100. They are analysed side by side and share what can be shared (same building, same street).
POST /v1/partner/analyses/batch
{
"criteria_id": "sc-3f9a0c21b7e44d12", // or "external_ref": "projet-4812"
"properties": [ { "ListingKey": "A-1042", … }, … ], // 1 to 100 listings
"format": "auto", // auto | reso | mlsconnect
"delivery": "response" // or "webhook"
}Listing format
"format": "reso"— a listing with RESO Data Dictionary field names (ListingKey,ListPrice,LivingArea,BedroomsTotal,Latitude,Longitude,PublicRemarks,Media…).- Your native format — if your feed is not RESO, we set up an adapter that reads your listings as your system produces them.
"format": "auto"(default) recognises the format on its own.
{
"ListingKey": "A-1042",
"ListPrice": 549000,
"LivingArea": 842,
"BedroomsTotal": 2,
"BathroomsTotalInteger": 1,
"EntryLevel": 3,
"Latitude": 45.5343, "Longitude": -73.5812,
"PublicRemarks": "Bright 3rd-floor condo, kitchen redone in 2024…",
"Media": [ { "MediaURL": "https://…/1.jpg" }, { "MediaURL": "https://…/2.jpg" } ]
}Coordinates are needed to check the perimeter and for every location measure. Photos are read in order, up to your contract's limit.
Three ways to receive the results
| Request | What comes back |
|---|---|
delivery: "response" (default) | the whole outcome at the end, in the response |
same + Accept: application/x-ndjson | one line per listing as soon as it is ready, then the whole outcome |
delivery: "webhook" | 202 at once; each listing arrives as analysis.completed, then batch.completed |
One listing's result
The same object everywhere — response, stream, webhook: the score, a sentence ready to display, and in result the details of every criterion.
{
"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, … (always in French)",
"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": "Over 900 sq ft", "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": "Metro within a 10-min walk", "is_exclusion": false,
"points_possible": 10, "points_earned": 10, "passed": true,
"methods": ["signal"], "resolved_by": "signal", "note": "nearest station 6 min on foot" },
{ "id": "cuisine_renovee", "label": "Renovated kitchen", "is_exclusion": false,
"points_possible": 10, "points_earned": 10, "passed": true,
"methods": ["llm"], "resolved_by": "llm", "inputs_used": ["description", "photos"],
"note": "\"kitchen redone in 2024\", quartz counters visible in photo 2" },
…
],
"unevaluated_criteria": [],
"skipped_criteria": [],
"explanation": "…",
"llm_explanation": "…"
}
}| Field | Meaning |
|---|---|
score | 0 to 100: points earned ÷ points of the scored criteria actually evaluated. 0 when the listing is ruled out. |
excluded | an exclusion holds; the labels are in exclusion_reasons |
score_min | / score_max: the score if every criterion that could not be checked failed / passed. score always lies between; equal when everything was checked. |
summary | one sentence: what rules the listing out, or the weightiest criteria met and what is missing (in French) |
result.breakdown[] | every criterion: passed (true / false, or null when the data is missing), points, resolved_by (the method that answered) and note (the value or evidence behind the verdict) |
result.unevaluated_criteria | criteria whose information does not exist; they leave the calculation |
result.skipped_criteria | criteria not computed because the listing was already ruled out |
result.llm_explanation | the AI's own explanation, when it took part |
warnings | notes on the listing (approximate position, rental rather than sale, photos ignored…) |
cached | result reused, not counted (see below) |
On the response
→ 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, … }
}| Field | Meaning |
|---|---|
ranking | the listings kept, best first (score, then score_max) |
excluded | the listings an exclusion ruled out |
rejected | refused free of charge: unreadable (422), outside the perimeter (403), twice in the request (409) |
failed | analysis failed on our side (502): not counted, send it again |
complete | false if the search was interrupted before the end |
As they finish
With Accept: application/x-ndjson, one JSON object per line. listing lines arrive in the order analyses finish; index is the listing's position in 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":{ …the non-streamed response body… }}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…: no stream
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 + details, as soon as ready
if (event.type === "listing_error") showFailed(event);
if (event.type === "result") return event.result; // final ranking
if (event.type === "error") throw new Error(event.detail);
}
}404, 422, 429…) stay ordinary HTTP responses, with no stream. Closing the connection midway abandons the analyses still running, which are not counted; the finished ones stay recorded.By 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": { … } } }- Each listing arrives with its full details.
batch.completedsums up the ranking without repeating them (result: null). - A search interrupted by a restart on our side ends with
batch.completedandcomplete: false: send again the listings you did not receive — those already analysed are replayed free of charge. GET /analyses/batches/{batch_id}reads a search's outcome again at any time, details included.
Scores already computed
Every analysis is kept. When the broker opens a listing, or a list shows listings already scored for this set, read the latest stored score instead of analysing again — it is free. stale: true says the criteria changed since: the score is out of date, run a search to refresh it.
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: the criteria changed since this analysis
"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, … } ]| Method | Route | Purpose |
|---|---|---|
| GET | /criteria-sets/{id}/listings/{listing} | one listing's latest score, with every criterion's details (404 if never analysed) |
| GET | /criteria-sets/{id}/listings?listing_ref=… | the latest score of each listing named (or of all, newest first); details=true to include the details |
Your geocoding (optional)
If your system already knows the property's exact position or the places around it, attach them to the listing as scorimmo_geo: Scorimmo uses them instead of looking them up.
{
"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": "Laurier Park", "distance_m": 420 }
]
}
}- The coordinates replace the listing's (unless
precision: "approximate"). - Each place in
placeshas atypefrom theplace_typesvocabulary and at least one of:walk_minutes(taken as is),distance_m(straight line, walking time estimated from it) or its coordinates. - A malformed
scorimmo_geois ignored, with a warning.
What counts
- One counted analysis = one listing analysed in a search.
- Free re-analysis for 24 hours: the same listing, with the same data, scored against the same criteria set within 24 hours is replayed (
cached: true,billed: false). Purely administrative fields (update dates…) change nothing; a change to the price, area, description, photos or criteria triggers a new analysis. - All or nothing: if the remaining quota cannot cover every listing a search needs analysed, nothing runs (
429). - Never counted: a listing outside the perimeter, unreadable or duplicated, an analysis that fails on our side, criteria links, criteria generation and reading the buyer's files, reading stored scores.
Errors
Every error has the shape {"detail": "message"}.
HTTP/1.1 429 Too Many Requests
Retry-After: 60
{ "detail": "Trop de requêtes : 60 par minute au maximum." }| Code | Meaning |
|---|---|
401 | token missing, invalid or revoked |
403 | account disabled |
404 | set, criterion, link, delivery or search not found (or belonging to another company) |
409 | criteria set limit reached, criterion id already used, or no webhook configured |
422 | invalid data: unanswerable criterion, webhook URL refused, more than 100 listings, criteria_id and external_ref together |
429 | monthly quota insufficient, or too many requests per minute (see Retry-After) |
End-to-end example
API=https://… # address provided with your token
TOKEN=smk_live_…
H=(-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json")
# 0. once: your webhook (keep the secret it returns)
curl -s -X PUT $API/v1/partner/webhook "${H[@]}" \
-d '{"url":"https://crm.example.com/hooks/scorimmo"}' | jq -r .secret
# 1. the broker clicks: a link for project 4812
curl -s -X POST $API/v1/partner/criteria-links "${H[@]}" \
-d '{"external_ref":"projet-4812","name":"Plateau condo project"}' | jq -r .url
# 2. the buyer fills in the link → criteria_set.updated reaches your webhook
# 3. a search: the listings, ranked, with the details
curl -s -X POST $API/v1/partner/analyses/batch "${H[@]}" \
-d "{\"external_ref\":\"projet-4812\",\"properties\":$(cat listings.json)}" \
| jq '.ranking[] | {listing_ref, score, summary}'