Manage Contacts

CRUD and reverse-lookup endpoints for the organization’s contact directory. All contacts are org-scoped; the caller’s organization is derived from the auth context.

Create contact

POST /contacts

Create a new contact. At least one of given_name, family_name, company_name, or preferred_name must be non-empty (the vCard FN rule). If preferred_name is omitted it is synthesized from the other name fields.

Request body

Field	Type	Required	Description
`preferred_name`	string \| null	No	Display name (max 255 chars). Synthesized if omitted.
`name_prefix`	string \| null	No	e.g. `"Dr."` (max 32)
`given_name`	string \| null	No	First name (max 128)
`middle_name`	string \| null	No	Middle name (max 128)
`family_name`	string \| null	No	Last name (max 128)
`name_suffix`	string \| null	No	e.g. `"Jr."` (max 32)
`company_name`	string \| null	No	Company (max 255)
`job_title`	string \| null	No	Title (max 255)
`birthday`	string \| null	No	ISO `YYYY-MM-DD`
`notes`	string \| null	No	Free-text note on the contact
`emails`	object[]	No	Up to 50 items. See Contact object.
`phones`	object[]	No	Up to 50 items (E.164 values)
`websites`	object[]	No	Up to 25 items
`dates`	object[]	No	Up to 25 non-birthday dates
`addresses`	object[]	No	Up to 10 postal addresses
`custom_fields`	object[]	No	Up to 50 free-form label/value pairs

Request example

JSON

{
  "given_name": "Jane",
  "family_name": "Doe",
  "company_name": "Acme Inc.",
  "emails": [
    { "value": "jane@acme.example", "label": "work", "is_primary": true }
  ],
  "phones": [
    { "value_e164": "+15551234567", "label": "mobile" }
  ]
}

Response (201)

Returns the created contact (see Contact object). If matching emails and phones belong to one suggested contact (review_status: "unreviewed") and none of those identifiers is in conflict, the request saves that suggestion instead of creating a second contact. The contact keeps its ID, memories, correspondence, and existing identifiers. Its memory_count and latest_memory reflect the retained memories, and creation_source stays communication. The submitted name fields replace the existing name. Supplied non-name profile fields are applied, and omitted non-name fields are preserved. Explicit null clears a supplied nullable non-name field. An explicit empty list clears that supplied non-identifier list. Saving a matching suggestion through create requires an admin API key or the Inkbox Console. Agent keys receive 409 when identifiers already belong to a contact. Setting review_status through PATCH also requires administrative authority.

Error responses

Status	Description
400	vCard FN rule violated — no name fields provided
409	`duplicate_contact_identifier`: an email or phone belongs to a saved contact, matches multiple contacts, or has a conflicting owner. The error includes `contact_id`.
422	Invalid email, non-E.164 phone, duplicate email/phone, or more than one `is_primary`

Code examples

curl -X POST "https://inkbox.ai/api/v1/contacts" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "given_name": "Jane",
    "family_name": "Doe",
    "emails": [{"value": "jane@acme.example", "label": "work"}]
  }'

const response = await fetch("https://inkbox.ai/api/v1/contacts", {
  method: "POST",
  headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
  },
  body: JSON.stringify({
      given_name: "Jane",
      family_name: "Doe",
      emails: [{ value: "jane@acme.example", label: "work" }],
  }),
});
const contact = await response.json();

import requests

response = requests.post(
    "https://inkbox.ai/api/v1/contacts",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "given_name": "Jane",
        "family_name": "Doe",
        "emails": [{"value": "jane@acme.example", "label": "work"}],
    },
)
contact = response.json()

Create contact with permissions

POST /contacts/with-permissions

Create a contact and configure one agent’s access in a single transaction using an admin API key. Agent-scoped keys cannot use this endpoint. Send the usual contact fields plus a required permissions object:

Field	Type	Required	Description
`identity_id`	UUID	Yes	An active agent in your organization
`email`	object	No	Optional `visible` and either legacy `contactable` or directional `inbound_contactable`/`outbound_contactable` lists, up to 50 addresses each
`phone`	object	No	Optional `visible` and either legacy `contactable` or directional `inbound_contactable`/`outbound_contactable` E.164 lists, up to 50 numbers each
`emails`	object	No	Up to 50 email-to-boolean choices. Each email must also appear in the submitted contact fields.
`phones`	object	No	Up to 50 E.164 phone-to-boolean choices. Each phone must also appear in the submitted contact fields.
`inbound_emails`, `outbound_emails`	object	No	Directional email-to-boolean choices, up to 50 each; do not combine with `emails`
`inbound_phones`, `outbound_phones`	object	No	Directional E.164 phone-to-boolean choices, up to 50 each; do not combine with `phones`
`profile`	boolean	No	Parent permission for all contact data
`memories`	boolean	No	Whether the agent can read contact memories while Profile is enabled

Use either nested email/phone access objects or address-to-boolean maps; do not mix the two shapes. Contactable addresses must appear in the submitted contact fields. Profile must be enabled before Email, Phone, or Memories can be enabled. Disabling Profile disables every child permission. Otherwise omitted choices preserve existing settings when saving a matching suggestion. Other agents’ settings are preserved. If any permission cannot be applied, neither contact changes nor permissions are saved. The response is the same contact object returned by ordinary creation. Legacy lists and boolean choices set both receiving and sending permission. Directional lists set only their side and preserve the other; null lists and mixed legacy/directional lists for the same group return 422. New options require SDK/CLI 0.7.3. Python uses ContactChannelAccessUpdate; TypeScript and CLI creation JSON use inboundContactable and outboundContactable. Rust adds create_with_access_options with DirectionalContactCreatePermissions. See directional contact access.

curl -X POST "https://inkbox.ai/api/v1/contacts/with-permissions" \
  -H "X-API-Key: YOUR_ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"given_name":"Ada","emails":[{"value":"ada@example.com"}],"permissions":{"identity_id":"11111111-1111-4111-8111-111111111111","email":{"visible":true,"contactable":["ada@example.com"]},"profile":true,"memories":false}}'

from inkbox import Inkbox, ContactEmail, ContactCreatePermissions, ContactChannelAccessUpdate

client = Inkbox(api_key="YOUR_ADMIN_API_KEY")
contact = client.contacts.create(
    given_name="Ada",
    emails=[ContactEmail(value="ada@example.com", label=None)],
    permissions=ContactCreatePermissions(
        identity_id="11111111-1111-4111-8111-111111111111",
        email=ContactChannelAccessUpdate(visible=True, contactable=["ada@example.com"]),
        profile=True,
        memories=False,
    ),
)

import { Inkbox } from "@inkbox/sdk";

const client = new Inkbox({ apiKey: "YOUR_ADMIN_API_KEY" });
const contact = await client.contacts.create({
  givenName: "Ada",
  emails: [{ value: "ada@example.com" }],
  permissions: {
    identityId: "11111111-1111-4111-8111-111111111111",
    email: { visible: true, contactable: ["ada@example.com"] },
    profile: true,
    memories: false,
  },
});

inkbox --api-key "$INKBOX_ADMIN_API_KEY" contacts create --json='{"givenName":"Ada","emails":[{"value":"ada@example.com"}],"permissions":{"identityId":"11111111-1111-4111-8111-111111111111","email":{"visible":true,"contactable":["ada@example.com"]},"profile":true,"memories":false}}'

Errors: 400 for an unavailable or foreign identity, 403 for insufficient authority, 409 for a contact conflict, and 422 for invalid or duplicate permission addresses or values absent from the contact request. The earlier action-based creation shape remains accepted by the API: its addresses array contains {kind, value, action} items, where kind is email or phone and action is allow or block. The SDKs and CLI accept nested group-access objects and the boolean permission maps.

List contacts

GET /contacts

List contacts visible under the caller’s contact permissions. Profile controls whether the contact is visible; Email, Phone, and Memories can be narrowed while Profile is enabled. Responses include only permitted identifiers and fields; fully hidden contacts are absent. Hosted voice in YOLO mode retains organization-wide contact reads.

Query parameters

Parameter	Type	Default	Description
`q`	string	—	Case-insensitive substring match over name, company, job title, the `notes` field, and the contact’s email addresses and phone numbers. Max 100 chars.
`order`	string	`name`	`"name"` (preferred_name ascending) or `"recent"` (created_at descending)
`review_status`	string[]	All	Repeat the parameter to include `"unreviewed"`, `"confirmed"`, or both. For example, `?review_status=unreviewed&review_status=confirmed`.
`limit`	integer	50	Results per page (1–200)
`offset`	integer	0	Offset for pagination

Response (200)

Returns an array of contact objects, each with memory_count and latest_memory for the memories currently in effect.

Code examples

curl -X GET "https://inkbox.ai/api/v1/contacts?q=acme&limit=25" \
  -H "X-API-Key: YOUR_API_KEY"

const response = await fetch(
  "https://inkbox.ai/api/v1/contacts?q=acme&limit=25",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const contacts = await response.json();

import requests

response = requests.get(
    "https://inkbox.ai/api/v1/contacts",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"q": "acme", "limit": 25},
)
contacts = response.json()

Lookup contact

GET /contacts/lookup

Reverse-lookup contacts by a single field. Useful for routing inbound email or phone calls to a known contact.

Query parameters

Exactly one of the following must be provided:

Parameter	Type	Description
`email`	string	Exact match against a stored email (canonicalized to lowercase)
`email_contains`	string	Substring match on stored email values (case-insensitive)
`email_domain`	string	Suffix match on `@<domain>`. Leading `@` tolerated (max 253 chars)
`phone`	string	Exact match against a stored E.164 phone number
`phone_contains`	string	Substring match on stored E.164 phone values

Response (200)

Returns an array of contact objects (up to 200). An empty array means no match.

Error responses

Status	Description
400	Zero or more than one filter provided; or `phone` is not a valid E.164 number

Code examples

curl -X GET "https://inkbox.ai/api/v1/contacts/lookup?email_domain=acme.example" \
  -H "X-API-Key: YOUR_API_KEY"

const response = await fetch(
  "https://inkbox.ai/api/v1/contacts/lookup?" +
      new URLSearchParams({ email_domain: "acme.example" }),
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const matches = await response.json();

import requests

response = requests.get(
    "https://inkbox.ai/api/v1/contacts/lookup",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"email_domain": "acme.example"},
)
matches = response.json()

Get contact

GET /contacts/{contact_id}

Fetch a single contact by its UUID.

Path parameters

Parameter	Type	Description
`contact_id`	UUID	Unique contact identifier

Code examples

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

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

import requests

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

Update contact

PATCH /contacts/{contact_id}

Update a contact using JSON-merge-patch semantics:

Omit a field to leave it unchanged
Send a value to set it
Send null on a nullable scalar to clear it
Send a list to replace the stored list wholesale (no per-item merge)

After applying the patch, the server re-runs the FN rule against the merged state — if the update would leave every name field empty, the request 400s. The response includes the contact’s current active memory_count and latest_memory.

Path parameters

Parameter	Type	Description
`contact_id`	UUID	Unique contact identifier

Request body

Any subset of the Create contact body fields. Agent-scoped callers cannot change email addresses, phone numbers, or review_status; they can edit other profile fields only when Profile access is enabled for that agent. Organization administrators can send review_status: "confirmed" to confirm an unreviewed contact. Confirmed contacts cannot transition back to unreviewed. Editing profile fields as an organization administrator also confirms an unreviewed contact. Confirmation records reviewed_at and reviewed_by in the response.

{
  "review_status": "confirmed"
}

Code examples

curl -X PATCH "https://inkbox.ai/api/v1/contacts/CONTACT_ID" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"job_title": "VP Engineering"}'

const response = await fetch(
  `https://inkbox.ai/api/v1/contacts/${contactId}`,
  {
      method: "PATCH",
      headers: {
          "X-API-Key": "YOUR_API_KEY",
          "Content-Type": "application/json",
      },
      body: JSON.stringify({ job_title: "VP Engineering" }),
  }
);
const contact = await response.json();

import requests

response = requests.patch(
    f"https://inkbox.ai/api/v1/contacts/{contact_id}",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"job_title": "VP Engineering"},
)
contact = response.json()

Delete contact

Humans using the Inkbox Console and admin API keys can delete contacts with configured visibility settings directly. No permission reset is required. Deleting a contact does not remove standalone email or phone communication rules.

DELETE /contacts/{contact_id}

Delete a contact. Returns 204 No Content on success.

Path parameters

Parameter	Type	Description
`contact_id`	UUID	Unique contact identifier

Code examples

curl -X DELETE "https://inkbox.ai/api/v1/contacts/CONTACT_ID" \
  -H "X-API-Key: YOUR_API_KEY"

await fetch(
  `https://inkbox.ai/api/v1/contacts/${contactId}`,
  {
      method: "DELETE",
      headers: { "X-API-Key": "YOUR_API_KEY" },
  }
);

import requests

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

Delete contacts in bulk

POST /contacts/bulk-delete

Delete 1–1,000 contacts with an admin API key or a claimed agent API key. Pass their UUIDs in contact_ids. Duplicate IDs produce one result, in first-occurrence order.

cURL

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

Response (200)

A missing or inaccessible contact produces an error for that ID without preventing deletion of the remaining contacts. Check every result, even when the HTTP response is 200.

JSON

{
  "deleted_count": 1,
  "error_count": 0,
  "results": [
    {
      "contact_id": "550e8400-e29b-41d4-a716-446655440000",
      "status": "deleted",
      "error": null
    }
  ]
}

Each result has contact_id, a status of deleted or error, an optional error message, and an optional error_code. Human/admin deletion does not require a visibility reset; restricted agent deletions can still fail per contact. Invalid UUIDs, an empty list, or more than 1,000 IDs return 422.

Contact object

Top-level fields

Field	Type	Description
`id`	UUID	Unique contact identifier
`organization_id`	string	Owning organization
`preferred_name`	string \| null	Display name. `null` when the contact has no name on file; automatically created contacts remain nameless when the source provides no display name. This field never falls back to the contact’s email address or phone number
`name_prefix`	string \| null
`given_name`	string \| null
`middle_name`	string \| null
`family_name`	string \| null
`name_suffix`	string \| null
`company_name`	string \| null
`job_title`	string \| null
`birthday`	string \| null	ISO `YYYY-MM-DD`
`notes`	string \| null	Free-text note
`emails`	object[]	See Email item
`phones`	object[]	See Phone item
`websites`	object[]	See Website item
`dates`	object[]	See Date item
`addresses`	object[]	See Address item
`custom_fields`	object[]	See Custom field item
`slack_accounts`	object[]	Read-only linked Slack accounts, each with `workspace_id`, `user_id`, and nullable `workspace_name`. Defaults to an empty list; subject to Profile visibility
`creation_source`	string	How the contact was created: `manual`, `vcard`, `communication`, or `backfill`
`review_status`	string	`unreviewed` or `confirmed`
`reviewed_at`	string \| null	ISO 8601 time of confirmation
`reviewed_by`	string \| null	Principal that confirmed the contact
`preferred_name_source`	string	Source of the display name: `manual`, `vcard`, `provider`, `mail_header`, or `identifier_fallback`
`preferred_name_locked_at`	string \| null	ISO 8601 time after which generated updates cannot replace the preferred name
`created_by_identity_id`	UUID \| null	Agent identity that created the contact, when applicable
`merged_into_contact_id`	UUID \| null	Surviving contact ID when this contact has been merged
`is_auto_created`	boolean	Whether the contact was created from communication history
`is_confirmed`	boolean	Convenience boolean equivalent to `review_status === "confirmed"`
`status`	string	`active`
`created_at`	string	ISO 8601
`updated_at`	string	ISO 8601
`memory_count`	integer	Memories currently in effect, excluding expired ones. Returned by list, create, update, and merge responses; omitted by get and lookup responses.
`latest_memory`	object \| null	Most recently updated active memory as `{id, content, updated_at}`. Returned with `memory_count`; omitted by get and lookup responses.

Email item

Field	Type	Description
`value`	string	Email address (stored lowercased)
`label`	string \| null	e.g. `"work"`, `"home"` (max 64)
`is_primary`	boolean	At most one email per contact is primary

Phone item

Field	Type	Description
`value_e164`	string	E.164 phone number (e.g. `+15551234567`)
`label`	string \| null	e.g. `"mobile"`, `"work"` (max 64)
`is_primary`	boolean	At most one phone per contact is primary

Website item

Field	Type	Description
`url`	string	HTTP/HTTPS URL (max 2048)
`label`	string \| null	e.g. `"personal"`, `"linkedin"` (max 64)

Date item

Field	Type	Description
`date`	string	ISO `YYYY-MM-DD`
`label`	string	Required free-string label (e.g. `"anniversary"`)

Address item

All fields are optional free text.

Field	Type	Description
`street`	string \| null	Street line(s)
`city`	string \| null
`region`	string \| null	State, province, or region
`postal`	string \| null	Postal or ZIP code
`country`	string \| null	Country name or ISO code
`label`	string \| null	e.g. `"home"`, `"work"`

Custom field item

Field	Type	Description
`label`	string	Field key (max 128)
`value`	string	Field value (max 1024)

​Create contact

​Request body

​Request example

​Response (201)

​Error responses

​Code examples

​Create contact with permissions

​List contacts

​Query parameters

​Response (200)

​Code examples

​Lookup contact

​Query parameters

​Response (200)

​Error responses

​Code examples

​Get contact

​Path parameters

​Code examples

​Update contact

​Path parameters

​Request body

​Code examples

​Delete contact

​Path parameters

​Code examples

​Delete contacts in bulk

​Response (200)

​Contact object

​Top-level fields

​Email item

​Phone item

​Website item

​Date item

​Address item

​Custom field item

Create contact

Request body

Request example

Response (201)

Error responses

Code examples

Create contact with permissions

List contacts

Query parameters

Response (200)

Code examples

Lookup contact

Query parameters

Response (200)

Error responses

Code examples

Get contact

Path parameters

Code examples

Update contact

Path parameters

Request body

Code examples

Delete contact

Path parameters

Code examples

Delete contacts in bulk

Response (200)

Contact object

Top-level fields

Email item

Phone item

Website item

Date item

Address item

Custom field item