## Create a property definition

`prism.properties.create(Literal["comment", "deal", "engagement", 9 more]object_type, PropertyCreateParams**kwargs)  -> PropertyDefinition`

**post** `/v2/prism/{teamId}/{objectType}/properties`

Define a new property on this object type, scoped to the calling team. Search the existing properties first (GET this path with `term`) and reuse a match instead of defining a second property for the same fact. Pass `list_id` in the body to scope the definition to one list/app; without it the property is workspace-global and appears on every list. A name already used in that scope, an explicitly requested slug already taken, or a slug that a shared property already owns all return 409 naming the definition to use instead. The property's display format is resolved from `type` automatically — pass `role_id` only to override it. For `select_str` and `multiselect_str` types you may pre-seed the choices via `options`.

### Parameters

- `team_id: Optional[str]`

- `object_type: Literal["comment", "deal", "engagement", 9 more]`

  - `"comment"`

  - `"deal"`

  - `"engagement"`

  - `"identity"`

  - `"ai_chat_thread"`

  - `"ai_chat_message"`

  - `"agent_site"`

  - `"document"`

  - `"action"`

  - `"event"`

  - `"organization"`

  - `"contact"`

- `name: str`

  Human-readable name, unique within the scope the definition is created in. A name already taken in that scope returns 409; the message names the existing definition's id, slug and type so you can write to it instead.

- `type: Literal["num", "str", "bool", 34 more]`

  Storage type for a property definition. Determines which per-type table holds the values, and which display formats the property can take.

  - `"num"`

  - `"str"`

  - `"bool"`

  - `"date"`

  - `"text"`

  - `"byte"`

  - `"select_str"`

  - `"multi_str"`

  - `"multiselect_str"`

  - `"jsonb"`

  - `"ref_identity"`

  - `"ref_user"`

  - `"ref_organization"`

  - `"ref_contact"`

  - `"ref_thread"`

  - `"ref_message"`

  - `"ref_event"`

  - `"ref_account"`

  - `"ref_ai_chat_thread"`

  - `"ref_ai_chat_message"`

  - `"multiref_ai_chat_message"`

  - `"multiref_agent_site"`

  - `"multiref_action"`

  - `"multiref_comment"`

  - `"multiref_contact"`

  - `"multiref_label"`

  - `"multiref_thread"`

  - `"multiref_messages"`

  - `"multiref_document"`

  - `"multiref_identity"`

  - `"multiref_organization"`

  - `"multiref_engagement"`

  - `"multiref_attendee"`

  - `"multiref_meeting_entry"`

  - `"multiref_read_receipt"`

  - `"multiref_account"`

  - `"multiref_source"`

- `icon: Optional[str]`

- `list_id: Optional[str]`

  Scopes the definition to one list/app. Omit it only for a property that genuinely belongs to the whole workspace: a definition created without `list_id` is workspace-global and surfaces on every list of this object type.

- `options: Optional[Iterable[Option]]`

  Only honored when `type` is `select_str` or `multiselect_str`.

  - `value: str`

  - `color_scheme: Optional[str]`

  - `description: Optional[str]`

  - `icon: Optional[str]`

  - `option_group: Optional[str]`

  - `slug: Optional[str]`

  - `sort_index: Optional[int]`

- `required: Optional[bool]`

  When true, records must carry a non-empty value for this property on create. Defaults to false.

- `role_id: Optional[str]`

  Optional display format for the property, drawn from the workspace's property roles. Omit it and the canonical role for `type` is applied (plain text, plain number, checkbox). Supply it only to pick a narrower format such as email, URL or currency; the role's data type must match `type`.

- `slug: Optional[str]`

  URL-safe identifier. When omitted it defaults to a slugified `name` and is disambiguated with a numeric suffix on conflict. When supplied explicitly it is treated as part of your write contract and is never silently renamed — a collision returns 409 instead.

- `idempotency_key: Optional[str]`

### Returns

- `class PropertyDefinition: …`

  Definition for a single property on an object type. Definitions with team_id and crm_id null are shared defaults; values may be scoped to a team and/or list (crm).

  - `id: str`

  - `slug: str`

  - `type: Literal["num", "str", "bool", 34 more]`

    Storage type for a property definition. Determines which per-type table holds the values, and which display formats the property can take.

    - `"num"`

    - `"str"`

    - `"bool"`

    - `"date"`

    - `"text"`

    - `"byte"`

    - `"select_str"`

    - `"multi_str"`

    - `"multiselect_str"`

    - `"jsonb"`

    - `"ref_identity"`

    - `"ref_user"`

    - `"ref_organization"`

    - `"ref_contact"`

    - `"ref_thread"`

    - `"ref_message"`

    - `"ref_event"`

    - `"ref_account"`

    - `"ref_ai_chat_thread"`

    - `"ref_ai_chat_message"`

    - `"multiref_ai_chat_message"`

    - `"multiref_agent_site"`

    - `"multiref_action"`

    - `"multiref_comment"`

    - `"multiref_contact"`

    - `"multiref_label"`

    - `"multiref_thread"`

    - `"multiref_messages"`

    - `"multiref_document"`

    - `"multiref_identity"`

    - `"multiref_organization"`

    - `"multiref_engagement"`

    - `"multiref_attendee"`

    - `"multiref_meeting_entry"`

    - `"multiref_read_receipt"`

    - `"multiref_account"`

    - `"multiref_source"`

  - `alias: Optional[Literal["app_stage"]]`

    Reserved alias naming this definition, or null. `app_stage` marks the list pipeline stage definition. Resolve stages by this field rather than by name, slug, or team_id: a superseded native `status` definition can coexist with the pipeline one and is otherwise identical on the wire.

    - `"app_stage"`

  - `crm_id: Optional[str]`

    Identifier of the list this definition is scoped to, when applicable.

  - `list_id: Optional[str]`

    Canonical identifier of the list this definition is scoped to.

  - `locked: Optional[bool]`

  - `name: Optional[str]`

  - `native: Optional[bool]`

  - `options: Optional[List[PropertyOption]]`

    Present only for select_str and multiselect_str types.

    - `id: str`

    - `slug: str`

    - `color_scheme: Optional[str]`

    - `crm_id: Optional[str]`

    - `description: Optional[str]`

    - `icon: Optional[str]`

    - `list_id: Optional[str]`

    - `option_group: Optional[str]`

    - `sort_index: Optional[int]`

    - `value: Optional[str]`

      Display value for the option.

  - `required: Optional[bool]`

    When true, records of this object type must carry a non-empty value for this property on create, and a patch may not clear it.

  - `role_id: Optional[str]`

    The property's display format. Always populated on definitions created through this API; a null here means the definition predates that and will render as an unknown format until it is patched.

  - `team_id: Optional[str]`

### Example

```python
import os
from micro_so import Micro

client = Micro(
    api_key=os.environ.get("MICRO_API_KEY"),  # This is the default and can be omitted
)
property_definition = client.prism.properties.create(
    object_type="comment",
    name="name",
    type="num",
)
print(property_definition.id)
```

#### Response

```json
{
  "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
  "slug": "slug",
  "type": "num",
  "alias": "app_stage",
  "crm_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
  "list_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
  "locked": true,
  "name": "name",
  "native": true,
  "options": [
    {
      "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
      "slug": "slug",
      "color_scheme": "color_scheme",
      "crm_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
      "description": "description",
      "icon": "icon",
      "list_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
      "option_group": "option_group",
      "sort_index": 0,
      "value": "value"
    }
  ],
  "required": true,
  "role_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
  "team_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"
}
```