Customers API | Keva Docs

The Customers API allows you to create, retrieve, and manage customer profiles. Customer profiles aggregate data across tickets and enable personalized support.

Endpoints

Method	Endpoint	Description
GET	`/api/customers`	List customers
POST	`/api/customers`	Create or update customer
GET	`/api/customers/:id`	Get customer profile
PATCH	`/api/customers/:id`	Update customer
GET	`/api/customers/lookup`	Lookup by email

List Customers

Retrieve a paginated list of customer profiles.

GET /api/customers

Query Parameters

Parameter	Type	Default	Description
`limit`	integer	50	Items per page (max: 100)
`offset`	integer	0	Offset for pagination
`search`	string	-	Search by email, name, or company
`vipOnly`	boolean	false	Filter VIP customers only

Example Request

curl "https://app.keva.support/api/customers?search=acme&limit=20" \
  -H "Authorization: Bearer keva_live_your_api_key"

Example Response

{
  "customers": [
    {
      "id": "cust_abc123",
      "email": "john@acme.com",
      "name": "John Smith",
      "company": "Acme Corp",
      "phone": "+1-555-0100",
      "jobTitle": "CTO",
      "location": "San Francisco, CA",
      "timezone": "America/Los_Angeles",
      "isVip": true,
      "priorityOverride": "high",
      "tags": ["enterprise", "early-adopter"],
      "totalTickets": 12,
      "openTickets": 1,
      "avgResolutionTime": 3600,
      "overallSentiment": "positive",
      "sentimentTrend": "improving",
      "firstTicketAt": "2023-06-15T10:00:00Z",
      "lastTicketAt": "2024-01-14T15:30:00Z",
      "salesforceContactId": "003ABC123",
      "hubspotContactId": "12345",
      "createdAt": "2023-06-15T10:00:00Z",
      "updatedAt": "2024-01-14T15:30:00Z"
    }
  ],
  "total": 156,
  "limit": 20,
  "offset": 0
}

Create or Update Customer

Create a new customer or update an existing one (upsert by email).

POST /api/customers

Request Body

Field	Type	Required	Description
`email`	string	Yes	Customer email (unique identifier)
`name`	string	No	Full name
`company`	string	No	Company name
`phone`	string	No	Phone number
`jobTitle`	string	No	Job title
`location`	string	No	Location/address
`timezone`	string	No	IANA timezone
`isVip`	boolean	No	VIP status
`priorityOverride`	string	No	`low`, `medium`, `high`, `urgent`
`tags`	array	No	Array of tag strings
`internalNotes`	string	No	Internal notes (not visible to customer)

Example Request

curl -X POST https://app.keva.support/api/customers \
  -H "Authorization: Bearer keva_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jane@startup.io",
    "name": "Jane Doe",
    "company": "Startup.io",
    "jobTitle": "Head of Support",
    "timezone": "America/New_York",
    "isVip": true,
    "tags": ["beta-tester", "startup"]
  }'

Example Response

{
  "customer": {
    "id": "cust_new456",
    "email": "jane@startup.io",
    "name": "Jane Doe",
    "company": "Startup.io",
    "jobTitle": "Head of Support",
    "timezone": "America/New_York",
    "isVip": true,
    "tags": ["beta-tester", "startup"],
    "totalTickets": 0,
    "openTickets": 0,
    "createdAt": "2024-01-15T18:00:00Z"
  }
}

Get Customer

Retrieve a customer profile by ID.

GET /api/customers/:id

Example Request

curl https://app.keva.support/api/customers/cust_abc123 \
  -H "Authorization: Bearer keva_live_your_api_key"

Update Customer

Update customer profile fields.

PATCH /api/customers/:id

Example Request

curl -X PATCH https://app.keva.support/api/customers/cust_abc123 \
  -H "Authorization: Bearer keva_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "isVip": true,
    "priorityOverride": "high",
    "internalNotes": "Enterprise customer, handle with care"
  }'

Lookup by Email

Find a customer by their email address.

GET /api/customers/lookup?email=customer@example.com

Example Request

curl "https://app.keva.support/api/customers/lookup?email=john@acme.com" \
  -H "Authorization: Bearer keva_live_your_api_key"

Auto-Creation

Customer profiles are automatically created when:

A new ticket is received from an unknown email
A widget conversation starts with a new email
You create a ticket via API with a new customer email

CRM Integration

Customer profiles can be synced with external CRMs:

Field	Description
`salesforceContactId`	Linked Salesforce Contact ID
`hubspotContactId`	Linked HubSpot Contact ID
`hubspotCompanyId`	Linked HubSpot Company ID

Configure CRM sync in Settings > Integrations > CRM.

Computed Fields

These fields are automatically calculated:

Field	Description
`totalTickets`	Total number of tickets
`openTickets`	Currently open tickets
`avgResolutionTime`	Average time to resolution (seconds)
`overallSentiment`	`positive`, `neutral`, `negative`
`sentimentTrend`	`improving`, `stable`, `declining`
`firstTicketAt`	Timestamp of first ticket
`lastTicketAt`	Timestamp of most recent ticket