---
title: "Démarrage rapide"
description: "Créez une clé d'API, appelez GET /v1/me, listez vos inscriptions et ajoutez un contact avec curl, JavaScript ou Python. L'API Matchai arrive bientôt."
last_updated: "2026-10-21"
lang: "fr-CA"
status: "coming-soon"
canonical: "https://matchai.co/docs/fr/developers/quickstart"
---

# Démarrage rapide

> Créez une clé d'API, appelez GET /v1/me, listez vos inscriptions et ajoutez un contact avec curl, JavaScript ou Python. L'API Matchai arrive bientôt.

**Bientôt disponible. Cette fonctionnalité est documentée avant son lancement pour que vous puissiez planifier votre intégration; elle n’est pas encore offerte.**

Source: https://matchai.co/docs/fr/developers/quickstart

Ce démarrage rapide vous mène d'une nouvelle clé d'API à votre premier contact en quatre appels. Il fonctionne sur votre propre compte Matchai : il n'y a donc aucune application à enregistrer et rien à bâtir d'abord.

<Callout title="Vous ne pouvez pas encore faire ces appels">
L'API Matchai sera bientôt disponible. Les requêtes ci-dessous montrent comment elle fonctionnera à son ouverture, pour que vous puissiez planifier votre intégration. D'ici là, bâtissez sur les [interfaces publiques](https://matchai.co/docs/fr/developers#what-is-live-today).
</Callout>

## Avant de commencer [#before-you-start]

- Un compte Matchai de professionnel de l'immobilier. Tout ce que vous appelez agit pour ce seul compte.
- Un moyen d'exécuter une requête : `curl`, Node.js 20 ou plus récent, ou Python 3 avec le paquet `requests`.

## Faire vos premiers appels [#make-your-first-calls]

<Steps>
<Step>

**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 :

```bash title="Terminal"
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](https://matchai.co/docs/fr/developers/authentication/api-keys) pour les portées, le renouvellement et la révocation.

</Step>
<Step>

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

<Tabs items={['curl', 'JavaScript', 'Python']}>
<Tab value="curl">

```bash title="Terminal"
curl https://api.matchai.co/v1/me \
  -H "Authorization: Bearer $MATCHAI_API_KEY"
```

</Tab>
<Tab value="JavaScript">

```js title="me.mjs"
const response = await fetch('https://api.matchai.co/v1/me', {
  headers: { Authorization: `Bearer ${process.env.MATCHAI_API_KEY}` },
});

if (!response.ok) {
  const { error } = await response.json();
  const requestId = response.headers.get('Matchai-Request-Id');
  throw new Error(`${error.code}: ${error.message} (request ${requestId})`);
}

const me = await response.json();
console.log(`Connected as ${me.display_name}. Energy: ${me.energy.balance_state}.`);
```

</Tab>
<Tab value="Python">

```python title="me.py"
import os

import requests

response = requests.get(
    "https://api.matchai.co/v1/me",
    headers={"Authorization": f"Bearer {os.environ['MATCHAI_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()

me = response.json()
print(f"Connected as {me['display_name']}. Energy: {me['energy']['balance_state']}.")
```

</Tab>
</Tabs>

Une réponse abrégée :

```json title="Response"
{
  "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.

</Step>
<Step>

**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.

<Tabs items={['curl', 'JavaScript', 'Python']}>
<Tab value="curl">

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

</Tab>
<Tab value="JavaScript">

```js title="listings.mjs"
const url = new URL('https://api.matchai.co/v1/listings');
url.searchParams.set('status', 'published');
url.searchParams.set('limit', '5');

const response = await fetch(url, {
  headers: { Authorization: `Bearer ${process.env.MATCHAI_API_KEY}` },
});
if (!response.ok) throw new Error(`Matchai answered ${response.status}`);

const { data, next_cursor } = await response.json();
for (const listing of data) {
  console.log(`${listing.title} - ${listing.status} - ${listing.url}`);
}
console.log(next_cursor ? `More: cursor=${next_cursor}` : 'That is every listing.');
```

</Tab>
<Tab value="Python">

```python title="listings.py"
import os

import requests

response = requests.get(
    "https://api.matchai.co/v1/listings",
    headers={"Authorization": f"Bearer {os.environ['MATCHAI_API_KEY']}"},
    params={"status": "published", "limit": 5},
    timeout=30,
)
response.raise_for_status()

page = response.json()
for listing in page["data"]:
    print(f"{listing['title']} - {listing['status']} - {listing['url']}")
print(f"More: cursor={page['next_cursor']}" if page["next_cursor"] else "That is every listing.")
```

</Tab>
</Tabs>

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

```json title="Response"
{
  "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](https://matchai.co/docs/developers/api-reference#pagination) pour la boucle complète.

</Step>
<Step>

**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.

<Tabs items={['curl', 'JavaScript', 'Python']}>
<Tab value="curl">

```bash title="Terminal"
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"
  }'
```

</Tab>
<Tab value="JavaScript">

```js title="contact.mjs"
import { randomUUID } from 'node:crypto';

const response = await fetch('https://api.matchai.co/v1/contacts', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.MATCHAI_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': randomUUID(),
  },
  body: JSON.stringify({
    type: 'lead',
    first_name: 'Julien',
    last_name: 'Bouchard',
    email: 'julien.bouchard@example.com',
  }),
});

const body = await response.json();

if (response.status === 409 && body.error.code === 'contact_exists') {
  // The id of the contact that already has this email is in error.param.
  console.log(`Already a contact: ${body.error.param}`);
} else if (!response.ok) {
  throw new Error(`${body.error.code}: ${body.error.message}`);
} else {
  console.log(`Added ${body.display_name} as a ${body.type} (${body.id}).`);
}
```

</Tab>
<Tab value="Python">

```python title="contact.py"
import os
import uuid

import requests

response = requests.post(
    "https://api.matchai.co/v1/contacts",
    headers={
        "Authorization": f"Bearer {os.environ['MATCHAI_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "type": "lead",
        "first_name": "Julien",
        "last_name": "Bouchard",
        "email": "julien.bouchard@example.com",
    },
    timeout=30,
)
body = response.json()

if response.status_code == 409 and body["error"]["code"] == "contact_exists":
    # The id of the contact that already has this email is in error.param.
    print(f"Already a contact: {body['error']['param']}")
elif not response.ok:
    raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
else:
    print(f"Added {body['display_name']} as a {body['type']} ({body['id']}).")
```

</Tab>
</Tabs>

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

```json title="Response"
{
  "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.

</Step>
</Steps>

## Quand un appel demande d'abord [#when-a-call-asks-first]

Certaines actions sont des **actions finales** : envoyer un message, publier une inscription, supprimer quelque chose. La connexion de votre clé commence sur **Me demander**, ce qui veut dire qu'une action finale ne s'exécute pas quand vous l'appelez. Elle répond `202 Accepted` et attend que vous l'approuviez dans Matchai :

```json title="Response (202)"
{
  "status": "pending_approval",
  "approval_id": "1e2f3a4b-5c6d-4e7f-8a8b-9c0d1e2f3a4b",
  "approval_url": "https://matchai.co/approvals/1e2f3a4b-5c6d-4e7f-8a8b-9c0d1e2f3a4b",
  "expires_at": "2026-10-25T13:05:00Z",
  "summary": "Send a message to Julien Bouchard"
}
```

Traitez `202` comme « en attente de la personne », jamais comme une action terminée. La section [Actions finales](https://matchai.co/docs/fr/developers/authentication#final-actions) explique comment suivre le résultat.

<Cards>
  <Card title="Authentification" href="https://matchai.co/docs/fr/developers/authentication">
    Les portées, les actions finales, et quand utiliser Se connecter avec Matchai plutôt qu'une clé.
  </Card>
  <Card title="Clés d'API" href="https://matchai.co/docs/fr/developers/authentication/api-keys">
    Créer des clés, choisir leurs portées, les renouveler et les révoquer.
  </Card>
  <Card title="Erreurs" href="https://matchai.co/docs/fr/developers/errors">
    Chaque code d'erreur, et les appels qui peuvent être réessayés sans risque.
  </Card>
  <Card title="Référence de l'API" href="https://matchai.co/docs/developers/api-reference">
    Chaque point de terminaison prévu, à commencer par GET /v1/me.
  </Card>
</Cards>

## Sitemap

- [Toutes les pages de la documentation Matchai](https://matchai.co/docs/sitemap.md)
- [llms.txt](https://matchai.co/docs/fr/llms.txt)