Introduction

Lisez et écrivez vos données CRM par programmation. Utilisez cette API pour synchroniser vos fiches avec des outils externes, automatiser des traitements ou alimenter des intégrations avec des plateformes ERP, e-commerce et analytiques.

Authentification

Chaque requête doit inclure un jeton d'accès personnel (PAT).

1. Ouvrez votre CRM Initiative
2. Allez dans Mes préférences → Jetons d'API
3. Créez un jeton. Il ressemble à itv_YXBpdG9rZW4_a1b2c3d4...
4. Envoyez-le comme jeton Bearer dans chaque requête :

curl https://app.initiative-crm.com/api/v1/me \
  -H "Authorization: Bearer itv_YXBpdG9rZW4_a1b2c3d4..."

URL de base

L'URL de base de l'API dépend de l'environnement :

Vous n'avez pas besoin de préciser à quelle instance vous appartenez dans l'URL — votre instance est encodée dans le jeton d'API et résolue côté serveur.

Démarrage rapide — créez votre premier contact

curl -X POST https://app.initiative-crm.com/api/v1/contacts \
  -H "Authorization: Bearer itv_YXBpdG9rZW4_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "attributes": {
        "firstname": "Jean",
        "lastname": "Dupont",
        "email": "[email protected]"
      }
    }
  }'

Une réponse réussie renvoie 201 Created avec le nouveau contact :

{
  "data": {
    "id": "65",
    "type": "contacts",
    "attributes": {
      "firstname": "Jean",
      "lastname": "Dupont",
      "email": "[email protected]",
      "assigned_user_id": { "id": "1", "label": "Admin User" },
      "createdtime": "2026-05-15T10:00:00Z",
      "modifiedtime": "2026-05-15T10:00:00Z"
    }
  },
  "meta": { "request_id": "550e8400-e29b-41d4-a716-446655440000" }
}

Le même schéma fonctionne pour n'importe quel module — remplacez /contacts par /leads, /accounts, /invoices, etc. Les champs obligatoires de chaque module sont indiqués dans son schéma, dans la barre latérale.

Concepts

Modules

Les fiches sont organisées en modules. Chaque module représente un type d'objet métier — Contacts, Accounts, Invoices, etc. Parcourez les modules dans la barre latérale, à gauche. La liste complète est également disponible via GET /modules.

Champs de référence

Les champs de référence (comme account_id sur un contact) renvoient toujours un objet contenant à la fois l'identifiant et un libellé lisible, ce qui vous évite une requête de recherche séparée :

"account_id": { "id": "49", "label": "ACME France" }

Identifiants

Tous les identifiants sont renvoyés sous forme de chaînes d'entiers ("49"), jamais de nombres. C'est uniforme dans toute l'API.

Horodatages

Les horodatages utilisent le format ISO 8601 en UTC : 2026-04-30T10:00:00Z.

Champs nuls

Les champs nuls sont omis des réponses par défaut afin d'alléger les charges utiles. Ajoutez ?include_nulls=true à n'importe quel GET pour les inclure explicitement.

Propriété des fiches

Chaque fiche a un propriétaire — l'utilisateur auquel elle est attribuée. Lors de la création ou de la mise à jour d'une fiche, vous pouvez définir le propriétaire explicitement en envoyant assigned_user_id dans le corps de la requête :

{ "data": { "attributes": { "firstname": "Jean", "lastname": "Dupont", "assigned_user_id": "7206" } } }

Si vous omettez assigned_user_id, la fiche est attribuée à l'utilisateur propriétaire du jeton d'API — c'est-à-dire vous. La plupart des intégrations n'ont pas besoin de renseigner ce champ.

Pagination

Les endpoints de liste renvoient une enveloppe paginée :

{
  "data": [ ... ],
  "meta": {
    "total": 240,
    "page": 1,
    "per_page": 20,
    "pages": 12,
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Contrôlez la pagination avec ?page=N&per_page=M. La taille de page par défaut est de 20, le maximum de 100.

Limitation du débit

Chaque jeton d'API dispose d'un quota de requêtes géré par un seau à jetons. La limite par défaut est configurée au niveau d'utilisateur.

Chaque réponse inclut trois en-têtes pour suivre votre quota restant :

Lorsque la limite est atteinte, l'API répond avec 429 Too Many Requests et ajoute un en-tête Retry-After (en secondes) :

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1748340000
Retry-After: 42

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded.",
    "request_id": "1f3c8e2a-..."
  }
}

Attendez le nombre de secondes indiqué dans Retry-After avant de renvoyer la requête. Ne réessayez pas immédiatement — le seau sera toujours vide.

Erreurs

Chaque réponse d'erreur utilise une enveloppe unique :

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Record not found.",
    "request_id": "1f3c8e2a-..."
  }
}

request_id est unique pour chaque requête — mentionnez-le lorsque vous contactez le support.

Erreurs de premier niveau

Erreurs de validation (422)

Une VALIDATION_ERROR répertorie tous les champs en échec d'un coup dans details[], chacun avec son propre code :

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The request body contains invalid data.",
    "request_id": "1f3c8e2a-...",
    "details": [
      { "field": "lastname", "code": "REQUIRED", "message": "This field is required." },
      { "field": "email", "code": "INVALID_FORMAT", "message": "Must be a valid email address." }
    ]
  }
}

Ces codes peuvent apparaître sur n'importe quelle création ou mise à jour. Certains endpoints définissent des codes de validation supplémentaires, spécifiques à l'endpoint (par exemple les abonnements aux webhooks, la conversion de prospects, l'envoi de documents, les commentaires et les catalogues de prix) — ils sont documentés sur les opérations qui les renvoient.

Consultez les schémas Error et ValidationError dans la section Components pour la structure exacte.

Versions

Ceci est la v1. Les changements incompatibles seront livrés sous une nouvelle version majeure (v2) ; la v1 restera disponible.