Documentation de l'API

Envoyez un PDF, un document Word ou une image, recevez du JSON structuré.

Introduction

Vous décrivez les données souhaitées sous forme de catégorie : une liste de champs, comme le numéro de facture, la date ou les lignes de facture, définie dans le tableau de bord. Parsevix lit le document, remplit ces champs et les renvoie en JSON, avec le texte lu et l'emplacement où chaque valeur a été trouvée.

L'API est servie en HTTPS depuis une URL de base unique. Les requêtes et les réponses sont en JSON, sauf les imports de fichiers, en multipart/form-data.

https://parsevix.com/api/v1

Chaque clé API appartient à un projet. Une clé ne voit et ne modifie que les documents, catégories et webhooks de ce projet.

En plus d'appeler l'API, vous pouvez recevoir les résultats via des webhooks, connecter Zapier ou envoyer des documents à l'adresse e-mail d'un projet.

Conventions

Les réponses de l'API utilisent des noms de champs en camelCase. Les corps des webhooks et des callbacks utilisent le snake_case.
Les horodatages sont en UTC, au format ISO 8601 (2026-10-25T10:12:06.791Z).
Les messages d'erreur sont en anglais, allemand, turc, français, espagnol, italien, néerlandais, polonais ou portugais, selon l'en-tête Accept-Language.

Démarrage rapide

1
Créer une clé API
Dans le tableau de bord, ouvrez votre projet, allez dans Clés API et créez une clé. Elle n'est affichée qu'une fois ; conservez-la, par exemple dans la variable d'environnement PARSEVIX_API_KEY. Le forfait Free inclut une clé, les forfaits payants davantage (voir Limites et crédits).
2
Définir une catégorie
Sous Catégories, créez une catégorie pour votre type de document et ajoutez les champs nécessaires, ou partez d'un modèle intégré. Les exemples de cette page utilisent une catégorie nommée Supplier invoice.
3
Envoyer un document
POST /extract envoie le fichier et attend le résultat. La réponse contient les champs remplis sous extracted.

Pour traiter de nombreux documents sans garder de requêtes ouvertes, envoyez-les de manière asynchrone et recevez les résultats via des webhooks.

curl https://parsevix.com/api/v1/extract \
  -H "X-API-Key: $PARSEVIX_API_KEY" \
  -F file=@invoice.pdf \
  -F category="Supplier invoice"

Réponse200· abrégé

{
  "id": "01a1728b-cc26-7ba9-ad3c-dcf5e6d8e581",
  "fileName": "invoice.pdf",
  "status": "Completed",
  "category": "Supplier invoice",
  "processingMode": "specific",
  "confidenceScore": 0.97,
  "pageCount": 1,
  "language": "en",
  "retained": false,
  "extracted": {
    "invoice_number": "F-2026-88343",
    "invoice_date": "2026-10-03",
    "due_date": "2026-10-17",
    "currency": "GBP",
    "seller": {
      "name": "Northgate Systems Ltd",
      "vat_id": "GB566163740"
    },
    "line_items": [
      {
        "description": "LED panel light",
        "quantity": 4,
        "unit_price": 542.55,
        "total": 2170.2
      },
      {
        "description": "Office chair",
        "quantity": 1,
        "unit_price": 475.86,
        "total": 475.86
      }
    ],
    "gross_total": 7848.88,
    "_field_blocks": {
      "invoice_number": [
        {
          "page": 1,
          "x": 35.04,
          "y": 378.24,
          "width": 159.84,
          "height": 11.04,
          "text": "Invoice number: F-2026-88343"
        }
      ],
      "seller.name": [
        {
          "page": 1,
          "x": 34.08,
          "y": 558.24,
          "width": 120.48,
          "height": 12.96,
          "text": "Northgate Systems Ltd"
        }
      ]
    }
  }
}

Tutoriels vidéo

Cinq courtes vidéos montrent les étapes principales du tableau de bord et votre première requête API. Chacune a une voix off et des sous-titres en neuf langues : choisissez-les sous l'icône d'engrenage du lecteur.

Les vidéos sont lues depuis YouTube (youtube-nocookie.com). Rien n'est chargé depuis YouTube tant que vous ne cliquez pas sur lecture ; Google reçoit alors votre adresse IP et peut enregistrer des cookies. Voir notre Politique de confidentialité.

Authentification

Envoyez votre clé API dans l'en-tête X-API-Key avec chaque requête.

X-API-Key: psvx_…

Une clé ne fonctionne que sur /api/v1 ; elle ne permet pas de se connecter au tableau de bord. Les clés sont créées et révoquées sous Clés API dans le projet. Une clé révoquée cesse immédiatement de fonctionner.

Gardez les clés sur votre serveur. Quiconque possède une clé peut envoyer des documents et lire les résultats du projet, et ces imports consomment vos crédits.

Quand une clé est refusée

Statut	Code	Signification
401	`apikey.missing`	Aucun en-tête `X-API-Key` n'a été envoyé.
401	`apikey.invalid`	La clé n'existe pas ou a été révoquée.
403	`apikey.plan_disabled`	Le forfait du compte n'inclut pas l'accès à l'API.
403	`apikey.paused_by_plan`	La clé ou son projet est en pause, car le forfait du compte autorise moins de clés ou de projets.
403	`apikey.account_unavailable`	Le compte est fermé ou sa suppression est programmée.
403	`apikey.project_unavailable`	Le projet de la clé a été supprimé.
429	`apikey.too_many_invalid`	Plus de 30 clés invalides sont venues de votre réseau en 10 minutes. Attendez `Retry-After` secondes ; une clé qui a fonctionné récemment n'est pas bloquée.

Réponse401

{
  "error": {
    "code": "apikey.invalid",
    "message": "The API key is not valid. It may have been revoked; create a new one in the project under API Keys."
  }
}

Modes de traitement

Chaque import est lu de l'une des quatre manières suivantes.

Catégorie automatique (auto-classify). Parsevix choisit la catégorie du projet la plus adaptée, puis en extrait les champs. Utilisé lorsque vous n'envoyez aucune catégorie, ou category=auto.
Classification seule (classify-only). Parsevix choisit la catégorie la plus adaptée sans rien extraire, pour trier les documents par type. Il lit les 3 premières pages et coûte 1 crédit par document. Les champs peuvent être extraits plus tard. Voir Classer un document.
Catégorie précise (specific). Vous nommez la catégorie ; ses champs sont extraits.
Sans schéma (auto-entity). Aucune catégorie n'est utilisée. Parsevix renvoie les champs qu'il trouve, nommés d'après les libellés du document lui-même. Voir Extraire sans schéma.

La langue du document est détectée automatiquement. Le paramètre facultatif language ne sert que de solution de repli pour les documents contenant trop peu de texte pour la détection.

Extraire un document

POST/api/v1/extract

Envoie un document et attend la fin de son traitement. La réponse contient les champs extraits.

filefileobligatoire: Le document : PDF, DOCX, PNG, JPEG ou TIFF, jusqu'à 10 Mo et 30 pages.
categorystringfacultatif: Nom d'une catégorie du projet. Omettez-le, ou envoyez auto, pour laisser Parsevix choisir.
languagestringfacultatif: Code ISO 639-1 à deux lettres, comme de. Utilisé uniquement si la langue ne peut pas être détectée.

Attente et limites

La requête reste ouverte jusqu'à ce que le résultat soit prêt, 285 secondes au maximum. Réglez le délai d'expiration de votre client HTTP au-delà.
Si le traitement dure plus longtemps, vous recevez 504 avec document.sync_timeout et le documentId. Le traitement continue ; le résultat est envoyé à vos webhooks.
Si le traitement échoue, vous recevez 422 avec document.sync_failed. reason en indique la cause ; voir motifs d'échec.
Chaque clé API peut avoir 5 requêtes ouvertes en même temps. Au-delà, la réponse est 429 avec document.sync_concurrency_limit. Une requête que vous fermez, ou qui expire, garde sa place jusqu'à ce que son document soit traité. Pour les imports en masse, utilisez l'import asynchrone.

Réponse

idstring: Identifiant du document.
fileNamestring: Le nom du fichier envoyé.
statusstring: Completed.
categorystring | null: La catégorie utilisée ; null sans schéma.
processingModestring: auto-classify, specific ou auto-entity.
confidenceScorenumber: Entre 0 et 1 : le degré de certitude de l'extraction.
pageCountinteger: Pages traitées ; chacune coûte un crédit.
languagestring: Langue détectée, ISO 639-1.
retainedboolean: Indique si Parsevix conserve le fichier et le résultat. Voir Conservation des données.
extractedobject: Les champs extraits. Voir Le résultat.

curl https://parsevix.com/api/v1/extract \
  -H "X-API-Key: $PARSEVIX_API_KEY" \
  -F file=@invoice.pdf \
  -F category="Supplier invoice"

Réponse200· abrégé

{
  "id": "01a1728b-cc26-7ba9-ad3c-dcf5e6d8e581",
  "fileName": "invoice.pdf",
  "status": "Completed",
  "category": "Supplier invoice",
  "processingMode": "specific",
  "confidenceScore": 0.97,
  "pageCount": 1,
  "language": "en",
  "retained": false,
  "extracted": {
    "invoice_number": "F-2026-88343",
    "invoice_date": "2026-10-03",
    "due_date": "2026-10-17",
    "currency": "GBP",
    "seller": {
      "name": "Northgate Systems Ltd",
      "vat_id": "GB566163740"
    },
    "line_items": [
      {
        "description": "LED panel light",
        "quantity": 4,
        "unit_price": 542.55,
        "total": 2170.2
      },
      {
        "description": "Office chair",
        "quantity": 1,
        "unit_price": 475.86,
        "total": 475.86
      }
    ],
    "gross_total": 7848.88,
    "_field_blocks": {
      "invoice_number": [
        {
          "page": 1,
          "x": 35.04,
          "y": 378.24,
          "width": 159.84,
          "height": 11.04,
          "text": "Invoice number: F-2026-88343"
        }
      ],
      "seller.name": [
        {
          "page": 1,
          "x": 34.08,
          "y": 558.24,
          "width": 120.48,
          "height": 12.96,
          "text": "Northgate Systems Ltd"
        }
      ]
    }
  }
}

Réponse422

{
  "error": {
    "code": "document.sync_failed",
    "message": "The file is damaged or is not a valid PDF, Word document or image.",
    "reason": "file_unreadable",
    "documentId": "01a1728b-cc26-7ba9-ad3c-dcf5e6d8e581"
  }
}

Réponse504

{
  "error": {
    "code": "document.sync_timeout",
    "message": "Extraction did not finish within 285 seconds. Large documents may need to be split.",
    "documentId": "01a1728b-cc26-7ba9-ad3c-dcf5e6d8e581"
  }
}

Extraire sans schéma

POST/api/v1/extract-auto

Comme POST /extract, mais sans catégorie : Parsevix renvoie tous les champs qu'il trouve dans le document.

filefileobligatoire: Le document : PDF, DOCX, PNG, JPEG ou TIFF, jusqu'à 10 Mo et 30 pages.
languagestringfacultatif: Code ISO 639-1 à deux lettres. Utilisé uniquement si la langue ne peut pas être détectée.

La sortie reste dans la langue du document. Les clés sont les libellés du document lui-même en snake_case (une facture en allemand donne rechnungsnummer), et les valeurs sont reprises telles qu'imprimées : les dates au format du document, les montants sous forme de chaînes comme "2.430,09".

Utilisez-le pour explorer un nouveau type de document. Pour les données que vous traitez automatiquement, une catégorie vous donne des clés fixes et des valeurs normalisées.

La réponse contient les mêmes champs que POST /extract, avec processingMode auto-entity et category null.

curl https://parsevix.com/api/v1/extract-auto \
  -H "X-API-Key: $PARSEVIX_API_KEY" \
  -F file=@invoice.pdf

Classer un document

POST/api/v1/classify

Envoie un document et attend que Parsevix ait choisi l'une des catégories du projet. Aucun champ n'est extrait. Utilisez-le pour trier ou acheminer les documents par type.

Les candidates sont les catégories propres au projet, pas les modèles intégrés. Parsevix lit les 3 premières pages : une classification coûte donc 1 crédit, quelle que soit la longueur du document.

filefileobligatoire: Le document : PDF, DOCX, PNG, JPEG ou TIFF, jusqu'à 10 Mo et 30 pages.
languagestringfacultatif: Code ISO 639-1 à deux lettres. Utilisé uniquement si la langue ne peut pas être détectée.

L'attente et les erreurs fonctionnent comme pour POST /extract : 285 secondes au maximum, 504 avec document.sync_timeout si cela dure plus longtemps, 422 avec document.sync_failed si le document ne peut pas être traité. Les 5 requêtes ouvertes par clé sont partagées entre les deux endpoints.

Réponse

idstring: Identifiant du document.
fileNamestring: Le nom du fichier envoyé.
statusstring: Completed.
categorystring: La catégorie choisie par Parsevix.
processingModestring: classify-only.
pageCountinteger: Nombre de pages du document. Les 3 premières ont été lues.
languagestring: Langue détectée, ISO 639-1.
retainedboolean: Indique si Parsevix conserve le fichier. Seul un document conservé peut être extrait plus tard.

Extraire plus tard

POST /documents/{id}/extract extrait les champs du document, selon la catégorie qui lui a été attribuée ou celle que vous indiquez. Cela coûte le nombre de pages du document moins le crédit déjà payé : un document de 5 pages coûte 4 crédits de plus, 5 au total.

Le fichier est nécessaire : le projet doit donc conserver les imports API (voir Conservation des données). Les documents importés depuis le tableau de bord ou reçus par e-mail sont toujours conservés. Les imports asynchrones peuvent aussi être classés : processingMode=classify-only sur POST /documents.

curl https://parsevix.com/api/v1/classify \
  -H "X-API-Key: $PARSEVIX_API_KEY" \
  -F file=@invoice.pdf

Réponse200

{
  "id": "01a172b4-5d2e-7c61-8f0a-3b9d6e1c4a27",
  "fileName": "invoice.pdf",
  "status": "Completed",
  "category": "Supplier invoice",
  "processingMode": "classify-only",
  "pageCount": 1,
  "language": "en",
  "retained": true
}

Import asynchrone

POST/api/v1/documents

Met un document en file d'attente et répond immédiatement avec 202 et la fiche du document. Utilisez-le pour les imports en masse et pour les clients qui ne peuvent pas garder une requête ouverte, comme Zapier.

filefileobligatoire: Le document : PDF, DOCX, PNG, JPEG ou TIFF, jusqu'à 10 Mo et 30 pages.
categorystringfacultatif: Nom d'une catégorie. Omettez-le, ou envoyez auto, pour laisser Parsevix choisir.
processingModestringfacultatif: auto-classify, specific, auto-entity ou classify-only. Facultatif : par défaut, il découle de category. classify-only ne peut pas être combiné avec une catégorie.
languagestringfacultatif: Code ISO 639-1 à deux lettres. Utilisé uniquement si la langue ne peut pas être détectée.
callbackUrlstringfacultatif: Une URL https publique. Parsevix y envoie le résultat une fois, sous forme de POST avec le même corps qu'un événement webhook.

Obtenir le résultat

Les webhooks du projet reçoivent extraction.completed ou extraction.failed. Un import classify-only envoie classification.completed au lieu de extraction.completed.
callbackUrl, si elle est indiquée, reçoit le même événement, avec les mêmes nouvelles tentatives. Il n'est pas signé : placez un jeton secret dans l'URL et vérifiez-le.
L'interrogation de GET /documents/{id} indique le statut, et le résultat uniquement si le projet conserve les imports API (voir Conservation des données).

curl https://parsevix.com/api/v1/documents \
  -H "X-API-Key: $PARSEVIX_API_KEY" \
  -F file=@invoice.pdf \
  -F category="Supplier invoice" \
  -F callbackUrl="https://example.com/parsevix/callback?token=a-secret-only-you-know"

Réponse202

{
  "id": "01a1728b-cc26-7ba9-ad3c-dcf5e6d8e581",
  "status": "Pending",
  "categoryName": "Supplier invoice",
  "processingMode": "specific",
  "fileName": "invoice.pdf",
  "fileSize": 22579,
  "source": "api",
  "discardFiles": true,
  "createdAt": "2026-10-25T10:12:06.791Z",
  "completedAt": null,
  "reprocessCount": 0,
  "lastReprocessedAt": null,
  "approvalStatus": "Unapproved",
  "isTrainingExample": false
}

Le résultat

extracted

Un objet dont les clés sont les noms de champs de la catégorie (fieldName dans le schéma de catégorie). Les objets et les listes suivent le schéma.

Les dates sont au format YYYY-MM-DD. Les nombres sont des nombres JSON, sans symbole monétaire ni séparateur de milliers. Un champ absent du document est omis ou vaut null.

Les données personnelles, comme les noms et les IBAN, sont renvoyées telles qu'écrites dans le document. Elles ne sont masquées que sur le chemin vers le modèle d'IA et restaurées avant de vous parvenir.

_field_blocks

L'emplacement où chaque valeur a été trouvée. Les clés sont des chemins de champs comme seller.name ou line_items[0].total ; chaque entrée liste les lignes de texte avec la page, le cadre et le texte. Une valeur qui n'a pas pu être localisée en est absente. Ignorez les clés commençant par _ si vous n'avez besoin que des données.

Coordonnées

PDF et DOCX : points PDF (1/72 de pouce). L'origine est le coin inférieur gauche de la page ; y est le bord supérieur du cadre, mesuré depuis le bas.
Images : pixels. L'origine est le coin supérieur gauche ; y est le bord supérieur, mesuré depuis le haut.

extracted200· abrégé

{
  "id": "01a1728b-cc26-7ba9-ad3c-dcf5e6d8e581",
  "fileName": "invoice.pdf",
  "status": "Completed",
  "category": "Supplier invoice",
  "processingMode": "specific",
  "confidenceScore": 0.97,
  "pageCount": 1,
  "language": "en",
  "retained": false,
  "extracted": {
    "invoice_number": "F-2026-88343",
    "invoice_date": "2026-10-03",
    "due_date": "2026-10-17",
    "currency": "GBP",
    "seller": {
      "name": "Northgate Systems Ltd",
      "vat_id": "GB566163740"
    },
    "line_items": [
      {
        "description": "LED panel light",
        "quantity": 4,
        "unit_price": 542.55,
        "total": 2170.2
      },
      {
        "description": "Office chair",
        "quantity": 1,
        "unit_price": 475.86,
        "total": 475.86
      }
    ],
    "gross_total": 7848.88,
    "_field_blocks": {
      "invoice_number": [
        {
          "page": 1,
          "x": 35.04,
          "y": 378.24,
          "width": 159.84,
          "height": 11.04,
          "text": "Invoice number: F-2026-88343"
        }
      ],
      "seller.name": [
        {
          "page": 1,
          "x": 34.08,
          "y": 558.24,
          "width": 120.48,
          "height": 12.96,
          "text": "Northgate Systems Ltd"
        }
      ]
    }
  }
}

Documents

Les documents du projet, de toutes les sources : le tableau de bord, l'API et l'e-mail.

Lister les documents

GET/api/v1/documents

Les plus récents en premier. Seuls les documents stockés sont listés : les imports API n'apparaissent que si le projet les conserve.

pageintegerfacultatif: Numéro de page, à partir de 1.
pageSizeintegerfacultatif: De 1 à 100 ; 20 par défaut.
statusstringfacultatif: Pending, Processing, Completed ou Failed.
categorystringfacultatif: Nom de la catégorie.
searchstringfacultatif: Partie du nom de fichier.
fileTypestringfacultatif: pdf, docx ou image.
sourcestringfacultatif: dashboard, api ou email.
processingModestringfacultatif: auto-classify, specific, auto-entity ou classify-only.

Obtenir un document

GET/api/v1/documents/{id}

Le document avec son résultat. outputDeanonymized contient les données extraites, le même objet que extracted. Un document classify-only a sa catégorie dans categoryName et pas de outputDeanonymized. Un document en échec a errorCode et errorMessage. Si le projet ne conserve pas les imports API, le statut est disponible, mais pas le résultat.

Retraiter un document

POST/api/v1/documents/{id}/reprocess

Relance l'extraction, par exemple après une modification des champs de la catégorie. Corps JSON facultatif : category (un nom, ou auto) et processingMode. Répond 202 ; le résultat arrive comme pour un import asynchrone. Les crédits sont de nouveau débités. Un document classify-only est de nouveau classé (1 crédit), sauf si vous indiquez une catégorie. Impossible pour les imports API dont les fichiers n'ont pas été conservés (document.files_not_retained).

Extraire un document classé

POST/api/v1/documents/{id}/extract

Pour un document envoyé avec classify-only : extrait ses champs selon la catégorie qui lui a été attribuée, ou selon la category indiquée dans le corps JSON facultatif. Coûte le nombre de pages du document moins le crédit payé pour la classification. Répond 202 ; le résultat arrive comme pour un import asynchrone, sous forme d'extraction.completed. Pour tout autre document, la réponse est 400 avec document.not_classify_only ; utilisez plutôt le retraitement.

Supprimer un document

DELETE/api/v1/documents/{id}

Supprime le document, son fichier et ses résultats. Répond 204.

Un identifiant qui n'existe pas dans le projet de la clé renvoie 404 avec document.not_found.

cURL

curl "https://parsevix.com/api/v1/documents?status=Completed&pageSize=20" \
  -H "X-API-Key: $PARSEVIX_API_KEY"

Réponse200· abrégé

{
  "data": [
    {
      "id": "01a1728b-cc26-7ba9-ad3c-dcf5e6d8e581",
      "status": "Completed",
      "categoryName": "Supplier invoice",
      "processingMode": "specific",
      "fileName": "invoice.pdf",
      "fileSize": 22579,
      "source": "api",
      "discardFiles": false,
      "createdAt": "2026-10-25T10:12:06.791Z",
      "completedAt": "2026-10-25T10:12:15.212Z",
      "reprocessCount": 0,
      "lastReprocessedAt": null,
      "approvalStatus": "Unapproved",
      "isTrainingExample": false
    }
  ],
  "totalCount": 1,
  "page": 1,
  "pageSize": 20
}

curl https://parsevix.com/api/v1/documents/01a1728b-cc26-7ba9-ad3c-dcf5e6d8e581 \
  -H "X-API-Key: $PARSEVIX_API_KEY"

Réponse200· abrégé

{
  "id": "01a1728b-cc26-7ba9-ad3c-dcf5e6d8e581",
  "status": "Completed",
  "categoryName": "Supplier invoice",
  "processingMode": "specific",
  "fileName": "invoice.pdf",
  "fileSize": 22579,
  "source": "api",
  "language": "en",
  "confidenceScore": 0.97,
  "pageCount": 1,
  "outputDeanonymized": {
    "invoice_number": "F-2026-88343",
    "invoice_date": "2026-10-03",
    "due_date": "2026-10-17",
    "currency": "GBP",
    "seller": {
      "name": "Northgate Systems Ltd",
      "vat_id": "GB566163740"
    },
    "line_items": [
      {
        "description": "LED panel light",
        "quantity": 4,
        "unit_price": 542.55,
        "total": 2170.2
      },
      {
        "description": "Office chair",
        "quantity": 1,
        "unit_price": 475.86,
        "total": 475.86
      }
    ],
    "gross_total": 7848.88,
    "_field_blocks": {
      "invoice_number": [
        {
          "page": 1,
          "x": 35.04,
          "y": 378.24,
          "width": 159.84,
          "height": 11.04,
          "text": "Invoice number: F-2026-88343"
        }
      ],
      "seller.name": [
        {
          "page": 1,
          "x": 34.08,
          "y": 558.24,
          "width": 120.48,
          "height": 12.96,
          "text": "Northgate Systems Ltd"
        }
      ]
    }
  },
  "errorMessage": null,
  "errorCode": null,
  "createdAt": "2026-10-25T10:12:06.791Z",
  "completedAt": "2026-10-25T10:12:15.212Z"
}

cURL

curl https://parsevix.com/api/v1/documents/01a1728b-cc26-7ba9-ad3c-dcf5e6d8e581/reprocess \
  -H "X-API-Key: $PARSEVIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"category": "auto"}'

cURL

curl https://parsevix.com/api/v1/documents/01a172b4-5d2e-7c61-8f0a-3b9d6e1c4a27/extract \
  -H "X-API-Key: $PARSEVIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Réponse202

{
  "id": "01a172b4-5d2e-7c61-8f0a-3b9d6e1c4a27",
  "status": "Pending",
  "categoryName": "Supplier invoice",
  "processingMode": "specific",
  "fileName": "invoice.pdf",
  "fileSize": 22579,
  "source": "api",
  "discardFiles": false,
  "createdAt": "2026-10-25T10:12:06.791Z",
  "completedAt": null,
  "reprocessCount": 1,
  "lastReprocessedAt": "2026-10-25T11:04:12.530Z",
  "approvalStatus": "Unapproved",
  "isTrainingExample": false
}

cURL

curl -X DELETE https://parsevix.com/api/v1/documents/01a1728b-cc26-7ba9-ad3c-dcf5e6d8e581 \
  -H "X-API-Key: $PARSEVIX_API_KEY"

Catégories

Les catégories du projet, y compris les modèles intégrés (isGlobal: true). Les catégories sont créées et modifiées dans le tableau de bord.

Lister les catégories

GET/api/v1/categories

Obtenir le schéma d'une catégorie

GET/api/v1/categories/{name}

Les champs qu'une catégorie extrait. fieldName est la clé dans extracted. fieldType vaut string, number, date, boolean, object ou array ; les objets et les tableaux ont leurs champs dans children. Le nom dans le chemin n'est pas sensible à la casse.

cURL

curl https://parsevix.com/api/v1/categories \
  -H "X-API-Key: $PARSEVIX_API_KEY"

Réponse200· abrégé

[
  {
    "id": 1,
    "name": "Invoice",
    "description": "Invoices and billing documents with seller/buyer info, line items, and totals",
    "isGlobal": true,
    "fieldCount": 48
  },
  {
    "id": 54,
    "name": "Supplier invoice",
    "description": "Commercial invoice: seller, buyer, line items and totals.",
    "isGlobal": false,
    "fieldCount": 26
  }
]

cURL

curl "https://parsevix.com/api/v1/categories/Supplier%20invoice" \
  -H "X-API-Key: $PARSEVIX_API_KEY"

Réponse200· abrégé

{
  "id": 54,
  "name": "Supplier invoice",
  "description": "Commercial invoice: seller, buyer, line items and totals.",
  "fields": [
    {
      "fieldName": "invoice_number",
      "displayName": "Invoice number",
      "fieldType": "string",
      "description": null,
      "children": []
    },
    {
      "fieldName": "invoice_date",
      "displayName": "Invoice date",
      "fieldType": "date",
      "description": null,
      "children": []
    },
    {
      "fieldName": "seller",
      "displayName": "Seller",
      "fieldType": "object",
      "description": null,
      "children": [
        {
          "fieldName": "name",
          "displayName": "Name",
          "fieldType": "string",
          "description": null,
          "children": []
        },
        {
          "fieldName": "vat_id",
          "displayName": "VAT / tax id",
          "fieldType": "string",
          "description": null,
          "children": []
        }
      ]
    }
  ]
}

Clé et crédits

GET/api/v1/me

Le projet de la clé et le solde de crédits du compte. Les crédits appartiennent au compte et sont partagés par tous ses projets ; resetsOn est le début de la période suivante. Avec un forfait annuel, la période est l'année de facturation et monthlyLimit contient les crédits de toute l'année.

cURL

curl https://parsevix.com/api/v1/me \
  -H "X-API-Key: $PARSEVIX_API_KEY"

Réponse200

{
  "projectId": "01a16af3-0b1f-7f2f-8282-b3824309d921",
  "projectName": "Accounts payable",
  "projectSlug": "accounts-payable",
  "keyName": "ERP connector",
  "keyPrefix": "psvx_nyskxlv",
  "email": "you@example.com",
  "credits": {
    "period": "2026-10-04",
    "resetsOn": "2026-11-04",
    "monthlyLimit": 1000,
    "used": 312,
    "remaining": 688,
    "planName": "Growth"
  }
}

Gérer les webhooks

Les webhooks peuvent être gérés dans le tableau de bord (Webhooks) ou via ces endpoints.

Créer un webhook

POST/api/v1/webhooks

urlstringobligatoire: Une URL https publique. Les adresses de réseaux privés sont refusées.
eventsstring[]obligatoire: Un ou plusieurs événements parmi extraction.completed, extraction.failed et classification.completed.
filtersobjectfacultatif: Facultatif. sources (dashboard, api, email) et categories (noms) limitent les documents qui envoient des événements.

La réponse contient une seule fois le secret de signature. Conservez-le pour vérifier les signatures.

Lister les webhooks

GET/api/v1/webhooks

Supprimer un webhook

DELETE/api/v1/webhooks/{id}

Exemples d'événements

GET/api/v1/webhooks/samples

Les derniers documents du projet sous forme de corps d'événement, pour tester votre récepteur. Paramètres : event (obligatoire), limit (1–10, 3 par défaut), category. S'il n'existe encore aucun document de ce type, un exemple est construit à partir du schéma de la catégorie.

cURL

curl https://parsevix.com/api/v1/webhooks \
  -H "X-API-Key: $PARSEVIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/parsevix/webhook",
    "events": ["extraction.completed", "extraction.failed"],
    "filters": { "sources": ["api", "email"] }
  }'

Réponse201

{
  "secret": "d0726faeb5c655d349fc30ed226e93e531ac2499800aacde100e83554b48701c",
  "id": "01a17295-c761-7b8f-b173-388bc754b1ba",
  "url": "https://example.com/parsevix/webhook",
  "events": [
    "extraction.completed",
    "extraction.failed"
  ],
  "filters": {
    "sources": [
      "api",
      "email"
    ],
    "categories": null
  },
  "isActive": true,
  "disabledAt": null,
  "disabledReason": null,
  "managedBy": null,
  "createdAt": "2026-10-25T10:23:09.311Z"
}

cURL

curl "https://parsevix.com/api/v1/webhooks/samples?event=extraction.completed&limit=1" \
  -H "X-API-Key: $PARSEVIX_API_KEY"

Webhooks

Lorsqu'un document est terminé, Parsevix envoie un POST avec un corps JSON à chacun des webhooks du projet. Les webhooks reçoivent les documents de toutes les sources : tableau de bord, API et e-mail.

Événements

Événement	Description
extraction.completed	Un document a été traité. `data` contient les champs extraits.
classification.completed	Un document `classify-only` a reçu sa catégorie : `document.category`, avec le nombre de pages du document dans `document.page_count`. Il n'y a pas de `data`.
extraction.failed	Un document n'a pas pu être traité, y compris un document `classify-only`. `error_code` est l'un des motifs d'échec ; `error` est le message affiché dans le tableau de bord.
test.ping	Envoyé par le bouton Tester sur la page d'un webhook dans le tableau de bord.

En-têtes

En-tête	Description
X-Webhook-Id	Identifiant de l'événement. Identique à chaque tentative ; utilisez-le pour ignorer les doublons. C'est aussi l'`id` du corps.
X-Webhook-Event	Le nom de l'événement.
X-Webhook-Timestamp	Heure Unix de cette tentative, en secondes.
X-Webhook-Signature	`sha256=` suivi du HMAC-SHA256 en hexadécimal de `{timestamp}.{raw body}`, calculé avec le secret du webhook.
X-Webhook-Attempt	Numéro de la tentative, à partir de 1.

Vérifier la signature

Calculez le HMAC sur le corps brut de la requête exactement tel que reçu, avant de l'analyser. Rejetez les événements dont l'horodatage a plus de 5 minutes.

Répondre

Répondez avec un statut 2xx dans les 10 secondes, puis traitez l'événement. Toute autre réponse compte comme un échec. Les redirections ne sont pas suivies.
Les envois en échec sont retentés après 1 minute, 5 minutes, 30 minutes, 2 heures, 6 heures et 24 heures : 7 tentatives sur environ 33 heures.
Répondre 410 Gone désactive immédiatement le webhook. Il est aussi désactivé lorsque trois événements ont échoué à chaque tentative et qu'aucun envoi n'a réussi depuis 3 jours. Le propriétaire reçoit un e-mail ; réactivez-le dans le tableau de bord. Les événements intermédiaires ne sont pas renvoyés.
Le secret peut être renouvelé dans le tableau de bord. L'ancien secret cesse immédiatement de fonctionner.

extraction.completed200· abrégé

{
  "id": "01a172a0-3f1e-7d42-9b6c-8e2f5a7d1c90",
  "event": "extraction.completed",
  "timestamp": "2026-10-25T10:12:21.592Z",
  "project_id": "01a16af3-0b1f-7f2f-8282-b3824309d921",
  "project_name": "Accounts payable",
  "project_slug": "accounts-payable",
  "document": {
    "id": "01a1728b-cc26-7ba9-ad3c-dcf5e6d8e581",
    "file_name": "invoice.pdf",
    "category": "Supplier invoice",
    "source": "api",
    "processing_mode": "specific",
    "language": "en",
    "confidence_score": 0.97
  },
  "data": {
    "invoice_number": "F-2026-88343",
    "invoice_date": "2026-10-03",
    "due_date": "2026-10-17",
    "currency": "GBP",
    "seller": {
      "name": "Northgate Systems Ltd",
      "vat_id": "GB566163740"
    },
    "line_items": [
      {
        "description": "LED panel light",
        "quantity": 4,
        "unit_price": 542.55,
        "total": 2170.2
      },
      {
        "description": "Office chair",
        "quantity": 1,
        "unit_price": 475.86,
        "total": 475.86
      }
    ],
    "gross_total": 7848.88,
    "_field_blocks": {
      "invoice_number": [
        {
          "page": 1,
          "x": 35.04,
          "y": 378.24,
          "width": 159.84,
          "height": 11.04,
          "text": "Invoice number: F-2026-88343"
        }
      ],
      "seller.name": [
        {
          "page": 1,
          "x": 34.08,
          "y": 558.24,
          "width": 120.48,
          "height": 12.96,
          "text": "Northgate Systems Ltd"
        }
      ]
    }
  }
}

classification.completed200

{
  "id": "01a172b5-8e47-7a13-b2c9-4f6d0a8e3b51",
  "event": "classification.completed",
  "timestamp": "2026-10-25T10:14:02.334Z",
  "project_id": "01a16af3-0b1f-7f2f-8282-b3824309d921",
  "project_name": "Accounts payable",
  "project_slug": "accounts-payable",
  "document": {
    "id": "01a172b4-5d2e-7c61-8f0a-3b9d6e1c4a27",
    "file_name": "invoice.pdf",
    "category": "Supplier invoice",
    "source": "api",
    "processing_mode": "classify-only",
    "language": "en",
    "page_count": 1
  }
}

extraction.failed200

{
  "id": "01a172a1-0c55-7e18-a3d4-6b9f2e8c1d07",
  "event": "extraction.failed",
  "timestamp": "2026-10-25T10:12:23.711Z",
  "project_id": "01a16af3-0b1f-7f2f-8282-b3824309d921",
  "project_name": "Accounts payable",
  "project_slug": "accounts-payable",
  "document": {
    "id": "01a1728b-cc26-7ba9-ad3c-dcf5e6d8e581",
    "file_name": "invoice.pdf",
    "category": "Supplier invoice",
    "source": "api",
    "processing_mode": "specific"
  },
  "error_code": "file_unreadable",
  "error": "The file is damaged or is not a valid PDF, Word document or image."
}

import hashlib
import hmac
import time

def verify(raw_body: bytes, headers, secret: str) -> bool:
    timestamp = headers["X-Webhook-Timestamp"]
    signature = headers["X-Webhook-Signature"]  # "sha256=<hex>"
    if abs(time.time() - int(timestamp)) > 300:
        return False  # plus de 5 minutes : peut-être rejoué
    expected = hmac.new(
        secret.encode(),
        timestamp.encode() + b"." + raw_body,
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(signature, "sha256=" + expected)

Zapier

L'application Parsevix pour Zapier se connecte avec une clé API d'un projet. Ajoutez-la via le lien d'invitation sur la page Zapier du projet dans le tableau de bord ou ici.

Déclencheurs

Extraction Completed : un document a été traité. En option, une seule catégorie ou source.
Extraction Failed : un document n'a pas pu être traité.
Document Classified : un document envoyé uniquement pour être classé a reçu sa catégorie, par exemple depuis une adresse e-mail configurée en classification seule.

Actions

Extract Document envoie un fichier issu d'une étape précédente, éventuellement avec une catégorie, et transmet les champs extraits aux étapes suivantes. Lorsqu'une catégorie est choisie, ses champs peuvent être mappés pendant la création du Zap.
Classify Document envoie un fichier et transmet aux étapes suivantes la catégorie choisie par Parsevix, sans extraire de champs. Utilisez-le pour acheminer les documents par type.

Les Zaps que vous activez apparaissent sur la page Zapier du projet et sous Webhooks.

E-mail

À partir du forfait Starter, chaque projet dispose d'une adresse e-mail sous Boîte de réception e-mail. Chaque pièce jointe d'un e-mail envoyé à cette adresse devient un document ; les résultats apparaissent dans le tableau de bord et sont envoyés à vos webhooks avec la source email.

Les adresses ont la forme name+inbox@inbox.parsevix.com. Selon le forfait, un projet peut en avoir plusieurs, par exemple une par fournisseur ou par service.

Par adresse

Traitement des pièces jointes : extraire chaque pièce jointe selon une catégorie fixe ; laisser Parsevix choisir la catégorie, puis extraire ; ou seulement choisir la catégorie (classify-only, 1 crédit par document), avec les champs extraits plus tard si nécessaire.
Expéditeurs autorisés : seuls les e-mails provenant de ces domaines sont acceptés, et uniquement s'ils passent DKIM ou SPF pour ce domaine ; un expéditeur usurpé est donc rejeté.

Ce qui est traité

Les pièces jointes PDF, DOCX, PNG, JPEG et TIFF, y compris celles des e-mails transférés. Les images affichées dans le corps de l'e-mail, comme les logos de signature, sont ignorées.
Un e-mail peut peser jusqu'à 30 Mo, et ses 20 premières pièces jointes deviennent des documents. Une adresse reçoit jusqu'à 1 000 e-mails et crée jusqu'à 1 000 documents en 24 heures ; au-delà, les e-mails sont refusés et les pièces jointes sont listées comme non importées. La réception est gratuite ; chaque document coûte des crédits comme n'importe quel autre.
Le même e-mail livré deux fois (même Message-ID) n'est traité qu'une fois.

Erreurs

Les erreurs ont un statut HTTP et un corps avec un code stable et un message lisible. Basez votre logique sur code ; les messages peuvent changer.

Codes de statut

Statut	Signification
400	La requête est invalide : paramètre manquant ou incorrect, fichier non pris en charge, crédits insuffisants. `validation.failed` liste les problèmes par paramètre dans `fields`.
401	Aucune clé API, ou une clé non valide.
403	La clé est valide mais ne peut pas être utilisée. Voir Authentification.
404	Le document, la catégorie, le webhook ou l'endpoint n'existe pas dans ce projet.
413	L'import dépasse la taille limite de la requête.
422	`POST /extract` ou `POST /classify` s'est exécuté, mais le document n'a pas pu être traité.
429	Limite de débit ou de requêtes simultanées atteinte. Attendez `Retry-After` secondes.
5xx	Une erreur serveur (avec une référence à communiquer au support), une maintenance (`503`) ou un délai dépassé (`504`).

Codes courants

Code	Signification
validation.file_required	Aucun `file` n'a été envoyé.
document.content_not_supported	Le contenu du fichier n'est pas du PDF, DOCX, PNG, JPEG ou TIFF, quel que soit son nom.
credit.file_size_exceeds_plan	Le fichier dépasse la taille autorisée par le forfait.
validation.language_invalid	`language` n'est pas un code à deux lettres.
document.callback_url_*	`callbackUrl` n'est pas une URL `https` publique de 2 000 caractères au maximum.
credit.insufficient_credits	Pas assez de crédits restants pour cette période.
document.refund_pending	Un remboursement de l'abonnement est en cours d'examen ; rien n'est traité tant qu'il n'est pas réglé.
category.not_found	Aucune catégorie portant ce nom dans le projet.
document.classify_only_category	`classify-only` a été envoyé avec une catégorie. Ce mode choisit lui-même la catégorie.
document.not_classify_only	`POST /documents/{id}/extract` a été appelé pour un document qui n'a pas été envoyé avec `classify-only`.
document.files_not_retained	Les fichiers de l'import API n'ont pas été conservés ; il ne peut donc pas être retraité.
webhook.url_*	L'URL du webhook n'est pas une URL `https` publique.
*.limit_reached	Une limite du forfait a été atteinte, comme le nombre de webhooks par projet.

Motifs d'échec

Pourquoi un document a échoué : reason dans la réponse 422 de POST /extract ou POST /classify, error_code dans extraction.failed, errorCode sur le document.

Code	Signification
too_many_pages	Plus de 30 pages. Divisez le fichier.
sync_too_many_pages	Plus de pages que `POST /extract` et `POST /classify` n'en acceptent.
pdf_encrypted	Le PDF est protégé par un mot de passe.
file_unreadable	Le fichier est endommagé ou n'est pas un document valide.
no_text	Aucun texte trouvé : page vierge, ou scan illisible.
no_categories	La catégorie devait être choisie automatiquement, mais le projet n'a aucune catégorie.
no_schema_fields	La catégorie n'a aucun champ.
no_fields_found	Aucun des champs de la catégorie n'a été trouvé dans le document ; il est probablement dans la mauvaise catégorie. Retraitez-le avec la bonne.
no_data_found	L'extraction automatique n'a trouvé aucune donnée dans le document.
insufficient_credits	Le document nécessite plus de crédits qu'il n'en reste pour cette période. Rien n'a été débité ; retraitez-le après un passage à un forfait supérieur ou la réinitialisation.
refund_pending	Un remboursement de l'abonnement était en cours d'examen. S'il est refusé, retraitez le document.
masking_failed	Les données personnelles n'ont pas pu être masquées ; le document n'a donc pas été envoyé au modèle d'IA. Réessayez.
worker_unavailable	Le traitement était temporairement indisponible. Réessayez.
ai_failed	Le modèle d'IA a échoué temporairement. Réessayez.
processing_failed	Une erreur interne. Réessayez ; contactez le support si elle se répète.
processing_timeout	Le traitement s'est arrêté avant la fin (par exemple lors d'un redémarrage). Réessayez.

Les cinq derniers sont temporaires : retraitez le document ou renvoyez-le. Les exécutions en échec ne sont pas facturées à la page.

Réponse400

{
  "error": {
    "code": "validation.failed",
    "message": "The file field is required.",
    "fields": {
      "file": [
        "The file field is required."
      ]
    }
  }
}

Réponse422

{
  "error": {
    "code": "document.sync_failed",
    "message": "The file is damaged or is not a valid PDF, Word document or image.",
    "reason": "file_unreadable",
    "documentId": "01a1728b-cc26-7ba9-ad3c-dcf5e6d8e581"
  }
}

Limites et crédits

Fichiers

PDF, DOCX, PNG, JPEG et TIFF (y compris multipages). Le type est déterminé par le contenu du fichier, pas par son nom.
Jusqu'à 10 Mo et 30 pages par document.

Crédits

Chaque page traitée coûte 1 crédit. Le choix automatique de la catégorie ne coûte rien de plus.
La classification seule (classify-only) coûte 1 crédit par document. Extraire un tel document plus tard coûte son nombre de pages moins ce crédit : le total reste donc de 1 crédit par page.
Une exécution en échec ne coûte rien pour ses pages. Un retraitement coûte de nouveau des crédits. La réception d'e-mails est gratuite.
Lorsque les crédits d'une période sont épuisés, les imports sont refusés avec credit.insufficient_credits jusqu'à la période suivante ou un passage à un forfait supérieur. Les crédits d'un document sont réservés dès que ses pages sont comptées ; s'ils ne suffisent plus, par exemple après de nombreux imports en parallèle, le document échoue avec insufficient_credits et rien n'est débité.

Débit de requêtes

Chaque clé API peut effectuer un certain nombre de requêtes par minute, selon le forfait. Chaque réponse contient X-RateLimit-Limit, X-RateLimit-Remaining et X-RateLimit-Reset (heure Unix). Au-delà de la limite, vous recevez 429 avec Retry-After.

Par forfait

Forfait	Requêtes / minute	Crédits / mois	Clés API	Webhooks / projet
Free	10	20	1	1
Starter	30	500	2	2
Growth	60	2 000	3	5
Pro	120	6 000	10	10
Business	300	20 000	illimité	25

Par ailleurs : POST /extract et POST /classify attendent 285 secondes au maximum et autorisent ensemble 5 requêtes ouvertes par clé.

Réponse429

{
  "error": {
    "code": "apikey.rate_limited",
    "message": "Too many requests for this API key: the limit is 60 per minute. Retry in 18 s.",
    "limit": 60,
    "retryAfterSeconds": 18
  }
}

Conservation des données

Ce que Parsevix conserve d'un import API est un paramètre du projet : Imports via l'API, sous Paramètres du projet. Par défaut, il est réglé sur Supprimer après traitement ; Conserver comme les imports du tableau de bord les conserve.

Supprimer après traitement : le fichier est supprimé à la fin du traitement et le résultat n'est pas stocké. La réponse de l'API, le webhook ou le callback en est la seule copie. Ces documents ne sont pas listés et ne peuvent être ni retraités ni téléchargés ; retained vaut false.
Conserver comme les imports du tableau de bord : les fichiers et les résultats sont stockés comme les imports depuis le tableau de bord, jusqu'à ce que vous les supprimiez.

Les imports depuis le tableau de bord et les documents reçus par e-mail sont toujours stockés. Les données personnelles sont masquées avant que le moindre texte n'atteigne le modèle d'IA ; voir Sécurité.