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
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
200— OK401— Clé absente, mal formée, inconnue ou révoquée403— Scope insuffisant (`forbidden_scope`) ou organisation suspendue (`org_suspended`)429— Plus de 300 requêtes par minute pour cette clé500— Erreur interne : réessayer plus tard
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
stagequery to_qualify | qualified | booked | presented | proposal_sent | signed | sans_suite — Ne garder que cette étapesearchquery string — Filtre texte sur le nom, l'email ou le handleupdated_sincequery string · date-time — Ne garder que les contacts modifiés depuis cette date (ISO 8601)limitquery integer (défaut 50) — Taille de page (1 à 200)cursorquery string — Curseur opaque renvoyé dans `next_cursor`
Réponses
200— Page de contacts401— Clé absente, mal formée, inconnue ou révoquée403— Scope insuffisant (`forbidden_scope`) ou organisation suspendue (`org_suspended`)422— Corps ou paramètre invalide ; `code` = `validation_error: <champ>`429— Plus de 300 requêtes par minute pour cette clé500— Erreur interne : réessayer plus tard
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
200— Contact mis à jour201— Contact créé401— Clé absente, mal formée, inconnue ou révoquée403— Scope insuffisant (`forbidden_scope`) ou organisation suspendue (`org_suspended`)422— Corps ou paramètre invalide ; `code` = `validation_error: <champ>`429— Plus de 300 requêtes par minute pour cette clé500— Erreur interne : réessayer plus tard
GET /contacts/{id}
Fiche d'un contact
Contact + deals (chacun avec ses encaissements) + calls.
Paramètres
idchemin, requis string · uuid
Réponses
200— Fiche401— Clé absente, mal formée, inconnue ou révoquée403— Scope insuffisant (`forbidden_scope`) ou organisation suspendue (`org_suspended`)404— Ressource inexistante dans votre organisation429— Plus de 300 requêtes par minute pour cette clé500— Erreur interne : réessayer plus tard
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
idchemin, requis string · uuid
Corps (exemple)
{
"stage": "sans_suite",
"lost_reason": "prix",
"owner_id": "m3mb3r…"
}
Réponses
200— Contact mis à jour401— Clé absente, mal formée, inconnue ou révoquée403— Scope insuffisant (`forbidden_scope`) ou organisation suspendue (`org_suspended`)404— Ressource inexistante dans votre organisation422— Corps ou paramètre invalide ; `code` = `validation_error: <champ>`429— Plus de 300 requêtes par minute pour cette clé500— Erreur interne : réessayer plus tard
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
statusquery open | won | lostcontact_idquery string · uuidupdated_sincequery string · date-timelimitquery integer (défaut 50) — Taille de page (1 à 200)cursorquery string — Curseur opaque renvoyé dans `next_cursor`
Réponses
200— Page de deals401— Clé absente, mal formée, inconnue ou révoquée403— Scope insuffisant (`forbidden_scope`) ou organisation suspendue (`org_suspended`)422— Corps ou paramètre invalide ; `code` = `validation_error: <champ>`429— Plus de 300 requêtes par minute pour cette clé500— Erreur interne : réessayer plus tard
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
201— Deal créé401— Clé absente, mal formée, inconnue ou révoquée403— Scope insuffisant (`forbidden_scope`) ou organisation suspendue (`org_suspended`)404— Ressource inexistante dans votre organisation422— Corps ou paramètre invalide ; `code` = `validation_error: <champ>`429— Plus de 300 requêtes par minute pour cette clé500— Erreur interne : réessayer plus tard
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
201— Encaissement enregistré401— Clé absente, mal formée, inconnue ou révoquée403— Scope insuffisant (`forbidden_scope`) ou organisation suspendue (`org_suspended`)404— Ressource inexistante dans votre organisation422— Corps ou paramètre invalide ; `code` = `validation_error: <champ>`429— Plus de 300 requêtes par minute pour cette clé500— Erreur interne : réessayer plus tard
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
statusquery booked | held | no_show | canceled | rescheduledcontact_idquery string · uuidupdated_sincequery string · date-timelimitquery integer (défaut 50) — Taille de page (1 à 200)cursorquery string — Curseur opaque renvoyé dans `next_cursor`
Réponses
200— Page de calls401— Clé absente, mal formée, inconnue ou révoquée403— Scope insuffisant (`forbidden_scope`) ou organisation suspendue (`org_suspended`)422— Corps ou paramètre invalide ; `code` = `validation_error: <champ>`429— Plus de 300 requêtes par minute pour cette clé500— Erreur interne : réessayer plus tard
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
201— Call créé401— Clé absente, mal formée, inconnue ou révoquée403— Scope insuffisant (`forbidden_scope`) ou organisation suspendue (`org_suspended`)404— Ressource inexistante dans votre organisation422— Corps ou paramètre invalide ; `code` = `validation_error: <champ>`429— Plus de 300 requêtes par minute pour cette clé500— Erreur interne : réessayer plus tard
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
sincequery string · date-time — Strictement après cette date (ISO 8601)limitquery integer (défaut 100)
Réponses
200— Activités401— Clé absente, mal formée, inconnue ou révoquée403— Scope insuffisant (`forbidden_scope`) ou organisation suspendue (`org_suspended`)422— Corps ou paramètre invalide ; `code` = `validation_error: <champ>`429— Plus de 300 requêtes par minute pour cette clé500— Erreur interne : réessayer plus tard
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
200— Endpoints (sans secret)401— Clé absente, mal formée, inconnue ou révoquée403— Scope insuffisant (`forbidden_scope`) ou organisation suspendue (`org_suspended`)429— Plus de 300 requêtes par minute pour cette clé500— Erreur interne : réessayer plus tard
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
201— Endpoint créé401— Clé absente, mal formée, inconnue ou révoquée403— Scope insuffisant (`forbidden_scope`) ou organisation suspendue (`org_suspended`)422— Corps ou paramètre invalide ; `code` = `validation_error: <champ>`429— Plus de 300 requêtes par minute pour cette clé500— Erreur interne : réessayer plus tard
DELETE /webhooks/{id}
Supprimer un endpoint
Supprime l'endpoint : plus aucun événement ne lui est envoyé.
Paramètres
idchemin, requis string · uuid
Réponses
200— Supprimé401— Clé absente, mal formée, inconnue ou révoquée403— Scope insuffisant (`forbidden_scope`) ou organisation suspendue (`org_suspended`)404— Ressource inexistante dans votre organisation429— Plus de 300 requêtes par minute pour cette clé500— Erreur interne : réessayer plus tard