Introduction
Typing all those paper business cards you pile up at trade shows into a CRM by hand is a real chore. So at work, I built a feature where "you upload a PDF (or images) stuffed with business cards, and it automatically bulk-registers the company and contact data."
At first I thought, "Just throw it at OCR and we're done." But once I actually tried it, I realized that OCR isn't as all-powerful as you'd think, and that the design decision of where to split the processing is the real key. In this post I'll share those key points, plus the problem I agonized over the most: "What do we do when a single page has multiple business cards lined up on it?"
The Overall Flow
- Upload a file (PDF / JPEG / PNG)
- Validate on the server side (format, size, page count)
- Create an "importing" history record and return a response right away
- Run the heavy work (OCR → structuring → create/update) in a background job
- The frontend polls the history ID and shows progress
The point is to cleanly separate "accepting" from "the actual processing." OCR and record matching can take anywhere from tens of seconds to several minutes, so if you try to do everything synchronously inside the request, it times out. The accepting API wraps up neatly at "save the file, create the history record, and kick off the job."
OCR Is a "Two-Step" Process
Reading a business card actually splits into two different processes.
- Reading the text (OCR) … Extract strings from the image. This is the job of a general-purpose OCR like Google Cloud Vision.
- Sorting into fields (structuring) … Decide which parts of the extracted text are "the company name, the person's name, the phone number," and so on. This is the job of our own field extraction model.
Card image → ① OCR (read all the text) → text → ② Structuring (sort into fields) → { company name, name, email... }
It's easy to assume "OCR = does everything, including structuring," but ① only outputs text and positions, and ② only organizes that into fields. They're separate roles.
Design Points That Paid Off
Validate based on the "contents."
If you check "is this a PDF?" by file extension or Content-Type, someone can get past it just by renaming an image to .pdf. It's safer to determine the real type from the magic bytes at the start of the file.
Don't load big files into memory.
A file with 100 business cards gets big. When sending it to storage (S3, etc.), stream it straight through without reading the whole thing into memory. The size check also looks only at metadata, not the contents.
Check the PDF page count with a lightweight read.
If all you want is to reject "more than N pages" at upload time, an image rendering library (ImageMagick, etc.) is way too heavy. Counting pages doesn't need rendering; reading the metadata with a lightweight PDF parser is plenty.
The Problem I Agonized Over Most: "Multiple Cards on One Page"
While nailing down the requirements, this case came up: multiple business cards lined up in a single scanned image (one page of a PDF). If you scan several cards at once on a copier or flatbed scanner, that's naturally what you get.
OCR doesn't split things "per card"
This was my blind spot. A general-purpose OCR (Vision, etc.) returns "all the text on the page + the position coordinates of each piece of text," but it has no feature to logically separate "which text belongs to which card" (Google Cloud Vision's official docs also clearly state that there's no built-in feature for identifying and separating multiple documents on one page, and that you need your own logic that analyzes block positions).
On top of that, OCR "blocks" (chunks of text) are grouped by layout proximity, so neighboring cards get merged into one, or a single card gets split into several. "1 block = 1 card" just doesn't hold.
The structuring model also assumes it's sorting "the text of one business card," so if you pass it text from multiple cards mixed together, you end up with bogus data that merges "Company A's name + Mr. B's name."
So we need to add our own "split per card" step
OCR (all text + coordinates) → [our own] split per card → Card A part → structuring
→ Card B part → structuring → …
How hard this splitting is depends heavily on how the cards are arranged.
| Arrangement | Approach | Difficulty |
|---|---|---|
| Fixed template (always 2×3, etc.) | Divide the page into fixed equal parts | Low (but every user is forced into the same arrangement) |
| Neatly arranged, but variable count | Dynamically detect rows/columns from "gaps" in the coordinates | Medium (rule-based; weak against tilt, cards touching, empty cells) |
| Completely random | Prepare an AI model that detects card regions | High (requires training and operating a model) |
The middle option, "infer the grid from coordinates," is a rule-based process that looks something like this:
- Collect the coordinates of all the text
- Treat large gaps in the X coordinates as "column boundaries"
- Treat large gaps in the Y coordinates as "row boundaries"
- Treat each cell as one card and group the text accordingly
Since it's geometry rather than AI, it's relatively lightweight, but it falls apart with tilt, cards touching each other, uneven sizes, and empty cells. The more robust you try to make it, the more tuning on real data you need, and if you push it all the way, you end up drifting toward "just detect the cards themselves with AI."
Lesson: if you can add "constraints" on the spec side, things get way easier
Rather than forcing tech to handle randomly placed cards, setting input constraints like "please scan the cards evenly spaced" cuts both development cost and accuracy risk dramatically. "How much input do we accept?" shouldn't be decided by engineers alone; it's something we should have aligned on with the product side early.
Handling Duplicate Data (Record Matching)
With bulk registration, duplicates with "companies/contacts that are already registered" are unavoidable. Here we have the user choose in advance:
- Companies are matched by "company name" or "company name + address" (address is an option because some people want to distinguish branch offices)
- Contacts are matched by email address
Matches are treated as updates, and non-matches as new records. We also let the user choose "whether to overwrite existing data with the card's values on a duplicate" (because some people don't want their data overwritten without asking).
Summary
- OCR is a two-step process: "read the text" + "sort into fields." OCR alone doesn't get you all the way to structured data.
- Separate accepting from the actual processing, and send heavy work to async jobs. Stream large files, and validate by contents.
- The biggest trap is "multiple cards per page." OCR won't split by card, so you have to implement the splitting yourself, and the difficulty changes drastically depending on the arrangement.
- That's exactly why agreeing with the product side on "how much we can constrain the input" is just as important as choosing the technology.
It was a great example of how the features that look like "just throw it at OCR" are actually the ones where designing the requirements and constraints matters most.
(Epilogue)
After all that groaning over "how do we split it if there are multiple cards on a page…", I checked with the product side and—
"We're assuming one business card per PDF page."
…Yep. A whole lot of worrying over nothing. lol
Still, I learned a lot. Before you throw tech at a problem, question the requirements first. A fine lesson, if I do say so myself.
Top comments (0)