Aller au contenu
Sursa Developers

GET/v1/cards

Lister les fiches

list_cards

Renvoie les fiches avec filtres, tri et pagination. Avec preview=1 (pour la vue en mosaïque), chaque fiche comporte aussi preview (les 200 premiers caractères du texte) et preview_tables (les feuilles avec leur nombre de lignes), dans les limites de votre profil de données.

Authentification

Envoyez une clé API dans l’en-tête Authorization : Authorization: Bearer <clé>.

Paramètres de requête

  • collectionstring | null
  • folderstring | null

    <folder ID> renvoie les fiches du dossier et de tous ses sous-dossiers. none renvoie les fiches de la collection qui ne sont dans aucun dossier et exige collection (sinon 400 cards.invalid_folder_filter). Si le dossier n’existe pas ou ne vous est pas visible, la requête renvoie 404 folders.not_found.

    length ≤ 64

  • statusstring | null

    Valeurs autorisées: processingreadyerrorarchivedall

  • ownerstring | null

    me, none ou un ID d’utilisateur.

  • owner_idinteger | null
  • verificationstring | null

    Valeurs autorisées: verifiedneeds_verificationstale

  • kindCardKind
  • typestring | null

    table renvoie les fiches avec des tables de faits, text les fiches sans table de faits.

    Valeurs autorisées: tabletext

  • tagsstring | null

    Étiquettes séparées par des virgules (une fiche doit les avoir toutes).

  • idsstring | null

    ID de fiches séparés par des virgules.

  • searchstring | null
  • categorystring | null
  • sensitiveboolean | null
  • sortCardSort

    Par défaut : "created_at"

  • orderstring

    Valeurs autorisées: ascdesc

    Par défaut : "desc"

  • limitinteger

    Par défaut : 200

  • offsetinteger

    Par défaut : 0

  • previewboolean

    true ajoute preview (les 200 premiers caractères) et preview_tables pour la vue en mosaïque.

    Par défaut : false

  • updated_sincestring (date-time)

    Uniquement les fiches dont updated_at est égal ou postérieur à ce moment (RFC 3339 avec décalage horaire), pour la synchronisation. Sans sort ni order explicites, la liste est triée par updated_at croissant, puis par id. Les fiches supprimées ne sont pas listées : les suppressions arrivent sous forme d’événements.

  • metadatamap of string

    Filtre par metadata : metadata[<key>]=<value> vérifie une correspondance exacte. Jusqu’à 3 conditions, qui doivent toutes être remplies (?metadata[team]=support&metadata[crm_id]=A-1042). Plus de 3 conditions ou une clé invalide renvoient 400 api.metadata_invalid.

  • collection_idinteger

    Collection par ID. Si collection est aussi transmis, collection_id l’emporte. Une collection qui n’existe pas dans l’organisation ou qui n’est pas visible renvoie 404 collections.not_found.

  • external_idstring

    Uniquement la fiche avec cet external_id.

  • cursorstring

    Curseur de la page suivante, tiré de X-Next-Cursor ou de next_cursor de la réponse précédente avec les mêmes filtres ; il porte la taille de page. Avec offset : 422 validation.failed ; curseur d’une autre liste, d’autres filtres ou mal formé : 400 api.cursor_invalid.

    length ≤ 512

  • expand[]array of string

    Objets liés à inclure dans la réponse (depuis la version 1.62.0) : un chemin de la liste x-expandable de l’opération. Répétez le paramètre jusqu’à 10 fois. Un chemin a au plus 2 segments séparés par un point (collection.default_owner). Dans une liste, le chemin commence par data. et s’applique à chaque élément de la page (expand[]=data.owner). Un objet développé va dans l’objet expanded de l’élément, et le champ d’ID reste en place. Un objet que l’appelant n’a pas le droit de voir selon les contrôles de sa propre opération de lecture est développé en null. Un chemin inconnu, plus de 10 chemins ou un chemin de plus de 2 segments renvoie 400 api.expand_invalid.

    items ≤ 10

Paramètres d’en-tête

  • X-View-Asstring

    Uniquement pour les clés API ayant le rôle admin. Exécute la requête avec le profil de données <profile>[:viewer|verifier|editor], par exemple employee:viewer. La clé d’installation ne peut pas utiliser cet en-tête (403).

Paramètres de cookie

  • kb_view_asstring

    Cookie du mode « View as » pour une session. POST /auth/view-as le définit et DELETE /auth/view-as le supprime.

Réponses

200Réponse réussie

En-têtes de la réponse

  • Link

    Adresse de la page suivante, <…>; rel="next". L’absence de cet en-tête signifie qu’il s’agit de la dernière page.

  • X-Next-Cursor

    Curseur de la page suivante pour le paramètre cursor. L’absence de cet en-tête signifie qu’il s’agit de la dernière page.

  • RateLimit-Policy

    Limites en vigueur, au format du brouillon IETF draft-ietf-httpapi-ratelimit-headers : éléments séparés par des virgules "<name>";q=<quota>;w=<window in seconds>. key est le débit de requêtes de la clé API (le quota est la rafale, la fenêtre est le temps nécessaire pour la reconstituer entièrement ; pour une session, c’est user, sans identifiants, ip) ; minute, day et month sont les quotas de l’organisation pour la minute, le jour et le mois calendaires en UTC.

  • RateLimit

    Ce qui reste de chaque limite de RateLimit-Policy : "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limite de l’entrée la plus stricte de RateLimit-Policy (celle à laquelle il reste le moins de requêtes).

  • X-RateLimit-Remaining

    Requêtes restantes au titre de la limite la plus stricte.

  • X-RateLimit-Reset

    Secondes restantes avant la réinitialisation de la limite la plus stricte.

application/json

Objet : CardList

array of Card
  • expandedCardExpanded
  • permissionsObjectPermissionList
  • accessstring

    Valeurs autorisées: wholepartial

  • access_contactstring

    Personne à contacter pour obtenir l’accès (uniquement si access=partial).

  • aclobject
    Champs
    • verifybooleanobligatoire
    • writebooleanobligatoire
  • categorystringobligatoire
  • category_confidencenumber | nullobligatoire
  • category_lockedbooleanobligatoire
  • category_reviewbooleanobligatoire
  • category_sourceCategorySource | nullobligatoire
  • collectionstringobligatoire
  • collection_idintegerobligatoire
  • collection_titlestring
  • commentsarray of CardComment
  • content_jsonContentJSON | null

    Contenu de l’éditeur de la dernière version publiée. Le champ peut être absent ; dans ce cas, obtenez le contenu de l’éditeur à partir d’un brouillon (POST /v1/drafts avec card_id).

  • editing_lockEditingLock | null

    Verrou de modification actif. Le champ peut être absent ; dans ce cas, l’éditeur apprend qui détient le verrou par la réponse 409 cards.locked de POST /v1/cards/{card_id}/lock.

  • created_atstring (date-time)obligatoire
  • days_since_verifiedintegerobligatoire
  • errorstring | nullobligatoire
  • eventsarray of CardEvent
  • feedback_negintegerobligatoire
  • feedback_posintegerobligatoire
  • foldersarray of CardFolderRef

    Liste des fiches uniquement : les dossiers qui contiennent la fiche (ceux que l’utilisateur voit), avec leurs chemins depuis la racine de la collection. Une liste vide signifie que la fiche n’est dans aucun dossier.

  • has_tablesboolean

    Liste des fiches uniquement.

  • hidden_partsboolean
  • idstringobligatoire
  • jobJob | null
  • kindCardKindobligatoire
  • org_idintegerobligatoire
  • owner_activeboolean | null
  • owner_idinteger | nullobligatoire
  • owner_namestring | nullobligatoire
  • pagesinteger | nullobligatoire
  • parserstring | nullobligatoire

    Analyseur du document sous forme de code neutre : document (structure complète : pages, titres, tableaux, pages numérisées), pdf (la couche texte du PDF), docx, xlsx, csv, markdown, html, text. La liste peut s’étendre.

  • partsarray of CardPartobligatoire
  • sensitivebooleanobligatoire
  • sha256string | nullobligatoire
  • sizeintegerobligatoire
  • snoozed_atstring (date-time) | null
  • snoozed_byinteger | null
  • snoozed_untilstring | null
  • source_changedbooleanobligatoire
  • source_pathstring | nullobligatoire
  • source_urlstring | nullobligatoire
  • statusstringobligatoire

    Valeurs autorisées: processingreadyerrorarchived

  • tablesarray of CardTable
  • tagsarray of stringobligatoire
  • titlestringobligatoire
  • trustnumberobligatoire
  • trust_if_verifiednumber
  • trust_partsTrustPartsobligatoire
  • updated_atstring (date-time)obligatoire
  • verificationVerificationobligatoire
  • verified_atstring (date-time) | nullobligatoire
  • verified_byinteger | nullobligatoire
  • verified_by_namestring | null
  • verifier_idsarray of integerobligatoire
  • verifiersarray of object
    Champs
    • activebooleanobligatoire
    • idintegerobligatoire
    • namestringobligatoire
  • verify_interval_daysintegerobligatoire
  • versionintegerobligatoire
  • versionsarray of CardVersion
  • source_archiveArchiveSource
  • created_byinteger | null
  • manual_optionsobject

    Paramètres d’analyse manuels (aperçu).

  • doc_kindDocKind | null

    Type de document. null si le type n’est pas déterminé (par exemple, pour les fiches indexées avant l’introduction des types de documents).

  • doc_kind_confidencenumber | null

    Degré de certitude quant au type de document, de 0 à 1.

  • doc_kind_sourcestring | null

    Ce qui a déterminé le type : des règles (rules), un utilisateur (manual) ou la classification automatique. La liste peut s’étendre : traitez une valeur inconnue comme une classification automatique.

    Valeurs autorisées: rulesmanualnull

  • invoiceDocInvoiceExtraction | null

    Champs d’une facture, d’un avoir ou d’un reçu (uniquement pour ces types, et uniquement dans la fiche, pas dans la liste). null si vous n’avez pas accès au document entier, car les champs sont extraits du document entier.

  • warningsarray of ReviewWarning

    Avertissements de l’analyse du document (ReviewWarning ; uniquement dans la fiche, pas dans la liste).

  • enrichmentCardEnrichmentStatus | null

    État de l’enrichissement (uniquement dans la fiche, pas dans la liste). Le type de document, les champs de facture et les entrées financières sont ajoutés en arrière-plan après l’indexation et peuvent être recalculés plus tard ; ils apparaissent dans la fiche quand ils sont prêts. null signifie qu’aucun état n’est disponible (la fiche a été indexée sans enrichissement en arrière-plan).

  • external_idstring | null

    ID de la fiche dans le système de l’intégrateur. Il est unique dans l’organisation parmi les fiches qui ne proviennent pas de sources ; null signifie qu’il n’est pas défini. /v1/cards-by-external-id/{external_id} lit et remplace la fiche par cet ID.

    length ≤ 512

  • metadataMetadata
400La requête est invalide : la valeur d’un paramètre ou l’état de l’objet ne permet pas l’action (`detail` est un message).

En-têtes de la réponse

  • RateLimit-Policy

    Limites en vigueur, au format du brouillon IETF draft-ietf-httpapi-ratelimit-headers : éléments séparés par des virgules "<name>";q=<quota>;w=<window in seconds>. key est le débit de requêtes de la clé API (le quota est la rafale, la fenêtre est le temps nécessaire pour la reconstituer entièrement ; pour une session, c’est user, sans identifiants, ip) ; minute, day et month sont les quotas de l’organisation pour la minute, le jour et le mois calendaires en UTC.

  • RateLimit

    Ce qui reste de chaque limite de RateLimit-Policy : "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limite de l’entrée la plus stricte de RateLimit-Policy (celle à laquelle il reste le moins de requêtes).

  • X-RateLimit-Remaining

    Requêtes restantes au titre de la limite la plus stricte.

  • X-RateLimit-Reset

    Secondes restantes avant la réinitialisation de la limite la plus stricte.

application/json

Objet : Error

401Aucun identifiant n’a été envoyé (ni cookie de session ni clé API), ou la clé est introuvable.

En-têtes de la réponse

  • RateLimit-Policy

    Limites en vigueur, au format du brouillon IETF draft-ietf-httpapi-ratelimit-headers : éléments séparés par des virgules "<name>";q=<quota>;w=<window in seconds>. key est le débit de requêtes de la clé API (le quota est la rafale, la fenêtre est le temps nécessaire pour la reconstituer entièrement ; pour une session, c’est user, sans identifiants, ip) ; minute, day et month sont les quotas de l’organisation pour la minute, le jour et le mois calendaires en UTC.

  • RateLimit

    Ce qui reste de chaque limite de RateLimit-Policy : "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limite de l’entrée la plus stricte de RateLimit-Policy (celle à laquelle il reste le moins de requêtes).

  • X-RateLimit-Remaining

    Requêtes restantes au titre de la limite la plus stricte.

  • X-RateLimit-Reset

    Secondes restantes avant la réinitialisation de la limite la plus stricte.

application/json

Objet : Error

403L’action n’est pas autorisée : le rôle est insuffisant, il n’y a pas d’accès à la collection ou à la fiche, la requête s’exécute en mode « View as », ou l’organisation est suspendue ou supprimée (`detail` est un objet avec `code: org_suspended | org_deleted`).

En-têtes de la réponse

  • RateLimit-Policy

    Limites en vigueur, au format du brouillon IETF draft-ietf-httpapi-ratelimit-headers : éléments séparés par des virgules "<name>";q=<quota>;w=<window in seconds>. key est le débit de requêtes de la clé API (le quota est la rafale, la fenêtre est le temps nécessaire pour la reconstituer entièrement ; pour une session, c’est user, sans identifiants, ip) ; minute, day et month sont les quotas de l’organisation pour la minute, le jour et le mois calendaires en UTC.

  • RateLimit

    Ce qui reste de chaque limite de RateLimit-Policy : "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limite de l’entrée la plus stricte de RateLimit-Policy (celle à laquelle il reste le moins de requêtes).

  • X-RateLimit-Remaining

    Requêtes restantes au titre de la limite la plus stricte.

  • X-RateLimit-Reset

    Secondes restantes avant la réinitialisation de la limite la plus stricte.

application/json

Objet : Error

404L’objet n’existe pas ou ne vous est pas accessible. L’API ne confirme pas l’existence d’un objet à accès restreint.

En-têtes de la réponse

  • RateLimit-Policy

    Limites en vigueur, au format du brouillon IETF draft-ietf-httpapi-ratelimit-headers : éléments séparés par des virgules "<name>";q=<quota>;w=<window in seconds>. key est le débit de requêtes de la clé API (le quota est la rafale, la fenêtre est le temps nécessaire pour la reconstituer entièrement ; pour une session, c’est user, sans identifiants, ip) ; minute, day et month sont les quotas de l’organisation pour la minute, le jour et le mois calendaires en UTC.

  • RateLimit

    Ce qui reste de chaque limite de RateLimit-Policy : "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limite de l’entrée la plus stricte de RateLimit-Policy (celle à laquelle il reste le moins de requêtes).

  • X-RateLimit-Remaining

    Requêtes restantes au titre de la limite la plus stricte.

  • X-RateLimit-Reset

    Secondes restantes avant la réinitialisation de la limite la plus stricte.

application/json

Objet : Error

422Erreur de validation : le corps ou les paramètres ne correspondent pas au schéma (`detail` est une liste d’erreurs de validation), ou la valeur d’un paramètre est hors des limites admises (`detail` est un message).

En-têtes de la réponse

  • RateLimit-Policy

    Limites en vigueur, au format du brouillon IETF draft-ietf-httpapi-ratelimit-headers : éléments séparés par des virgules "<name>";q=<quota>;w=<window in seconds>. key est le débit de requêtes de la clé API (le quota est la rafale, la fenêtre est le temps nécessaire pour la reconstituer entièrement ; pour une session, c’est user, sans identifiants, ip) ; minute, day et month sont les quotas de l’organisation pour la minute, le jour et le mois calendaires en UTC.

  • RateLimit

    Ce qui reste de chaque limite de RateLimit-Policy : "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limite de l’entrée la plus stricte de RateLimit-Policy (celle à laquelle il reste le moins de requêtes).

  • X-RateLimit-Remaining

    Requêtes restantes au titre de la limite la plus stricte.

  • X-RateLimit-Reset

    Secondes restantes avant la réinitialisation de la limite la plus stricte.

application/json

Objet : Error

429Trop de requêtes (`api.rate_limited`), quota de l’organisation pour la minute, le jour ou le mois épuisé (`api.quota_exceeded` ; `error.details` contient `quota`, `limit` et `reset_at`), limite de l’organisation atteinte, ou service de réponses occupé (`answers.engine_busy`). Attendez le délai indiqué dans l’en-tête `Retry-After`.

En-têtes de la réponse

  • Retry-After

    Nombre de secondes à attendre avant de réessayer la requête.

  • RateLimit-Policy

    Limites en vigueur, au format du brouillon IETF draft-ietf-httpapi-ratelimit-headers : éléments séparés par des virgules "<name>";q=<quota>;w=<window in seconds>. key est le débit de requêtes de la clé API (le quota est la rafale, la fenêtre est le temps nécessaire pour la reconstituer entièrement ; pour une session, c’est user, sans identifiants, ip) ; minute, day et month sont les quotas de l’organisation pour la minute, le jour et le mois calendaires en UTC.

  • RateLimit

    Ce qui reste de chaque limite de RateLimit-Policy : "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limite de l’entrée la plus stricte de RateLimit-Policy (celle à laquelle il reste le moins de requêtes).

  • X-RateLimit-Remaining

    Requêtes restantes au titre de la limite la plus stricte.

  • X-RateLimit-Reset

    Secondes restantes avant la réinitialisation de la limite la plus stricte.

application/json

Objet : Error

Codes d’erreur

Codes que ce point de terminaison peut renvoyer dans error.code, en plus des codes généraux communs à toutes les requêtes.

Limites de débit

Les réponses portent les en-têtes RateLimit et RateLimit-Policy, ainsi que les anciens X-RateLimit-Limit, X-RateLimit-Remaining et X-RateLimit-Reset. Une réponse 429 contient Retry-After en secondes : attendez, puis réessayez.

← cards · Référence de l’API