# vCard API
> Generate and parse vCard (.vcf) contact cards. Build a standards-compliant vCard 3.0 from simple fields — name (or first/last), organisation, job title, one or more phone numbers and emails, websites, a postal address, birthday, note and a photo URL — ready to download as a .vcf or embed in a contact QR code (pair it with the QR API for "scan to save contact"). Or go the other way: parse any vCard string back into clean structured fields. Pure local processing — no key, no third-party service, nothing stored. Live. 3 endpoints. Built for digital business cards, contact QR codes, address-book import/export, CRM integrations and email-signature tools.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/vcard-api/..."
```

## Pricing
- **Free** (Free) — 1,600 calls/Mo, 2 req/s
- **Starter** ($8/Mo) — 33,000 calls/Mo, 8 req/s
- **Pro** ($27/Mo) — 192,000 calls/Mo, 20 req/s
- **Mega** ($63/Mo) — 980,000 calls/Mo, 50 req/s

## Endpoints

### vCard

#### `GET /v1/generate` — Generate a vCard

**Parameters:**
- `first_name` (query, optional, string) — First name Example: `Ada`
- `last_name` (query, optional, string) — Last name Example: `Lovelace`
- `org` (query, optional, string) — Organisation Example: `Analytical Engine`
- `title` (query, optional, string) — Job title
- `phone` (query, optional, string) — Phone(s), comma-separated Example: `+1-555-0100`
- `email` (query, optional, string) — Email(s), comma-separated Example: `ada@example.com`
- `url` (query, optional, string) — Website(s)
- `city` (query, optional, string) — City
- `country` (query, optional, string) — Country
- `birthday` (query, optional, string) — Birthday (YYYY-MM-DD)
- `note` (query, optional, string) — Note

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/vcard-api/v1/generate?first_name=Ada&last_name=Lovelace&org=Analytical+Engine&phone=%2B1-555-0100&email=ada%40example.com"
```

**Response:**
```json
{
    "data": {
        "lines": 8,
        "vcard": "BEGIN:VCARD\r\nVERSION:3.0\r\nN:Lovelace;Ada;;;\r\nFN:Ada Lovelace\r\nORG:Analytical Engine\r\nTEL;TYPE=CELL,VOICE:+1-555-0100\r\nEMAIL;TYPE=INTERNET:ada@example.com\r\nEND:VCARD"
    },
    "meta": {
        "timestamp": "2026-06-02T16:52:02.387Z",
        "request_id": "8ad1411a-bd59-41f4-8346-d6a31092ce76"
    },
    "status": "ok",
    "message": "Generate a vCard",
    "success": true
}
```

#### `GET /v1/parse` — Parse a vCard

**Parameters:**
- `vcard` (query, required, string) — vCard text to parse Example: `BEGIN:VCARD
VERSION:3.0
FN:Ada Lovelace
EMAIL:ada@example.com
TEL:+1-555-0100
END:VCARD`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/vcard-api/v1/parse?vcard=BEGIN%3AVCARD%0AVERSION%3A3.0%0AFN%3AAda+Lovelace%0AEMAIL%3Aada%40example.com%0ATEL%3A%2B1-555-0100%0AEND%3AVCARD"
```

**Response:**
```json
{
    "data": {
        "urls": [],
        "emails": [
            "ada@example.com"
        ],
        "phones": [
            "+1-555-0100"
        ],
        "full_name": "Ada Lovelace"
    },
    "meta": {
        "timestamp": "2026-06-02T16:52:02.499Z",
        "request_id": "024aee86-ac17-4b8d-aa74-bc9cc2836e7f"
    },
    "status": "ok",
    "message": "Parse a vCard",
    "success": true
}
```

### Meta

#### `GET /v1/meta` — Spec

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/vcard-api/v1/meta"
```

**Response:**
```json
{
    "data": {
        "auth": "none upstream; this gateway requires x-api-key",
        "name": "vCard API",
        "note": "Generate a vCard (.vcf) from fields (name/first_name/last_name, org, title, phone, email, url, address fields, birthday, note, photo_url — phone/email/url accept comma-separated lists) via /v1/generate, and parse a vCard back into structured fields via /v1/parse. vCard 3.0 for broad compatibility (incl. contact QR codes — pair with the QR API). Instant, nothing stored.",
        "source": "Local vCard 3.0 build/parse — no key, no upstream",
        "endpoints": 3
    },
    "meta": {
        "timestamp": "2026-06-02T16:52:02.603Z",
        "request_id": "face0f90-dd4e-48be-9fab-7c03f99f2998"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


---
Marketplace page: https://www.oanor.com/api/vcard-api
OpenAPI spec: https://www.oanor.com/api/vcard-api/openapi.json