AuthentificationBientôt disponible

Chaque requête à l'API Matchai agit pour un seul compte Matchai. Il y a deux façons d'obtenir l'identifiant de connexion qui le prouve, et la bonne dépend du compte avec lequel vous travaillez.

Deux façons d'accéderCopier le lien de cette section

Les deux vont dans le même en-tête :

Authorization: Bearer matchai_…

Un jeton d'accès OAuth s'envoie de la même façon, à la place de la clé.

Ce qu'une requête peut faireCopier le lien de cette section

Une requête peut faire ce que le titulaire du compte peut faire dans Matchai, selon les mêmes règles et les mêmes permissions, et rien de plus. Deux éléments la restreignent davantage :

• Les portées limitent les parties du compte auxquelles l'identifiant de connexion peut toucher.
• Les actions finales attendent l'approbation du titulaire du compte, à moins qu'il ait permis à votre application de les exécuter.

GET /v1/me/connection (getConnection) indique à votre application comment elle est connectée : l'application, les portées accordées, auth_type (api_key ou oauth), approval_mode (ask_me ou allowed) et si la connexion est en mode test.

PortéesCopier le lien de cette section

Chaque opération de la référence de l'API indique les portées dont elle a besoin. Ne demandez que ce que votre application utilise : un professionnel est plus enclin à appuyer sur Autoriser quand la liste est courte et que chaque ligne a du sens.

Quand il manque une portée à un identifiant de connexion, l'appel échoue avec 403 et le code scope_missing, et le message nomme la portée. Pour une clé, créez une nouvelle clé qui a la portée et révoquez l'ancienne. Pour une connexion OAuth, faites repasser le professionnel par le flux de connexion de votre application, pour qu'il puisse accepter la liste plus longue.

Quelques opérations ne demandent aucune portée parce qu'elles ne touchent qu'à ce qui est déjà public, comme la consultation du profil publié d'un professionnel. Elles sont marquées Free (gratuit) dans la référence, et une clé ou un jeton y est facultatif.

Actions finalesCopier le lien de cette section

Quatre sortes d'actions sont finales : envoyer quelque chose à une autre personne, publier quelque chose pour le public, payer, et supprimer du contenu du compte. L'Assistant Matchai demande toujours avant de faire l'une ou l'autre, et l'API impose la même règle à votre application. Chaque action finale est marquée Final action (action finale) dans la référence.

Le titulaire du compte choisit comment votre application les gère, connexion par connexion :

Tout ce qui n'est pas une action finale s'exécute selon les portées de l'identifiant de connexion, comme la même modification le ferait dans l'application : les lectures, les brouillons et les changements aux propres dossiers du titulaire du compte. Retirer la configuration de votre propre application, comme un abonnement à un webhook, n'est pas non plus une action finale.

Concevez votre application pour les deux réglages. Le titulaire du compte peut changer le réglage en tout temps, alors ne présumez jamais de celui que vous aurez.

Suivre une approbationCopier le lien de cette section

Une action finale sous Me demander répond 202 et ne fait encore rien :

{
  "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"
}

Une approbation a l'un de cinq statuts :

GET /v1/approvals (listApprovals) liste les demandes que votre connexion a faites, et accepte un filtre status.

Envoyez un Idempotency-Key avec chaque action finale. Si votre requête expire et que vous la répétez avec la même clé, vous recevez la même approbation en attente au lieu d'une deuxième.

Cet exemple publie une inscription et gère les deux réglages :

import { randomUUID } from 'node:crypto';

const response = await fetch(`https://api.matchai.co/v1/listings/${listingId}/publish`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.MATCHAI_API_KEY}`,
    'Idempotency-Key': randomUUID(),
  },
});

if (response.status === 202) {
  // Ask me: nothing has happened yet.
  const pending = await response.json();
  console.log(`Waiting: ${pending.summary}`);
  console.log(`The account holder can answer at ${pending.approval_url}`);
} else if (response.ok) {
  // Allowed: the listing is published now.
  const listing = await response.json();
  console.log(`Published at ${listing.url}`);
} else {
  const { error } = await response.json();
  throw new Error(`${error.code}: ${error.message}`);
}

Limites d'énergieCopier le lien de cette section

Certaines actions dépensent de l'Énergie Matchai, comme les fonctionnalités d'IA le font dans l'application : rédiger une inscription avec l'IA, retoucher des photos, traduire, rédiger un brouillon avec l'IA, envoyer un courriel, et les messages envoyés par texto. La référence marque chacune d'elles et indique le poids de l'action : légère, modérée, élevée, ou variable.

• L'API n'affiche jamais l'énergie sous forme de nombre. GET /v1/me renvoie son état : full, comfortable, low ou empty.
• Un appel qui demande plus que ce qui reste ne fait rien. Il répond 402 avec le code insufficient_energy, et rien n'est dépensé.
• Le titulaire du compte peut fixer une limite d'énergie pour chaque connexion, pour qu'un script qui s'emballe s'arrête à un plafond qu'il a choisi. Quand votre connexion l'atteint, les appels qui dépensent de l'énergie répondent 402 avec le code energy_limit_reached, et GET /v1/me/connection indique energy_limit_reached: true.

Montrez à la personne le message d'un 402 : il dit ce qui s'est passé et quoi faire ensuite. Consultez Erreurs.

Mettre fin à une connexionCopier le lien de cette section

Une connexion prend fin de l'une de trois façons, et chacune arrête tous les identifiants de connexion qui lui appartiennent :

• Le professionnel appuie sur Déconnecter sur la page Connecteurs.
• Vous révoquez une clé d'API.
• Votre application appelle DELETE /v1/me/connection (disconnect). Cet appel met fin à la connexion comme si le professionnel avait appuyé sur Déconnecter, et ne supprime rien dans le compte.

Une fois une connexion terminée, ses abonnements aux webhooks sont désactivés et ses requêtes répondent 401. Traitez cette réponse comme un signal de reconnexion, et non comme une panne.

Mode testCopier le lien de cette section

Une application connectée seulement au compte de son propre développeur est en mode test. Les connexions de test ne sont pas facturées, et les événements qu'elles produisent portent test_mode: true. La page Créer une application Matchai explique comment cela fonctionne, et qui paie une fois que d'autres professionnels se connectent.