Quickstart

This quickstart walks through the calls nearly every integration makes: check who you are, create a customer, open a conversation for them, and add a message. You need admin access to a Kustomer org. Use a sandbox org if you have one.

1. Create an API key

1. Open API keys

   In Kustomer, go to Settings › Security › API Keys and select Add API Key.

2. Name the key and pick roles

   Give it a name like quickstart. For this tutorial, add these roles: org.permission.customer.create, org.permission.customer.read, org.permission.conversation.create and org.permission.message.create. Roles can't be changed after creation, so pick what your integration needs. See API keys and roles.

3. Copy the token

   Set an expiry (or none) and, optionally, a CIDR IP restriction. Then create the key and copy the token. Kustomer only shows it once.

Store the token and your org name in environment variables. Your org name is the subdomain you use to sign in: for acme.kustomerapp.com, it's acme.

export KUSTOMER_API_KEY="eyJhbGciOi..."
export KUSTOMER_ORG="acme"

2. Verify the key

Ask the API which token you're using. This works with any valid key, whatever its roles.

curl "https://$KUSTOMER_ORG.api.kustomerapp.com/v1/auth/tokens/current" \
  -H "Authorization: Bearer $KUSTOMER_API_KEY"

A 200 response describes the token, including its roles and the machine user behind it:

{
  "data": {
    "type": "auth_token",
    "id": "5822276811e88a1000787abe",
    "attributes": {
      "name": "quickstart",
      "lastTokenChars": "xyz123",
      "roles": ["org.permission.customer.create", "org.permission.customer.read", "..."]
    },
    "relationships": {
      "org": { "data": { "type": "org", "id": "57f29863a1dbf61100e6aa92" } },
      "user": { "data": { "type": "user", "id": "58190b991f2932100010d683" } }
    }
  }
}

If you get 401, check that the header reads Bearer, a space, then the token, and that you're using your org's host. See Errors.

3. Create a customer

Customers are the center of the data model. Give each one an externalId that matches the ID in your own system so you can find them again without storing Kustomer IDs.

curl -X POST "https://$KUSTOMER_ORG.api.kustomerapp.com/v1/customers" \
  -H "Authorization: Bearer $KUSTOMER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jane Doe",
    "externalId": "crm-10293",
    "emails": [{ "type": "home", "email": "jane.doe@example.com" }],
    "tags": ["quickstart"]
  }'

Requests send plain JSON attributes. Responses come back wrapped in a data envelope with type, id, attributes and relationships. Request and response format explains the envelope.

{
  "data": {
    "type": "customer",
    "id": "5822a4a5aa5f92110005d69a",
    "attributes": {
      "name": "Jane Doe",
      "displayName": "Jane Doe",
      "externalId": "crm-10293",
      "emails": [{ "email": "jane.doe@example.com", "verified": false, "type": "home" }],
      "tags": ["quickstart"],
      "createdAt": "2026-10-21T14:02:11.925Z"
    },
    "links": { "self": "/v1/customers/5822a4a5aa5f92110005d69a" }
  }
}

4. Open a conversation

curl -X POST "https://$KUSTOMER_ORG.api.kustomerapp.com/v1/customers/$CUSTOMER_ID/conversations" \
  -H "Authorization: Bearer $KUSTOMER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Where is my order?", "status": "open", "priority": 3, "tags": ["quickstart"] }'

priority runs from 1 to 5 and status is open or done on create. Copy data.id from the response.

5. Add a message

Messages carry the actual communication. channel and app are required: channel is the medium, and app identifies the integration that produced the message. The text goes in preview.

curl -X POST "https://$KUSTOMER_ORG.api.kustomerapp.com/v1/conversations/$CONVERSATION_ID/messages" \
  -H "Authorization: Bearer $KUSTOMER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "chat",
    "app": "quickstart",
    "direction": "in",
    "preview": "Hi! My order #4417 has not arrived yet."
  }'

Open the customer in Kustomer: the conversation and message are on their timeline.

Next steps