Régies · intégration technique

API v1 · VERIFIMMO Suisse

Une API de lecture, pour que vos dossiers arrivent déjà dans votre CRM.

Trois endpoints REST, une clé par enseigne, aucun abonnement. Vous lisez les dossiers que les candidats vous ont partagés, exactement ceux-là. La clé de bac à sable ci-dessous fonctionne immédiatement : vous pouvez écrire votre intégration avant même de nous avoir parlé.

Clé de bac à sable Comprendre l'offre régie

La règle d'accès

Une clé ne crée jamais un accès : elle industrialise un accès déjà consenti.

C'est le seul principe à retenir avant d'écrire une ligne de code. Il explique la plupart des réponses 404 que vous rencontrerez en production.

Périmètre nominatif

Votre clé ne voit que les partages adressés aux adresses e-mail que vous nous avez déclarées. Aucun paramètre de requête ne peut élargir ce périmètre.

Lecture seule

Deux portées seulement, et aucune écriture. L'API ne peut ni modifier un dossier, ni prolonger un partage, ni contacter un candidat.

Tout est journalisé

Chaque lecture de fiche ou de pièce est tracée et visible du candidat, au même titre qu'une consultation humaine. La transparence fait partie du produit.

Portées disponibles

dossiers:readLire les dossiers partagés (métadonnées, attestation)
pieces:readTélécharger les pièces justificatives

Mise en route

Quatre étapes, dont une seule dépend de nous.

01
Le candidat vous partage son dossier
Rien ne commence par un contrat : c'est le locataire qui décide. Il crée un partage vers l'adresse e-mail nominative d'un de vos collaborateurs. L'API n'ouvre jamais un accès, elle industrialise un accès déjà consenti.
02
Vous codez immédiatement, en bac à sable
La clé de démonstration ci-dessous est publique et fonctionne tout de suite. Elle renvoie un dossier fictif complet, aux formats exacts de la production. Vous n'attendez ni contrat, ni premier partage réel pour écrire votre intégration.
03
Vous demandez votre clé de production
Écrivez-nous avec le nom de votre enseigne et la liste nominative des adresses e-mail de vos collaborateurs. Nous émettons une clé dont le périmètre est exactement cette liste, avec les portées que vous demandez.
04
Vous remplacez la clé, et c'est en ligne
Même URL, même format de réponse : seule la clé change. Chaque lecture est journalisée et visible du candidat, comme une consultation humaine. Vous pouvez nous demander la révocation d'une clé à tout moment.

Bac à sable

Cette clé fonctionne maintenant. Copiez-la, collez-la dans votre terminal.

Elle est publique et volontairement documentée : elle ne donne accès à aucune donnée réelle. Les réponses sont un dossier fictif, aux formats exacts de la production, servi sans aucune lecture de notre base. Un client qui fonctionne ici fonctionne en réel — seule la clé change.

Clé de bac à sable (publique)

vki_5a4d0b0e_5a4d0b0e5a4d0b0e5a4d0b0e5a4d0b0e5a4d0b0e5a4d0b0e

1. Lister les dossiers partagés

curl -s "https://verifimmo.ch/api/public/v1/dossiers?per_page=10" \
  -H "Authorization: Bearer vki_5a4d0b0e_5a4d0b0e5a4d0b0e5a4d0b0e5a4d0b0e5a4d0b0e5a4d0b0e"

2. Lire un dossier complet

curl -s "https://verifimmo.ch/api/public/v1/dossiers/00000000-5a4d-4b0e-8000-000000000001" \
  -H "Authorization: Bearer vki_5a4d0b0e_5a4d0b0e5a4d0b0e5a4d0b0e5a4d0b0e5a4d0b0e5a4d0b0e"

3. Obtenir le lien d'une pièce

curl -s "https://verifimmo.ch/api/public/v1/dossiers/00000000-5a4d-4b0e-8000-000000000001/pieces/extrait_poursuites?format=json" \
  -H "Authorization: Bearer vki_5a4d0b0e_5a4d0b0e5a4d0b0e5a4d0b0e5a4d0b0e5a4d0b0e5a4d0b0e"

En bac à sable, un seul identifiant de dossier existe (00000000-5a4d-4b0e-8000-000000000001) et les réponses portent sandbox: true. Vérifiez que votre code ignore ce champ : il disparaît en production.

Référence

Trois endpoints, et rien d'autre à apprendre.

Base : https://verifimmo.ch. Authentification par en-tête Authorization: Bearer, ou x-api-key si votre CRM ne sait pas envoyer de Bearer.

GET/api/public/v1/dossiersdossiers:read

Liste paginée des dossiers qui vous sont partagés, du plus récent au plus ancien.

Paramètres : page (défaut 1), per_page (défaut 20, max 50)

GET/api/public/v1/dossiers/{id}dossiers:read

Vue complète d'un dossier : candidat, attestation, 11 points tranchés, synthèse d'analyste, liste des pièces.

Paramètres : aucun

GET/api/public/v1/dossiers/{id}/pieces/{docKey}pieces:read

Accès à une pièce validée : redirection 302 vers un lien signé valable 5 minutes.

Paramètres : format=json pour recevoir le lien au lieu de la redirection

Réponse type — dossier complet

Extrait raccourci. La réponse réelle contient les 11 points, les points d'attention et l'ensemble des pièces validées.

GET /api/public/v1/dossiers/{id}

{
  "version": "v1",
  "sandbox": true,
  "share": { "id": "00000000-5a4d-4b0e-8000-000000000001", "propertyRef": "DEMO-3P-LAUSANNE" },
  "candidate": { "name": "Marie Exemple", "city": "Lausanne" },
  "dossier": { "reference": "VI-2026-0042", "status": "validated" },
  "certificate": {
    "reference": "VI-2026-0042",
    "valid": true,
    "identityVerified": true,
    "expiresAt": "2028-01-15T09:12:00.000Z",
    "checks": [{ "key": "identite", "label": "Identité vérifiée", "status": "passed" }],
    "summary": "Candidate en emploi stable, revenus réguliers…"
  },
  "pieces": [
    {
      "docKey": "extrait_poursuites",
      "label": "Extrait des poursuites",
      "mimeType": "application/pdf",
      "href": "/api/public/v1/dossiers/00000000-5a4d-4b0e-8000-000000000001/pieces/extrait_poursuites"
    }
  ]
}

Erreurs et cadence

Ce que votre code doit savoir gérer.

Statut	Code	Signification
401	missing_api_key	Aucune clé présentée dans Authorization ou x-api-key.
401	invalid_api_key	Clé au mauvais format, inconnue ou révoquée.
401	revoked_api_key	Clé révoquée : demandez-nous une nouvelle clé.
403	missing_scope	La clé n'a pas la portée requise par cet endpoint.
403	no_agency_domain	Aucun domaine e-mail n'est rattaché à votre régie : le périmètre de la clé est indéterminable.
404	share_not_found	Dossier inexistant, partage expiré ou révoqué, ou hors du périmètre de votre clé.
404	piece_not_found	Pièce absente du dossier, ou pas encore validée par un analyste.
429	rate_limited	Cadence dépassée. Respectez l'en-tête Retry-After.

Cadence

60 requêtes par minute et 600 par heure. Les en-têtes X-RateLimit-* et Retry-After accompagnent chaque réponse 429 : respectez-les plutôt que de réessayer en boucle.
La clé de démonstration suit la même cadence par minute : le bac à sable sert à écrire votre client, pas à le tester en boucle.

Liens de pièces

Les liens signés expirent après 5 minutes. Ne les stockez pas : redemandez-les au moment où votre utilisateur ouvre le document. Une pièce n'est exposée que si un analyste l'a validée.

Traitez votre clé de production comme un mot de passe

Elle s'utilise de serveur à serveur uniquement : jamais dans un navigateur, une application mobile ou un dépôt de code. Nous ne la réaffichons jamais après son émission et nous la révoquons sur simple demande.

Prochaine étape

Votre bac à sable fonctionne ? Demandez votre clé.

Indiquez le nom de votre enseigne, les adresses e-mail nominatives de vos collaborateurs et les portées souhaitées. Nous émettons la clé et la transmettons à votre responsable technique.

Demander une clé de production Revenir à l'offre régie

5 minutes · offre de lancement dès CHF 69 · certification en 48h garantie