---
canonical_url: "https://docs.composio.dev/toolkits/peerdom"
markdown_url: "https://docs.composio.dev/toolkits/peerdom.md"
product: "platform"
version: null
last_updated: null
---

# Peerdom

Peerdom helps organizations map roles, people, groups, projects, goals, pages, and cards through a collaborative organizational platform.

- **Category:** project management
- **Auth:** API_KEY
- **Composio-managed OAuth available?** N/A
- **Tools:** 19
- **Triggers:** 0
- **Slug:** `PEERDOM`
- **Version:** 00000000_00

## Tools

### Create Custom Field Definition

**Slug:** `PEERDOM_CREATE_CUSTOM_FIELD_DEFINITION`

Create one custom-field definition that controls a named field's owner, type, multiplicity, order, and visibility.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | Yes | Definition name and API key used when writing custom-field values. |
| `order` | integer | Yes | Display order among custom fields. |
| `entity` | string ("node" | "peer" | "project" | "goal") | Yes | Entity type that owns this field. |
| `public` | boolean | Yes | Whether the field is publicly visible in Peerdom public data. |
| `node_type` | string ("circle" | "role" | "generic") | Yes | Applicable node subtype; use generic for peer fields. |
| `field_type` | string ("text" | "textarea" | "email" | "link" | "date" | "relation" | "image" | "list") | Yes | Value type enforced by Peerdom. |
| `multi_entry` | boolean | Yes | Whether entities may store multiple values for this field. |
| `translation` | object | No | Optional display labels keyed by Peerdom's supported language codes. |
| `relation_scope` | string ("group" | "page" | "peer" | "role") | No | Allowed target type. Required when field_type is relation; omit for all other field types. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create Group

**Slug:** `PEERDOM_CREATE_GROUP`

Create a group from an existing parent-group anchor on a map. Set external to true to detach the new group as a top-level external group.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | Yes | Name of the new group. |
| `color` | string | No | Optional display color. Use a palette hex value returned by GET_ORGANIZATION_CONTEXT; arbitrary hex colors are rejected. Omit this field to let Peerdom choose its default color. |
| `shape` | string ("circle") | No | Node shape. Only circle is exposed because it is the live-verified safe value. |
| `map_id` | string | Yes | Map that will contain the group; resolve it with GET_ORGANIZATION_CONTEXT. |
| `external` | boolean | No | Create an external top-level group. parent_group_id is still required as Peerdom's creation anchor. |
| `custom_fields` | object | No | Values keyed by existing node custom-field definition name. |
| `parent_group_id` | string | Yes | Existing parent group used as the creation anchor. Required even when external is true; external=true detaches the created group afterward. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create Peer

**Slug:** `PEERDOM_CREATE_PEER`

Create an email-free person record in the organization; this tool deliberately cannot provision a Peerdom login account.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `nickname` | string | Yes | Peer's display nickname; part of the verified minimum create shape. |
| `birthdate` | string | No | Birth date in YYYY-MM-DD form. |
| `last_name` | string | Yes | Peer's last name; part of the verified minimum create shape. |
| `first_name` | string | Yes | Peer's first name; part of the verified minimum create shape. |
| `custom_fields` | object | No | Values keyed by existing custom-field definition name; list definitions before using this field. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create Role

**Slug:** `PEERDOM_CREATE_ROLE`

Create a role under a parent group on a map using core role fields that do not require Peerdom's Contribution or Goals apps.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | Yes | Name of the new role. |
| `color` | string | No | Optional display color. Use a palette hex value returned by GET_ORGANIZATION_CONTEXT; arbitrary hex colors may be rejected. Omit this field to let Peerdom choose its default color. |
| `map_id` | string | Yes | ID of the map that will contain the role. |
| `external` | boolean | No | Whether the role is external to the organization. |
| `custom_fields` | object | No | Values keyed by existing role custom-field definition name; list definitions before using this field. |
| `parent_group_id` | string | Yes | ID of the group under which to create the role. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Deactivate Peer

**Slug:** `PEERDOM_DEACTIVATE_PEER`

Mark a peer as former. This is a soft delete: the peer is removed from normal active-peer reads but remains available when former peers are included.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `peer_id` | string | Yes | ID of the peer to mark as former. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Delete Custom Field Definition

**Slug:** `PEERDOM_DELETE_CUSTOM_FIELD_DEFINITION`

Permanently delete a custom-field definition. WARNING: Peerdom cascade-deletes every value stored against the definition; this cannot be undone and requires explicit confirmation.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `definition_id` | string | Yes | ID of the custom-field definition to permanently delete. Every value stored against this definition will also be deleted. |
| `confirm_cascade_delete` | boolean ("true") | Yes | Must be true to confirm permanent deletion of the definition and all values stored against it. This confirmation is validated locally and is not sent to Peerdom. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Delete Group

**Slug:** `PEERDOM_DELETE_GROUP`

Permanently delete one group after reading it to block accidental root-group deletion. Root deletion requires separate explicit authorization.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `group_id` | string | Yes | ID of the group to delete; do not pass a map's root group unless removal is intended. |
| `confirm_delete` | boolean ("true") | Yes | Must be true to confirm permanent deletion of this group. |
| `allow_root_group_delete` | boolean ("true") | No | Set true only to explicitly allow deleting a map root group. Root deletion can remove a large organizational subtree. External top-level groups are not map roots and do not need it. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Delete Role

**Slug:** `PEERDOM_DELETE_ROLE`

Delete one role by ID and return the deleted role for confirmation.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `role_id` | string | Yes | ID of the role to delete. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Custom Field Definitions

**Slug:** `PEERDOM_GET_CUSTOM_FIELD_DEFINITIONS`

List custom-field definitions or return one definition by ID so agents can use the organization's real field names and value types.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `entity` | string ("node" | "peer" | "project" | "goal") | No | Only list definitions owned by this entity type; ignored for exact lookup. |
| `definition_id` | string | No | Definition ID to retrieve. Omit to list definitions. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Groups

**Slug:** `PEERDOM_GET_GROUPS`

List organization groups or return one group by ID, with optional map and peer filters and optional custom-field-value expansion.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `limit` | integer | No | Maximum groups in this page (1-100); used only when listing. |
| `map_id` | string | No | Only list groups on this map; omit for the live map. |
| `peer_id` | string | No | Only list groups associated with this peer. |
| `group_id` | string | No | Group ID to retrieve. Omit to list groups. |
| `next_cursor` | string | No | Opaque continuation cursor returned by an earlier list call. |
| `include_custom_fields` | boolean | No | Include custom-field values on returned groups. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Organization Context

**Slug:** `PEERDOM_GET_ORGANIZATION_CONTEXT`

Return the connected Peerdom organization and its maps, including the live map ID and tenant palette needed to create groups and roles.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Peers

**Slug:** `PEERDOM_GET_PEERS`

List peers with optional former-peer and custom-field inclusion, or return one peer by ID with optional roles and custom fields.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `limit` | integer | No | Maximum peers in this page (1-100); used only when listing. |
| `include` | array | No | Related data to include. roles applies only when peer_id is supplied; customfields works for list and detail. |
| `peer_id` | string | No | Peer ID to retrieve. Omit to list peers. |
| `next_cursor` | string | No | Opaque continuation cursor returned by an earlier list call. |
| `include_former` | boolean | No | Include former peers; required to retrieve a peer after deactivation. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Roles

**Slug:** `PEERDOM_GET_ROLES`

List roles or return one role by ID, with optional peer, group, and map filters plus holder, group, representing-node, and custom-field expansions.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `limit` | integer | No | Maximum roles in this page (1-100); used only when listing. |
| `map_id` | string | No | Only list roles on this map; omit for the live map. |
| `include` | array | No | Related role data to include: holders, customfields, groups, or representing. Multiple values may be supplied. |
| `peer_id` | string | No | Only list roles held by this peer; takes precedence over group_id. |
| `role_id` | string | No | Role ID to retrieve. Omit to list roles. |
| `group_id` | string | No | Only list roles in this group; ignored when peer_id is supplied. |
| `next_cursor` | string | No | Opaque continuation cursor returned by an earlier list call. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Unassign Role Holder

**Slug:** `PEERDOM_UNASSIGN_ROLE_HOLDER`

Remove one peer's assignment from one role without deleting either the peer or the role.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `peer_id` | string | Yes | Peer whose role assignment to remove. |
| `role_id` | string | Yes | Role from which to remove the peer. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Update Custom Field Definition

**Slug:** `PEERDOM_UPDATE_CUSTOM_FIELD_DEFINITION`

Rename a custom-field definition and its custom-field API key, or update its labels, display order, or public visibility without changing its value type or owner.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | No | New definition name; this also changes the API key used to write custom-field values. |
| `order` | integer | No | New display order. |
| `public` | boolean | No | New public visibility state. |
| `translation` | object | No | Replacement display labels keyed by supported language code. |
| `definition_id` | string | Yes | ID of the custom-field definition to update. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Update Group

**Slug:** `PEERDOM_UPDATE_GROUP`

Update selected group properties such as name, parent, external state, color, shape, or custom fields. Omitted fields remain unchanged.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | No | New group name; omit to preserve it. |
| `color` | string | No | New display color. Use a palette hex value returned by GET_ORGANIZATION_CONTEXT; arbitrary hex colors may be rejected. Omit to preserve the current color. |
| `shape` | string ("circle") | No | New node shape. Only circle is exposed because it is the live-verified safe value; omit to preserve the current shape. |
| `external` | boolean | No | Whether the group is external; omit to preserve it. |
| `group_id` | string | Yes | ID of the group to update. |
| `custom_fields` | object | No | Named custom-field values to update. |
| `parent_group_id` | string | No | New parent group ID; omit to preserve it. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Update Peer

**Slug:** `PEERDOM_UPDATE_PEER`

Update selected profile fields on an existing peer; omitted fields remain unchanged despite the provider using PUT.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `peer_id` | string | Yes | ID of the peer to update. |
| `nickname` | string | No | New display nickname; omit to preserve it. |
| `last_name` | string | No | New last name; omit to preserve it. |
| `first_name` | string | No | New first name; omit to preserve it. |
| `custom_fields` | object | No | Replacement values for named custom fields included in this update. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Update Role

**Slug:** `PEERDOM_UPDATE_ROLE`

Update selected core role properties without changing Contribution- or Goals-specific settings.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | No | New role name; omit to preserve it. |
| `color` | string | No | New display color. Use a palette hex value returned by GET_ORGANIZATION_CONTEXT; arbitrary hex colors may be rejected. Omit to preserve the current color. |
| `role_id` | string | Yes | ID of the role to update. |
| `external` | boolean | No | Whether the role is external; omit to preserve it. |
| `custom_fields` | object | No | Named custom-field values to update. |
| `parent_group_id` | string | No | New parent group ID; omit to preserve it. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Assign Or Update Role Holder

**Slug:** `PEERDOM_UPSERT_ROLE_HOLDER`

Ensure a peer holds a role, creating the assignment when absent or updating its percentage, focus, and elected-until date when present.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `focus` | string | No | Optional focus or responsibility note for the assignment. |
| `peer_id` | string | Yes | Peer who should hold the role. |
| `role_id` | string | Yes | Role to assign. |
| `percentage` | number | No | Allocation percentage for this role; omit when no change is needed. |
| `elected_until` | string | No | Optional election end date in YYYY-MM-DD form. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |