## Create a property definition

**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`.

### Path Parameters

- `teamId: optional string`

- `objectType: "comment" or "deal" or "engagement" or 9 more`

  - `"comment"`

  - `"deal"`

  - `"engagement"`

  - `"identity"`

  - `"ai_chat_thread"`

  - `"ai_chat_message"`

  - `"agent_site"`

  - `"document"`

  - `"action"`

  - `"event"`

  - `"organization"`

  - `"contact"`

### Header Parameters

- `"Idempotency-Key": optional string`

### Body Parameters

- `name: string`

  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: "num" or "str" or "bool" or 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 string`

- `list_id: optional string`

  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 array of object { value, color_scheme, description, 4 more }`

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

  - `value: string`

  - `color_scheme: optional string`

  - `description: optional string`

  - `icon: optional string`

  - `option_group: optional string`

  - `slug: optional string`

  - `sort_index: optional number`

- `required: optional boolean`

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

- `role_id: optional string`

  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 string`

  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.

### Returns

- `PropertyDefinition object { id, slug, type, 10 more }`

  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: string`

  - `slug: string`

  - `type: "num" or "str" or "bool" or 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 "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 string`

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

  - `list_id: optional string`

    Canonical identifier of the list this definition is scoped to.

  - `locked: optional boolean`

  - `name: optional string`

  - `native: optional boolean`

  - `options: optional array of PropertyOption`

    Present only for select_str and multiselect_str types.

    - `id: string`

    - `slug: string`

    - `color_scheme: optional string`

    - `crm_id: optional string`

    - `description: optional string`

    - `icon: optional string`

    - `list_id: optional string`

    - `option_group: optional string`

    - `sort_index: optional number`

    - `value: optional string`

      Display value for the option.

  - `required: optional boolean`

    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 string`

    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 string`

### Example

```http
curl https://developers.micro.so/v2/prism/$TEAM_ID/$OBJECT_TYPE/properties \
    -H 'Content-Type: application/json' \
    -H "x-api-key: $MICRO_API_KEY" \
    -d '{
          "name": "name",
          "type": "num"
        }'
```

#### 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"
}
```