Invoice Parsing in Python — Extract Invoice & Receipt Data with One Endpoint

The guide

1. 1

   Install the requests library

   One dependency is all you need:

   pip install requests

2. 2

   Set your API key as an environment variable

   Never hardcode the key in your source code:

   export DOCUPARSE_API_KEY="dex_your_key_here"

3. 3

   Submit the file and fetch the result

   POST the file to /api/v1/extract, then fetch the result from GET /api/v1/documents/{id}. The fetched data object has every field already named. On Starter and Pro you can skip polling: add a webhook in Dashboard → Settings and DocuParse API will POST the finished result to your endpoint.

   import os, time, requests
   
   API = "https://docuparseapi.com/api/v1"
   HEADERS = {"Authorization": f"Bearer {os.environ['DOCUPARSE_API_KEY']}"}
   
   def parse_document(path: str) -> dict:
       # 1. Submit
       with open(path, "rb") as f:
           submit = requests.post(f"{API}/extract", headers=HEADERS,
                                  files={"file": (os.path.basename(path), f)}, timeout=30).json()
       if not submit.get("success"):
           raise RuntimeError(f"[{submit['error']['code']}] {submit['error']['message']}")
   
       # 2. Fetch the result
       for _ in range(40):
           doc = requests.get(f"{API}/documents/{submit['document_id']}",
                              headers=HEADERS, timeout=30).json()
           if doc["status"] == "completed":
               return doc["data"]
           if doc["status"] == "failed":
               raise RuntimeError(f"Extraction failed: {submit['document_id']}")
           time.sleep(1.5)
       raise TimeoutError(submit["document_id"])
   
   data = parse_document("invoice.pdf")
   print(data["merchant"], data["total"], data["currency"])

   Need your API key first?

   20 free documents/month — no credit card

   Sign up — get a free API key
4. 4

   Handle errors by error code

   parse_document raises with the error code from the submit step:

   try:
       data = parse_document("invoice.pdf")
   except RuntimeError as e:
       msg = str(e)
       if "LIMIT_EXCEEDED" in msg:
           print("Monthly limit reached")
       elif "UNSUPPORTED_FILE_TYPE" in msg:
           print("Use PDF, JPG, PNG or CSV")
       elif "Extraction failed" in msg:
           print("Try a cleaner scan")

5. 5

   For async apps, use httpx

   If you're using FastAPI or asyncio, run the same two steps with httpx.AsyncClient:

   import asyncio, os
   import httpx
   
   API = "https://docuparseapi.com/api/v1"
   HEADERS = {"Authorization": f"Bearer {os.environ['DOCUPARSE_API_KEY']}"}
   
   async def parse_document_async(path: str) -> dict:
       async with httpx.AsyncClient(timeout=30) as client:
           # 1. Submit
           with open(path, "rb") as f:
               submit = (await client.post(f"{API}/extract", headers=HEADERS,
                                           files={"file": (os.path.basename(path), f.read())})).json()
           if not submit.get("success"):
               raise RuntimeError(f"[{submit['error']['code']}] {submit['error']['message']}")
   
           # 2. Fetch the result
           for _ in range(40):
               doc = (await client.get(f"{API}/documents/{submit['document_id']}", headers=HEADERS)).json()
               if doc["status"] == "completed":
                   return doc["data"]
               if doc["status"] == "failed":
                   raise RuntimeError(f"Extraction failed: {submit['document_id']}")
               await asyncio.sleep(1.5)
       raise TimeoutError(submit["document_id"])

Full working example

import os, time, requests

API = "https://docuparseapi.com/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['DOCUPARSE_API_KEY']}"}

def parse_document(path: str) -> dict:
    # 1. Submit
    with open(path, "rb") as f:
        submit = requests.post(f"{API}/extract", headers=HEADERS,
                               files={"file": (os.path.basename(path), f)}, timeout=30).json()
    if not submit.get("success"):
        raise RuntimeError(f"[{submit['error']['code']}] {submit['error']['message']}")

    # 2. Fetch the result
    for _ in range(40):
        doc = requests.get(f"{API}/documents/{submit['document_id']}",
                           headers=HEADERS, timeout=30).json()
        if doc["status"] == "completed":
            return doc["data"]
        if doc["status"] == "failed":
            raise RuntimeError(f"Extraction failed: {submit['document_id']}")
        time.sleep(1.5)
    raise TimeoutError(submit["document_id"])

data = parse_document("invoice.pdf")
print(data["merchant"], data["total"], data["currency"])