Lire des listes

Filtrer, trier et paginer la liste d'un type de fiche, et n'en lire que les propriétés utiles.

5 min de lecture Mise à jour le 11 novembre 2026

Chaque type de fiche a sa liste, à l'adresse du type : https://staging-api.docage.com/Contacts, https://staging-api.docage.com/Companies, https://staging-api.docage.com/Transactions… Elle rend les fiches que l'utilisateur a le droit de voir, et ses réglages voyagent dans le corps de la requête. Elle se lit par la méthode QUERY (RFC 10008), faite pour une lecture qui porte un corps :

QUERY https://staging-api.docage.com/Contacts
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9…
Content-Type: application/json

{
  "Filter": {
    "OperatorType": "And",
    "Operands": [
      { "PropertyName": "City", "Comparison": "=", "Value": "Lyon" },
      { "PropertyName": "LastName", "Comparison": "startswith", "Value": "Mar" }
    ]
  },
  "SortOrder": "LastName;CreationDate_Desc",
  "Skip": 0,
  "Take": 50,
  "EntityProperties": ["Id", "FirstName", "LastName", "Email", "City"]
}

curl -X QUERY "https://staging-api.docage.com/Contacts" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "Content-Type: application/json" \
  -d '{
    "Filter": {"OperatorType": "And", "Operands": [{"PropertyName": "City", "Comparison": "=", "Value": "Lyon"}, {"PropertyName": "LastName", "Comparison": "startswith", "Value": "Mar"}]},
    "SortOrder": "LastName;CreationDate_Desc",
    "Skip": 0,
    "Take": 50,
    "EntityProperties": ["Id", "FirstName", "LastName", "Email", "City"]
  }'

using HttpClient client = new();
using HttpRequestMessage request = new(new HttpMethod("QUERY"), "https://staging-api.docage.com/Contacts");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);
request.Content = new StringContent("""
    {
      "Filter": {
        "OperatorType": "And",
        "Operands": [
          {
            "PropertyName": "City",
            "Comparison": "=",
            "Value": "Lyon"
          },
          {
            "PropertyName": "LastName",
            "Comparison": "startswith",
            "Value": "Mar"
          }
        ]
      },
      "SortOrder": "LastName;CreationDate_Desc",
      "Skip": 0,
      "Take": 50,
      "EntityProperties": [
        "Id",
        "FirstName",
        "LastName",
        "Email",
        "City"
      ]
    }
    """, Encoding.UTF8, "application/json");
using HttpResponseMessage response = await client.SendAsync(request);
string result = await response.Content.ReadAsStringAsync();
if (!response.IsSuccessStatusCode)
    throw new HttpRequestException(result);

const response = await fetch("https://staging-api.docage.com/Contacts", {
  method: "QUERY",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "Filter": {"OperatorType": "And", "Operands": [{"PropertyName": "City", "Comparison": "=", "Value": "Lyon"}, {"PropertyName": "LastName", "Comparison": "startswith", "Value": "Mar"}]},
    "SortOrder": "LastName;CreationDate_Desc",
    "Skip": 0,
    "Take": 50,
    "EntityProperties": ["Id", "FirstName", "LastName", "Email", "City"]
  })
});
const text = await response.text();
if (!response.ok) throw new Error(text);
const result = text ? JSON.parse(text) : null;

La réponse est un tableau de fiches. L'en-tête Docage-TotalItems donne le nombre de fiches que le filtre retient en tout : de quoi savoir combien de pages lire.

La même lecture se fait aussi par GET https://staging-api.docage.com/Contacts, avec le même corps : c'est la forme d'origine, toujours servie. Chaque lecture à corps de l'API répond ainsi aux deux méthodes, et la référence les montre toutes deux ; sa console d'essai envoie le corps de la seule opération QUERY.

Attention

Le corps d'un GET n'est pas transmis par tous les clients HTTP : le fetch d'un navigateur le refuse, et la console d'essai de la référence ne le propose pas. Sans corps, ni filtre ni pagination : la liste rend tout ce que l'utilisateur voit. Préférez QUERY, et donnez toujours Take.

Paginer

Skip est le nombre de fiches à passer, Take le nombre de fiches à rendre. Take à 0, ou absent, rend la liste entière. Pour lire une liste longue, avancez de page en page (Skip = 0, 50, 100…) jusqu'à atteindre le total de Docage-TotalItems.

Trier

SortOrder nomme une ou plusieurs propriétés, séparées par des points-virgules ; _Desc après un nom trie en ordre décroissant (LastName;CreationDate_Desc). Une propriété inconnue est ignorée.

Filtrer

Un filtre simple compare une propriété à une valeur :

JSON

{ "PropertyName": "Email", "Comparison": "contains", "Value": "@example.com" }

Comparison : = (d'office), <>, <, <=, >, >=, et pour un texte contains, notcontains, startswith, endswith.
Un filtre composé réunit d'autres filtres dans Operands, par OperatorType : And (tous), Or (l'un d'eux) ou Not (la négation).
Un champ personnalisé se désigne par CustomFields. suivi de son nom technique (CustomFields.NumeroAdherent) — voir Champs personnalisés.

Une date se compare à un instant : écrivez-la en ISO 8601 avec son fuseau, un Z ou un décalage. L'API la ramène en UTC avant de comparer — 2026-11-10T10:00:00+02:00 vaut 08:00 UTC — et lit en UTC une date sans fuseau (voir Dates et fuseaux). Pour une période, réunissez >= sur son début et < sur sa fin :

JSON

{
  "OperatorType": "And",
  "Operands": [
    { "PropertyName": "CreationDate", "Comparison": ">=", "Value": "2026-11-01T00:00:00+01:00" },
    { "PropertyName": "CreationDate", "Comparison": "<", "Value": "2026-12-01T00:00:00+01:00" }
  ]
}

between existe aussi, ses deux bornes dans un tableau ("Value": ["…", "…"]), toutes deux comprises. Un champ personnalisé de type date se compare comme il est rangé : le jour seul (2026-11-10), ou un instant UTC suffixé d'un Z (2026-11-10T08:00:00Z), sans décalage.

Un filtre ne s'élargit jamais : un critère qui ne se lit pas — une propriété inconnue, une valeur d'un autre type — ne retient aucune fiche, au lieu d'être ignoré. Une liste vide inattendue se relit donc d'abord critère par critère.

N'en lire que l'utile

EntityProperties restreint les propriétés rendues à celles que vous nommez, par leur nom exact (LastName, pas lastname) ; la notation pointée lit une fiche liée (Template.Name). L'identifiant et ce que l'API calcule pour vous, comme votre niveau de droit sur la fiche (RightLevel), partent toujours. Une liste longue se lit bien plus vite ainsi.

Pour peupler un sélecteur, QUERY https://staging-api.docage.com/Contacts/EntitiesIdAndName rend seulement l'identifiant et le nom de chaque fiche ; il accepte le même corps (le filtre, le tri et la pagination), sans EntityProperties.

Lire la corbeille

VisibleState choisit l'état des fiches rendues : -2 (ou "Deleted") pour la corbeille, -3 (ou "Blocked") pour les organisations et les utilisateurs bloqués. Vide, ou toute autre valeur, la liste rend les fiches actives. Un seul état à la fois, et seulement les fiches que vous voyez :

QUERY https://staging-api.docage.com/Contacts
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9…
Content-Type: application/json

{ "VisibleState": -2, "SortOrder": "DeletionDate_Desc", "Take": 50 }

curl -X QUERY "https://staging-api.docage.com/Contacts" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "Content-Type: application/json" \
  -d '{
    "VisibleState": -2,
    "SortOrder": "DeletionDate_Desc",
    "Take": 50
  }'

using HttpClient client = new();
using HttpRequestMessage request = new(new HttpMethod("QUERY"), "https://staging-api.docage.com/Contacts");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);
request.Content = new StringContent("""
    {
      "VisibleState": -2,
      "SortOrder": "DeletionDate_Desc",
      "Take": 50
    }
    """, Encoding.UTF8, "application/json");
using HttpResponseMessage response = await client.SendAsync(request);
string result = await response.Content.ReadAsStringAsync();
if (!response.IsSuccessStatusCode)
    throw new HttpRequestException(result);

const response = await fetch("https://staging-api.docage.com/Contacts", {
  method: "QUERY",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "VisibleState": -2,
    "SortOrder": "DeletionDate_Desc",
    "Take": 50
  })
});
const text = await response.text();
if (!response.ok) throw new Error(text);
const result = text ? JSON.parse(text) : null;

Chaque fiche de la corbeille porte la date de sa mise à la corbeille (DeletionDate) et l'identifiant de l'utilisateur qui l'y a mise (DeletionUserId). Pour la restaurer ou la supprimer définitivement, voir Mettre un contact à la corbeille et le restaurer.

Les autres réglages

OrganizationId : les seules fiches d'une organisation — voir Organisations et intégrateurs.
IsTemplate : true pour lister les modèles du type plutôt que ses fiches — voir Modèles et instances.
BoxId : les seules fiches rangées dans un classeur, modèles rangés compris. Un classeur introuvable ou que vous ne voyez pas, ou un type de fiche qui ne se range pas dans un classeur, rend une liste vide — voir Ranger des fiches dans un classeur.
ContactId : les fiches d'un contact — les cartes dont il est l'interlocuteur principal, les événements et les réservations qui le désignent. PipelineItemId : les fiches d'une carte — ses parcours, ses événements et ses réservations. Sur un autre type de fiche, ces deux réglages sont sans effet et la liste reste entière : passez par LinkedToTypeName et LinkedToId.
LinkedToTypeName et LinkedToId : les fiches liées à une fiche donnée, par toutes ses liaisons (un contact et ses parcours, ses cartes, ses conversations…).