Inkbox

> # Documentation index
> Fetch the complete documentation index at: https://inkbox.ai/sitemap.xml
> Use this file to discover all available pages before exploring further.

---

# Contacts API
description: Org-wide contact directory for AI agents — names, emails, phones, and per-identity access control

---


# Contacts API

An organization-wide address book shared across every agent in your org. Each contact aggregates names, emails, phones, addresses, websites, and arbitrary custom fields. New contacts are visible to every active agent by default (a wildcard access row is seeded on create); narrow visibility by granting or revoking specific identities under [Access control](/docs/api/contacts/access).

API base URL:


## Quick start

Create an account and get your API key from the Inkbox console:

[Get API key](https://inkbox.ai/console/api-keys)

All contact API requests require authentication with an API key or Clerk JWT. Read endpoints accept admin API keys, claimed agent API keys, and Clerk JWT; unclaimed (mid-signup) agent keys are rejected. Grants to specific identities (`POST .../access` with an identity_id) are admin + JWT only.


## Contacts


  **[Create contact](/docs/api/contacts/manage)** `POST` `/api/v1/contacts` — Create a new contact in your organization

  **[List contacts](/docs/api/contacts/manage)** `GET` `/api/v1/contacts` — List contacts with optional substring search

  **[Get contact](/docs/api/contacts/manage)** `GET` `/api/v1/contacts/{contact_id}` — Get a single contact by ID

  **[Lookup contact](/docs/api/contacts/manage)** `GET` `/api/v1/contacts/lookup` — Reverse-lookup contacts by email, domain, or phone

  **[Update contact](/docs/api/contacts/manage)** `PATCH` `/api/v1/contacts/{contact_id}` — Update a contact with JSON-merge-patch semantics

  **[Delete contact](/docs/api/contacts/manage)** `DELETE` `/api/v1/contacts/{contact_id}` — Delete a contact


## Access control


  **[Grant identity access](/docs/api/contacts/access)** `POST` `/api/v1/contacts/{contact_id}/access` — Grant an identity access, or reset the contact to the wildcard default

  **[List access rules](/docs/api/contacts/access)** `GET` `/api/v1/contacts/{contact_id}/access` — List wildcard or per-identity access rows for a contact

  **[Revoke identity access](/docs/api/contacts/access)** `DELETE` `/api/v1/contacts/{contact_id}/access/{identity_id}` — Revoke an identity's access (materializes wildcard first if needed)


## vCards


  **[Import vCards](/docs/api/contacts/vcards)** `POST` `/api/v1/contacts/import` — Bulk-import a vCard stream (up to 1000 cards per request)

  **[Export vCard](/docs/api/contacts/vcards)** `GET` `/api/v1/contacts/{contact_id}.vcf` — Download a single contact as a .vcf file


## Additional resources

- [Notes API](/docs/api/notes)
- [Mail API](/docs/api/mail)
- [Phone API](/docs/api/phone)