Manage Identities

Agent identities are the unit of presence on Inkbox. Each identity owns exactly one mailbox and one tunnel; you can optionally attach a phone number, a dedicated iMessage line, and vault-secret access. Handles are globally unique across all Inkbox customers and are normalized — a leading @ is automatically stripped, so @my-agent and my-agent are equivalent.

Create identity

POST /identities

Atomically provisions the identity, its mailbox, and its tunnel in a single transaction. You can optionally provision and link a phone number, claim and attach a dedicated iMessage line, and attach access to existing vault secrets in the same request. The mailbox and tunnel are always created; the nested mailbox and tunnel bodies only customize them.

Request body

Field	Type	Required	Description
`agent_handle`	string	Yes	Handle for the identity. Globally unique. Leading `@` is stripped.
`display_name`	string	No	Human-readable name for the identity. Max 255 chars. Defaults to `agent_handle` when omitted.
`description`	string \| null	No	Description published on the identity’s public Agent Card when A2A is enabled. Treat it as public copy. Defaults to `null`. Empty string `""` is accepted and stored distinctly from `null`.
`imessage_enabled`	boolean	No	Whether the identity can be reached over iMessage. Defaults to `false`; set `true` to opt in.
`contact_sharing_enabled`	boolean	No	Whether an attached dedicated iMessage line automatically shares the identity’s display name (falling back to its handle) and its avatar when available. Defaults to `true`. The value remains saved when no dedicated line is attached.
`claim_imessage_number`	boolean (`true` only)	No	Set `true` to claim and attach a new dedicated iMessage line. Requires `imessage_enabled: true`.
`mailbox`	object	No	Optional mailbox-spec. The mailbox is always provisioned; this body only customizes the sending domain or local part.
`tunnel`	object	No	Optional tunnel-spec. The tunnel is always provisioned; this body only opts into passthrough TLS.
`phone_number`	object	No	Optional phone-number provisioning payload. Omit to skip.
`vault_secret_ids`	string or array	No	Optional vault secret attachment request. Provide a single secret ID, a list of IDs, or `"all"` / `"*"` to attach all active secrets.

`mailbox` fields

Field	Type	Required	Description
`email_local_part`	string	No	Custom local part. Only meaningful when the resolved sending domain is a custom domain — on the platform domain the local part is forced to `agent_handle`.
`sending_domain`	string \| null	No	Bare-domain selector (e.g. `"mail.acme.com"`, not a full email address). Omit to use the org default sending domain; pass `null` to force the platform domain; pass a string to pin to a verified custom domain.

Sending-domain resolution. Omitting mailbox does not necessarily yield {agent_handle}@inkboxmail.com. The server resolves the sending domain in three cases: if the org has set a verified custom domain as its default, omitting the body lands the mailbox on that custom domain with a server-chosen local part; passing "sending_domain": null forces the platform domain and the local part to agent_handle; passing an explicit bare-domain string pins the mailbox to that verified custom domain (404 if the domain isn’t verified for your org).

`tunnel` fields

Field	Type	Required	Description
`tls_mode`	string	No	`"edge"` (default) or `"passthrough"`. Fixed at creation.

The tunnel name is always forced to agent_handle; the public hostname is e.g. my-agent.inkboxwire.com.

`phone_number` fields

Field	Type	Required	Description
`type`	string	No	Number type to provision. Only `local` is supported. Defaults to `local`.
`state`	string	No	Optional US state abbreviation filter.
`incoming_call_action`	string	No	How inbound calls are handled: `hosted_agent` (default; Inkbox Voice AI answers), `auto_accept`, `auto_reject`, `webhook`, or `forward`. Set `auto_reject` explicitly to reject inbound calls.
`client_websocket_url`	string	Conditionally	Required when `incoming_call_action` is `auto_accept`. Must be a `wss://` URL.
`incoming_call_webhook_url`	string	Conditionally	Required when `incoming_call_action` is `webhook`. Must be an `https://` URL.
`forwarding_target_type`	string	Conditionally	`phone` or `sip`. Required when `incoming_call_action` is `forward`.
`forwarding_phone_number`	string	Conditionally	E.164 destination required for a `phone` forwarding target.
`forwarding_sip_uri`	string	Conditionally	Complete `sip:user@public-dns-host[:port]` URI required for a `sip` forwarding target; private/single-label and IP hosts are not accepted.

`vault_secret_ids`

Use this to attach existing vault secret access to the new identity. The organization must already have an active vault. If omitted, no vault secret access is attached. Accepted forms:

A single stringified UUID to attach one secret
A list of UUIDs to attach specific secrets
"all" or "*" to attach all active secrets in the active vault

Request example

JSON

{
  "agent_handle": "sales-agent",
  "display_name": "Sales Agent",
  "description": "Sales-outreach agent owned by the GTM team.",
  "tunnel": { "tls_mode": "edge" },
  "phone_number": { "type": "local" }
}

To claim and attach a dedicated line while creating the identity, set both fields in the same request:

JSON

{
  "agent_handle": "sales-agent",
  "imessage_enabled": true,
  "claim_imessage_number": true
}

Identity creation does not require the dedicated-line Idempotency-Key header.

Response (201)

Returns the full identity-detail shape with nested mailbox and tunnel objects always populated. phone_number and imessage_number are populated when those numbers were provisioned.

JSON

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "organization_id": "org_2abc123def456",
  "agent_handle": "sales-agent",
  "display_name": "Sales Agent",
  "description": "Sales-outreach agent owned by the GTM team.",
  "status": "active",
  "imessage_enabled": false,
  "contact_sharing_enabled": true,
  "imessage_filter_mode": "blacklist",
  "mail_filter_mode": "blacklist",
  "phone_filter_mode": "blacklist",
  "email_address": "sales-agent@inkboxmail.com",
  "has_avatar": false,
  "signing_key_configured": false,
  "signing_key_created_at": null,
  "created_at": "2026-03-01T12:00:00Z",
  "updated_at": "2026-03-01T12:00:00Z",
  "mailbox": {
    "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
    "email_address": "sales-agent@inkboxmail.com",
    "sending_domain": "inkboxmail.com",
    "filter_mode": "blacklist",
    "agent_identity_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "created_at": "2026-03-01T12:00:00Z",
    "updated_at": "2026-03-01T12:00:00Z"
  },
  "tunnel": {
    "id": "e5f6a7b8-c9d0-1234-ef01-345678901234",
    "tunnel_name": "sales-agent",
    "agent_identity_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "tls_mode": "edge",
    "status": "active",
    "public_host": "sales-agent.inkboxwire.com",
    "zone": "inkboxwire.com",
    "created_at": "2026-03-01T12:00:00Z",
    "updated_at": "2026-03-01T12:00:00Z"
  },
  "phone_number": {
    "id": "d4e5f6a7-b8c9-0123-defa-234567890123",
    "number": "+14155550100",
    "type": "local",
    "state": "CA",
    "status": "active",
    "sms_status": "ready",
    "sms_error_code": null,
    "sms_error_detail": null,
    "sms_ready_at": "2026-03-01T12:00:05Z",
    "incoming_call_action": "hosted_agent",
    "client_websocket_url": null,
    "incoming_call_webhook_url": null,
    "forwarding_target_type": null,
    "forwarding_phone_number": null,
    "forwarding_sip_uri": null,
    "filter_mode": "blacklist",
    "agent_identity_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "created_at": "2026-03-01T12:00:00Z",
    "updated_at": "2026-03-01T12:00:00Z"
  },
  "imessage_number": null
}

mailbox and tunnel are always populated for active customer identities; phone_number and imessage_number are optional. When claim_imessage_number is true, imessage_number contains the claimed line’s id, E.164 number, and response-only type. The type value remains "dedicated_outbound" for compatibility and is not a capability selector. If vault_secret_ids is omitted, no vault secret access is attached. The embedded tunnel object is a durable-config summary. Live connection state (currently_connected), connection telemetry, and cert material live on the tunnels endpoints — fetch GET /api/v1/tunnels/{tunnel_id} when you need them; it resolves connection state fresh on every read.

Mailbox local-part validation

When you provide mailbox.email_local_part, it must satisfy these rules:

Length: 3–64 characters
Characters: lowercase letters, numbers, hyphens (-), underscores (_), and dots (.)
Start/end: must begin and end with a letter or number
No consecutive dots: my..agent is rejected
No @: provide the handle only, not a full email address
Reserved names blocked: some system addresses are reserved; you’ll get a 409 if you pick one.

Handle validation

Handles are globally unique across all Inkbox customers. They must satisfy:

Length: 3–63 characters
Characters: lowercase letters (a-z), digits (0-9), and hyphens (-)
Start/end: must begin and end with a letter or digit
No consecutive hyphens

Some handles are reserved; you’ll get a 409 if you pick one.

Error responses

Status	Description
402	An identity or iMessage capacity limit was reached. For a dedicated-line quota response, review billing in the Inkbox Console or contact support@inkbox.ai.
403	Organization ID missing from token
404	No active vault exists for the organization, requested vault secrets were not found, the requested sending domain isn’t a verified custom domain for your org, or no phone numbers matched the requested criteria
409	Handle is already taken — see envelope below
422	Request validation failed (e.g. `claim_imessage_number: true` supplied without `imessage_enabled: true`, invalid local part, over-long description, or unknown field)
429	Phone number limit reached for the organization
502	Phone number provisioning failed
503	Identity provisioning is temporarily unavailable. For a dedicated-line inventory response, honor `Retry-After`: brief contention may return `5` seconds, while depletion may return `3600` seconds. The response may say that a number is expected within 24 hours.

The 409 body uses a stable error envelope:

JSON

{
  "detail": {
    "code": "agent_handle_unavailable",
    "message": "Agent handle 'sales-agent' is unavailable.",
    "blocking_namespace": "identities"
  }
}

blocking_namespace is a programmatic discriminator with three possible values — "identities", "tunnels", or "mail" — indicating which resource produced the conflict.

Code examples

curl -X POST "https://inkbox.ai/api/v1/identities" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agent_handle": "sales-agent", "display_name": "Sales Agent", "description": "Sales-outreach agent.", "tunnel": {"tls_mode": "edge"}, "phone_number": {"type": "local"}}'

const response = await fetch("https://inkbox.ai/api/v1/identities", {
  method: "POST",
  headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
  },
  body: JSON.stringify({
      agent_handle: "sales-agent",
      display_name: "Sales Agent",
      description: "Sales-outreach agent.",
      tunnel: { tls_mode: "edge" },
      phone_number: { type: "local" },
  }),
});
const identity = await response.json();

import requests

response = requests.post(
    "https://inkbox.ai/api/v1/identities",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "agent_handle": "sales-agent",
        "display_name": "Sales Agent",
        "description": "Sales-outreach agent.",
        "tunnel": {"tls_mode": "edge"},
        "phone_number": {"type": "local"},
    },
)
identity = response.json()

List identities

GET /identities

List all identities for your organization, newest first. Each row carries the same nested mailbox / tunnel / phone_number / imessage_number blocks as Get identity, so rendering an org-wide view takes one request — no per-identity follow-ups. Agent-scoped API keys receive only their own identity. Admin-scoped API keys and the Inkbox Console receive every identity in the organization.

Response (200)

JSON

[
  {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "organization_id": "org_2abc123def456",
    "agent_handle": "sales-agent",
    "display_name": "Sales Agent",
    "description": "Sales-outreach agent.",
    "status": "active",
    "imessage_enabled": true,
    "contact_sharing_enabled": true,
    "imessage_filter_mode": "blacklist",
    "mail_filter_mode": "blacklist",
    "phone_filter_mode": "blacklist",
    "email_address": "sales-agent@inkboxmail.com",
    "has_avatar": true,
    "signing_key_configured": true,
    "signing_key_created_at": "2026-03-05T10:15:00Z",
    "created_at": "2026-03-01T12:00:00Z",
    "updated_at": "2026-03-01T12:00:00Z",
    "mailbox": {
      "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
      "email_address": "sales-agent@inkboxmail.com",
      "sending_domain": "inkboxmail.com",
      "filter_mode": "blacklist",
      "agent_identity_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "created_at": "2026-03-01T12:00:00Z",
      "updated_at": "2026-03-01T12:00:00Z"
    },
    "tunnel": {
      "id": "e5f6a7b8-c9d0-1234-ef01-345678901234",
      "tunnel_name": "sales-agent",
      "agent_identity_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "tls_mode": "edge",
      "status": "active",
      "public_host": "sales-agent.inkboxwire.com",
      "zone": "inkboxwire.com",
      "created_at": "2026-03-01T12:00:00Z",
      "updated_at": "2026-03-01T12:00:00Z"
    },
    "phone_number": null,
    "imessage_number": null
  }
]

The embedded tunnel block is the same durable-config summary as on Get identity — live connection state comes from GET /api/v1/tunnels/{tunnel_id}.

Code examples

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

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

import requests

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

Get identity

GET /identities/{agent_handle}

Get a single identity with its linked communication channels. Returns the identity-detail shape with nested mailbox, tunnel, and (when attached) phone_number and imessage_number objects. With an agent-scoped API key, only the caller’s own identity is reachable; any other handle returns 404.

Path parameters

Parameter	Type	Description
`agent_handle`	string	Handle of the identity (leading `@` is stripped)

Response (200)

JSON

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "organization_id": "org_2abc123def456",
  "agent_handle": "sales-agent",
  "display_name": "Sales Agent",
  "description": "Sales-outreach agent owned by the GTM team.",
  "status": "active",
  "imessage_enabled": true,
  "contact_sharing_enabled": true,
  "imessage_filter_mode": "blacklist",
  "mail_filter_mode": "blacklist",
  "phone_filter_mode": "blacklist",
  "email_address": "sales-agent@inkboxmail.com",
  "has_avatar": false,
  "signing_key_configured": true,
  "signing_key_created_at": "2026-03-05T10:15:00Z",
  "created_at": "2026-03-01T12:00:00Z",
  "updated_at": "2026-03-01T12:00:00Z",
  "mailbox": {
    "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
    "email_address": "sales-agent@inkboxmail.com",
    "sending_domain": "inkboxmail.com",
    "filter_mode": "blacklist",
    "agent_identity_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "created_at": "2026-02-20T10:00:00Z",
    "updated_at": "2026-02-20T10:00:00Z"
  },
  "tunnel": {
    "id": "e5f6a7b8-c9d0-1234-ef01-345678901234",
    "tunnel_name": "sales-agent",
    "agent_identity_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "tls_mode": "edge",
    "status": "active",
    "public_host": "sales-agent.inkboxwire.com",
    "zone": "inkboxwire.com",
    "created_at": "2026-03-01T12:00:00Z",
    "updated_at": "2026-03-01T12:00:00Z"
  },
  "phone_number": {
    "id": "d4e5f6a7-b8c9-0123-defa-234567890123",
    "number": "+14155550100",
    "type": "local",
    "state": "CA",
    "status": "active",
    "sms_status": "ready",
    "sms_error_code": null,
    "sms_error_detail": null,
    "sms_ready_at": "2026-02-25T14:00:05Z",
    "incoming_call_action": "auto_accept",
    "client_websocket_url": "wss://example.com/audio",
    "incoming_call_webhook_url": null,
    "forwarding_target_type": null,
    "forwarding_phone_number": null,
    "forwarding_sip_uri": null,
    "filter_mode": "blacklist",
    "agent_identity_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "created_at": "2026-02-25T14:00:00Z",
    "updated_at": "2026-02-25T14:00:00Z"
  },
  "imessage_number": {
    "id": "3c34233a-c336-4ea6-8dc4-b5d26c996c47",
    "number": "+13105550123",
    "type": "dedicated_outbound"
  }
}

mailbox and tunnel are always populated for active customer identities. phone_number is null when no phone number is attached. imessage_number is null when the identity uses shared service or has no dedicated line attached. Its type remains "dedicated_outbound" as a response-only compatibility field. The embedded tunnel object is a durable-config summary; fetch GET /api/v1/tunnels/{tunnel_id} for live connection state and certificate material.

Error responses

Status	Description
403	Organization ID missing from token
404	Identity not found

Code examples

curl -X GET "https://inkbox.ai/api/v1/identities/sales-agent" \
  -H "X-API-Key: YOUR_API_KEY"

const handle = "sales-agent";
const response = await fetch(
  `https://inkbox.ai/api/v1/identities/${handle}`,
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const identity = await response.json();

import requests

handle = "sales-agent"
response = requests.get(
    f"https://inkbox.ai/api/v1/identities/{handle}",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
identity = response.json()

Update identity

PATCH /identities/{agent_handle}

Update an identity’s handle, display name, description, iMessage settings, attached iMessage line, or contact-rule filter modes. Returns the full identity-detail object, including the attached imessage_number.

Path parameters

Parameter	Type	Description
`agent_handle`	string	Current handle of the identity to update

Request body

Field	Type	Required	Description
`agent_handle`	string	No	New handle. Globally unique. Renaming also renames the linked tunnel in the same transaction. Forbidden when the linked mailbox lives on the platform domain — the handle is the mailbox name there, so a rename would break inbound delivery (returns 409).
`display_name`	string \| null	No	New display name. Max 255 chars.
`description`	string \| null	No	New description. Published on the public Agent Card when A2A is enabled.
`imessage_enabled`	boolean	No	Toggle whether the identity can be reached over iMessage.
`contact_sharing_enabled`	boolean	No	Toggle automatic name and optional photo sharing for an attached dedicated iMessage line. Disabling it removes the line’s automatic sharing profile; the setting remains saved if the line is detached.
`claim_imessage_number`	boolean (`true` only)	No	Set `true` to claim and attach a new dedicated iMessage line. Requires an admin API key and an `Idempotency-Key` header, or use the Inkbox Console.
`imessage_number_id`	UUID \| null	No	Attach an existing organization-owned dedicated line by ID, atomically swap lines, or send `null` to detach the current line and return to shared service. Requires an admin API key, or use the Inkbox Console.
`imessage_filter_mode`	string	No	Alias of `phone_filter_mode` for shared SMS, calls, and iMessage permissions. Setting either changes both; conflicting values in one request return `422`. Requires an admin API key or the Inkbox Console.
`mail_filter_mode`	string	No	`"whitelist"` or `"blacklist"` for this identity’s mail contact rules. Requires an admin API key, or manage it from the Inkbox Console.
`phone_filter_mode`	string	No	`"whitelist"` or `"blacklist"` for shared SMS, calls, and iMessage permissions. Can be configured without a dedicated number. Alias of `imessage_filter_mode`; conflicting values return `422`. Requires admin credentials or the Inkbox Console.

PATCH semantics

The server distinguishes three caller intents on display_name and description:

Intent	Wire payload	Result
Leave unchanged	omit the key from the body	row untouched
Clear	`{"<field>": null}`	column cleared to `null`
Replace	`{"<field>": "new text"}`	column updated

agent_handle, imessage_enabled, contact_sharing_enabled, claim_imessage_number, imessage_filter_mode, mail_filter_mode, and phone_filter_mode accept only the omit half — sending null for those fields is not a clear operation. imessage_number_id is different: an explicit null detaches the dedicated line while leaving it owned by your organization. claim_imessage_number: true and imessage_number_id cannot appear in the same request. A request also cannot claim or attach a line while setting imessage_enabled: false.

Claim idempotency header

Idempotency-Key is required whenever claim_imessage_number is true:

Retry the same logical claim with the same key to receive its original result.
Reusing the key with different input returns 409.
Generate a new key only for a genuinely new claim.

Idempotency-Key: <unique stable key>

Request example

JSON

{
  "display_name": "Sales Agent v2",
  "description": null
}

An existing enabled identity can claim and attach a dedicated line atomically:

bash

curl -X PATCH "https://inkbox.ai/api/v1/identities/sales-agent" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Idempotency-Key: claim-sales-agent-line-01" \
  -H "Content-Type: application/json" \
  -d '{"claim_imessage_number": true}'

Response (200)

Returns the full identity-detail object. When the identity has a dedicated line, its imessage_number field is:

JSON

{
  "imessage_number": {
    "id": "3c34233a-c336-4ea6-8dc4-b5d26c996c47",
    "number": "+13105550123",
    "type": "dedicated_outbound"
  }
}

Error responses

Status	Description
400	`claim_imessage_number: true` was supplied without an `Idempotency-Key` header
402	The organization’s quota does not permit another dedicated iMessage line. Review billing in the Inkbox Console or contact support@inkbox.ai.
403	Organization context is missing, or the caller is not permitted to manage the requested dedicated-line or filter-mode field
404	Identity not found, or the requested dedicated line is unavailable to the organization
409	The idempotency key was reused with incompatible input, the requested number is already attached, the identity is inactive or not enabled for iMessage, the new handle is unavailable, or a rename was rejected because the linked mailbox lives on the platform domain
422	Request validation failed (e.g. conflicting phone/iMessage filter aliases, `claim_imessage_number: true` and `imessage_number_id` together, a line claimed while disabling iMessage, or an over-long display name)
503	Dedicated iMessage-number inventory is temporarily unavailable. Honor `Retry-After`: brief contention may return `5` seconds, while depletion may return `3600` seconds. The response may say that a number is expected within 24 hours.

The 409 body for an unavailable handle uses the same envelope as create: { detail: { code: "agent_handle_unavailable", message, blocking_namespace } }. The 409 for a platform-domain rename returns a flat { detail: "Cannot rename agent_handle: ..." } body explaining that the handle is the mailbox name on the platform domain.

Code examples

curl -X PATCH "https://inkbox.ai/api/v1/identities/sales-agent" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"display_name": "Sales Agent v2"}'

const handle = "sales-agent";
const response = await fetch(
  `https://inkbox.ai/api/v1/identities/${handle}`,
  {
      method: "PATCH",
      headers: {
          "X-API-Key": "YOUR_API_KEY",
          "Content-Type": "application/json",
      },
      body: JSON.stringify({ display_name: "Sales Agent v2" }),
  }
);
const identity = await response.json();

import requests

handle = "sales-agent"
response = requests.patch(
    f"https://inkbox.ai/api/v1/identities/{handle}",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"display_name": "Sales Agent v2"},
)
identity = response.json()

Delete identity

DELETE /identities/{agent_handle}

Delete an identity. The linked mailbox and tunnel are deleted as part of the cascade. Any identity-scoped API keys tied to this identity are revoked. Any linked phone number is released back to the carrier as part of the cascade — phone numbers cannot exist without an identity. The handle, its platform email address, and its tunnel name stay reserved permanently and cannot be claimed again by any organization. Returns 204 No Content on success. If the carrier release fails, the entire delete is aborted with a 502 and the identity stays active so you can retry safely.

Path parameters

Parameter	Type	Description
`agent_handle`	string	Handle of the identity to delete

Error responses

Status	Description
403	Organization ID missing from token
404	Identity not found
502	Carrier release of the linked phone number failed — retry shortly

Code examples

curl -X DELETE "https://inkbox.ai/api/v1/identities/sales-agent" \
  -H "X-API-Key: YOUR_API_KEY"

const handle = "sales-agent";
await fetch(
  `https://inkbox.ai/api/v1/identities/${handle}`,
  {
      method: "DELETE",
      headers: { "X-API-Key": "YOUR_API_KEY" },
  }
);

import requests

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

Identity object

Field	Type	Description
`id`	UUID	Unique identity identifier
`organization_id`	string	Organization that owns this identity
`agent_handle`	string	Globally unique handle
`display_name`	string \| null	Human-readable display name
`description`	string \| null	Description published on the public Agent Card when A2A is enabled
`status`	string	Lifecycle status. Existing identities may return `paused` as a read-only compatibility value; it cannot be set through create or update requests. `deleted` may appear on deleted identities.
`imessage_enabled`	boolean	Whether the identity can be reached over iMessage. Defaults to `false`
`contact_sharing_enabled`	boolean	Whether an attached dedicated iMessage line automatically shares this identity’s display name (falling back to its handle) and optional avatar. New identities default to `true`; identities that already had dedicated lines when the feature launched were initialized to `false`. The preference remains saved without an attached line.
`imessage_filter_mode`	string	Alias of `phone_filter_mode`; both report the same shared SMS, calls, and iMessage mode. Defaults to `"blacklist"`
`mail_filter_mode`	string	`"whitelist"` or `"blacklist"` for this identity’s mail contact rules. Defaults to `"blacklist"`
`phone_filter_mode`	string	`"whitelist"` or `"blacklist"` for shared phone contact rules, covering SMS, calls, and iMessage. Defaults to `"blacklist"`
`email_address`	string \| null	Email address of the linked mailbox
`has_avatar`	boolean	Whether a contact-card avatar is stored for this identity
`signing_key_configured`	boolean	Whether this identity has a webhook signing key configured
`signing_key_created_at`	string \| null	When the signing key was last set or rotated (ISO 8601); `null` when none is configured
`created_at`	string	Creation timestamp (ISO 8601)
`updated_at`	string	Last update timestamp (ISO 8601)

signing_key_configured and signing_key_created_at are status only — the signing secret itself is never returned here. The plaintext key is shown once by the per-identity signing-key rotate endpoint.

Identity detail object

Extends the identity object with linked channel data. Returned by the list, create, get, and update endpoints.

Field	Type	Description
…all identity fields
`mailbox`	object \| null	Linked mailbox object, including `signature_html`, `signature_text`, and `signature_enabled`. Always populated for active customer identities. Configure signatures through Update mailbox, not the identity update.
`tunnel`	object \| null	Linked tunnel object. Always populated for active customer identities.
`phone_number`	object \| null	Linked phone number object, or `null` if no phone number is attached
`imessage_number`	object \| null	Attached dedicated iMessage line with `id`, E.164 `number`, and response-only `type` (`"dedicated_outbound"`), or `null` when the identity uses shared service

Existing imessage_number_id attachment and detachment remain available. Detaching a dedicated line leaves it owned by the organization and visible from GET /api/v1/imessage/numbers. There is no customer-facing line-release endpoint.

​Create identity

​Request body

​mailbox fields

​tunnel fields

​phone_number fields

​vault_secret_ids

​Request example

​Response (201)

​Mailbox local-part validation

​Handle validation

​Error responses

​Code examples

​List identities

​Response (200)

​Code examples

​Get identity

​Path parameters

​Response (200)

​Error responses

​Code examples

​Update identity

​Path parameters

​Request body

​PATCH semantics

​Claim idempotency header

​Request example

​Response (200)

​Error responses

​Code examples

​Delete identity

​Path parameters

​Error responses

​Code examples

​Identity object

​Identity detail object

Create identity

Request body

`mailbox` fields

`tunnel` fields

`phone_number` fields

`vault_secret_ids`

Request example

Response (201)

Mailbox local-part validation

Handle validation

Error responses

Code examples

List identities

Response (200)

Code examples

Get identity

Path parameters

Response (200)

Error responses

Code examples

Update identity

Path parameters

Request body

PATCH semantics

Claim idempotency header

Request example

Response (200)

Error responses

Code examples

Delete identity

Path parameters

Error responses

Code examples

Identity object

Identity detail object