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
.vcfaddress 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 |