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	Ja	Das Dokument, aus dem Daten extrahiert werden (PDF, JPEG, PNG, GIF, WebP, TIFF, BMP, HEIC, AVIF)
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

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	Ja	Die vom Upload-Endpunkt zurückgegebene Datei-ID
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

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
}

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.

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.

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	Ja	Das Dokument, aus dem Daten extrahiert werden (PDF, JPEG, PNG, GIF, WebP, TIFF, BMP, HEIC, AVIF)
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

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	Ja	Die vom Upload-Endpunkt zurückgegebene Datei-ID
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

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
}

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