Référence de l’API

Parse propose deux façons d’extraire des données des documents : une méthode synchrone à appel unique et une méthode asynchrone en trois étapes.

Tous les endpoints nécessitent un token Bearer dans le header Authorization. Consultez Authentification pour savoir comment créer et utiliser votre clé API.

URL de base : https://api-parse.conversiontools.io

Méthode 1 : Appel unique (synchrone)

Téléversez un fichier et démarrez l’extraction en une seule requête. Par défaut, l’appel renvoie immédiatement une réponse 202 avec un identifiant d’extraction : interrogez le résultat ou utilisez un webhook. Passez wait pour maintenir la requête ouverte et recevoir les petits documents directement.

POST

/v1/extract

Headers

Header	Valeur
Authorization	Bearer YOUR_API_KEY
Content-Type	multipart/form-data

Paramètres (form-data)

Paramètre	Type	Obligatoire	Description
file	File	Oui	Le document dont extraire les données (PDF, JPEG, PNG, GIF, WebP, TIFF, BMP, HEIC, AVIF)
schema_id	String	Non	ID du schéma pour contrôler quels champs sont extraits
wait	Number	Non	Secondes pendant lesquelles la requête reste ouverte pour renvoyer le résultat directement s’il se termine à temps (0 = renvoyer immédiatement - la valeur par défaut ; maximum 120)
webhook_url	String	Non	URL http(s) publique notifiée quand l’extraction se termine, pour ne pas avoir à interroger
no_cache	Boolean	Non	Mettez 1 pour forcer une nouvelle extraction au lieu de réutiliser un résultat stocké pour un document identique

Exemple

curl -X POST https://api-parse.conversiontools.io/v1/extract \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@invoice.pdf" \
  -F "wait=60"

Réponse (200 - avec wait, quand le document se termine à temps)

{
  "success": true,
  "id": "ext_789...",
  "filename": "invoice.pdf",
  "status": "completed",
  "data": {
    "vendor_name": "Acme Corp",
    "invoice_number": "INV-2024-001",
    "date": "2024-01-15",
    "total": 1650.00
  },
  "pages_used": 1
}

Réponse (202 - par défaut)

Par défaut, et chaque fois que le document dépasse la fenêtre d’attente, le serveur renvoie une 202 avec un identifiant d’extraction. Interrogez GET /v1/extractions/:id jusqu’à ce que status soit completed ou failed : basez-vous toujours sur status, jamais sur le temps. Ou passez une URL de webhook pour ne pas avoir à interroger.

{
  "success": true,
  "id": "ext_789...",
  "status": "processing"
}

# Poll until the extraction reaches a terminal status
while true; do
  RESULT=$(curl -s https://api-parse.conversiontools.io/v1/extractions/EXTRACTION_ID \
    -H "Authorization: Bearer YOUR_API_KEY")
  STATUS=$(echo "$RESULT" | grep -o '"status": *"[a-z]*"')
  case "$STATUS" in
    *completed*|*failed*) break ;;
  esac
  sleep 2
done
echo "$RESULT"

Méthode 2 : Téléversement + Extraction (asynchrone)

Un flux en trois étapes : téléversez d’abord le fichier, puis démarrez une extraction, puis interrogez le résultat. Cette méthode vous donne plus de contrôle - vous pouvez réutiliser le même fichier téléversé pour plusieurs extractions avec des schémas différents.

POST

/v1/upload

Téléversez un document et recevez un file_id pour l’extraction.

Paramètres (form-data)

Paramètre	Type	Obligatoire	Description
file	File	Oui	Le document à téléverser (PDF, JPEG, PNG, GIF, WebP, TIFF, BMP, HEIC, AVIF)

Exemple

curl -X POST https://api-parse.conversiontools.io/v1/upload \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@invoice.pdf"

Réponse

{
  "success": true,
  "file_id": "abc123...",
  "filename": "invoice.pdf",
  "size": 52480
}

POST

/v1/extract

Démarrez une extraction sur un fichier téléversé à l’aide de son file_id. Vous pouvez éventuellement indiquer un schema_id pour contrôler quels champs sont extraits.

Headers

Header	Valeur
Authorization	Bearer YOUR_API_KEY
Content-Type	application/json

Paramètres (corps JSON)

Paramètre	Type	Obligatoire	Description
file_id	String	Oui	L’ID du fichier renvoyé par le endpoint de téléversement
schema_id	String	Non	ID du schéma pour contrôler quels champs sont extraits
webhook_url	String	Non	URL http(s) publique notifiée quand l’extraction se termine, pour ne pas avoir à interroger
no_cache	Boolean	Non	Mettez true pour forcer une nouvelle extraction au lieu de réutiliser un résultat stocké pour un document identique

Exemple

curl -X POST https://api-parse.conversiontools.io/v1/extract \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"file_id": "abc123...", "schema_id": "sch_456...", "webhook_url": "https://example.com/hooks/parse"}'

Réponse

{
  "success": true,
  "id": "ext_789...",
  "status": "processing"
}

GET

/v1/extractions/:id

Récupérez le résultat d’une extraction. Interrogez ce endpoint jusqu’à ce que status soit completed.

Exemple

curl https://api-parse.conversiontools.io/v1/extractions/ext_789... \
  -H "Authorization: Bearer YOUR_API_KEY"

Réponse

{
  "success": true,
  "id": "ext_789...",
  "filename": "invoice.pdf",
  "status": "completed",
  "data": {
    "vendor_name": "Acme Corp",
    "invoice_number": "INV-2024-001",
    "date": "2024-01-15",
    "items": [
      {
        "description": "Consulting Services",
        "quantity": 10,
        "unit_price": 150.00,
        "amount": 1500.00
      }
    ],
    "subtotal": 1500.00,
    "tax": 150.00,
    "total": 1650.00,
    "currency": "USD"
  },
  "pages_used": 1
}

Webhooks

Passez une webhook_url et Parse envoie un POST à cette adresse dès que l’extraction se termine ou échoue : vous n’avez donc jamais à interroger. La notification contient uniquement l’identifiant de l’extraction et le statut, jamais les données extraites ; récupérez le résultat via l’API. L’URL doit être une adresse http ou https publique ; les adresses privées et internes sont refusées. La livraison est retentée plusieurs fois et n’affecte jamais l’extraction elle-même.

Contenu de la notification

{
  "event": "extraction.completed",
  "id": "ext_789...",
  "status": "completed",
  "pages_used": 2,
  "error": null,
  "created_at": "2026-07-26T10:00:00.000Z",
  "completed_at": "2026-07-26T10:00:41.000Z"
}

Extractions répétées

Si vous renvoyez le même document avec le même schéma, Parse renvoie immédiatement le résultat stocké, sans le décompter de vos pages. Ces réponses contiennent "cached": true. Modifier le schéma, ou passer no_cache, déclenche une nouvelle extraction.

Exporter vers CSV / Excel

Convertissez le résultat d’une extraction terminée en feuille de calcul. Les exports sont gratuits, reproductibles et ne consomment pas de pages. Les tableaux imbriqués sont dénormalisés : les champs d’en-tête se répètent sur chaque ligne, de sorte que la sortie est prête pour les tableaux croisés dynamiques et les imports. Astuce : passez output_format (csv ou xlsx) dans la requête d’extraction et l’export démarre automatiquement dès que l’extraction est terminée.

POST

/v1/extractions/:id/export

Démarrez l’export. Idempotent par format : les appels répétés renvoient la conversion en cours ou le statut du fichier terminé.

Exemple

curl -X POST https://api-parse.conversiontools.io/v1/extractions/ext_789.../export \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"format": "xlsx"}'

Réponse

{
  "success": true,
  "status": "processing",
  "format": "xlsx",
  "progress": 0
}

GET

/v1/extractions/:id/export?format=xlsx

Interrogez l’export. Pendant la conversion, la réponse est du JSON avec status: "processing" et un pourcentage progress. Lorsque le fichier est prêt, le corps de la réponse est le fichier lui-même (avec Content-Disposition: attachment).

Exemple

curl -L -o invoice.xlsx \
  "https://api-parse.conversiontools.io/v1/extractions/ext_789.../export?format=xlsx" \
  -H "Authorization: Bearer YOUR_API_KEY"

DELETE

/v1/extractions/:id

Supprimez une extraction et toutes ses données stockées (le résultat et les éventuels fichiers d’export). Les documents source sont toujours supprimés automatiquement dans les 24 heures suivant le traitement ; les résultats extraits sont conservés jusqu’à ce que vous les supprimiez - via ce endpoint ou depuis le tableau de bord.

Exemple

curl -X DELETE https://api-parse.conversiontools.io/v1/extractions/ext_789... \
  -H "Authorization: Bearer YOUR_API_KEY"

Réponses d’erreur

401 Unauthorized

{
  "error": "Invalid API key",
  "param": "authorization"
}

429 Rate Limited

{
  "error": "Monthly page limit exceeded",
  "code": "LIMIT_REACHED",
  "message": "You've reached your monthly page limit (100 pages).",
  "remedy": { "text": "View plans and upgrade", "path": "/pricing" }
}

Référence de l’API

Parse propose deux façons d’extraire des données des documents : une méthode synchrone à appel unique et une méthode asynchrone en trois étapes.

Tous les endpoints nécessitent un token Bearer dans le header Authorization. Consultez Authentification pour savoir comment créer et utiliser votre clé API.

URL de base : https://api-parse.conversiontools.io

Méthode 1 : Appel unique (synchrone)

POST

/v1/extract

Headers

Header	Valeur
Authorization	Bearer YOUR_API_KEY
Content-Type	multipart/form-data

Paramètres (form-data)

Paramètre	Type	Obligatoire	Description
file	File	Oui	Le document dont extraire les données (PDF, JPEG, PNG, GIF, WebP, TIFF, BMP, HEIC, AVIF)
schema_id	String	Non	ID du schéma pour contrôler quels champs sont extraits
wait	Number	Non	Secondes pendant lesquelles la requête reste ouverte pour renvoyer le résultat directement s’il se termine à temps (0 = renvoyer immédiatement - la valeur par défaut ; maximum 120)
webhook_url	String	Non	URL http(s) publique notifiée quand l’extraction se termine, pour ne pas avoir à interroger
no_cache	Boolean	Non	Mettez 1 pour forcer une nouvelle extraction au lieu de réutiliser un résultat stocké pour un document identique

Exemple

curl -X POST https://api-parse.conversiontools.io/v1/extract \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@invoice.pdf" \
  -F "wait=60"

Réponse (200 - avec wait, quand le document se termine à temps)

{
  "success": true,
  "id": "ext_789...",
  "filename": "invoice.pdf",
  "status": "completed",
  "data": {
    "vendor_name": "Acme Corp",
    "invoice_number": "INV-2024-001",
    "date": "2024-01-15",
    "total": 1650.00
  },
  "pages_used": 1
}

Réponse (202 - par défaut)

{
  "success": true,
  "id": "ext_789...",
  "status": "processing"
}

# Poll until the extraction reaches a terminal status
while true; do
  RESULT=$(curl -s https://api-parse.conversiontools.io/v1/extractions/EXTRACTION_ID \
    -H "Authorization: Bearer YOUR_API_KEY")
  STATUS=$(echo "$RESULT" | grep -o '"status": *"[a-z]*"')
  case "$STATUS" in
    *completed*|*failed*) break ;;
  esac
  sleep 2
done
echo "$RESULT"

Méthode 2 : Téléversement + Extraction (asynchrone)

POST

/v1/upload

Téléversez un document et recevez un file_id pour l’extraction.

Paramètres (form-data)

Paramètre	Type	Obligatoire	Description
file	File	Oui	Le document à téléverser (PDF, JPEG, PNG, GIF, WebP, TIFF, BMP, HEIC, AVIF)

Exemple

curl -X POST https://api-parse.conversiontools.io/v1/upload \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@invoice.pdf"

Réponse

{
  "success": true,
  "file_id": "abc123...",
  "filename": "invoice.pdf",
  "size": 52480
}

POST

/v1/extract

Démarrez une extraction sur un fichier téléversé à l’aide de son file_id. Vous pouvez éventuellement indiquer un schema_id pour contrôler quels champs sont extraits.

Headers

Header	Valeur
Authorization	Bearer YOUR_API_KEY
Content-Type	application/json

Paramètres (corps JSON)

Paramètre	Type	Obligatoire	Description
file_id	String	Oui	L’ID du fichier renvoyé par le endpoint de téléversement
schema_id	String	Non	ID du schéma pour contrôler quels champs sont extraits
webhook_url	String	Non	URL http(s) publique notifiée quand l’extraction se termine, pour ne pas avoir à interroger
no_cache	Boolean	Non	Mettez true pour forcer une nouvelle extraction au lieu de réutiliser un résultat stocké pour un document identique

Exemple

curl -X POST https://api-parse.conversiontools.io/v1/extract \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"file_id": "abc123...", "schema_id": "sch_456...", "webhook_url": "https://example.com/hooks/parse"}'

Réponse

{
  "success": true,
  "id": "ext_789...",
  "status": "processing"
}

GET

/v1/extractions/:id

Récupérez le résultat d’une extraction. Interrogez ce endpoint jusqu’à ce que status soit completed.

Exemple

curl https://api-parse.conversiontools.io/v1/extractions/ext_789... \
  -H "Authorization: Bearer YOUR_API_KEY"

Réponse

{
  "success": true,
  "id": "ext_789...",
  "filename": "invoice.pdf",
  "status": "completed",
  "data": {
    "vendor_name": "Acme Corp",
    "invoice_number": "INV-2024-001",
    "date": "2024-01-15",
    "items": [
      {
        "description": "Consulting Services",
        "quantity": 10,
        "unit_price": 150.00,
        "amount": 1500.00
      }
    ],
    "subtotal": 1500.00,
    "tax": 150.00,
    "total": 1650.00,
    "currency": "USD"
  },
  "pages_used": 1
}

Webhooks

Contenu de la notification

{
  "event": "extraction.completed",
  "id": "ext_789...",
  "status": "completed",
  "pages_used": 2,
  "error": null,
  "created_at": "2026-07-26T10:00:00.000Z",
  "completed_at": "2026-07-26T10:00:41.000Z"
}

Extractions répétées

Exporter vers CSV / Excel

POST

/v1/extractions/:id/export

Démarrez l’export. Idempotent par format : les appels répétés renvoient la conversion en cours ou le statut du fichier terminé.

Exemple

curl -X POST https://api-parse.conversiontools.io/v1/extractions/ext_789.../export \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"format": "xlsx"}'

Réponse

{
  "success": true,
  "status": "processing",
  "format": "xlsx",
  "progress": 0
}

GET

/v1/extractions/:id/export?format=xlsx

Exemple

curl -L -o invoice.xlsx \
  "https://api-parse.conversiontools.io/v1/extractions/ext_789.../export?format=xlsx" \
  -H "Authorization: Bearer YOUR_API_KEY"

DELETE

/v1/extractions/:id

Exemple

curl -X DELETE https://api-parse.conversiontools.io/v1/extractions/ext_789... \
  -H "Authorization: Bearer YOUR_API_KEY"

Réponses d’erreur

401 Unauthorized

{
  "error": "Invalid API key",
  "param": "authorization"
}

429 Rate Limited

{
  "error": "Monthly page limit exceeded",
  "code": "LIMIT_REACHED",
  "message": "You've reached your monthly page limit (100 pages).",
  "remedy": { "text": "View plans and upgrade", "path": "/pricing" }
}