Démarrage rapideBientôt disponible

Créez une clé d'API.

Ouvrez Paramètres → Connecteurs, déployez Options avancées (pour les développeurs) et allez à Clés d'API. Créez une clé, nommez-la (par exemple « Démarrage rapide ») et donnez-lui trois portées : profile:read, listings:read et contacts:write.

Copiez la clé tout de suite. Matchai ne l'affiche qu'une fois. Elle commence par matchai_. Gardez-la dans une variable d'environnement, jamais dans votre code :

export MATCHAI_API_KEY="matchai_…"

Chaque clé appartient à la connexion Accès à l'API de votre compte, qui apparaît sur la page Connecteurs comme toute autre connexion. Consultez Clés d'API pour les portées, le renouvellement et la révocation.

Vérifiez quel compte la clé atteint. GET /v1/me renvoie le compte pour lequel votre clé agit.

curl https://api.matchai.co/v1/me \
  -H "Authorization: Bearer $MATCHAI_API_KEY"

Une réponse abrégée :

{
  "user_id": "3f1c9a2e-7b44-4d0e-9c1a-5e8f2b6d4a10",
  "professional_id": "8a2d4f6b-1c3e-4a5b-9d7f-0e2c4b6a8d1f",
  "username": "camilletremblay",
  "display_name": "Camille Tremblay",
  "job_title": "Residential real estate broker",
  "language": "fr-CA",
  "timezone": "America/Toronto",
  "site_id": "0f1a2b3c-4d5e-4f6a-9b7c-8d9e0f1a2b3c",
  "page_url": "https://camilletremblay.matchai.pro",
  "energy": { "balance_state": "comfortable" }
}

energy.balance_state vaut full, comfortable, low ou empty. L'Énergie Matchai n'est jamais affichée sous forme de nombre. Les noms et les identifiants de ces exemples sont fictifs.

Listez vos inscriptions. GET /v1/listings renvoie les inscriptions que vous pouvez gérer, de la plus récemment modifiée à la plus ancienne. Les listes arrivent par pages : passez limit pour fixer la taille d'une page, et le next_cursor d'une page comme cursor de la suivante.

curl -G https://api.matchai.co/v1/listings \
  -H "Authorization: Bearer $MATCHAI_API_KEY" \
  -d status=published \
  -d limit=5

Une réponse abrégée, avec une inscription :

{
  "data": [
    {
      "id": "b7e4c2a1-9f3d-4e6b-8a5c-1d2f3e4a5b6c",
      "slug": "condo-rue-fabre-plateau-mont-royal",
      "url": "https://camilletremblay.matchai.co/listings/condo-rue-fabre-plateau-mont-royal",
      "status": "published",
      "availability": "available",
      "title": "Bright corner condo steps from Parc La Fontaine",
      "price": { "amount": 649000, "currency": "CAD" },
      "updated_at": "2026-10-18T09:41:52Z"
    }
  ],
  "next_cursor": null
}

Pour garder une copie de vos inscriptions synchronisée, passez updated_since avec l'heure de votre dernière synchronisation. Consultez la pagination pour la boucle complète.

Ajoutez un contact. POST /v1/contacts ajoute un prospect, un client ou un professionnel. Envoyez un en-tête Idempotency-Key avec chaque POST : si votre requête expire, vous pouvez la répéter avec la même clé, et Matchai n'ajoutera pas le contact deux fois.

curl https://api.matchai.co/v1/contacts \
  -H "Authorization: Bearer $MATCHAI_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "lead",
    "first_name": "Julien",
    "last_name": "Bouchard",
    "email": "julien.bouchard@example.com"
  }'

Une réponse 201 renvoie le nouveau contact, abrégé ici :

{
  "id": "c5d8e1f2-3a4b-4c6d-9e8f-7a6b5c4d3e2f",
  "type": "lead",
  "first_name": "Julien",
  "last_name": "Bouchard",
  "display_name": "Julien Bouchard",
  "email": "julien.bouchard@example.com",
  "created_at": "2026-10-16T19:12:44Z"
}

Quand l'adresse courriel ou le numéro de téléphone appartient déjà à l'un de vos contacts, Matchai n'ajoute rien et répond 409 avec le code contact_exists. C'est pourquoi le code ci-dessus le vérifie.