vCards
Round-trip contacts through the RFC 6350 vCard format. Use these endpoints to migrate contacts from Apple Contacts, Google Contacts, LinkedIn exports, or other vCard-producing address books.
Import vCards POST
POST /contacts/importBulk-import contacts from a vCard body. The request body must be text/vcard or text/x-vcard, UTF-8 encoded, and at most 5 MB containing up to 1000 cards.
Each card is imported in isolation, so one bad card doesn't poison the rest. The response is always 200 OK — partial failure is reflected in the created_count / error_count and per-card results list.
Request headers
| Header | Required | Description |
|---|---|---|
Content-Type | Yes | text/vcard or text/x-vcard |
X-API-Key | Yes | Your API key |
Response (200)
JSON| Field | Type | Description |
|---|---|---|
created_count | integer | Number of contacts created |
error_count | integer | Number of cards that failed to import |
results[].index | integer | 0-based position within the uploaded stream |
results[].status | string | "created" or "error" |
results[].contact | object | Full Contact object (when status == "created") |
results[].error | string | Rejection reason (when status == "error") |
Error responses
| Status | Description |
|---|---|
| 400 | Body is not UTF-8 |
| 413 | Body exceeds 5 MB or 1000 cards |
| 415 | Content-Type is not text/vcard or text/x-vcard |
| 422 | Body contains no complete BEGIN:VCARD / END:VCARD pairs |
Code examples
cURLExport vCard GET
GET /contacts/{contact_id}.vcfDownload a single contact as a text/vcard; charset=utf-8 file. The response includes a Content-Disposition: attachment header with a filename derived from the contact's preferred_name.
Path parameters
| Parameter | Type | Description |
|---|---|---|
contact_id | UUID | Contact ID |
Response (200)
Response body is raw vCard text:
BEGIN:VCARD
VERSION:3.0
FN:Jane Doe
N:Doe;Jane;;;
EMAIL;TYPE=WORK:jane@acme.example
TEL:+15551234567
END:VCARD
Code examples
cURL