See related

Introduction to our API

Last Update: Nov 2024 • Est. Read Time: 3 MIN
To check plan availability, see the pricing page.

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

Who can access this feature?
User typesAll organizations can access our APIs. Rate limits differ by tier.


In this article

This article will help you get started using Kustomer's REST APIs. For more information on our APIs, see our API documentation.

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 its 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. It 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. Resources are 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. We recommend Postman as a good free-to-use tool for getting started with the API.

Sending requests

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

For a full list of our available endpoints, see API reference documentation.

Authentication

All requests to the Kustomer API are authenticated using an API token included with your request's Authorization header. Admins can manage API keys within Kustomer from the API Keys settings page. You can access this page by going to Settings > Security > API Keys.

When creating a new key, you can select an API role and apply a friendly label. Roles are useful to limit the operations requests using that key can perform.


To use your API key, include it in the Authorization request header, and prefix the key with “Bearer” and a single space.

Rate limiting

To ensure quality service and to prevent abuse, Kustomer limits the number of API requests that can be made in a short period of time. API rate limits differ by pricing tier. For more information on our pricing tiers, see our pricing plans. To help you track your rate limit usage, we include headers in API responses that include your current rate-limiting status:

For more information about our rate limits, see API rate limits.

Sending Data With Requests

Most POSTGETand 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 standard format is readable by nearly all modern programming languages and environments. Most API endpoints are structured similarly, 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": "janedoe@gmail.com",
        "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"
  }
 }
}


Error Messages

Errors commonly returned by the API will follow a common format: an HTTP status code indicating the error and a response body containing more information about the error. In the following example, the request failed because the user didn't have the proper permission set role to access that endpoint.