Account Settings

The Account Settings module allows secure, real-time management of customer accounts. It gives users full control over profile details, and notification preferences. The functionality is divided into two main sections for better organization:

🔹 Customer Management
Manage key customer information to ensure account data remains accurate and current.
  • View and edit customer profile details (name, email, etc.)
  • Delete accounts when needed

🔹 Notification Channel Management
Set up and manage how customers receive alerts and messages.
  • Create, update, or delete notification channels (e.g., email, webhook)
  • Test channels to ensure they work as expected
  • Enable or disable channels as needed
  • Verify channels for secure communication

This structure ensures that customer account settings are easy to manage, reliable, and aligned with communication preferences.
ENDPOINTS
Expand all
  • Customer management
    GET/customer/{customer_id}
    PATCH/customer
    DELETE/customer
    PUT/customer/username
    PATCH/customer/username
  • Customer notification channel management
Get Customer Profile
This endpoint retrieves the profile information of the currently authenticated customer. It returns a structured response containing essential details about the customer, their team, and associated organization.

You can use this endpoint to display customer profile data in dashboards, account settings pages, or any area where customer-specific context is needed.

Key response fields include:
  • Customer: ID, email, full name, role
  • Team: ID and name of the associated team
  • Organization: name, subscription plan, and trial period
  • Limits: available resource and service limits

This allows your application to stay in sync with the customer’s account and access permissions in real time.

Authorization: Bearer YOUR_TOKEN


To make changes or remove the account, See the Update Customer or Delete Customer endpoints.
JavaScript
Response codes
const axios = require('axios');

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

axios.get(url, {
  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).
Update Customer Information
This endpoint is used to update the profile information of the currently authenticated customer. It supports editing basic customer details such as name and surname to keep account information accurate and up to date.

Apply this endpoint when:
Customers request to update their visible profile information like first or last name.

Supported fields include:
  • First name
  • Surname

This helps maintain consistent and user-managed customer records across your application.

Authorization: Bearer YOUR_TOKEN


Looking for full profile access or removal? Refer to Get Customer or Delete Customer.
Request Body Parameters
  • name string
    The updated first name of the customer. Example: 'John'
  • surname string
JavaScript
Response codes
const axios = require('axios');

const url = "https://customer-cmd.api.pinghome.io/v1/customer";
const data = {
    "name": "John",
    "surname": "Smith"
};

axios.patch(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).
Delete Customer Account
This endpoint is used to permanently delete a customer account from the system. To perform this action, a valid deletion reason must be provided.

When to use:
When a customer requests account removal or when the account must be deactivated for business, compliance, or security reasons.

Important notes:
  • This action is irreversible — all associated data will be removed.
  • A reason for deletion is required for auditing and record-keeping purposes.

This endpoint helps enforce data control and compliance with user account management policies.

Authorization: Bearer YOUR_TOKEN


Expected Behavior:


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

Need to view or update customer details instead? Visit Get Customer or Update Customer.
Request Body Parameters
  • reason string
    The reason for deleting the customer. Example: 'poor-features'
JavaScript
Response codes
const axios = require('axios');

const url = "https://customer-cmd.api.pinghome.io/v1/customer";
const data = {
    "reason": "poor-features"
};

axios.delete(url, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  },
  data
})
.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).
Update Customer Username
This endpoint is used to update the username of the currently authenticated customer. To perform the update, a valid email address must be provided as part of the request to ensure ownership and verification.

Use this endpoint when a customer needs to change their existing username — for example, after an email change, rebranding, or correcting a previous entry.

This ensures that each customer's username remains unique and tied to their verified email identity.

Authorization: Bearer YOUR_TOKEN


Expected Behavior:


  • On success, the username will be updated, and a message will confirm that verification is required. To complete the process, you need to verify the new username using the Confirm Customer Username Change endpoint.
  • If the request is unauthorized or invalid, the system will respond with an error message.
Request Body Parameters
  • email string
    The email address to be associated with the customer's username. Example: 'pinghome@gmail.com'
JavaScript
Response codes
const axios = require('axios');

const url = "https://customer-cmd.api.pinghome.io/v1/customer/username";
const data = {
    "email": "pinghome@gmail.com"
};

axios.put(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).
Confirm Customer Username Change
This endpoint is used to confirm a username change for the currently authenticated customer. After initiating a change, a confirmation code is sent to the associated email address. To finalize the update, submit this code.

You can call this endpoint after calling Update Customer Username to verify and apply the new username.

This verification step ensures that all username changes are authorized and securely confirmed by the account owner.

Authorization: Bearer YOUR_TOKEN


Expected Behavior:


  • On success, the system will verify the username and return a confirmation message.
  • If the request is unauthorized or invalid, the system will respond with an error message.
Request Body Parameters
  • code string
    The verification code sent to the customer. Example: '293479'
JavaScript
Response codes
const axios = require('axios');

const url = "https://customer-cmd.api.pinghome.io/v1/customer/username";
const data = {
    "code": "293479"
};

axios.patch(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).
Create Personal Notification Channel
This API endpoint allows creating a new personal notification channel. Notification channels can include SMS, email, or other communication methods used to deliver updates, alerts, or promotional information to the customer. You must include the value and type of the notification channel.

Common use cases:

  • SMS notifications: Use this endpoint to configure an sms notification channel for sending alerts or updates directly to the customer’s phone.
  • Email notifications: Set up an email notification channel to keep customers informed about important alerts, updates, ensuring they receive timely information.
  • Push notifications: Add a webhook or other URL-based notification method to send push notifications or real-time updates to external platforms integrated with customer data.


Authorization: Bearer YOUR_TOKEN


Expected Behavior:


  • On success, the system will create the notification channel and return a confirmation message. To complete the verification process, please use the Verify Personal 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 customer. Example: 'c03b02ec-244f-4d2c-8f68-3910071ed5c8'
Request Body Parameters
  • value string
    The value of the notification channel, such as a phone number or email. Example: '+994551234567'
  • type string
JavaScript
Response codes
const axios = require('axios');

const url = "https://customer-cmd.api.pinghome.io/v1/customer/c03b02ec-244f-4d2c-8f68-3910071ed5c8/notification-channel";
const data = {
  "value": "+994551234567",
  "type": "sms"
};

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 Personal Notification Channels
This endpoint retrieves all notification channels that are currently configured for the authenticated customer. These channels define how the customer receives alerts and system notifications (e.g., via email or webhooks).

Designed for:
Listing all communication channels a customer has set up, allowing administrators or users to confirm notification preferences.

Response may include:
  • Channel type (e.g., email, webhook)
  • Status (enabled/disabled)
  • Verification state
  • Delivery endpoint or address

To update or test a channel, see the Update Notification Channel or Test Notification Channel endpoints.

Authorization: Bearer YOUR_TOKEN


Expected Behavior:


  • On success, the system will return the customer'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 customer. Example: '6fb4e64f-ad18-46e3-920c-92639adb137c'
JavaScript
Response codes
const axios = require('axios');

const url = "https://customer-query.api.pinghome.io/v1/customer/{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);
});
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).
Update Personal Notification Channel
This endpoint allows you to update an existing notification channel for the authenticated customer. It is used to modify properties such as the channel value (e.g., email address or webhook URL) and priority level.

Use this where:
A customer wants to change where or how they receive system notifications — for example, updating their email or changing the importance of a channel.

Important notes:
  • The request must include the channel type and updated values
  • The channel must already exist — this endpoint cannot create new channels
  • Changes may affect how and when the customer receives alerts

To view existing channels, use the Get Notification Channels endpoint. To test delivery after updating, use the Test Notification Channel endpoint.

Authorization: Bearer YOUR_TOKEN


Expected Behavior:


  • On success, the system will update the specified notification channel and return a confirmation message indicating that the updated channel needs to be verified. To complete the verification process, please use the Verify Personal Notification Channel endpoint.
  • 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 customer. Example: 'c03b02ec-244f-4d2c-8f68-3910071ed5c8'
Request Body Parameters
  • value string
    The updated notification channel value, such as a phone number or email address. Example: 'new.email@ping-home.org'
  • priority positive integer
JavaScript
Response codes
const axios = require('axios');

const url = "https://customer-cmd.api.pinghome.io/v1/customer/c03b02ec-244f-4d2c-8f68-3910071ed5c8/notification-channel";
const data = {
  "value": "new.email@ping-home.org",
  "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);
});
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).
Verify Personal Notification Channel
This endpoint is used to verify a notification channel for the authenticated customer. It is typically called after a new notification channel (e.g., an email address) has been added or updated, and requires confirmation.

This step helps verify that the notification channel is legitimate and trusted before allowing message delivery.

Important notes:
  • The request must include the confirmation code sent to the channel (e.g., via email)
  • Priority may also be included to identify or reorder channels if required
  • Only unverified channels can be confirmed using this endpoint


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 customer. 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/v1/customer/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);
});
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).
Delete Personal Notification Channel
This endpoint allows you to delete a specific notification channel configured for the authenticated customer. The notification channel to be removed is identified using the priority value passed as a query parameter.

When to use:
A customer wants to stop receiving alerts via a specific channel or wishes to remove outdated contact methods.

Important notes:
  • The priority parameter is required to identify which channel to delete
  • Only channels associated with the authenticated customer can be removed
  • Once deleted, the channel must be re-added if needed in the future

To view or modify channels before deletion, use the Get Notification Channels or Update Notification Channel endpoints.

Authorization: Bearer YOUR_TOKEN


Expected Behavior:


  • On success, the specified notification channels will be deleted, and the system will return a confirmation message.
  • If the request is unauthorized or invalid, the system will respond with an appropriate error message, indicating the issue.
Path Parameters
  • id string
    The unique ID of the customer. Example: 'c03b02ec-244f-4d2c-8f68-3910071ed5c8'
Query Parameters
  • priority positive integer
    The priority of the notification channels to be deleted. This value can be found in the response of the Get Personal Notification Channels endpoint. Example: priority=3&priority=4
JavaScript
Response codes
const axios = require('axios');

const url = "https://customer-cmd.api.pinghome.io/v1/customer/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);
});
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).
Test Personal Notification Channel
This endpoint allows you to send a test message to one of the customer's configured notification channels. It helps confirm that the channel is set up correctly and able to receive notifications.

Typical scenario:
Run this after adding or enabling a notification channel to make sure messages are delivered successfully.

Important notes:
  • The priority of the channel to test must be included in the request
  • Sends a non-intrusive test message — does not trigger real alerts
  • Useful for validating setup and troubleshooting delivery issues

To configure channels before testing, see the Create Notification Channel or Enable Notification Channel endpoints.

Authorization: Bearer YOUR_TOKEN


Expected Behavior:


  • On success, the system will send a test message to 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 customer. Example: 'c03b02ec-244f-4d2c-8f68-3910071ed5c8'
Request Body Parameters
  • priority positive integer
    The priority of the notification channel to test. This value can be found in the response of the Get Personal Notification Channels endpoint. Example: 1
JavaScript
Response codes
const axios = require('axios');

const url = "https://customer-cmd.api.pinghome.io/v1/customer/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);
});
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).
Update Personal Notification Channel Status
This endpoint allows you to enable or disable a specific notification channel for the authenticated customer. It is used to control whether alerts are actively delivered to a given channel without deleting it.

Recommended when:
A notification channel needs to be deactivated temporarily or reactivated later for continued use.

Important notes:
  • The request must include the enabled field (boolean) and the priority of the channel
  • Setting enabled: false deactivates delivery, while true reactivates it
  • This action does not delete or modify the channel configuration

To test the channel after enabling it, use the Test Notification Channel endpoint. To permanently remove a channel, see Delete Notification Channel.

Authorization: Bearer YOUR_TOKEN


Expected Behavior:


  • On success, the system will update the enabled status of the notification channel and return a confirmation message.
  • If the request is unauthorized or invalid, the system will respond with an appropriate error message, such as unauthorized access or invalid input.
Path Parameters
  • id string
    The unique ID of the customer. Example: 'c03b02ec-244f-4d2c-8f68-3910071ed5c8'
Request Body Parameters
  • enabled boolean
    The status of the notification channel. Example: true
  • priority positive integer
JavaScript
Response codes
const axios = require('axios');

const url = "https://customer-cmd.api.pinghome.io/v1/customer/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);
});
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).