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

Send raw vCard text or upload as a file — both are supported.

Quickstart (cURL)

curl -X POST https://api.correctvcf.com/api/validate-vcf \
  -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'
  },
  body,
});
const data = await res.json();

Python (requests)

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

Quickstart (cURL)

curl -X POST https://api.correctvcf.com/api/validate-vcf \
  -F "[email protected]"

JavaScript (fetch)

const form = new FormData();
form.append('file', new Blob([/* file bytes */], { type: 'text/vcard' }), 'contacts.vcf');

const res = await fetch('https://api.correctvcf.com/api/validate-vcf', {
  method: 'POST',
  body: form,
});
const data = await res.json();

Python (requests)

import requests
files = { 'file': ('contacts.vcf', open('contacts.vcf','rb'), 'text/vcard') }
r = requests.post('https://api.correctvcf.com/api/validate-vcf', files=files)
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/plain or multipart/form-data. You can enable autofix behaviour with a query param or header.

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 (`1` to enable).
`x-correctvcf-uid-host`	Alternate way to specify UID host used during autofix.
`cf-turnstile-response`	Cloudflare Turnstile token (required for some browser-origin requests).

POST /api/autofix-vcf

Apply safe autofixes to a VCF payload. Returns the fixed text and a list of changes indicating which rules were applied.

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

Error reference

Status	Meaning	Notes
`200`	Validation succeeded	Warnings may still be present.
`422`	Validation failed	See `issues[]` for details.
`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