API-Referenz

Parse bietet zwei Wege, um Daten aus Dokumenten zu extrahieren: eine synchrone Methode mit einem einzigen Aufruf und eine asynchrone Methode in drei Schritten.

Alle Endpunkte erfordern einen Bearer-Token im Authorization-Header. Siehe Authentifizierung, um zu erfahren, wie Sie Ihren API-Schlüssel erstellen und verwenden.

Basis-URL: https://api-parse.conversiontools.io

Methode 1: Einzelaufruf (synchron)

Laden Sie eine Datei hoch und starten Sie die Extraktion in einer einzigen Anfrage. Standardmäßig kehrt der Aufruf sofort mit einer 202-Antwort und einer Extraktions-ID zurück - fragen Sie das Ergebnis ab oder nutzen Sie einen Webhook. Mit wait halten Sie die Anfrage offen, um kleine Dokumente direkt zu erhalten.

POST

/v1/extract

Header

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

Parameter (form-data)

Parameter	Typ	Erforderlich	Beschreibung
file	File	Eines von beiden	Das Dokument, aus dem Daten extrahiert werden (PDF, JPEG, PNG, GIF, WebP, TIFF, BMP, HEIC, AVIF)
file_url	String	Eines von beiden	Öffentliche http(s)-Adresse des Dokuments, statt es hochzuladen. Parse lädt es selbst herunter (siehe Extraktion aus einer URL)
filename	String	Nein	Dateiname, unter dem ein file_url-Dokument gespeichert wird
schema_id	String	Nein	Schema-ID, um zu steuern, welche Felder extrahiert werden
wait	Number	Nein	Sekunden, die die Anfrage offen gehalten wird, um das Ergebnis direkt zu liefern, wenn es rechtzeitig fertig ist (0 = sofort zurückkehren - Standard; Maximum 120)
webhook_url	String	Nein	Öffentliche http(s)-URL, die benachrichtigt wird, sobald die Extraktion fertig ist - so müssen Sie nicht abfragen
no_cache	Boolean	Nein	Auf 1 setzen, um eine neue Extraktion zu erzwingen, statt ein gespeichertes Ergebnis für ein identisches Dokument wiederzuverwenden
password	String	Nein	Dokumentpasswort, falls das PDF verschlüsselt ist. Nur für passwortgeschützte Dateien erforderlich; ein PDF mit reinen Berechtigungsbeschränkungen wird auch ohne geöffnet

Beispiel

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

Antwort (200 - mit wait, wenn das Dokument rechtzeitig fertig wird)

{
  "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
}

Antwort (202 - Standard)

Standardmäßig - und immer, wenn das Dokument länger als das Wartefenster braucht - liefert der Server eine 202 mit einer Extraktions-ID zurück. Fragen Sie GET /v1/extractions/:id ab, bis status completed oder failed ist - verzweigen Sie immer anhand von status, nie anhand der Zeit. Oder übergeben Sie eine Webhook-URL, damit Sie gar nicht abfragen müssen.

{
  "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"

Methode 2: Upload + Extraktion (asynchron)

Ein dreistufiger Ablauf: Laden Sie zuerst die Datei hoch, starten Sie dann eine Extraktion und fragen Sie anschließend das Ergebnis ab. Diese Methode gibt Ihnen mehr Kontrolle - Sie können dieselbe hochgeladene Datei für mehrere Extraktionen mit unterschiedlichen Schemata wiederverwenden.

POST

/v1/upload

Laden Sie ein Dokument hoch und erhalten Sie eine file_id für die Extraktion.

Parameter (form-data)

Parameter	Typ	Erforderlich	Beschreibung
file	File	Ja	Das hochzuladende Dokument (PDF, JPEG, PNG, GIF, WebP, TIFF, BMP, HEIC, AVIF)

Beispiel

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

Antwort

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

POST

/v1/extract

Starten Sie eine Extraktion für eine hochgeladene Datei anhand ihrer file_id. Geben Sie optional eine schema_id an, um zu steuern, welche Felder extrahiert werden.

Header

Header	Wert
Authorization	Bearer YOUR_API_KEY
Content-Type	application/json

Parameter (JSON-Body)

Parameter	Typ	Erforderlich	Beschreibung
file_id	String	Eines von beiden	Die vom Upload-Endpunkt zurückgegebene Datei-ID
file_url	String	Eines von beiden	Öffentliche http(s)-Adresse des Dokuments, statt es hochzuladen. Parse lädt es selbst herunter (siehe Extraktion aus einer URL)
filename	String	Nein	Dateiname, unter dem ein file_url-Dokument gespeichert wird
schema_id	String	Nein	Schema-ID, um zu steuern, welche Felder extrahiert werden
webhook_url	String	Nein	Öffentliche http(s)-URL, die benachrichtigt wird, sobald die Extraktion fertig ist - so müssen Sie nicht abfragen
no_cache	Boolean	Nein	Auf true setzen, um eine neue Extraktion zu erzwingen, statt ein gespeichertes Ergebnis für ein identisches Dokument wiederzuverwenden
password	String	Nein	Dokumentpasswort, falls das PDF verschlüsselt ist. Nur für passwortgeschützte Dateien erforderlich; ein PDF mit reinen Berechtigungsbeschränkungen wird auch ohne geöffnet

Beispiel

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"}'

Antwort

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

GET

/v1/extractions/:id

Rufen Sie das Ergebnis einer Extraktion ab. Fragen Sie diesen Endpunkt ab, bis status den Wert completed hat.

Beispiel

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

Antwort

{
  "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
}

Extraktion aus einer URL

Statt die Datei hochzuladen, können Sie ihre Adresse als file_url senden - in der form-data-Anfrage oder in der JSON-Anfrage. Parse lädt das Dokument herunter und behandelt es danach genau wie einen Upload: gleiche Größenbegrenzung, gleiche Seitenabrechnung, gleiche Wiederverwendung gespeicherter Ergebnisse. Das eignet sich für Automatisierungswerkzeuge, die eine Datei nur als Link vorliegen haben.

Senden Sie entweder file (bzw. file_id) oder file_url, nicht beides. Der Link muss eine öffentliche http- oder https-Adresse sein, die sich ohne Anmeldung öffnen lässt; private und interne Adressen werden abgelehnt, auch nach einer Weiterleitung. Der Download muss innerhalb von 20 Sekunden abgeschlossen sein, und die Datei darf höchstens 100 MB groß sein. Kann die Datei nicht abgerufen werden, schlägt die Anfrage mit einem 400 (bei zu großen Dateien 413) fehl, der den Grund nennt, und es werden keine Seiten verbraucht.

Beispiel

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

Webhooks

Übergeben Sie eine webhook_url, und Parse sendet einen POST an diese Adresse, sobald die Extraktion abgeschlossen ist oder fehlschlägt - Sie müssen also nie abfragen. Die Benachrichtigung enthält nur die Extraktions-ID und den Status, niemals die extrahierten Daten; rufen Sie das Ergebnis anschließend über die API ab. Die URL muss eine öffentliche http- oder https-Adresse sein; private und interne Adressen werden abgelehnt. Die Zustellung wird einige Male wiederholt und beeinflusst die Extraktion selbst nie. Auch eine Anfrage, die aus einem gespeicherten Ergebnis beantwortet wird, erhält ihren Webhook - sofort -, und eine Anfrage, die an eine bereits laufende Extraktion desselben Dokuments angehängt wird, erhält ihn, sobald diese abgeschlossen ist.

Benachrichtigungs-Payload

{
  "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"
}

Wiederholte Extraktionen

Wird dasselbe Dokument erneut mit demselben Schema gesendet, liefert Parse sofort das gespeicherte Ergebnis zurück, und es wird nicht auf Ihre Seiten angerechnet. Diese Antworten enthalten "cached": true. Wenn Sie das Schema ändern oder no_cache übergeben, wird eine neue Extraktion ausgeführt. Eine mit einer solchen Anfrage gesendete webhook_url wird trotzdem aufgerufen.

Export nach CSV / Excel

Wandeln Sie das Ergebnis einer abgeschlossenen Extraktion in eine Tabelle um. Exporte sind kostenlos, wiederholbar und verbrauchen keine Seiten. Verschachtelte Arrays werden denormalisiert: Kopffelder wiederholen sich in jeder Zeile, sodass die Ausgabe für Pivot-Tabellen und Importe bereit ist. Tipp: Übergeben Sie output_format (csv oder xlsx) in der Extraktionsanfrage, und der Export startet automatisch, sobald die Extraktion abgeschlossen ist.

POST

/v1/extractions/:id/export

Starten Sie den Export. Idempotent pro Format: Wiederholte Aufrufe liefern die laufende Umwandlung oder den Status der fertigen Datei zurück.

Beispiel

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"}'

Antwort

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

GET

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

Fragen Sie den Export ab. Während der Umwandlung ist die Antwort JSON mit status: "processing" und einem progress-Prozentsatz. Wenn die Datei bereit ist, ist der Antworttext die Datei selbst (mit Content-Disposition: attachment).

Beispiel

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

Löschen Sie eine Extraktion und alle ihre gespeicherten Daten (Ergebnis und etwaige Exportdateien). Quelldokumente werden innerhalb von 24 Stunden nach der Verarbeitung immer automatisch gelöscht; extrahierte Ergebnisse werden gespeichert, bis Sie sie löschen - über diesen Endpunkt oder im Dashboard.

Beispiel

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

Fehlerantworten

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" }
}

API-Referenz

Parse bietet zwei Wege, um Daten aus Dokumenten zu extrahieren: eine synchrone Methode mit einem einzigen Aufruf und eine asynchrone Methode in drei Schritten.

Alle Endpunkte erfordern einen Bearer-Token im Authorization-Header. Siehe Authentifizierung, um zu erfahren, wie Sie Ihren API-Schlüssel erstellen und verwenden.

Basis-URL: https://api-parse.conversiontools.io

Methode 1: Einzelaufruf (synchron)

POST

/v1/extract

Header

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

Parameter (form-data)

Parameter	Typ	Erforderlich	Beschreibung
file	File	Eines von beiden	Das Dokument, aus dem Daten extrahiert werden (PDF, JPEG, PNG, GIF, WebP, TIFF, BMP, HEIC, AVIF)
file_url	String	Eines von beiden	Öffentliche http(s)-Adresse des Dokuments, statt es hochzuladen. Parse lädt es selbst herunter (siehe Extraktion aus einer URL)
filename	String	Nein	Dateiname, unter dem ein file_url-Dokument gespeichert wird
schema_id	String	Nein	Schema-ID, um zu steuern, welche Felder extrahiert werden
wait	Number	Nein	Sekunden, die die Anfrage offen gehalten wird, um das Ergebnis direkt zu liefern, wenn es rechtzeitig fertig ist (0 = sofort zurückkehren - Standard; Maximum 120)
webhook_url	String	Nein	Öffentliche http(s)-URL, die benachrichtigt wird, sobald die Extraktion fertig ist - so müssen Sie nicht abfragen
no_cache	Boolean	Nein	Auf 1 setzen, um eine neue Extraktion zu erzwingen, statt ein gespeichertes Ergebnis für ein identisches Dokument wiederzuverwenden
password	String	Nein	Dokumentpasswort, falls das PDF verschlüsselt ist. Nur für passwortgeschützte Dateien erforderlich; ein PDF mit reinen Berechtigungsbeschränkungen wird auch ohne geöffnet

Beispiel

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

Antwort (200 - mit wait, wenn das Dokument rechtzeitig fertig wird)

{
  "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
}

Antwort (202 - Standard)

{
  "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"

Methode 2: Upload + Extraktion (asynchron)

POST

/v1/upload

Laden Sie ein Dokument hoch und erhalten Sie eine file_id für die Extraktion.

Parameter (form-data)

Parameter	Typ	Erforderlich	Beschreibung
file	File	Ja	Das hochzuladende Dokument (PDF, JPEG, PNG, GIF, WebP, TIFF, BMP, HEIC, AVIF)

Beispiel

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

Antwort

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

POST

/v1/extract

Starten Sie eine Extraktion für eine hochgeladene Datei anhand ihrer file_id. Geben Sie optional eine schema_id an, um zu steuern, welche Felder extrahiert werden.

Header

Header	Wert
Authorization	Bearer YOUR_API_KEY
Content-Type	application/json

Parameter (JSON-Body)

Parameter	Typ	Erforderlich	Beschreibung
file_id	String	Eines von beiden	Die vom Upload-Endpunkt zurückgegebene Datei-ID
file_url	String	Eines von beiden	Öffentliche http(s)-Adresse des Dokuments, statt es hochzuladen. Parse lädt es selbst herunter (siehe Extraktion aus einer URL)
filename	String	Nein	Dateiname, unter dem ein file_url-Dokument gespeichert wird
schema_id	String	Nein	Schema-ID, um zu steuern, welche Felder extrahiert werden
webhook_url	String	Nein	Öffentliche http(s)-URL, die benachrichtigt wird, sobald die Extraktion fertig ist - so müssen Sie nicht abfragen
no_cache	Boolean	Nein	Auf true setzen, um eine neue Extraktion zu erzwingen, statt ein gespeichertes Ergebnis für ein identisches Dokument wiederzuverwenden
password	String	Nein	Dokumentpasswort, falls das PDF verschlüsselt ist. Nur für passwortgeschützte Dateien erforderlich; ein PDF mit reinen Berechtigungsbeschränkungen wird auch ohne geöffnet

Beispiel

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"}'

Antwort

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

GET

/v1/extractions/:id

Rufen Sie das Ergebnis einer Extraktion ab. Fragen Sie diesen Endpunkt ab, bis status den Wert completed hat.

Beispiel

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

Antwort

{
  "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
}

Extraktion aus einer URL

Beispiel

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

Webhooks

Benachrichtigungs-Payload

{
  "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"
}

Wiederholte Extraktionen

Export nach CSV / Excel

POST

/v1/extractions/:id/export

Starten Sie den Export. Idempotent pro Format: Wiederholte Aufrufe liefern die laufende Umwandlung oder den Status der fertigen Datei zurück.

Beispiel

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"}'

Antwort

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

GET

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

Beispiel

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

Beispiel

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

Fehlerantworten

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" }
}