Getting started with Kustomer API

Learn about the Kustomer REST APIs, and how these 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. 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.

Sending requests

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

Sending 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"
  }
 }
}