Créer, modifier et supprimer des fiches

Ce guide montre comment créer une fiche, savoir qui en est propriétaire et comment modifier cela, choisir correctement entre PATCH et PUT pour une mise à jour, supprimer une fiche, et lire tous les problèmes au niveau des champs qu'une écriture peut produire à partir d'une seule erreur de validation. Il vous faut seulement un jeton d'API et votre URL de base, comme indiqué dans le guide de démarrage ; pour les noms de champs, les types et les formats de valeurs — à quoi ressemble réellement la valeur d'un champ référence ou picklist — consultez Champs, formats et mise en forme des réponses, puisque ce guide traite uniquement du cycle de vie de l'écriture en lui-même.

1. Création

Chaque création est un POST /api/v1/{module} dont le corps est enveloppé dans data.attributes :

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

{
  "data": {
    "id": "1589",
    "type": "contacts",
    "attributes": {
      "firstname": "Claire",
      "lastname": "Moreau",
      "email": "[email protected]",
      "assigned_user_id": { "id": "7206", "label": "Taylor Morgan" },
      "createdtime": "2026-08-03T14:32:37Z",
      "modifiedtime": "2026-08-03T14:32:37Z"
    }
  },
  "meta": { "request_id": "dea47ef7-5c55-4fb8-9a73-53dea682ff03" }
}

Une création réussie renvoie 201. Le corps de la réponse ci-dessus est réduit par souci de lisibilité — la réponse réelle renvoie tous les champs du module, pas seulement ceux que vous avez envoyés (voir l'étape 2 pour assigned_user_id, qui est apparu sans avoir été demandé). L'enveloppe {"data":{"attributes":{…}}} est identique pour chaque slug de module créable — remplacez contacts par accounts, potentials, products, etc. ; rien d'autre dans la forme ne change.

2. À qui appartient la nouvelle fiche

assigned_user_id n'est pas obligatoire à la création : omettez-le et la nouvelle fiche appartient à l'utilisateur propriétaire du jeton.

curl -sS -H "Authorization: Bearer itv_YOUR_TOKEN_HERE" "https://app.initiative-crm.com/api/v1/me" | jq '.data.id'

"7206"

C'est le même "7206" que celui renvoyé dans assigned_user_id.id à l'étape 1 — ce jeton appartient à Taylor Morgan, et chaque fiche qu'il crée sans propriétaire explicite est attribuée à Taylor Morgan. Pour définir un propriétaire différent, envoyez une simple chaîne d'identifiant entier :

curl -sS -X PATCH "https://app.initiative-crm.com/api/v1/contacts/1589" \
  -H "Authorization: Bearer itv_YOUR_TOKEN_HERE" -H "Content-Type: application/json" \
  -d '{"data":{"attributes":{"assigned_user_id":"7206"}}}' | jq '.data.attributes.assigned_user_id'

{ "id": "7206", "label": "Taylor Morgan" }

assigned_user_id se relit sous la forme {id, label} comme un champ référence (voir Champs, formats et mise en forme des réponses), mais s'écrit de la même façon, avec une simple chaîne d'identifiant. Cette valeur par défaut automatique n'intervient qu'à la création — PATCH/PUT n'inventent jamais de valeur pour un champ que vous n'avez pas envoyé (voir l'étape 4 pour comprendre pourquoi cela compte pour PUT).

3. Modifier quelques champs — PATCH

PATCH valide et écrit uniquement les champs présents dans le corps de la requête. Tout le reste de la fiche reste inchangé :

curl -sS -X PATCH "https://app.initiative-crm.com/api/v1/contacts/1589" \
  -H "Authorization: Bearer itv_YOUR_TOKEN_HERE" -H "Content-Type: application/json" \
  -d '{"data":{"attributes":{"email":"[email protected]"}}}' \
  | jq '.data.attributes | {firstname, lastname, email}'

{
  "firstname": "Claire",
  "lastname": "Moreau",
  "email": "[email protected]"
}

Seul email était dans la requête ; firstname et lastname sont revenus inchangés. C'est le bon verbe pour « modifier quelques champs sur une fiche existante » — ce qui correspond à la plupart des mises à jour.

4. Remplacer une fiche — PUT

PUT exécute la même validation qu'à la création : chaque champ obligatoire défini par le module (d'après GET /api/v1/modules/{module}, voir Champs, formats et mise en forme des réponses) doit être présent dans le corps de la requête, pas seulement le champ que vous cherchez réellement à modifier. Envoyez un corps partiel et il est rejeté :

curl -sS -X PUT "https://app.initiative-crm.com/api/v1/contacts/1589" \
  -H "Authorization: Bearer itv_YOUR_TOKEN_HERE" -H "Content-Type: application/json" \
  -d '{"data":{"attributes":{"email":"[email protected]"}}}' -w '\n%{http_code}\n'

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed.",
    "request_id": "2eb0f87d-2847-4f5b-a053-10507ebf8c94",
    "details": [
      { "field": "lastname", "code": "REQUIRED", "message": "Field 'lastname' is required." },
      { "field": "assigned_user_id", "code": "REQUIRED", "message": "Field 'assigned_user_id' is required." }
    ]
  }
}
422

Contacts a deux champs obligatoires : lastname et assigned_user_id. Envoyer firstname, lastname et email — un corps qui semble complet si vous ne regardez que les champs qui vous intéressent — échoue quand même, car assigned_user_id manque aussi :

curl -sS -X PUT "https://app.initiative-crm.com/api/v1/contacts/1589" \
  -H "Authorization: Bearer itv_YOUR_TOKEN_HERE" -H "Content-Type: application/json" \
  -d '{"data":{"attributes":{"firstname":"Claire","lastname":"Moreau","email":"[email protected]"}}}'

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed.",
    "request_id": "ee1f7aa9-a3b3-4afd-b364-fd4206f42ed7",
    "details": [
      { "field": "assigned_user_id", "code": "REQUIRED", "message": "Field 'assigned_user_id' is required." }
    ]
  }
}

Contrairement à la création (étape 2), PUT ne définit jamais assigned_user_id par défaut à votre place — vous devez toujours l'envoyer explicitement. L'appel ne réussit qu'une fois que tous les champs obligatoires sont présents dans le corps :

curl -sS -X PUT "https://app.initiative-crm.com/api/v1/contacts/1589" \
  -H "Authorization: Bearer itv_YOUR_TOKEN_HERE" -H "Content-Type: application/json" \
  -d '{"data":{"attributes":{"lastname":"Moreau","assigned_user_id":"7206","email":"[email protected]"}}}' \
  | jq '.data.attributes | {firstname, lastname, email}'

{
  "firstname": "Claire",
  "lastname": "Moreau",
  "email": "[email protected]"
}

Remarquez que firstname — jamais présent dans aucun des trois corps PUT ci-dessus — vaut toujours "Claire". Malgré son nom, PUT ne réinitialise pas ici toute la ressource exactement à ce que vous avez envoyé ; il exige seulement que tous les champs obligatoires soient présents. Les champs optionnels que vous ne mentionnez pas conservent la valeur qu'ils avaient déjà, exactement comme avec PATCH. La seule vraie différence entre les deux verbes est ce contrôle de complétude de la validation.

Si vous voulez seulement modifier quelques champs, utilisez PATCH. PUT n'apporte rien de plus pour une modification partielle — il ajoute seulement une barre plus haute à franchir, et il n'efface toujours pas les champs que vous omettez ; ce n'est donc pas non plus un moyen de « réinitialiser » une fiche.

5. Lire un échec de validation

Une écriture peut échouer sur plusieurs champs à la fois. La réponse liste chaque champ en échec dans un unique tableau details[] — un seul aller-retour suffit pour tous les voir et les corriger :

curl -sS -X POST "https://app.initiative-crm.com/api/v1/contacts" \
  -H "Authorization: Bearer itv_YOUR_TOKEN_HERE" -H "Content-Type: application/json" \
  -d '{"data":{"attributes":{"email":"not-an-email"}}}'

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed.",
    "request_id": "a4c1c92a-1a11-45e5-8c33-4fb88abf93ed",
    "details": [
      { "field": "lastname", "code": "REQUIRED", "message": "Field 'lastname' is required." },
      { "field": "email", "code": "INVALID_FORMAT", "message": "Field 'email' must be a valid email address." }
    ]
  }
}

Les deux problèmes — le champ obligatoire manquant et celui envoyé mais mal formé — sont signalés ensemble, alors qu'ils n'ont aucun rapport entre eux. details[].code fait partie d'un ensemble fixe et transversal de codes ; certaines opérations peuvent aussi ajouter des codes spécifiques à l'endpoint, documentés sur ces opérations, mais ces sept codes couvrent toute écriture de fiche classique :

Ce ne sont pas toutes les valeurs trop longues qui déclenchent MAX_LENGTH de façon fiable dans l'implémentation actuelle — un simple champ string comme mailingstate se comporte comme documenté ci-dessus, mais au moins un champ de nom composite a été observé conservant silencieusement son ancienne valeur au lieu de générer une erreur sur une écriture trop longue. Vérifiez le champ précis que vous écrivez si MAX_LENGTH compte pour votre intégration.

6. Suppression

DELETE /api/v1/{module}/{id} est définitif — il n'y a pas d'annulation possible via l'API, ni d'endpoint de suppression douce/restauration :

curl -sS -X DELETE "https://app.initiative-crm.com/api/v1/contacts/1589" -H "Authorization: Bearer itv_YOUR_TOKEN_HERE" -w '%{http_code}\n'

204

Un GET sur le même identifiant juste après renvoie 404. Le supprimer à nouveau — la fiche a déjà disparu — renvoie aussi 404, pas un second 204 :

curl -sS -H "Authorization: Bearer itv_YOUR_TOKEN_HERE" "https://app.initiative-crm.com/api/v1/contacts/1589" -w '%{http_code}\n'
curl -sS -X DELETE "https://app.initiative-crm.com/api/v1/contacts/1589" -H "Authorization: Bearer itv_YOUR_TOKEN_HERE" -w '%{http_code}\n'

404
404

Si vous avez besoin qu'une fiche disparaisse des vues actives tout en restant récupérable, ne la supprimez pas via cette API — cet endpoint ne fait pas cette distinction.

7. Quand une fiche semble manquante

Un GET sur un identifiant qui n'a jamais existé renvoie la même chose qu'un GET sur un identifiant auquel vous n'avez tout simplement pas accès : 404 NOT_FOUND.

curl -sS -H "Authorization: Bearer itv_YOUR_TOKEN_HERE" "https://app.initiative-crm.com/api/v1/contacts/999999999" -w '\n%{http_code}\n'

{"error":{"code":"NOT_FOUND","message":"Record 999999999 not found in Contacts","request_id":"dfeb82e1-e5b0-4159-8fe4-04cd4ac56cac"}}
404

C'est délibéré : un 404 pour « n'existe pas » et un 404 pour « existe, mais n'est pas visible avec vos droits d'accès » sont volontairement indissociables, afin qu'un client ne puisse pas utiliser les codes de réponse pour sonder quels identifiants de fiches sont réels.

Erreurs courantes

• PUT avec un corps partiel. Chaque champ obligatoire défini par le module doit être présent, pas seulement le champ que vous modifiez — voir l'étape 4. Si vous voulez seulement modifier quelques champs, utilisez plutôt PATCH.
• Oublier l'enveloppe data.attributes. Un corps plat ({"lastname": "…"} au lieu de {"data":{"attributes":{"lastname": "…"}}}) n'est pas rejeté comme du JSON mal formé — le serveur le lit comme une charge utile vide, ce qui vous donne un 422 VALIDATION_ERROR pour les champs obligatoires, ce qui peut ressembler à un problème de champ alors que le vrai problème est l'enveloppe.
• Envoyer assigned_user_id sous la forme {"id": "…"} au lieu d'une simple chaîne. On pourrait s'attendre à ce que cela échoue, mais ce n'est pas le cas — l'API extrait ici .id d'un objet, de la même façon que pour les champs référence (voir Champs, formats et mise en forme des réponses). Cela fonctionne dans les deux cas ; envoyez quand même la simple chaîne, puisque c'est ce qui est documenté.
• Renvoyer un 422 sans le modifier. Le details[] de l'erreur nomme chaque champ en échec (étape 5) ; corrigez-les tous avant de renvoyer la requête, sinon vous obtiendrez la même erreur en retour.
• S'attendre à ce que la suppression soit réversible. DELETE est immédiat et définitif — il n'y a ni corbeille, ni annulation, ni restauration via cette API (étape 6).