Calendar & Contacts

The unified calendar/contact converter moves data between vcard (.vcf address books), ics (iCalendar / RFC 5545 event feeds), and json. It is the building block behind the individual vcard-to-json, json-to-vcard, ics-to-json, and json-to-ics endpoints.

Use it to normalize contact and event data across systems — CRMs, mail clients, scheduling services, and custom apps.

Base URL

https://convert.toolkitapi.io

Endpoints

Method Endpoint Purpose
POST /v1/convert/calendar Convert between vcard, ics, and json

Authentication is via the X-API-Key header (or Authorization: Bearer).

Note

A pre-rendered copy of this page exists at _archive/calendar-and-contacts.md. This page is the canonical per-slug reference for the /v1/convert/calendar route.


Request Body

Field Type Required Description
from_format string Yes Source format: vcard, ics, json
to_format string Yes Target format: json, vcard, ics
data string | object Yes Inline source content (a string for vcard/ics, a JSON value for json)
calendar_name string No Calendar name used for ICS output

Supported Conversions

From To
vcard json
ics json
json vcard, ics

Direct vcard ↔ ics conversion is not supported — route through json.


Response Fields

Field Type Description
result string | any Converted payload (a string for vcard/ics, structured JSON for json)
count integer Number of contacts or events converted

REST API Examples

vCard → JSON

curl -X POST "https://convert.toolkitapi.io/v1/convert/calendar" \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from_format": "vcard",
    "to_format": "json",
    "data": "BEGIN:VCARD\nVERSION:3.0\nFN:Alice Example\nEMAIL:[email protected]\nEND:VCARD"
  }'
{
  "result": [{"fn": "Alice Example", "email": "[email protected]"}],
  "count": 1
}
const resp = await fetch("https://convert.toolkitapi.io/v1/convert/calendar", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({
    from_format: "vcard",
    to_format: "json",
    data: "BEGIN:VCARD\nVERSION:3.0\nFN:Alice Example\nEMAIL:[email protected]\nEND:VCARD",
  }),
});
const data = await resp.json();
console.log(data.count, data.result);

JSON → vCard

curl -X POST "https://convert.toolkitapi.io/v1/convert/calendar" \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from_format": "json",
    "to_format": "vcard",
    "data": {
      "fn": "Jane Doe",
      "email": "[email protected]",
      "tel": "+1-555-234-5678",
      "org": "Acme Corp",
      "title": "Product Manager",
      "url": "https://janedoe.toolkitapi.io"
    }
  }'
const contact = {
  fn: "Jane Doe",
  email: "[email protected]",
  tel: "+1-555-234-5678",
  org: "Acme Corp",
};

const resp = await fetch("https://convert.toolkitapi.io/v1/convert/calendar", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ from_format: "json", to_format: "vcard", data: contact }),
});
const { result } = await resp.json();
console.log(result); // "BEGIN:VCARD\nVERSION:3.0\nFN:Jane Doe\n..."

ICS → JSON

curl -X POST "https://convert.toolkitapi.io/v1/convert/calendar" \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from_format": "ics",
    "to_format": "json",
    "data": "BEGIN:VCALENDAR\nVERSION:2.0\nBEGIN:VEVENT\nSUMMARY:Standup\nDTSTART:20260101T090000Z\nEND:VEVENT\nEND:VCALENDAR"
  }'

Python SDK Examples

vCard → JSON

from toolkitapi import Convert

cv = Convert(api_key="tk_...")

result = cv.calendar(
    from_format="vcard",
    to_format="json",
    data="BEGIN:VCARD\nVERSION:3.0\nFN:John Smith\nEMAIL:[email protected]\nEND:VCARD",
)

print(result["count"])   # 1
print(result["result"])  # [{"fn": "John Smith", "email": "[email protected]"}]

JSON → ICS

from toolkitapi import Convert

cv = Convert(api_key="tk_...")

event = {
    "summary": "Product review",
    "dtstart": "2026-02-10T15:00:00Z",
    "dtend": "2026-02-10T16:00:00Z",
    "location": "Zoom",
}

result = cv.calendar(
    from_format="json",
    to_format="ics",
    data=event,
    calendar_name="Work",
)
print(result["result"])  # BEGIN:VCALENDAR ...

Use Cases

  • CRM import/export — Move contacts between CRMs that prefer different formats.
  • Calendar sync — Convert ICS feeds into JSON for custom scheduling UIs.
  • Contact migration — Bulk-convert .vcf address books to JSON.
  • Event publishing — Generate ICS files from JSON event data.

FAQs

Which pairs are supported?

vcard ↔ json and ics ↔ json. Direct vcard ↔ ics is not supported — convert via JSON.

Which vCard / iCalendar versions?

vCard 3.0 and 4.0 are supported. iCalendar output is RFC 5545 compatible.

Are recurring events preserved?

Yes — RRULE fields round-trip between ICS and JSON.

Errors

Status Meaning
400 Unsupported conversion pair or malformed source data
401 Missing or invalid API key
422 Request body failed schema validation