Home

Documentation

Scorimmo API

Have the buyer give their criteria, receive them in your software, then rank the listings of your searches against them. Display stays entirely on your side.

Overview

The flow, end to end:

  1. The broker clicks on a project (or a prospect — Scorimmo does not need to know which). Your software calls POST /criteria-links with your id for that record (external_ref). Scorimmo files a criteria set under it and returns a link.
  2. 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.
  3. The criteria are generated and reach you by webhook (criteria_set.updated). You display them; the broker edits them through the /criteria-sets routes.
  4. 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. CAD and sq ft in Quebec, EUR and m² in France).
  • Error messages (detail) are written in French.
MethodRoutePurpose
GET/accountcontract, market, this month's usage
GET/criteria-schemafields, measures and place types available
PUT/webhookyour endpoint (secret returned once)
GET/webhookthe configured webhook
DELETE/webhookremove it
POST/webhook/testsend a signed ping, see the outcome
GET/webhook/deliveriesrecent deliveries (?status=failed)
GET/webhook/deliveries/{id}one delivery, with its payload
POST/webhook/deliveries/{id}/retrysend it again
POST/criteria-linksa 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}/criteriareplace the whole list
POST/criteria-sets/{id}/criteriaadd 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/batchscore 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
  }
}
LimitWhat 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 sets409 on POST /criteria-links for a new external_ref; delete a set to free a slot
Requests per minute429 with Retry-After: 60
Geographic perimetera listing outside it is refused (403 in rejected) — not counted
Photos per listingthe 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": { … } }
EventWhen
criteria_set.updatedthe buyer sent their answer; their criteria are in the set
criteria_set.generation_failednothing usable came out of it; the buyer can add detail and send again
analysis.completedone listing of a search, scored, with its details
analysis.failedone listing could not be scored (not counted)
batch.completeda search delivered by webhook is over
pingsent 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.

Node.js
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 2xx response 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 failed and stays listed. Redirects are not followed.
  • Scorimmo-Delivery is 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     → 202

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:

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": "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": []
  }
}
FieldContent
criteria_setthe whole set as it now stands (same shape as GET /criteria-sets/{id})
sourcequestionnaire, text, pdf or audio
answersquestionnaire: each question and the answer, readable
brieftext, PDF or audio: the text the criteria came from (as corrected by the buyer)
unmappedwhat the buyer asked for that no criterion can check — worth showing the broker
rejectedcriteria drafted then dropped because they could not be evaluated, with why
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." }
}

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"] } }] }
  ]
}
MethodRoutePurpose
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}/criteriareplace the whole list
POST/criteria-sets/{id}/criteriaadd 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-schemafields, measures and place types, to build the editor

Anatomy of a criterion

FieldRole
idstable id, a-z 0-9 _, 2 to 64 characters, unique within the set
labeldisplayed label, up to 300 characters
is_exclusiontrue = dealbreaker: if it holds, the listing is ruled out. The label therefore names the problem ("Price > $650,000", "Ground floor"), never the wish.
pointsweight of a scored criterion: from 1 (a small bonus) to 10 (a top priority for the buyer), never more. Always 0 for an exclusion.
definitionoptional clarification, read by the AI
categoryoptional grouping for your display
evaluationsone 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.

  1. reso_field — exact comparison on a listing field. Parameters field, op (gt, gte, lt, lte, eq) and value.
  2. signal — a measure of the location. Parameters signal, op, value, and those specific to the measure (radius, place type, destination address…).
  3. llm — judged by the AI. Parameter inputs: ["description"] (default), ["photos"] or both.

Listing fields (reso_field)

FieldContent
list_priceasking price
living_arealiving area, in the market's unit
rooms_totalnumber of rooms
bedrooms_totalbedrooms
bathrooms_total_integerbathrooms
year_builtyear built
entry_levelfloor (0 = ground floor)
lot_size_arealot size
association_feecondo fees, per month
tax_annual_amountannual property taxes
monthly_taxes_and_feestaxes and condo fees, per month
energy_class_rankenergy class (EPC): A = 1 … G = 7
ghg_class_rankclimate class (GHG): A = 1 … G = 7

Location measures (signal)

MeasureWhat it returns
metro_walk_minuteswalking minutes to the nearest metro station
grocery_walk_minuteswalking minutes to the nearest grocery store
place_walk_minuteswalking minutes to the nearest place of a given type (school, park, pharmacy…)
place_countnumber of places of a given type within a radius
commercial_density_countdensity of shops and restaurants around the property
commute_minutestravel time to an address (destination), by car, transit, bike or on foot (mode)
osm_nearest_distance_mdistance in metres to the nearest OpenStreetMap feature (coastline, beach, park, station…)
osm_countnumber of OpenStreetMap features within a radius
air_quality_indexair quality index
pollen_indexpollen index
roof_sunshine_hoursannual sunshine hours on the roof
roof_solar_potential_kwhthe roof's solar potential
elevation_melevation
The exact list of fields, measures and place types available for your market, with their parameters, is returned by GET /v1/partner/criteria-schema. Use it as the reference to build a criteria editor.

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." }
CodeMeaning
401token missing, invalid or revoked
403account disabled
404set, criterion, link, delivery or search not found (or belonging to another company)
409criteria set limit reached, criterion id already used, or no webhook configured
422invalid data: unanswerable criterion, webhook URL refused, more than 100 listings, criteria_id and external_ref together
429monthly quota insufficient, or too many requests per minute (see Retry-After)

End-to-end example

bash
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}'