Skip to content
Micro micro
Go to Micro
API Reference
Prism
Properties

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 ParametersExpand Collapse
teamId: optional string
formatuuid
objectType: "comment" or "deal" or "engagement" or 9 more
One of the following:
"comment"
"deal"
"engagement"
"identity"
"ai_chat_thread"
"ai_chat_message"
"agent_site"
"document"
"action"
"event"
"organization"
"contact"
Header ParametersExpand Collapse
"Idempotency-Key": optional string
minLength1
maxLength255
Body ParametersJSONExpand Collapse
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.

One of the following:
"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.

formatuuid
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.

formatuuid
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.

ReturnsExpand Collapse
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
formatuuid
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.

One of the following:
"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.

crm_id: optional string

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

formatuuid
list_id: optional string

Canonical identifier of the list this definition is scoped to.

formatuuid
locked: optional boolean
name: optional string
native: optional boolean
options: optional array of PropertyOption { id, slug, color_scheme, 7 more }

Present only for select_str and multiselect_str types.

id: string
formatuuid
slug: string
color_scheme: optional string
Deprecatedcrm_id: optional string
formatuuid
description: optional string
icon: optional string
list_id: optional string
formatuuid
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.

formatuuid
team_id: optional string
formatuuid

Create a property definition

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"
        }'
{
  "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"
}
Returns Examples
{
  "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"
}