Team Organization & Role Setup

Facilitates comprehensive management of team structures and roles within the system. It covers creating, updating, and deleting teams, managing team memberships, and configuring notification channels. The management is organized into two main categories:

Team management: Functions include creating and managing teams, handling member invitations and removals, and updating team details, ensuring effective team structure and collaboration.

Team notification channel management: Involves managing notification channels associated with teams. This includes creating, updating, verifying, and deleting notification channels, as well as testing their functionality for proper communication.

Supports efficient team organization and communication, providing tools for well-structured teams and properly configured notifications.

ENDPOINTS

Expand all

Team management
POST/team
GET/teams
DELETE/team/{id}
PUT/team/{id}
GET/team/{id}/invitations
POST/team/{id}/invitation
DELETE/team/{id}/invitation
GET/team/{id}/members
DELETE/team/{id}/member/{memberId}
PATCH/team/{id}/member/{memberId}
POST/team/{id}/invitation/reminder
Team notification channel management
Service management

Create New Team

This API endpoint allows you to set up teams to better manage your monitoring operations. This is useful for distributing tasks like monitoring alerts, managing notifications, and responding to incidents among different team members. It helps you organize roles and responsibilities so that your system is always being monitored effectively by the right people

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the system will create the team and return a confirmation message along with the team details.
If the request is unauthorized or invalid, the system will respond with an error message.

Request Body Parameters

name string
The name of the team. Example: 'TeamName'

JavaScript

Response codes

const axios = require('axios');

const url = "https://customer-cmd.api.pinghome.io/default/v1/team";
const data = {
    "name": "TeamName"
};

axios.post(url, data, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

ResponseThis section is used to view the possible HTTP response codes returned by the API. These codes indicate the status of a request, such as 201 (Created), 401 (Unauthorized), 409 (Conflict), or 422 (Unprocessable Entity).

Get Teams

This API endpoint you to retrieve a list of all the teams within your account. Each team will come with details like team_id, name, member_count, and created_at.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the system will return a list of teams along with their details.
If the request is unauthorized, the system will respond with an authentication error message.

JavaScript

Response codes

const axios = require('axios');

const url = "https://customer-query.api.pinghome.io/default/v1/teams";

axios.get(url, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Update Team Information

This API endpoint allows you to modify an existing team, by providing the name.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the system will update the team information and return a confirmation message.
If the request is unauthorized or invalid, the system will respond with an error message.

Path Parameters

id string
The unique ID of the team. Example: 'c03b02ec-244f-4d2c-8f68-3910071ed5c8'

Request Body Parameters

name string
The updated name of the team. Example: 'TeamName'

JavaScript

Response codes

const axios = require('axios');

const url = "https://customer-cmd.api.pinghome.io/default/v1/team/c03b02ec-244f-4d2c-8f68-3910071ed5c8";
const data = {
    "name": "TeamName"
};

axios.put(url, data, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Delete Team

This API endpoint lets you delete an existing team from your monitoring setup.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the system will delete the team and return a confirmation message.
If the request is unauthorized or invalid, the system will respond with an error message.

Path Parameters

id string
The unique ID of the team. Example: 'c03b02ec-244f-4d2c-8f68-3910071ed5c8'

JavaScript

Response codes

const axios = require('axios');

const url = "https://customer-cmd.api.pinghome.io/default/v1/team/c03b02ec-244f-4d2c-8f68-3910071ed5c8";

axios.delete(url, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Get Team Invitation Details

This API endpoint helps you to manage and track the invitations you've sent out while forming teams. You can view important details such as the channel used for the invitation (email, SMS), the type of invitation, the sender's information, and the current status (pending, accepted, or declined).

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the system will return a list of team invitations and their statuses.
If the request is unauthorized, the system will respond with an authentication error message.

Path Parameters

id string
The unique ID of the team. Example: '6fb4e64f-ad18-46e3-920c-92639adb137c'

JavaScript

Response codes

const axios = require('axios');

const url = "https://customer-query.api.pinghome.io/default/v1/team/6fb4e64f-ad18-46e3-920c-92639adb137c/invitations";

axios.get(url, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Invite New Team Member

This API endpoint enables you to invite a new member to your team. To create an invitation, the request must include details such as the channel_value and channel_type. This allows for streamlined team expansion and collaboration.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the system will generate an invitation for the new team member and return a confirmation message.
If the request is unauthorized or contains invalid parameters, the system will respond with an appropriate error message.

Path Parameters

id string
The unique ID of the team. Example: 'c03b02ec-244f-4d2c-8f68-3910071ed5c8'

Request Body Parameters

channel_value string
The value of the invitation channel, e.g., an email address like 'test@pinghome.eu'.
channel_type string

JavaScript

Response codes

const axios = require('axios');

const url = "https://customer-cmd.api.pinghome.io/default/v1/team/c03b02ec-244f-4d2c-8f68-3910071ed5c8/invitation";
const data = {
  "channel_value": "test@pinghome.eu",
  "channel_type": "email"
};

axios.post(url, data, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Delete Team Member Invitation

This API endpoint helps to delete a previously sent invitation for a team member. The request must include the channel_value. This feature is useful for managing team memberships and ensuring that outdated or unnecessary invitations are eliminated.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the system will delete the specified team member invitation and return a confirmation message.
If the request is unauthorized or contains invalid parameters, the system will respond with an appropriate error message.

Path Parameters

id string
The unique ID of the team. Example: 'c03b02ec-244f-4d2c-8f68-3910071ed5c8'

Request Body Parameters

channel_value string
The value of the invitation channel, e.g., an email address like 'test@pinghome.eu'.

JavaScript

Response codes

const axios = require('axios');

const url = "https://customer-cmd.api.pinghome.io/default/v1/team/c03b02ec-244f-4d2c-8f68-3910071ed5c8/invitation";
const data = {
  "channel_value": "test@pinghome.eu"
};

axios.delete(url, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  },
  data: data
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Get Team Members

This API endpoint enables you to retrieve a detailed list of team members associated with your account. The response includes essential information such as each member's customer_id, email, name, role within the team, and other relevant details.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the system will return a detailed list of team members along with their associated information.
If the request is unauthorized, the system will respond with an authentication error message.

Path Parameters

id string
The unique ID of the team. Example: '6fb4e64f-ad18-46e3-920c-92639adb137c'

JavaScript

Response codes

const axios = require('axios');

const url = "https://customer-query.api.pinghome.io/default/v1/team/6fb4e64f-ad18-46e3-920c-92639adb137c/members";

axios.get(url, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Delete Team Member

This API endpoint allows you to delete a specific team member from your team. By providing the necessary details, you can effectively manage your team and ensure that only active members have access to monitoring features. This is important for maintaining team organization, especially when roles change or a member no longer needs access.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the system will delete the specified team member and return a confirmation message.
If the request is unauthorized or invalid, the system will respond with an appropriate error message.

Path Parameters

id string
The unique ID of the team. Example: 'c03b02ec-244f-4d2c-8f68-3910071ed5c8'
memberId string

JavaScript

Response codes

const axios = require('axios');

const url = "https://customer-cmd.api.pinghome.io/default/v1/team/c03b02ec-244f-4d2c-8f68-3910071ed5c8/member/a43b87f6-9012-4f1e-bf5f-7c2f5b6e4f29";

axios.delete(url, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Update Team Member

This API endpoint allows you to update a team member’s information. You can modify the member's role and, if needed, assign them to a different team using new_team_id. If you want to keep the team member in their current team, leave new_team_id unchanged. This feature is useful for adjusting team roles and shifting members between teams to maintain proper access and organization.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the system will update the team member and return a confirmation message.
If the request is unauthorized or invalid, the system will respond with an error message.

Path Parameters

id string
The unique ID of the team. Example: 'c03b02ec-244f-4d2c-8f68-3910071ed5c8'
memberId string

Request Body Parameters

role string
The new role of the team member (e.g., 'user', 'manager').
new_team_id string

JavaScript

Response codes

const axios = require('axios');

const url = "https://customer-cmd.api.pinghome.io/default/v1/team/c03b02ec-244f-4d2c-8f68-3910071ed5c8/member/a43b87f6-9012-4f1e-bf5f-7c2f5b6e4f29";
const data = {
  "role": "user",
  "new_team_id": "c03b02ec-244f-4d2c-8f68-3910071ed5c8"
};

axios.patch(url, data, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Send Invitation Reminder to Team Member

This API endpoint allows sending a reminder for a pending team member invitation. You should include the channel_value to resend the invitation reminder.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the system will send the invitation reminder and return a confirmation message.
If the request is unauthorized or invalid, the system will respond with an error message.

Path Parameters

id string
The unique ID of the team. Example: 'c03b02ec-244f-4d2c-8f68-3910071ed5c8'

Request Body Parameters

channel_value string
The channel value (email or phone number) where the invitation reminder will be sent. Example: 'test@pinghome.eu'

JavaScript

Response codes

const axios = require('axios');

const url = "https://customer-cmd.api.pinghome.io/default/v1/team/c03b02ec-244f-4d2c-8f68-3910071ed5c8/invitation/reminder";
const data = {
  "channel_value": "test@pinghome.eu"
};

axios.post(url, data, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Create Team Notification Channel

Notification channels are used to send alerts or messages to teams through various mediums, such as webhooks, email, or other integrations. To create new team notification channel you must provide the value and type.

Common use cases:

Create webhook for alerts: Add a webhook URL to enable real-time notifications for system alerts, incidents, or other events to be sent to the team’s communication platform.
Set up email alerts: Configure an email address to receive important alerts or updates related to the team's operations, ensuring critical notifications are not missed.
Integrate with external systems: Add an external service or tool (e.g., Slack, PagerDuty) as a notification channel to centralize team communication for incidents and system updates.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the system will create the notification channel and return a confirmation message.
If the request is unauthorized or invalid, the system will respond with an error message.

Path Parameters

id string
The unique ID of the team. Example: 'c03b02ec-244f-4d2c-8f68-3910071ed5c8'

Request Body Parameters

value string
The value of the notification channel. Example: 'https://webhook.site/3f4db7ad-ca7f-4080-ab06-6056ea9eed3a'
type string

JavaScript

Response codes

const axios = require('axios');

const url = "https://customer-cmd.api.pinghome.io/default/v1/team/c03b02ec-244f-4d2c-8f68-3910071ed5c8/notification-channel";
const data = {
  "value": "https://webhook.site/3f4db7ad-ca7f-4080-ab06-6056ea9eed3a",
  "type": "webhook"
};

axios.post(url, data, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Get Team Notification Channels

This API endpoint allows you to retrieve the notification channels associated with a specific team.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the system will return the team’s notification channels, including their details such as type, priority, and status. The priority parameter indicates the importance level of the notification channel.
If the request is unauthorized, the system will respond with an authentication error message.

Path Parameters

id string
The unique ID of the team. Example: 'c03b02ec-244f-4d2c-8f68-3910071ed5c8'

JavaScript

Response codes

const axios = require('axios');

const url = "https://customer-query.api.pinghome.io/default/v1/team/{id}/notification-channels?include_types=sms,email&exclude_types=push-notification";

axios.get(url, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Update Team Notification Channel

You can update the notification channel for a specific team. To do this, provide the new notification channel value and its priority.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the system will add the new notification channel and return a confirmation message indicating that the channel needs to be verified. To complete the verification process, please use the Verify Team Notification Channel endpoint.
If the request is unauthorized or invalid, the system will respond with an error message.

Path Parameters

id string
The unique ID of the team. Example: 'c03b02ec-244f-4d2c-8f68-3910071ed5c8'

Request Body Parameters

value string
The new notification channel value (e.g., webhook URL or email address). Example: 'https://webhook.site/3f4db7ad-ca7f-4080-ab06-6056ea9eed3a'
priority positive integer

JavaScript

Response codes

const axios = require('axios');

const url = "https://customer-cmd.api.pinghome.io/default/v1/team/c03b02ec-244f-4d2c-8f68-3910071ed5c8/notification-channel";
const data = {
  "value": "https://webhook.site/3f4db7ad-ca7f-4080-ab06-6056ea9eed3a",
  "priority": 1
};

axios.put(url, data, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Verify Team Notification Channel

This functionality allows you to verify a newly added notification channel for your team. To complete the verification, you need to provide the necessary verification details, such as the code sent to the email, and priority.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the system will verify the notification channel and return a confirmation message.
If the request is unauthorized or invalid, the system will respond with an error message.

Path Parameters

id string
The unique ID of the team. Example: 'c03b02ec-244f-4d2c-8f68-3910071ed5c8'

Request Body Parameters

code string
The verification code provided to confirm the notification channel. Example: '087608'
priority positive integer

JavaScript

Response codes

const axios = require('axios');

const url = "https://customer-cmd.api.pinghome.io/default/v1/team/c03b02ec-244f-4d2c-8f68-3910071ed5c8/notification-channel/verification";
const data = {
  "code": "087608",
  "priority": 1
};

axios.patch(url, data, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Delete Team Notification Channel

This functionality allows you to delete notification channels associated with your team. The request must include the priority of the channels to be deleted as query parameters.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the system will delete the specified notification channels and return a confirmation message.
If the request is unauthorized or invalid, the system will respond with an error message.

Path Parameters

id string
The unique ID of the team. Example: 'c03b02ec-244f-4d2c-8f68-3910071ed5c8'

Query Parameters

priority positive integer
A list of notification channel priorities to delete. This value can be found in the response of the Get Team Notification Channels endpoint. Example: priority=3&priority=4

JavaScript

Response codes

const axios = require('axios');

const url = "https://customer-cmd.api.pinghome.io/default/v1/team/c03b02ec-244f-4d2c-8f68-3910071ed5c8/notification-channel?priority=3,4";

axios.delete(url, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Test Team Notification Channel

Use this API endpoint to verify the functionality of a team’s notification channel. The request must include the priority of the notification channel to be tested.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the system will send a test message to the specified notification channel and return a confirmation message.
If the request is unauthorized or invalid, the system will respond with an error message.

Path Parameters

id string
The unique ID of the team. Example: 'c03b02ec-244f-4d2c-8f68-3910071ed5c8'

Request Body Parameters

priority positive integer
The priority of the notification channel to be tested. This value can be found in the response of the Get Team Notification Channels endpoint. Example: 1

JavaScript

Response codes

const axios = require('axios');

const url = "https://customer-cmd.api.pinghome.io/default/v1/team/c03b02ec-244f-4d2c-8f68-3910071ed5c8/notification-channel/test";
const data = {
  "priority": 1
};

axios.post(url, data, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Update Team Notification Channel Status

You can update the status of a team notification channel by modifying the enabled field, which accepts a boolean value (true or false) and the priority of the notification channel being updated.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the system will update the notification channel status and return a confirmation message.
If the request is unauthorized or invalid, the system will respond with an error message.

Path Parameters

id string
The unique ID of the team. Example: 'c03b02ec-244f-4d2c-8f68-3910071ed5c8'

Request Body Parameters

enabled boolean
Boolean value indicating whether the notification channel is enabled or disabled. Example: true
priority positive integer

JavaScript

Response codes

const axios = require('axios');

const url = "https://customer-cmd.api.pinghome.io/default/v1/team/c03b02ec-244f-4d2c-8f68-3910071ed5c8/notification-channel/enabled";
const data = {
  "enabled": true,
  "priority": 1
};

axios.put(url, data, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Create Service

This API endpoint enables creating of a new service by providing the name and team_id in the request body. This is useful for organizations or teams that need to add new services to their system.

Common use cases:

Create a new service: If a new feature or product line is being introduced within a team, this API can be used to register it as a new service.
Infrastructure scaling: As organizations grow, they can easily expand their services to handle more operations or customer demands.

HTTP Method: POST

Authorization: Bearer YOUR_TOKEN

Request Body Parameters

name string
The name of the service.
Example: 'ServiceName'
team_id string

JavaScript

Response codes

const axios = require('axios');

const url = 'https://resource-cmd.api.pinghome.io/default/v1/service';
const data = {
  name: 'ServiceName',
  team_id: '39ed7fbd-200b-41eb-8467-a91f0809e802'
};

axios.post(url, data, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Update Service Name

This API endpoint allows you to update the name of a service by providing its ID as a path parameter and the new service name in the request body. This operation is essential for keeping your service names up to date and relevant within your system.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the service name will be updated, and a confirmation message will be returned.
If the request is unauthorized, an error message indicating authorization failure will be returned. If the request is invalid or contains incorrect data, a message specifying the issues will be provided.

Path Parameters

id string
The unique service ID to update.
Example: 'c03b02ec-244f-4d2c-8f68-3910071ed5c8'

Request Body Parameters

name string
The new name of the service.
Example: 'ServiceName'

JavaScript

Response codes

const axios = require('axios');

const url = 'https://resource-cmd.api.pinghome.io/default/v1/service/c03b02ec-244f-4d2c-8f68-3910071ed5c8';
const data = { name: 'ServiceName' };

axios.put(url, data, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Delete Service

This API endpoint allows you to delete a service by providing its ID as a path parameter. This action is crucial for maintaining an organized service list in your system.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the service will be deleted, and a confirmation message will be returned.
If the request is unauthorized, an error message will indicate authorization failure. If the service ID is invalid or not found, a message specifying the issue will be provided.

Path Parameters

id string
The unique service ID to delete.
Example: 'c03b02ec-244f-4d2c-8f68-3910071ed5c8'

JavaScript

Response codes

const axios = require('axios');

const url = 'https://resource-cmd.api.pinghome.io/default/v1/service/c03b02ec-244f-4d2c-8f68-3910071ed5c8';

axios.delete(url, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN'
  }
})
.then(response => {
  console.log('Service deleted successfully');
})
.catch(error => {
  console.error(error);
});

Get Service Details

This API endpoint allows you to retrieve service data by providing its ID.

Authorization: Bearer YOUR_TOKEN

Path Parameters

id string
The unique ID of the service.
Example: 'b39c7ff9-2ead-4a0d-a095-320b77d8bbdb'

JavaScript

Response codes

const axios = require('axios');

const url = 'https://resource-query.api.pinghome.io/default/v1/team-service/b39c7ff9-2ead-4a0d-a095-320b77d8bbdb';

axios.get(url, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});