Getting started with Kustomer API

Learn about the Kustomer REST APIs and how they can be used to interact with resources within Kustomer.

The Kustomer API is a powerful tool that allows your organization to interact with nearly every resource within Kustomer. You can securely insert and update customers, messages, conversations, custom objects (KObjects), and much more through a series of REST APIs.

API uses

The Kustomer API has many uses, but is best applied to programmatic interactions with the Kustomer platform.

For example, an airline using Kustomer could program their flight tracking software to update a customer’s timeline in Kustomer when a flight is delayed. This event would be instantly available to the airline’s customer service agents and could also trigger a workflow that instantly sends an SMS message to the customer informing them of the delay.

Using the Kustomer API

The Kustomer API is an HTTP API based on RESTful design principles, with resources accessible via a URL similar to a website address. The base URL you'll use in these API requests depends on the production point of deployment for your organization instance:

  • Prod1 (US): https://api.kustomerapp.com
  • Prod2 (EU): https://api.prod2.kustomerapp.com

Each address represents a different resource. For example, requests sent to https://api.kustomerapp.com/v1/customers manipulate Customer objects. The request has a different outcome depending on the HTTP verb used in your request.

A request sent to https://api.kustomerapp.com/v1/customers with the GET verb returns a list of customers belonging to your organization. Sending a POST request to the same endpoint creates a new customer.

You can interact with the Kustomer API using any standard HTTP client or your own scripts and programs.

Setting up Postman

You can use the API software of your choice, but our developer documentation is written around the use of Postman.

If you'd like to use Postman, follow these steps to set up the app and create a workspace:

  1. Sign up for a Postman account.
  2. In the toolbar, select Workspaces > Create Workspace.
1006
  1. Fill in the Name and Summary of your Kustomer API workspace, and select Personal under Visibility.
  2. Select Create Workspace to confirm.
  3. In your new workspace, press the Plus + icon in the toolbar to create a new request.
1592

After creating the workspace, you'll need to add headers to make an API request.

  1. Select the Headers tab underneath the request URL bar.
  2. Fill in the following Key values:
    • Content-Type: application/json
    • Authorization: Bearer API_KEY (the space is required)
2268

Learn more about creating and using workspaces in the Postman documentation.

Sending requests

Sending requests is as simple as choosing an endpoint, a request method, and setting the proper headers, as described below:

2080

Including data with requests

Most POST, GET, and PUT requests require data to be sent with them. This data is stored in the request body as a JSON object. For example, to update a customer's displayName, the request body might look like this:

{
 “displayName”: “Jane”
}

Responses

Like requests bodies, responses are formatted in JSON. This is a standard format readable by nearly all modern programming languages and environments. Most API endpoints are structured in the same way, with a top-level data property that contains either an array of objects or an object with an id property, attributes, and relationships. The following is an example API response for a GET request to /v1/customers/{id}:

{
 "data": {
  "type": "customer",
  "id": "59df762a921c59001021f409",
  "attributes": {
    "name": "Jane Doe",
    "displayName": "Jane Doe",
    "displayColor": "blue",
    "displayIcon": "compass",
    "externalId": "59df762a921c59001021f409",
    "firstName": "Jane",
    "lastName": "Done",
    "signedUpAt": null,
    "avatarUrl": null,
    "username": null,
    "emails": [
      {
        "email": "[email protected]",
        "verified": false,
        "type": "home"
      }
    ],
    "phones": [{
      "phone": "+12065551234",
      "type": "home"
    }]
  },
  "relationships": {
    "org": {
      "links": {
        "self": "/v1/orgs/59d682e535145200131693ca"
      },
      "data": {
        "type": "org",
        "id": "59d682e535145200131693ca"
      }
    },
    "messages": {
      "links": {
        "self": "/v1/customers/59df762a921c59001021f409/messages"
      }
    }
  },
  "links": {
    "self": "/v1/customers/59df762a921c59001021f409"
  }
 }
}