---
title: "Create an identity with its mandatory mailbox and tunnel, optionally also a phone number and/or attached vault secret access"
method: POST
path: "/api/v1/identities/"
tags: ["Identities"]
---

# Create an identity with its mandatory mailbox and tunnel, optionally also a phone number and/or attached vault secret access

`POST /api/v1/identities/`

## Request body

- AgentIdentityCreateRequest
  - `agent_handle` string, required — Agent handle for the identity. A leading '@' is stripped automatically and the handle must be globally unique.
  - `display_name` string, nullable — Human-readable display name for the identity. Defaults to agent_handle if omitted.
  - `description` string, nullable — Free-form description of what the identity is. Visible only to your org.
  - `imessage_enabled` boolean — Whether this identity can be reached through the shared iMessage service. Defaults to false; set true to opt in.
  - `contact_sharing_enabled` boolean — Whether an attached dedicated iMessage line automatically shares this identity's name and optional avatar. Defaults to true.
  - `claim_imessage_number` true, nullable — Claim and attach a dedicated iMessage line during identity creation. Requires imessage_enabled=true.
  - `mailbox` AgentIdentityMailboxCreateRequest
    - `email_local_part` string, nullable — Optional mailbox email local part to use before the sending domain. On the platform domain it must equal agent_handle (the server forces it). Omit on the platform domain to use agent_handle automatically; supply for a custom domain to pick a specific local part.
    - `sending_domain` string, nullable — Optional sending-domain name (e.g. 'assistant.alexwilcox.io'). Omit to inherit the org's default (custom domain if verified, else inkboxmail.com); pass null to force the platform default; pass a verified custom-domain string to bind this mailbox to it.
  - `tunnel` AgentIdentityTunnelCreateRequest
    - `tls_mode` 'edge' | 'passthrough'
  - `phone_number` AgentIdentityPhoneNumberCreateRequest
    - `type` 'local' | 'toll_free'
    - `state` string, nullable — Optional US state abbreviation filter. Only used for local numbers.
    - `incoming_call_action` 'auto_accept' | 'auto_reject' | 'webhook' | 'hosted_agent' | 'forward'
    - `client_websocket_url` string, nullable — WebSocket URL (wss://) for audio bridging. Required when incoming_call_action is 'auto_accept'.
    - `incoming_call_webhook_url` string, nullable — Webhook URL (https://) for incoming call notifications. Required when incoming_call_action is 'webhook'.
    - `forwarding_target_type` 'phone' | 'sip'
    - `forwarding_phone_number` string, nullable — Phone number in E.164 format (e.g. '+15551234567').
    - `forwarding_sip_uri` string, nullable — Complete SIP destination in sip:user@host format.
  - `vault_secret_ids` union — Optional vault secret attachment request to scope vault secret access to the newly created agent identity.
    - string, uuid
    - string[]
    - '*' | 'all'

## Response `201`

Successful Response

- AgentIdentityDetailResponse
  - `id` string, uuid, required
  - `organization_id` string, required
  - `agent_handle` string, required
  - `display_name` string, nullable
  - `description` string, nullable
  - `status` 'active' | 'paused' | 'deleted'
  - `imessage_enabled` boolean
  - `contact_sharing_enabled` boolean
  - `imessage_filter_mode` 'whitelist' | 'blacklist'
  - `mail_filter_mode` 'whitelist' | 'blacklist'
  - `phone_filter_mode` 'whitelist' | 'blacklist'
  - `email_address` string, email, nullable
  - `has_avatar` boolean
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required
  - `signing_key_configured` boolean
  - `signing_key_created_at` string, date-time, nullable
  - `mailbox` MailboxResponse
    - `id` string, uuid, required
    - `email_address` string, required
    - `status` 'active' | 'paused' | 'deleted'
    - `sending_domain` string — Bare domain the mailbox sends from, derived from email_address. Matches the platform default (inkboxmail.com) or the customer's verified custom domain.
    - `filter_mode` 'whitelist' | 'blacklist', required
    - `agent_identity_id` string, uuid, nullable — ID of the agent identity that owns this mailbox, or null on tombstones / system mailboxes.
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required
    - `storage_used_bytes` integer — Live storage used by this inbox, in bytes.
    - `storage_limit_bytes` integer, nullable — Resolved plan-tiered storage cap in bytes; null when the route did not resolve it (the ORM does not carry the cap).
    - `filter_mode_change_notice` FilterModeChangeNotice
      - `new_filter_mode` 'whitelist' | 'blacklist', required
      - `redundant_rule_action` string, required — 'block' or 'allow'; the action whose rules are now redundant.
      - `redundant_rule_count` integer, required — Count of active rules whose action equals redundant_rule_action. 0 = clean flip; >0 = console UI should prompt the operator to review.
    - `unread_count` integer, nullable
  - `phone_number` PhoneNumberResponse
    - `id` string, uuid, required
    - `number` string, required
    - `type` 'local' | 'toll_free', required
    - `status` 'active' | 'paused' | 'released', required
    - `sms_status` 'pending' | 'ready' | 'assignment_failed', required
    - `sms_error_code` string, nullable
    - `sms_error_detail` string, nullable
    - `sms_ready_at` string, date-time, nullable
    - `incoming_call_action` 'auto_accept' | 'auto_reject' | 'webhook' | 'hosted_agent' | 'forward', required
    - `client_websocket_url` string, nullable, required
    - `incoming_call_webhook_url` string, nullable, required
    - `forwarding_target_type` 'phone' | 'sip'
    - `forwarding_phone_number` string, nullable
    - `forwarding_sip_uri` string, nullable
    - `filter_mode` 'whitelist' | 'blacklist', required
    - `state` string, nullable — 2-letter US state abbreviation for LOCAL numbers (e.g. 'NY'). Null for toll-free numbers.
    - `agent_identity_id` string, uuid, nullable — ID of the agent identity that owns this phone number, or null if the number is standalone (not tied to any agent).
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required
    - `filter_mode_change_notice` FilterModeChangeNotice
      - `new_filter_mode` 'whitelist' | 'blacklist', required
      - `redundant_rule_action` string, required — 'block' or 'allow'; the action whose rules are now redundant.
      - `redundant_rule_count` integer, required — Count of active rules whose action equals redundant_rule_action. 0 = clean flip; >0 = console UI should prompt the operator to review.
  - `imessage_number` AgentIdentityIMessageNumberResponse
    - `id` string, uuid, required
    - `number` string, required
    - `type` 'dedicated_outbound', required
    - `status` 'active' | 'paused' | 'released'
    - `inbound_only` false — Deprecated compatibility field; dedicated lines can initiate.
  - `tunnel` TunnelSummaryResponse
    - `id` string, uuid, required
    - `tunnel_name` string, required
    - `agent_identity_id` string, uuid, nullable — Identifier of the identity associated with this tunnel, when available.
    - `tls_mode` 'edge' | 'passthrough', required
    - `status` 'awaiting_cert' | 'active' | 'deleted', required
    - `public_host` string, required
    - `zone` string, required
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required

## Other responses

- `402` — An identity or dedicated-number quota was exceeded.
- `422` — Validation Error
- `503` — Identity provisioning is temporarily unavailable.
- `4XX` — Client error with Support Agent information.
- `5XX` — Server error with Support Agent information.

---

[API](https://skmtc.dev/inkbox/apis/inkbox-api.md) · [All operations](https://skmtc.dev/inkbox/apis/inkbox-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/inkbox/inkbox-api/revisions/31f357e7e6f8/schema)