vCard QR codes on iOS: why they work, and why they sometimes don't

On iOS, a contact QR code is read by the Camera app, which shows a small contact sheet with an "Add to Contacts" button — it never adds anything automatically. Codes that fail do so for a short list of reasons: the payload is not valid vCard, the line endings are wrong, required fields are missing, or the escaping breaks a value in half. Version 3.0 of the format, with CRLF line endings, is the dialect that behaves predictably across iOS versions.

Android reads the same format but presents it differently, which matters if your code has to work for both.

What iOS actually does with the scan

Point the Camera app at a contact code and iOS parses the vCard, then displays a sheet with the name, phone numbers and email addresses it found, plus an "Add to Contacts" action. Nothing is written to the address book until that button is tapped. If the parse fails, you get either raw text or a generic link preview — that is the signal that the payload, not the print, is the problem.

The camera sheet is deliberately conservative. It shows one contact per scan, and it will not merge into an existing record by itself; that decision is left to the person scanning. Designers who expect the scan to silently update a CRM-style record are expecting something the platform does not do.

The fields that decide whether it works

PropertyWhat it isWhy it matters on iOS
BEGIN:VCARD / END:VCARDEnvelopeWithout both, the parser discards the payload
VERSION:3.0Format version4.0 is partially supported and behaves inconsistently across apps; 3.0 is the safe target
NStructured name, five semicolon-separated partsDrives sorting and duplicate detection; a malformed N produces odd display names
FNFormatted nameRequired in 3.0 and used as the sheet's title; omit it and some parsers reject the record
TEL;TYPE=CELLPhone with a typeUntyped numbers import as "other" and are easy to miss
EMAIL;TYPE=INTERNETEmail with a typeSame problem: untyped values land in the wrong bucket
ORGCompanyCommas inside the value must be escaped or the company is truncated
URLWebsiteNeeds a full scheme; a bare domain is not always linkified

One structural detail is easy to get wrong: N takes five parts separated by semicolons — family, given, additional, prefix, suffix. A record for Dana Whitfield is N:Whitfield;Dana;;;. Leaving the trailing semicolons off is tolerated by some parsers and rejected by others, and it is the usual cause of a contact appearing as a single blob with the surname in the wrong field.

Why the same contact shows up twice

Duplicate entries after a scan come from three places, and none of them is a bug in the format:

  • Scanning twice. Each scan produces a new record; iOS does not deduplicate on import. A code on a lanyard gets scanned more than once by the same person.
  • Two different codes for the same person. A printed badge and a slide deck generated separately can differ in FN or phone formatting, which looks like a different contact to the address book.
  • Inconsistent phone formatting. +1 415 555 0132 and 4155550132 are different strings even though the number is the same. Pick one format and keep it across every code you issue.

There is no clean fix on the code side beyond consistency. Write one canonical record per person, store it, and generate every code from that source.

Escaping, again, but with different characters

vCard has its own escaping rules, and they are not the WiFi ones. Inside a property value, four characters need a backslash: backslash itself, semicolon, comma, and newline (written as \n). Colons and quotes are fine.

Wrong: ORG:Northline Studio, Ltd
Right: ORG:Northline Studio\, Ltd

The wrong version is the interesting one: many parsers split on the comma and keep "Northline Studio", silently dropping the rest. Nobody notices until someone searches for the company name and finds a truncated entry. A semicolon in a company name — "Studio; Partners" — is worse, because it can shift the value into the next field entirely.

This generator escapes those four characters in name, company and any other text field, and prints the payload so the backslashes are visible before you print.

Line endings are not cosmetic

vCard is a line-based format and the specification requires CRLF between properties. Parsers are supposed to accept LF alone, and most do, but the failure mode when they do not is ugly: the whole record collapses into one line and the phone shows a wall of text instead of a contact sheet.

If you are generating codes from a script, write \r\n explicitly. If you are editing a vCard in a text editor, check that the file did not get converted to Unix line endings on save. The generator emits CRLF for exactly this reason.

Photos, notes and payload size

An embedded photo is base64 text inside the payload, and a single thumbnail can add several kilobytes. That forces a much higher QR version, which means smaller modules at the same printed size — the trade-off described in the capacity guide. For a business card code, leave the photo out. If the identity needs a face, print it next to the code.

Notes fields are the other common bloat source. A full bio in a NOTE property turns a 200-byte record into a 900-byte one, and for no benefit: nobody reads a paragraph inside a contact sheet.

What Android does differently

Android's camera and scanner apps usually show a preview card with an "Add" action, and some OEM skins offer to append the new details to an existing contact — behaviour iOS does not have. The payload is the same, but two things change in practice:

  • Android tends to be more tolerant of missing N parts and LF-only line endings, so a code that works on Android may still fail on iOS. Test on iOS first if your audience is mixed.
  • Third-party scanner apps on Android sometimes only offer "copy text" for a vCard payload, which looks like a failure but is a limitation of that app.

Testing a contact code properly

  1. Generate the code, then read the payload box and check every line ends where you expect it to.
  2. Scan with an iPhone using the Camera app, not a third-party scanner, and confirm a contact sheet appears rather than raw text.
  3. Tap "Add to Contacts", then open the saved record and check the company name, the phone type and the website.
  4. Delete the test contact before you hand the code to anyone.
  5. If the code is going into print, repeat the test on the printed proof.

Frequently asked questions

Does iOS save the contact automatically?

No. The Camera app shows a preview and requires a tap on "Add to Contacts". No contact QR format can bypass that confirmation, and any tool claiming otherwise is describing Android behaviour or its own app.

Why does my phone show plain text instead of a contact?

Usually the payload is not valid vCard: a missing BEGIN or END line, a missing VERSION, no FN, or LF-only line endings that collapsed the record. Check the payload readout against the table above, then reprint.

Can I put a photo in the contact code?

Yes, but it is rarely worth it. Base64 images inflate the payload dramatically, which raises the symbol version and shrinks the modules at any given print size. Print the photo beside the code instead.

Build a vCard code with the fields in the order iOS expects, CRLF line endings and automatic escaping, then verify the output in the payload box before printing. If a printed code has already stopped working, start with the failure checklist.

Written by the QRQuick team. Last updated November 19, 2026.