Account Settings | Pinghome Public API Documentation

Account Settings

Account settings enables users to manage and configure customer accounts efficiently. Key features include updating customer information, managing notification preferences, and deleting accounts when needed. To keep everything simple, the functionality is divided into two main sections:

Customer management: This section allows you to view, update, or delete customer details, manage email changes, and handle customer feedback, ensuring that information stays up-to-date and accurate.

Notification channel management: This feature lets you create, update, and remove notification channels for customers. It also provides tools to test and verify these channels for smooth communication.

ENDPOINTS

Expand all

Customer management
GET/customer/{customer_id}
PATCH/customer
DELETE/customer
PUT/customer/username
PATCH/customer/username
POST/customer/feedback
Customer notification channel management

Get Customer Profile

This endpoint retrieves comprehensive information about a specific customer.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the system will return the customer's profile information, including details about their team, organization, and any associated limits.
If the request is unauthorized or the customer is not found, an error message will be returned explaining the issue.

Path Parameters

customer_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/default/v1/customer/6fb4e64f-ad18-46e3-920c-92639adb137c";

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 API endpoint allows for the updating of an existing customer record, including fields such as name and surname.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

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

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-query.api.pinghome.io/default/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);
});

Delete Customer Account

This API endpoint allows deleting an existing customer record. You must provide a reason for deletion.

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.

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/default/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);
});

Update Customer Username

This API endpoint allows updating the username of an existing customer by providing a valid email.

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/default/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);
});

Confirm Customer Username Change

This API endpoint allows verifying a new username. You need to include the confirmation code when making the request.

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/default/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);
});

Submit Customer Feedback

This API endpoint allows you to submit feedback about your experience.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

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

Request Body Parameters

feedback string
The feedback provided by the customer. Example: 'Good experience'

JavaScript

Response codes

const axios = require('axios');

const url = "https://customer-cmd.api.pinghome.io/default/v1/customer/feedback";
const data = {
  "feedback": "Good experience"
};

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 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.
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/default/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);
});

Get Personal Notification Channels

This API endpoint retrieves the notification channels for a customer.

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/default/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);
});

Update Personal Notification Channel

This API endpoint allows updating an existing notification channel for a specific customer. The request must contain the updated notification channel details, including the value and priority of the notification channel.

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/default/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);
});

Verify Personal Notification Channel

This API endpoint allows verifying a new notification channel for a customer. The request body must contain the necessary verification details, such as the confirmation 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 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/default/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);
});

Delete Personal Notification Channel

This API endpoint allows for the deletion of customer notification channels. To specify which channels to delete, you must include the priority as a query parameter.

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/default/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);
});

Test Personal Notification Channel

This API endpoint allows sending a test message to a customer's notification channel. The request must contain the priority of the notification channel to test.

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/default/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);
});

Update Personal Notification Channel Status

This API endpoint allows updating the status of a customer's notification channel. The request must include the enabled field, which accepts a boolean value (true or false), and the priority of the 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/default/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);
});