logo
API docs by Redocly

Peerdom Public API (0.6.0)

Download OpenAPI specification:Download

Peerdom Support: support@peerdom.org URL: https://peerdom.com Terms of Service

Purpose

Peerdom’s RESTful API offers organizations another way to work with the data they manage in Peerdom, making it easy to integrate with other tools or automate processes.

API Access Requirements

API access is available only to organizations with an active paid subscription or during an active trial period. Organizations upgrade to Peerdom+ to gain access.

Create your API key in your organization’s settings.

Peerdom's API URL is https://api.peerdom.app/

Authentication

All API endpoints operate in the context of a single organization, determined by the API key you provide. Most endpoints require this key to return data.

Include your API key in the request header using: X-Api-Key.

Data Encoding

The API returns JSON-encoded data. Apply any additional encoding needed for your specific context (for example, escape HTML tags when rendering in a browser).

Peers

API endpoints related to Peers

Get List of Peers

Gets a lists of all peers within the organization's namespace.

Authorizations:
X-Api-Key
query Parameters
limit
integer [ 1 .. 100 ]

Pagination: limit the result to limit items (1-100). Recommended for large orgs.

offset
integer >= 0

Pagination: skip the first offset items (0-based).

includeFormer
boolean

When true, former peers (those who have left) are included in the result alongside active ones. Defaults to false (active peers only).

with
string

Use customfields for inclusion of custom fields. (roles is only effective on GET /peers/{id}; it is ignored on the list.)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create New Peer

Create a new peer within the organization's namespace.

Authorizations:
X-Api-Key
Request Body schema: application/json
required

Create one peer (single object) or many peers (array, 1..n). An array is created atomically: all peers are created or none are.

One of
firstName
required
string
lastName
string
nickName
string
email
string <email>

The peer's email address.

birthdate
string <date>
percentage
integer

Contribution App needs to be enabled for this attribute.

object

The custom fields for a peer. You can add the properties from the predefined custom fields. Please refer to the example in the sample request.

Responses

Request samples

Content type
application/json
[ ]

Response samples

Content type
application/json
Example
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "firstName": "string",
  • "lastName": "string",
  • "nickName": "string",
  • "slug": "string",
  • "avatarUrl": "string",
  • "birthdate": "2019-08-24T14:15:22Z",
  • "joinedAt": "2019-08-24T14:15:22Z",
  • "leftAt": "2019-08-24T14:15:22Z",
  • "roles": [
    ],
  • "contribution": 0,
  • "contributionUnit": "string",
  • "customFields": [
    ]
}

Get Single Peer

Gets a single peer based on their single ID.

Authorizations:
X-Api-Key
path Parameters
id
required
string <uuid>

ID of peer to fetch

query Parameters
with
string

Comma-separated list of extra data to include. Use customfields for custom fields, and roles to include the roles this peer holds.

includeFormer
boolean

When true, a former peer (one who has left) can be fetched by id. Defaults to false, which returns 404 for former peers.

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "firstName": "string",
  • "lastName": "string",
  • "nickName": "string",
  • "slug": "string",
  • "avatarUrl": "string",
  • "birthdate": "2019-08-24T14:15:22Z",
  • "joinedAt": "2019-08-24T14:15:22Z",
  • "leftAt": "2019-08-24T14:15:22Z",
  • "roles": [
    ],
  • "contribution": 0,
  • "contributionUnit": "string",
  • "customFields": [
    ]
}

Update A Peer

Update a single peer based on the ID supplied.

Authorizations:
X-Api-Key
path Parameters
id
required
string <uuid>

ID of peer to update

Request Body schema: application/json
required

Update a peer

firstName
string
lastName
string
nickName
string
email
string <email>

The peer's email address.

birthdate
string <date>
percentage
integer

Contribution App needs to be enabled for this attribute.

object

The custom fields for a peer. You can add the properties from the predefined custom fields. Please refer to the example in the sample request.

Responses

Request samples

Content type
application/json
{
  • "firstName": "string",
  • "lastName": "string",
  • "nickName": "string",
  • "email": "user@example.com",
  • "birthdate": "2019-08-24",
  • "percentage": 0,
  • "customFields": {
    }
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "firstName": "string",
  • "lastName": "string",
  • "nickName": "string",
  • "slug": "string",
  • "avatarUrl": "string",
  • "birthdate": "2019-08-24T14:15:22Z",
  • "joinedAt": "2019-08-24T14:15:22Z",
  • "leftAt": "2019-08-24T14:15:22Z",
  • "roles": [
    ],
  • "contribution": 0,
  • "contributionUnit": "string",
  • "customFields": [
    ]
}

Delete A Peer

Delete a single peer based on the ID supplied.

Authorizations:
X-Api-Key
path Parameters
id
required
string <uuid>

ID of peer to delete

Responses

Response samples

Content type
application/json
{
  • "message": "string"
}

Set A Peer's Photo

Set (upload or replace) a peer's profile photo. The image is resized and stored, and the peer's avatarUrl is updated. Provide the image in one of two ways on this single endpoint:

  • multipart/form-data with a file field (raw image bytes), or
  • application/json with an imageUrl the server fetches itself.

For imageUrl the fetch is restricted for safety: HTTPS only, public hosts only (private, loopback, link-local and cloud-metadata addresses are rejected), a few redirects at most, and a short timeout.

Allowed formats: JPEG, PNG, WebP. Maximum size 5 MB and maximum dimensions 4000x4000 pixels. Uploading the same image again is a no-op.

Authorizations:
X-Api-Key
path Parameters
id
required
string <uuid>

ID of the peer whose photo to set

Request Body schema:
required
file
required
string <binary>

Image file (JPEG, PNG or WebP). Max 5 MB, max 4000x4000 px.

Responses

Request samples

Content type
No sample

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "firstName": "string",
  • "lastName": "string",
  • "nickName": "string",
  • "slug": "string",
  • "avatarUrl": "string",
  • "birthdate": "2019-08-24T14:15:22Z",
  • "joinedAt": "2019-08-24T14:15:22Z",
  • "leftAt": "2019-08-24T14:15:22Z",
  • "roles": [
    ],
  • "contribution": 0,
  • "contributionUnit": "string",
  • "customFields": [
    ]
}

Roles

API endpoints related to Roles

Create a new Role

Create a new role within the organtization

Authorizations:
X-Api-Key
Request Body schema: application/json
required

Create one role (single object) or many roles (array, 1..n). You can create a role inside the organization or as an external role. An array is created atomically: all roles are created or none are.

One of
name
required
string
mapId
required
string <uuid>
parentId
required
string <uuid>

The Id should be a valid group ID. In order to find the groups on your map, please check these routes Get a list of groups. For roles, kindly visit this route Get a list of roles

electable
boolean
external
boolean

Set external to true if node is outside of the organization.

color
string

The choice of color for the node in hexa decimal string format.

shape
string

Specifies the shape of the node. Acceptable values are "circle" or "hexagon", each determining the visual representation of the node within the interface.

object

The custom fields for a group/role. You can add the properties from the predefined custom fields. Please refer to the example in the sample request.

Array of objects (Goals)
groupEmail
string

Email for node(group/role) communication

representingId
string <uuid>

Id of the group the new role represents (must be the role's parent group).

Responses

Request samples

Content type
application/json
Example
{
  • "name": "string",
  • "mapId": "d6853b15-65cc-485b-a478-286f3c59e1a7",
  • "parentId": "70850378-7d3c-4f45-91b7-942d4dfbbd43",
  • "electable": true,
  • "external": true,
  • "color": "string",
  • "shape": "string",
  • "customFields": {
    },
  • "goals": [
    ],
  • "groupEmail": "string",
  • "representingId": "6d629f63-017c-4219-ac49-0f085d73f873"
}

Response samples

Content type
application/json
Example
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "color": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "parentId": "70850378-7d3c-4f45-91b7-942d4dfbbd43",
  • "representing": {
    },
  • "slug": "string",
  • "external": true,
  • "electable": true,
  • "salaryLevel": "string",
  • "mirrored": true,
  • "shape": "string",
  • "customFields": [
    ],
  • "holders": [
    ],
  • "goals": [
    ],
  • "purpose": "string",
  • "accountabilities": [
    ],
  • "groups": [
    ],
  • "groupEmail": "string"
}

Get List Of Roles

Get a list of all roles within the organization's namespace.

Optionally filterable to only include roles held by a given peer or that belong to a given group. The result may optionally be extended by showing a list of peers holding the roles.

Authorizations:
X-Api-Key
query Parameters
peer
string <uuid>

Peer ID to filter roles by. If set, this parameter overrides the group parameter.

group
string <uuid>

Group ID to filter roles by.

with
string

Use holders for a list of all peers holding the roles, customfields for inclusion of custom fields, groups to include the role's parent group (circle), or representing to include the node the role represents. Comma-separated combination of values is allowed (e.g. holders,customfields,groups,representing).

mapId
string <uuid>

Filter the role nodes on the basis of map ID. If there is no map Id provided, the role nodes of the live map will be returned.

limit
integer [ 1 .. 100 ]

Pagination: limit the result to limit items (1-100). Recommended for large maps.

offset
integer >= 0

Pagination: skip the first offset items (0-based).

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Single role from live or draft map excluding archived maps

Get a single role based on the ID supplied.

Authorizations:
X-Api-Key
path Parameters
id
required
string <uuid>

ID of role to fetch

query Parameters
with
string

Use holders for a list of all peers holding the role, customfields for inclusion of custom fields, groups to include the role's parent group (circle), or representing to include the node the role represents. Comma-separated combination of values is allowed (e.g. holders,customfields,groups,representing).

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "color": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "parentId": "70850378-7d3c-4f45-91b7-942d4dfbbd43",
  • "representing": {
    },
  • "slug": "string",
  • "external": true,
  • "electable": true,
  • "salaryLevel": "string",
  • "mirrored": true,
  • "shape": "string",
  • "customFields": [
    ],
  • "holders": [
    ],
  • "goals": [
    ],
  • "purpose": "string",
  • "accountabilities": [
    ],
  • "groups": [
    ],
  • "groupEmail": "string"
}

Update an existing role

Update an existing role based on the ID supplied.

Authorizations:
X-Api-Key
path Parameters
id
required
string <uuid>

ID of role to update

Request Body schema: application/json
required

Update the following fields of an existing role

name
string
color
string

The choice of color for the node in hexa decimal string format.

parentId
string

The Id should be a valid group/role ID. In order to find the groups on your map, please check these routes Get a list of groups. For roles, kindly visit this route Get a list of roles

external
boolean

Set external to true if node is outside of the organization.

object

The custom fields for a group/role. You can add the properties from the predefined custom fields. Please refer to the example in the sample request.

shape
string

Specifies the shape of the node. Acceptable values are "circle" or "hexagon", each determining the visual representation of the node within the interface.

Array of objects (Goals)
representing
string or null

The Id of the group the role represents, or null to clear it.

representingAll
boolean

If true, the change to the above field "representing" will be copied to all the mirrored nodes.

electable
boolean

Set the value to true, if the role is electable.

groupEmail
string

Email for node(group/role) communication

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "color": "string",
  • "parentId": "string",
  • "external": true,
  • "customFields": {
    },
  • "shape": "string",
  • "goals": [
    ],
  • "representing": "string",
  • "representingAll": true,
  • "electable": true,
  • "groupEmail": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "color": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "parentId": "70850378-7d3c-4f45-91b7-942d4dfbbd43",
  • "representing": {
    },
  • "slug": "string",
  • "external": true,
  • "electable": true,
  • "salaryLevel": "string",
  • "mirrored": true,
  • "shape": "string",
  • "customFields": [
    ],
  • "holders": [
    ],
  • "goals": [
    ],
  • "purpose": "string",
  • "accountabilities": [
    ],
  • "groups": [
    ],
  • "groupEmail": "string"
}

Delete Single Role from live or draft map excluding archived maps

Delete a single role based on the ID supplied.

Authorizations:
X-Api-Key
path Parameters
id
required
string <uuid>

ID of role to delete

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "color": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "parentId": "70850378-7d3c-4f45-91b7-942d4dfbbd43",
  • "representing": {
    },
  • "slug": "string",
  • "external": true,
  • "electable": true,
  • "salaryLevel": "string",
  • "mirrored": true,
  • "shape": "string",
  • "customFields": [
    ],
  • "holders": [
    ],
  • "goals": [
    ],
  • "purpose": "string",
  • "accountabilities": [
    ],
  • "groups": [
    ],
  • "groupEmail": "string"
}

Assign holders to several roles in one request

Assign peers to multiple roles in a single atomic request. The body is an array of {roleId, holders[]} groups; every assignment across every group is created in one transaction (all-or-none). Collapses what used to be one call per role into a single round trip.

Authorizations:
X-Api-Key
Request Body schema: application/json
required
Array (non-empty)
roleId
required
string <uuid>
required
Array of objects (HolderCreate) non-empty

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "created": 0,
  • "items": [
    ]
}

Assign existing role to a peer

Assign existing role from live or draft map to a peer

Authorizations:
X-Api-Key
path Parameters
roleId
required
string <uuid>

ID of role to that needs to be assigned to the peer

Request Body schema: application/json
required

Assign one peer (single object) or many peers (array, 1..n) to this role. An array is created atomically: all assignments are created or none are.

One of
peerId
required
string <uuid>
percentage
number
focus
string
electedUntil
string <date>

Responses

Request samples

Content type
application/json
[ ]

Response samples

Content type
application/json
Example
{
  • "peerId": "60a07d40-746d-414c-b70b-908ca16e7459",
  • "roleId": "7382d58e-652a-4905-b7c9-bcca1e0e5391",
  • "focus": "string",
  • "percentage": "string"
}

Unassign existing role from a peer

Unassign existing role from a peer

Authorizations:
X-Api-Key
path Parameters
roleId
required
string <uuid>

ID of role that needs to be unassigned from the peer

peerId
required
string <uuid>

ID of peer that needs to be removed from the given role

Responses

Response samples

Content type
application/json
{
  • "message": "Role Unassinged successfully"
}

Update existing role holder

Update the role holder's percentage, focus, and electedUntil based on the role ID and peer ID.

Authorizations:
X-Api-Key
path Parameters
roleId
required
string <uuid>

ID of the role associated with the holder

peerId
required
string <uuid>

ID of the peer assigned to the role

Request Body schema: application/json
required

Update the role holder's details

percentage
string
electedUntil
string <date>
focus
string

Responses

Request samples

Content type
application/json
{
  • "percentage": "string",
  • "electedUntil": "2019-08-24",
  • "focus": "string"
}

Response samples

Content type
application/json
{
  • "peerId": "60a07d40-746d-414c-b70b-908ca16e7459",
  • "roleId": "7382d58e-652a-4905-b7c9-bcca1e0e5391",
  • "focus": "string",
  • "percentage": "string"
}

Get Role Holder

Retrieve a role holder by role ID and peer ID.

Authorizations:
X-Api-Key
path Parameters
roleId
required
string <uuid>

ID of the role

peerId
required
string <uuid>

ID of the peer

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "percentage": "string",
  • "focus": "string",
  • "electedUntil": "2019-08-24"
}

Groups

API endpoints related to Groups.

Note: The default terminology has been changed to /groups. For backward compatibility, /circles is still available and functions the same as /groups. Please update your integrations to use /groups as /circles will eventually be deprecated.

Create a new group

Create a new group. You can create a group inside the organization map or it can be an external group.

Authorizations:
X-Api-Key
Request Body schema: application/json
required

Create one group (single object) or many groups (array, 1..n). You can create a group inside the organization map or as an external group. An array is created atomically: all groups are created or none are.

One of
name
required
string
mapId
required
string <uuid>
parentId
required
string <uuid>

The Id should be a valid group ID. In order to find the groups on your map, please check these routes Get a list of groups. For roles, kindly visit this route Get a list of roles

electable
boolean
external
boolean

Set external to true if node is outside of the organization.

color
string

The choice of color for the node in hexa decimal string format.

shape
string

Specifies the shape of the node. Acceptable values are "circle" or "hexagon", each determining the visual representation of the node within the interface.

object

The custom fields for a group/role. You can add the properties from the predefined custom fields. Please refer to the example in the sample request.

Array of objects (Goals)
groupEmail
string

Email for node(group/role) communication

Responses

Request samples

Content type
application/json
[ ]

Response samples

Content type
application/json
Example
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "parentId": "70850378-7d3c-4f45-91b7-942d4dfbbd43",
  • "slug": "string",
  • "external": true,
  • "color": "string",
  • "shape": "string",
  • "customFields": [
    ],
  • "goals": [
    ],
  • "groupEmail": "string"
}

Get List Of Groups

Get a list of groups within the organization's namespace.

Authorizations:
X-Api-Key
query Parameters
with
string

Use customfields for inclusion of custom fields.

peer
string <uuid>

Peer ID to filter groups by.

mapId
string <uuid>

Filter the group nodes on the basis of map ID. If there is no map Id provided, the group nodes of the live map will be returned.

limit
integer [ 1 .. 100 ]

Pagination: limit the result to limit items (1-100). Recommended for large maps.

offset
integer >= 0

Pagination: skip the first offset items (0-based).

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Single Group

Get a single group based on the supplied ID from live or draft map excluding archived maps

Authorizations:
X-Api-Key
path Parameters
id
required
string <uuid>

ID of group to fetch

query Parameters
with
string

Use customfields for inclusion of custom fields.

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "parentId": "70850378-7d3c-4f45-91b7-942d4dfbbd43",
  • "slug": "string",
  • "external": true,
  • "color": "string",
  • "shape": "string",
  • "customFields": [
    ],
  • "goals": [
    ],
  • "groupEmail": "string"
}

Delete Single Group

Delete a single group based on the supplied group ID from live or draft map excluding archived maps.

Authorizations:
X-Api-Key
path Parameters
id
required
string <uuid>

ID of group to delete

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "parentId": "70850378-7d3c-4f45-91b7-942d4dfbbd43",
  • "slug": "string",
  • "external": true,
  • "color": "string",
  • "shape": "string",
  • "customFields": [
    ],
  • "goals": [
    ],
  • "groupEmail": "string"
}

Update Single Group using group ID

Update a single group based on the ID supplied.

Authorizations:
X-Api-Key
path Parameters
id
required
string <uuid>

ID of group to update

Request Body schema: application/json
required

Update an existing group

name
string
color
string

The choice of color for the node in hexa decimal string format.

parentId
string

The Id should be a valid group/role ID. In order to find the groups on your map, please check these routes Get a list of groups. For roles, kindly visit this route Get a list of roles

external
boolean

Set external to true if node is outside of the organization.

shape
string

Specifies the shape of the node. Acceptable values are "circle" or "hexagon", each determining the visual representation of the node within the interface.

object

The custom fields for a group/role. You can add the properties from the predefined custom fields. Please refer to the example in the sample request.

Array of objects (Goals)
groupEmail
string

Email for node(group/role) communication

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "color": "string",
  • "parentId": "string",
  • "external": true,
  • "shape": "string",
  • "customFields": {
    },
  • "goals": [
    ],
  • "groupEmail": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "parentId": "70850378-7d3c-4f45-91b7-942d4dfbbd43",
  • "slug": "string",
  • "external": true,
  • "color": "string",
  • "shape": "string",
  • "customFields": [
    ],
  • "goals": [
    ],
  • "groupEmail": "string"
}

Projects

API endpoints related to Projects

Get List Of Projects

Get a list of projects within the organization's namespace.

Optionally filterable to only include projects that belong to a given peer.

Authorizations:
X-Api-Key
query Parameters
peer
string <uuid>

Peer ID to filter projects by.

limit
integer [ 1 .. 100 ]

Pagination: limit the result to limit items (1-100). Applies to the unfiltered list (ignored when peer is supplied).

offset
integer >= 0

Pagination: skip the first offset items (0-based). Applies to the unfiltered list (ignored when peer is supplied).

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Single Project

Get a single project based on the supplied ID.

Authorizations:
X-Api-Key
path Parameters
id
required
string <uuid>

ID of project to fetch

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "slug": "string",
  • "description": "string",
  • "notes": "string",
  • "externalUrl": "string",
  • "archived": true,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "startedAt": "2019-08-24T14:15:22Z",
  • "endedAt": "2019-08-24T14:15:22Z",
  • "archviedAt": "2019-08-24T14:15:22Z",
  • "group": true
}

Maps

API endpoints related to Maps

Get List of Maps

Gets a lists of all Maps within the organization's namespace.

Authorizations:
X-Api-Key

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Post a draft map

Create a draft map

Authorizations:
X-Api-Key
Request Body schema: application/json
optional

Create a new draft map

private
boolean

Set to true to make the draft map private; set to false to keep it public.

Responses

Request samples

Content type
application/json
{
  • "private": true
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "slug": "string",
  • "draft": true,
  • "tenant": {
    },
  • "layout": {
    },
  • "private": true,
  • "archived": true,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Tenant

API endpoints related to Tenant

Get tenant's details

Retrieve details of the tenant associated with the Auth Key.

Authorizations:
X-Api-Key

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "slug": "string",
  • "liveMapId": "7db03005-b826-405a-a2a4-d90f0f552934"
}

Apps

API endpoints related to activating Peerdom apps

Activate App

Activate an app for the organization. Idempotent: activating an already-enabled app succeeds without side effects. Only flips the enablement flag; billing for charged apps is handled separately.

Authorizations:
X-Api-Key
path Parameters
name
required
string
Enum: "contribution" "drafts" "goals" "pages" "projects"

Name of the app to activate.

Responses

Response samples

Content type
application/json
{
  • "app": "goals",
  • "enabled": true
}

Custom Fields

API endpoints related to custom-field definitions (the schema/vocabulary)

List custom-field definitions

List the organization's custom-field definitions (the schema/vocabulary, not the per-entity values). Call this before writing peers/roles/groups so source data maps to the organization's real field names. Optionally filter by the owning entity with ?entity=.

Authorizations:
X-Api-Key
query Parameters
entity
string
Enum: "node" "peer" "project" "goal"

Only return definitions for this owning entity.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create custom-field definition(s)

Create one definition (single object) or many (array, 1..n). An array is created atomically: all definitions are created or none are. Create the definitions before setting their values on peers/roles/groups.

Authorizations:
X-Api-Key
Request Body schema: application/json
required
One of
name
required
string
type
string
Enum: "text" "textarea" "email" "link" "date" "relation" "image" "list"

Defaults to text when omitted.

entity
string
Enum: "node" "peer" "project" "goal"
nodeType
string
Enum: "circle" "role" "generic"
multiEntry
boolean
relationScope
string
Enum: "group" "page" "peer" "role"

Required when type is relation.

object (Translation)

Localized labels keyed by language code.

order
integer
public
boolean

Responses

Request samples

Content type
application/json
[ ]

Response samples

Content type
application/json
Example
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "type": "text",
  • "entity": "node",
  • "nodeType": "circle",
  • "multiEntry": true,
  • "relationScope": "group",
  • "translation": {
    },
  • "order": 0,
  • "public": true
}

Import

Import peers, groups, roles and holders in one request

Apply a single JSON document that creates peers, groups, roles and holder assignments together, atomically (all-or-none). Entities created in the same document are wired together with transient ref aliases: give an item a ref, then point at it from a parent (parentRef) or a holder (roleRef / peerRef). Aliases are in-memory only and never stored. Items that already exist can be referenced by real id instead. Synchronous — keep batches reasonably sized.

Authorizations:
X-Api-Key
Request Body schema: application/json
required
mapId
required
string <uuid>

Target map for the groups/roles in this import.

Array of objects (PeerCreate)
Array of objects
Array of objects
Array of objects

Responses

Request samples

Content type
application/json
{
  • "mapId": "d6853b15-65cc-485b-a478-286f3c59e1a7",
  • "peers": [
    ],
  • "groups": [
    ],
  • "roles": [
    ],
  • "holders": [
    ]
}

Response samples

Content type
application/json
{
  • "imported": {
    }
}