How Credits, Quotas & Deduplication Work
Credit accounting in CVFormatter is strictly deterministic and predictable. You are only charged when novel document bytes are ingested or when automated AI proofreading is explicitly requested. Polling status, downloading structured JSON, and exporting Word (.docx) files are always completely free.
Understanding organization credit pools
When you inspect your organization via GET /credits, your balances are drawn in real time from three prioritized account buckets:
Complimentary credits issued upon workspace signup. Consumed first before any subscription allocation is drawn.
Recurring monthly allowance refreshed at the start of your billing cycle. Consumed automatically once starter credits reach zero.
On-demand credit top-ups that never expire. Acts as overflow protection when monthly limits are exceeded during hiring surges.
API operation credit matrix
Reference this breakdown to calculate pipeline costs and ensure you never encounter unexpected rate overages:
| Operation | Endpoint Route | Credit Impact |
|---|---|---|
| Upload new candidate resume | POST /resumes | −1 Resume credit |
| Upload with auto-proofread enabled | POST /resumes (auto_proofread=true) | −1 Resume + −1 Proofread credit |
| Upload duplicate file binary | POST /resumes | 0 credits (Deduplicated FREE) |
| Poll parsing status | GET /resumes/:id | 0 credits (Unlimited FREE) |
| Fetch extracted structured JSON | GET /resumes/:id/data | 0 credits (Unlimited FREE) |
| Export / Download DOCX document | POST /resumes/:id/export | 0 credits (Unlimited FREE) |
| Generate 30-day web preview link | POST /resumes/:id/preview | 0 credits (Unlimited FREE) |
| Force reprocess original file | POST /resumes/:id/reprocess | −1 Resume credit |
Zero-cost content hashing & deduplication rules
Recruiting platforms and webhook listeners often retry or submit duplicate applicant files by mistake. To protect your organization against accidental credit exhaustion, CVFormatter applies cryptographic content hashing to every upload:
When a file binary is received at POST /resumes, our edge gateway computes its SHA-256 hash. If that exact hash has been parsed inside your organization within the past 30 days, the engine bypasses OCR and LLM model extraction entirely.
deduplicated: trueThe API immediately returns the existing resume record with "deduplicated": true and "credits_reserved": 0. Your integration can immediately retrieve the parsed structured JSON without waiting for re-parsing.
Deduplication looks exclusively at underlying raw file bytes, not the file name. Uploading John_Doe.pdf and then uploading the identical document as Resume_Final_2026.pdf will correctly trigger duplicate protection and cost zero credits.
Auto-Proofread add-on quotas & rules
Auto-Proofread runs our fine-tuned editorial LLM across parsed candidate profiles to standardize punctuation, fix grammar mistakes, verify chronological consistency, and enhance impact verbs. Proofreading credits operate under dedicated quota rules:
Explicit Opt-In: Auto-proofreading is never triggered automatically unless you set auto_proofread: true in your multipart form submission or during a reprocess call.
Balance Check via can_use: Before queueing large batches, verify that auto_proofread.can_use returns true in GET /credits. This confirms your organization has available credits and an active subscription add-on.
Concurrent Run Locking: If an automated proofreading job is already running on a resume, subsequent reprocess requests specifying {"auto_proofread": true} will return an HTTP 409 conflict to prevent double credit deduction.
Why polling, queries, and document exports are always free
Unlike legacy parsers that charge per query or assess hidden fees for Word exports, CVFormatter only meters GPU compute during initial file parsing. Once a resume enters COMPLETED status:
- You can fetch structured candidate JSON via
GET /resumes/:id/dataas many times as necessary to sync your database. - You can render and download branded Word (.docx) files across multiple template themes without spending additional credits.
- You can generate shareable 30-day preview links for internal client hiring managers at no additional cost.