parserail

Official Python SDK for ParseRail — the AI back-end for your product. Parse documents, extract fields, redact PII, analyze contracts, fight chargebacks, and enrich companies.

pip install parserail

Quickstart

from parserail import ParseRail

client = ParseRail(api_key="ksk_live_...")

doc = client.parse(file_url="https://.../invoice.pdf")
print(doc["totalAmount"])              # 4820.5
print(doc["usage"]["balanceRemaining"])  # 1990

Get a key at parserail.thecompound.tech. There is no free tier. Credits are bought up front. Zero dependencies, stdlib only, Python 3.8+.

Dry run

A new key has a zero balance. Pass dry_run=True to check your key and request bodies before you buy credits:

client = ParseRail(api_key="ksk_live_...", dry_run=True)
check = client.sentiment(text="The product works well.")
print(check["wouldCharge"], check["balance"], check["liveStatus"])  # 2 0 402

The client sends ParseRail-Dry-Run: 1 on every call. The API checks the key, the rate limit, the body and the balance. It runs no model and charges nothing. An invalid body raises ParseRailError with code invalid_request, the same as a live call.

Methods

Every method returns the endpoint result as a dict, including a usage envelope. A non-2xx response raises a typed ParseRailError (and never burns credits).

client.parse(file_url=...)                                  # documents → JSON
client.extract(text=..., fields=["order", "total"])         # pull named fields
client.classify(text=..., labels=["billing", "tech"])       # label text
client.summarize(text=..., length="standard")               # summary + actions
client.redact(text=...)                                      # strip PII/PHI
client.sentiment(text=..., aspects=["product"])             # sentiment + aspects
client.contract(file_url=...)                               # contract → terms + risks
client.chargeback(reason=..., transaction={"amount": 129})  # representment packet
client.enrich(email="sam@stripe.com")                       # company profile
client.account()                                            # balance

Async & webhooks

A hundred-page contract doesn't fit in a request/response cycle. The document endpoints — parse, invoice, receipt, statement, resume, tables, split, compare, contract — take async_=True and hand you a job instead of a result. (async is a Python keyword, hence the trailing underscore; the wire field is async.)

job = client.parse(file_url="https://.../contract.pdf", async_=True)
done = client.wait_for_job(job["jobId"])

if done["status"] == "succeeded":
    print(done["result"]["totalAmount"])
else:
    print(done["error"])          # failed jobs are never charged

Use client.get_job(job_id) for a single poll if you'd rather drive the loop yourself.

Every job reaches a terminal state. If the instance running yours dies mid-flight, it is marked failed with an explanation rather than left running forever — and you aren't billed for it. Nothing is silently retried; resubmit and you stay in control of the spend.

Webhooks

Pass a callback_url (public https) and the finished job is POSTed to it, signed with your account's webhook secret from the API keys page:

client.parse(file_url=..., async_=True, callback_url="https://you.example/hooks/parserail")

import hmac, hashlib

# X-ParseRail-Signature: sha256=<hex HMAC-SHA256 of the RAW body>
def verify(raw_body: bytes, header: str, secret: str) -> bool:
    expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(header.removeprefix("sha256="), expected)

Delivery is best-effort and never retried — polling is the source of truth.

Error handling

from parserail import ParseRail, ParseRailError

client = ParseRail(api_key="ksk_live_...")
try:
    client.parse(file_url="https://.../invoice.pdf")
except ParseRailError as err:
    # err.code: "insufficient_credits" | "rate_limited" | "unauthorized" | ...
    print(err.code, err.status, err.message)