CorrectVCF API

Validate and inspect .vcf (vCard) files using simple HTTP endpoints. You can self-host the documentation via the OpenAPI spec or start with the examples below.

Base URL: https://api.correctvcf.com

Download OpenAPI 3.0 Spec Try the Web Tool

Quickstart

Quickstart (cURL)

curl -X POST https://api.correctvcf.com/api/validate-vcf \
  -H "Authorization: Bearer <API_KEY>" \
+  -H "Content-Type: text/vcard" \
  --data-binary @contacts.vcf

JavaScript (fetch)

const body = /* string or Buffer of file contents */ '';

const res = await fetch('https://api.correctvcf.com/api/validate-vcf', {
  method: 'POST',
  headers: {
    'Content-Type': 'text/vcard',
    'Authorization': 'Bearer <API_KEY>',
  },
  body,
});
const data = await res.json();

Python (requests)

import requests
headers = {
  'Content-Type': 'text/vcard',
    'Authorization': 'Bearer <API_KEY>',
}
data = open('contacts.vcf','rb').read()
r = requests.post('https://api.correctvcf.com/api/validate-vcf', data=data, headers=headers)
print(r.json())

Common behaviour

Free tier rate limit: 5 requests/minute per IP, enforced via Durable Object.
All responses include X-Request-Id — reference it if you contact support.
Validation failures return HTTP 422 with issues[] and meta.
Rate limit breaches return HTTP 429 with Retry-After, X-RateLimit-Limit, and X-RateLimit-Remaining.
VCF payloads are processed in memory and not persisted; logs only retain request metadata.

POST /api/validate-vcf

Validate a single VCF payload supplied as text/vcard or text/plain, or upload via multipart/form-data using a file field. Add query params or headers to enable autofix behaviour.

Query	Description
`policy`	Validation profile (e.g., `rfc` default, or vendor profiles such as `apple`, `google`, `outlook`).
`autofix`	`1` enables safe autofixes (e.g., insert VERSION, normalize emails/phones, fix folding).
`uid_host`	Domain suffix used when generating UIDs during autofix.

Header	Description
`x-correctvcf-autofix`	Alternate way to enable autofixes.
`x-correctvcf-uid-host`	Alternate way to specify UID host.
`cf-turnstile-response`	Cloudflare Turnstile token (required for some browser-origin requests).

curl -X POST https://api.correctvcf.com/api/validate-vcf \
  -H "Content-Type: text/plain" \
  --data-binary @contacts.vcf

Example 200 response

{
  "ok": true,
  "issues": [],
  "meta": {
    "count": 1,
    "format": "vcard",
    "policy": "rfc6350"
  }
}

Example 422 response

{
  "ok": false,
  "issues": [
    { "code": "RFC.VCARD.VERSION.MISSING", "level": "error", "message": "vCard is missing VERSION property" }
  ],
  "meta": {
    "count": 1,
    "format": "vcard",
    "policy": "rfc6350"
  }
}

POST /api/validate-bulk

Validate multiple VCF files by uploading a ZIP archive. The same query params/headers as the single endpoint apply to every file.

Maximum 50 files per archive.
Maximum 5 MiB total uncompressed size.
Only entries ending in .vcf are processed (others ignored).

zip contacts.zip a.vcf b.vcf
curl -X POST https://api.correctvcf.com/api/validate-bulk \
  -H "Content-Type: application/zip" \
  --data-binary @contacts.zip

The response aggregates per-file results:

{
  "ok": false,
  "issues": [],
  "meta": {
    "count": 2,
    "format": "vcard",
    "policy": "rfc6350"
  },
  "files": [
    { "name": "a.vcf", "status": 200, "result": { "ok": true, "issues": [] } },
    { "name": "b.vcf", "status": 422, "result": { "ok": false, "issues": [{ "code": "RFC.VERSION.MISSING" }] } }
  ]
}

Error reference

Status	Meaning	Notes
`200`	Validation succeeded	Warnings may still be present.
`422`	Validation failed	See `issues[]`, `meta`.
`400`	Invalid bulk archive	ZIP could not be parsed.
`413`	Bulk limit exceeded	Too many files or >5 MiB uncompressed.
`429`	Rate limit reached	Respect `Retry-After` before retrying.
`500`	Internal error	Retry and include `X-Request-Id` if reporting.

Discovery

Lightweight endpoints to check service status and client capabilities.

GET /api/health

curl https://api.correctvcf.com/api/health

GET /api/version

curl https://api.correctvcf.com/api/version

GET /api/caps

curl https://api.correctvcf.com/api/caps

Next steps

Higher plan limits, API keys, and webhook integrations are on the roadmap. Submit issues and requests on the repo for updates or drop us a note via the contact form.

OpenAPI (machine-readable): /docs/openapi.yaml