logo
API docs by Redocly

Peerdom Public API (0.2.7)

Download OpenAPI specification:Download

Peerdom Team: hello@peerdom.org URL: http://about.peerdom.org 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

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.

Responses

Request samples

Content type
application/json
{
  • "firstName": "string",
  • "lastName": "string",
  • "nickName": "string",
  • "birthdate": "2019-08-24T14:15:22Z",
  • "percentage": 0
}

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

Update a peer

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

Contribution App needs to be enabled for this attribute.

Responses

Request samples

Content type
application/json
{
  • "firstName": "string",
  • "lastName": "string",
  • "nickName": "string",
  • "birthdate": "2019-08-24T14:15:22Z",
  • "percentage": 0
}

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
{
  • "code": 0,
  • "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

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
parentId
required
string

The Id should be a valid circle ID. In order to find the circles on your map, please check these routes Get a list of circles. 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.

customFields
object

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

Array of objects (Goals)
representing
string

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

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "mapId": "string",
  • "parentId": "string",
  • "electable": true,
  • "external": true,
  • "color": "string",
  • "customFields": {
    },
  • "goals": [
    ],
  • "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,
  • "customFields": [
    ],
  • "holders": [
    ],
  • "goals": [
    ]
}

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 circle. 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 circle parameter.

circle
string <uuid>

Circle 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).

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,
  • "customFields": [
    ],
  • "holders": [
    ],
  • "goals": [
    ]
}

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

Update the following fields of an existing role

name
string
parentId
string

The Id should be a valid circle/role ID. In order to find the circles on your map, please check these routes Get a list of circles. 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 circle/role. You can add the properties from the predefined custom fields. Please refer to the example in the sample request.

Array of objects (Goals)
representing
string

The Id of the circle, 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.

Responses

Request samples

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

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,
  • "customFields": [
    ],
  • "holders": [
    ],
  • "goals": [
    ]
}

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,
  • "customFields": [
    ],
  • "holders": [
    ],
  • "goals": [
    ]
}

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

Assign peer to a existing role

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

Responses

Request samples

Content type
application/json
{
  • "peerId": "string",
  • "percentage": 0,
  • "focus": "string",
  • "electedUntil": "2022-06-09"
}

Response samples

Content type
application/json
{
  • "peerId": "string",
  • "roleId": "string",
  • "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"
}

Circles

API endpoints related to Circles

Create a new circle

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

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

Create a new circle

name
required
string
mapId
required
string
parentId
required
string

The Id should be a valid circle ID. In order to find the circles on your map, please check these routes Get a list of circles. 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.

customFields
object

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

Array of objects (Goals)

Responses

Request samples

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

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,
  • "customFields": [
    ],
  • "goals": [
    ]
}

Get List Of Circles

Get a list of circles 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 circles by.

mapId
string <uuid>

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

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Single Circle

Get a single circle based on the supplied ID.

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

ID of circle 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,
  • "customFields": [
    ],
  • "goals": [
    ]
}

Delete Single Circle

Delete a single circle based on the ID supplied.

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

ID of circle 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,
  • "customFields": [
    ],
  • "goals": [
    ]
}

Update Single Circle using circle ID

Update a single circle based on the ID supplied.

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

ID of circle to update

Request Body schema: application/json

Update an existing circle

name
string
parentId
string

The Id should be a valid circle/role ID. In order to find the circles on your map, please check these routes Get a list of circles. 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 circle/role. You can add the properties from the predefined custom fields. Please refer to the example in the sample request.

Array of objects (Goals)

Responses

Request samples

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

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,
  • "customFields": [
    ],
  • "goals": [
    ]
}

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
[
  • {
    }
]