Build a vCard QR payload string

The result is a deterministic text string with the required vCard markers, safe escaping, and interoperable line endings. Paste that payload into a QR encoder or pass it to the next step in an automated pipeline. A name is required, while every other contact field is optional, so the same operation works for a minimal personal card or a more complete business contact.

Build the contact payload before generating the QR code

A contact QR code normally contains structured text rather than an image-specific contact format. This capability creates that structured layer for you: a vCard 3.0 payload beginning with BEGIN:VCARD, declaring VERSION:3.0, providing the required formatted name, and ending with END:VCARD. Supply a non-empty name and optionally add a phone number, email address, and organization. Blank optional values are left out instead of producing meaningless empty properties. The returned payload can then become the text input to any standards-aware QR code encoder. Keeping payload construction separate from image generation is useful because you can inspect, store, test, or reuse the contact data before choosing QR dimensions, error correction, colors, or output format. It also makes failures easier to diagnose: if a scanner recognizes the vCard text but the printed symbol is hard to read, the problem belongs to QR rendering rather than contact formatting. The operation is deterministic, so identical inputs produce identical payload strings every time.

Understand escaping, line endings, and optional properties

vCard values are not arbitrary lines of text. Backslashes, commas, semicolons, and embedded line breaks have structural meanings, so raw concatenation can change the contact or produce a payload that different address-book applications interpret inconsistently. This builder escapes those characters in every supplied value and uses CRLF line endings expected by the vCard format. A line break inside an organization or name becomes an escaped newline within one property rather than an accidental new vCard property. The name is written as FN, the display-name property required for this compact contact card. Phone, email, and organization become TEL, EMAIL, and ORG only when their trimmed values are non-empty. Input strings are trimmed at their outer edges, but meaningful characters within each value remain intact. The output also includes a final CRLF after END:VCARD, which makes the payload suitable for systems that expect a conventionally terminated text record. These choices favor a small, predictable QR payload while preserving the contact information supplied by the caller.

Use the payload reliably in QR and automation workflows

Take the returned payload field exactly as produced and provide it as the text content of your QR generator. Do not JSON-stringify it a second time or replace the line endings with visible slash characters; the QR symbol must encode the actual vCard text. After rendering, test the code with more than one camera or contact application when it will be printed or distributed broadly. Scanner behavior, print size, contrast, and QR error-correction settings are outside this capability, even though they affect the final experience. For automation, keep the structured source fields alongside the generated payload so a contact change can regenerate the card cleanly instead of editing encoded text. Validate email and telephone semantics upstream if your product requires strict business rules: this operation treats them as contact strings and focuses on vCard-safe serialization. The API costs $0.002 for each successful request, while the browser experience can run the same pure transformation locally. Invalid calls with an empty or whitespace-only name return an input error instead of creating a contact that address books cannot label usefully.