logo
API docs by Redocly

Peerdom Public API (0.3.2)

Download OpenAPI specification:Download

Peerdom Team: hello@peerdom.org URL: https://peerdom.com Terms of Service

Purpose

Organisations may use the Peerdom's RESTful API as an additional way to interact with their organisational data managed within Peerdom.

Authentication

The endpoints of the API always operate within the context of a single organisation. The organisation's context is determined by a presented API key.

For this reason, most if not all API endpoints are protected and require an API key to be accessed successfully.

When querying the API, the API key is to be presented in the request header, using the header name X-Api-Key.

Please contact our team to request an API key for your organisation.

Data Encoding

The API encodes its data for JSON. No further encoding/sanitizing is applied.

Please note: It is the responsability of the consumer to apply further encoding depending on the context (e.g. encode HTML-tags in a web context etc.)

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

Pagination: Limit list by limit results.

offset
integer

Pagination: Retrieval offset.

with
string

Use customfields for inclusion of custom fields.

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 a new peer

firstName
required
string
lastName
string
nickName
string
birthdate
string <date-time>
percentage
integer

Contribution App needs to be enabled for this attribute.

customFields
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",
  • "birthdate": "2019-08-24T14:15:22Z",
  • "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",
  • "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

Use customfields for inclusion of custom fields.

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",
  • "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
birthdate
string <date-time>
percentage
integer

Contribution App needs to be enabled for this attribute.

customFields
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",
  • "birthdate": "2019-08-24T14:15:22Z",
  • "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",
  • "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"
}

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 a new role. You can create a role inside the organization or it can be an external role.

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 "group" or "hexagon", each determining the visual representation of the node within the interface.

customFields
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

representing
string

Id of the group, the new role needs to represent.

Responses

Request samples

Content type
application/json
{
  • "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",
  • "representing": "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",
  • "slug": "string",
  • "external": true,
  • "electable": true,
  • "salaryLevel": "string",
  • "mirrored": true,
  • "shape": "string",
  • "customFields": [
    ],
  • "holders": [
    ],
  • "goals": [
    ],
  • "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. Or customfields for inclusion of custom fields for the roles. Comma-separated combination of values is allowed (e.g. holders,customfields).

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.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Single Role

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 roles. Or customfields for inclusion of custom fields. Comma-separated combination of values is allowed (e.g. holders,customfields).

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",
  • "slug": "string",
  • "external": true,
  • "electable": true,
  • "salaryLevel": "string",
  • "mirrored": true,
  • "shape": "string",
  • "customFields": [
    ],
  • "holders": [
    ],
  • "goals": [
    ],
  • "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.

customFields
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 "group" or "hexagon", each determining the visual representation of the node within the interface.

Array of objects (Goals)
representing
string

The Id of the group, the role is representing

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",
  • "slug": "string",
  • "external": true,
  • "electable": true,
  • "salaryLevel": "string",
  • "mirrored": true,
  • "shape": "string",
  • "customFields": [
    ],
  • "holders": [
    ],
  • "goals": [
    ],
  • "groupEmail": "string"
}

Delete Single Role

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",
  • "slug": "string",
  • "external": true,
  • "electable": true,
  • "salaryLevel": "string",
  • "mirrored": true,
  • "shape": "string",
  • "customFields": [
    ],
  • "holders": [
    ],
  • "goals": [
    ],
  • "groupEmail": "string"
}

Assign existing role to a peer

Assign existing role 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 peer to a existing role

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

Responses

Request samples

Content type
application/json
{
  • "peerId": "60a07d40-746d-414c-b70b-908ca16e7459",
  • "percentage": 0,
  • "focus": "string",
  • "electedUntil": "2022-06-09"
}

Response samples

Content type
application/json
{
  • "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"
}

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 a new group

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 "group" or "hexagon", each determining the visual representation of the node within the interface.

customFields
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",
  • "mapId": "d6853b15-65cc-485b-a478-286f3c59e1a7",
  • "parentId": "70850378-7d3c-4f45-91b7-942d4dfbbd43",
  • "electable": true,
  • "external": true,
  • "color": "string",
  • "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"
}

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.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Single Group

Get a single group based on the supplied ID.

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 ID supplied.

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 "group" or "hexagon", each determining the visual representation of the node within the interface.

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

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
{ }