Jomi — API publique

Version 1.0.0 · base https://app.thejomi.app/api/v1 · spécification brute : /openapi.json

API REST par organisation : contacts, deals, encaissements, calls, journal d'activités et webhooks sortants. Authentification par clé API (`Authorization: Bearer crm_live_…`), créée dans Réglages → API & webhooks. Toutes les réponses sont en JSON, non cachées. Devise de référence : celle de l'organisation (`organization.currency`, EUR ou USD, choisie à l'onboarding, modifiable dans Réglages → Relances, objectifs, devise) ; les montants saisis dans l'autre devise sont convertis au taux BCE du jour. Limites : 300 requêtes par minute et par clé (en-têtes `RateLimit-Policy`, et `RateLimit` + `Retry-After` sur un 429). Erreurs : `{ "error": { "code", "message", "docs" } }`, codes stables listés sur https://thejomi.app/developers#erreurs. Versions et dépréciation : la version est dans l'adresse (`/api/v1`) ; dans une version, seulement des ajouts (ignorer les champs inconnus). Un changement incompatible passe par `/api/v2`. Le retrait d'une opération ou d'une version est annoncé au moins 6 mois avant, par mail aux admins concernés et par les en-têtes `Deprecation` et `Sunset` (RFC 9745, RFC 8594). Détail : https://thejomi.app/developers#versions-et-depreciation

Authentification

En-tête Authorization: Bearer crm_live_… sur chaque requête. La clé se crée dans Réglages → API & webhooks (admin) et n'est affichée qu'une fois. Scopes : read (GET) et write (POST / PATCH / DELETE). Limite : 300 requêtes par minute et par clé (en-tête RateLimit-Policy ; RateLimit et Retry-After sur un 429). Erreurs : { "error": { "code", "message", "docs" } } avec les statuts 401, 403, 404, 422, 429, 500. Guide complet (MCP, webhooks, versions et dépréciation) : thejomi.app/developers.

Endpoints

GET /me

Organisation et clé utilisées

Test de connexion : renvoie l'organisation rattachée à la clé et les scopes de la clé.

Réponses

GET /contacts

Lister les contacts

Triés par `updated_at` croissant (pratique pour une synchronisation incrémentale avec `updated_since`). Pagination par curseur : suivre `next_cursor` tant que `has_more` est vrai. Les contacts archivés sont inclus (champ `archived`).

Paramètres

Réponses

POST /contacts

Créer ou mettre à jour un contact (idempotent)

Clé d'idempotence : `external_id` si fourni (identifiant chez vous), sinon `email`. Si le contact existe, seuls les champs fournis sont modifiés ; `note` est ajoutée en tête des notes (une seule fois) ; `stage` déclenche la même synchronisation deal / relance que l'app ; `deal_*` n'est pris en compte qu'à la création. À la création : étape `qualified` par défaut, relance automatique programmée (sauf étape close), propriétaire = admin de l'organisation. Renvoie 201 à la création, 200 à la mise à jour.

Corps (exemple)

{
  "external_id": "typeform-8812",
  "full_name": "Jeanne Martin",
  "email": "jeanne@example.com",
  "handle": "@jeanne",
  "phone": "+33612345678",
  "source": "website",
  "stage": "qualified",
  "note": "Formulaire site — veut un audit",
  "deal_value": 3000,
  "deal_currency": "EUR",
  "deal_title": "Audit"
}

Réponses

GET /contacts/{id}

Fiche d'un contact

Contact + deals (chacun avec ses encaissements) + calls.

Paramètres

Réponses

PATCH /contacts/{id}

Changer l'étape d'un contact

Synchronise le deal (Signé → gagné, Sans suite → perdu, étape active → ouvert) et la relance automatique, exactement comme le glisser-déposer du pipeline. `proposal_sent` (Proposition envoyée) n'est à utiliser que si l'organisation a activé cette étape (Réglages → Pipeline). Avec `stage: sans_suite`, `lost_reason` (facultatif) enregistre le motif : prix, timing, decideur, besoin, concurrence, confiance, injoignable, non_qualifie ou autre — il alimente « Pourquoi on perd » dans Performance. `owner_id` (uuid d'un membre actif, pas un observateur) assigne le contact à la personne qui le suit ; il peut se combiner avec `stage`.

Paramètres

Corps (exemple)

{
  "stage": "sans_suite",
  "lost_reason": "prix",
  "owner_id": "m3mb3r…"
}

Réponses

GET /deals

Lister les deals

Montants dans la devise de référence de l'organisation (`value`) ; montant facturé dans sa devise dans `original_amount` + `currency`. Triés par `updated_at`, pagination par curseur.

Paramètres

Réponses

POST /deals

Créer un deal

Nouvelle opportunité sur un contact. Un client déjà Signé / Sans suite revient dans le pipeline à l'étape « Qualifié » (ses deals gagnés sont conservés). `value` est dans `currency` (défaut : devise de référence de l'organisation ; l'autre devise est convertie au taux BCE du jour).

Corps (exemple)

{
  "contact_id": "c0ffee…",
  "title": "Accompagnement 3 mois",
  "value": 4500,
  "currency": "USD",
  "category": "coaching"
}

Réponses

POST /payments

Enregistrer un encaissement

Le deal passe « gagné » et le contact « Signé » (relance coupée), comme dans l'app. `amount` est dans `currency` (défaut : devise de référence de l'organisation) ; pour un paiement dans l'autre devise, `received_amount` = montant réellement crédité dans la devise de référence (relevé bancaire) prime sur le taux du jour. Si le taux est indisponible, la réponse est 422 : renvoyer avec `received_amount`.

Corps (exemple)

{
  "deal_id": "d3a1…",
  "amount": 1500,
  "currency": "EUR",
  "method": "stripe",
  "paid_at": "2026-09-26T10:12:00Z",
  "note": "Acompte 50 %"
}

Réponses

GET /calls

Lister les calls

Calls de l'organisation, triés par `updated_at` (synchronisation incrémentale avec `updated_since`), pagination par curseur. Les suivis client (`type: suivi`) sont inclus ; ils ne comptent pas dans les statistiques de vente.

Paramètres

Réponses

POST /calls

Journaliser un call

Round auto-attribué (R1, R2…) si absent, sauf pour un suivi client. Statut par défaut : `booked` si `scheduled_at` est dans le futur, `held` sinon.

Corps (exemple)

{
  "contact_id": "c0ffee…",
  "type": "closing",
  "scheduled_at": "2026-09-30T14:00:00Z",
  "duration_min": 45
}

Réponses

GET /events

Journal d'activités

Activités de l'organisation (contact créé, étape changée, call, encaissement, relance…) en ordre chronologique à partir de `since` (7 derniers jours par défaut). Pour suivre le flux : rappeler avec `since` = `next_since`.

Paramètres

Réponses

GET /webhooks

Lister les endpoints

Endpoints sortants de l'organisation, par date de création. Le secret HMAC n'est jamais renvoyé ici.

Réponses

POST /webhooks

Créer un endpoint

Le `secret` (clé HMAC) n'est renvoyé qu'à la création : conservez-le. Événements : contact.created, contact.updated, contact.stage_changed, deal.created, deal.won, deal.lost, payment.recorded, call.scheduled, call.held, call.no_show.

Corps (exemple)

{
  "url": "https://hooks.example.com/crm",
  "events": [
    "contact.created",
    "deal.won",
    "payment.recorded"
  ],
  "description": "Sync compta"
}

Réponses

DELETE /webhooks/{id}

Supprimer un endpoint

Supprime l'endpoint : plus aucun événement ne lui est envoyé.

Paramètres

Réponses