vCards

Move contacts between Inkbox and other address books using vCards. Use an admin API key or a claimed agent API key for these endpoints. For scoped exports, Profile controls whether the contact is included and exposes names, notes, addresses, and labels on permitted identifiers. vCards do not include contact memories. See contact permissions.

Import vCards

POST /contacts/import

Bulk-import contacts from a vCard body. The request body must be text/vcard or text/x-vcard, UTF-8 encoded, and at most 10 MiB containing up to 2,500 cards. Split larger imports into separate requests. Each card has its own result, so a failed card does not prevent the others from importing. Accepted batches return 200 OK, with partial failures reported in error_count and the per-card results list. A card matching one eligible suggested contact saves it when imported with admin credentials. Agent imports report an identifier conflict instead. Omitted non-name profile fields, memories, and existing identifiers are preserved. Exports include only the caller’s permitted identifiers and profile fields.

Request headers

Header	Required	Description
`Content-Type`	Yes	`text/vcard` or `text/x-vcard`
`X-API-Key`	Yes	Your API key
`X-VCard-Preview-Hash`	No	The `preview_hash` from Preview an import. A changed payload or conflict result returns `409` before importing.

Response (200)

Field	Type	Description
`created_count`	integer	Number of cards that created a contact or saved a matching suggested contact
`error_count`	integer	Number of cards that failed to import
`results[].index`	integer	0-based position within the uploaded stream
`results[].status`	string	`created`, `conflict`, or `error`. Saving a matching suggestion reports `created` with the suggestion’s existing contact ID.
`results[].contact`	object	Full Contact object (when `status == "created"`)
`results[].error`	string \| null	Rejection reason for an error or conflict
`results[].conflicting_contact_id`	UUID \| null	Existing contact that owns an identifier from the card, when `status` is `conflict`

Error responses

Status	Description
400	Body is not UTF-8
409	The supplied preview hash no longer matches; preview again before importing
413	Body exceeds 10 MiB or 2,500 cards
415	Content-Type is not `text/vcard` or `text/x-vcard`
422	Body contains no complete `BEGIN:VCARD` / `END:VCARD` pairs

Code examples

curl -X POST "https://inkbox.ai/api/v1/contacts/import" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: text/vcard" \
  --data-binary @contacts.vcf

import { readFile } from "node:fs/promises";

const vcfBody = await readFile("contacts.vcf", "utf-8");
const response = await fetch("https://inkbox.ai/api/v1/contacts/import", {
  method: "POST",
  headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "text/vcard",
  },
  body: vcfBody,
});
const result = await response.json();
console.log(result.created_count, result.error_count);

import requests

with open("contacts.vcf", "rb") as fh:
    response = requests.post(
        "https://inkbox.ai/api/v1/contacts/import",
        headers={
            "X-API-Key": "YOUR_API_KEY",
            "Content-Type": "text/vcard",
        },
        data=fh.read(),
    )
result = response.json()
print(result["created_count"], result["error_count"])

Preview an import

POST /contacts/import/preview

Validate a vCard batch and find conflicts with existing contacts before importing it. This endpoint does not create contacts. Send a JSON object with a required vcard string containing at most 10 MiB of UTF-8 text and 2,500 cards.

cURL

curl -X POST "https://inkbox.ai/api/v1/contacts/import/preview" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"vcard": "BEGIN:VCARD\r\nVERSION:4.0\r\nFN:Jane Doe\r\nEMAIL:jane@example.com\r\nEND:VCARD\r\n"}'

Response (200)

Field	Type	Description
`contact_count`	integer	Number of cards in the batch
`conflicts`	object[]	Cards matching identifiers already owned by existing contacts; empty when none match
`conflicts[].index`	integer	Zero-based card position
`conflicts[].contact_ids`	UUID[]	Matching existing contacts
`payload_hash`	string	Hash identifying the submitted vCard text
`preview_hash`	string	Hash identifying the text and its conflict results

To ensure the import matches your preview, send the same vCard text to Import vCards with X-VCard-Preview-Hash set to preview_hash. If the text or conflicts change, import returns 409; run the preview again. An oversized vCard returns 413. Invalid content, an empty batch, or too many cards returns 422.

Export multiple contacts

POST /contacts/vcard-export

Export 1–25 contacts as a single vCard document. Pass their UUIDs in contact_ids. Duplicate IDs are exported once, in first-occurrence order.

cURL

curl -X POST "https://inkbox.ai/api/v1/contacts/vcard-export" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contact_ids": ["550e8400-e29b-41d4-a716-446655440000"]}'

Response (200)

Field	Type	Description
`content_type`	string	`text/vcard; charset=utf-8`
`contact_count`	integer	Number of exported contacts
`vcard`	string	Combined vCard text; save this string to a `.vcf` file

A missing or inaccessible contact returns 404. An export larger than 1,000,000 UTF-8 bytes returns 413. Invalid IDs, an empty list, or more than 25 IDs return 422.

Export vCard

GET /contacts/{contact_id}.vcf

Download 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:4.0
FN:Jane Doe
N:Doe;Jane;;;
EMAIL;TYPE=WORK:jane@acme.example
TEL:+15551234567
END:VCARD

Code examples

curl -X GET "https://inkbox.ai/api/v1/contacts/CONTACT_ID.vcf" \
  -H "X-API-Key: YOUR_API_KEY" \
  -o jane-doe.vcf

const response = await fetch(
  `https://inkbox.ai/api/v1/contacts/${contactId}.vcf`,
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const vcfText = await response.text();

import requests

response = requests.get(
    f"https://inkbox.ai/api/v1/contacts/{contact_id}.vcf",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
vcf_text = response.text

Agent signup API

Agent identity API

Agent2Agent API

Message retries

Mail API

Phone API

iMessage API

Slack API

Webhooks API

Tunnels API

Contacts API

Notes API

Vault API

Billing API

Import vCards

Request headers

Response (200)

Error responses

Code examples

Preview an import

Response (200)

Export multiple contacts

Response (200)

Export vCard

Path parameters

Response (200)

Code examples

​Import vCards

​Request headers

​Response (200)

​Error responses

​Code examples

​Preview an import

​Response (200)

​Export multiple contacts

​Response (200)

​Export vCard

​Path parameters

​Response (200)

​Code examples

Import vCards

Request headers

Response (200)

Error responses

Code examples

Preview an import

Response (200)

Export multiple contacts

Response (200)

Export vCard

Path parameters

Response (200)

Code examples