LiyaSupport
API Reference

Contacts API

Create, retrieve, update, and manage customer contact records programmatically.

6 min read Updated July 2026

Endpoints

GET/v1/contactsList contacts
POST/v1/contactsCreate a contact
GET/v1/contacts/:idRetrieve a contact
PATCH/v1/contacts/:idUpdate a contact
DELETE/v1/contacts/:idDelete a contact
GET/v1/contacts/:id/conversationsList contact's conversations
POST/v1/contacts/:id/tagsAdd tags
DELETE/v1/contacts/:id/tags/:tagRemove a tag

Create a contact

POST /v1/contacts

bash
curl -X POST https://api.liyasupport.com/v1/contacts \
  -H "Authorization: Bearer lsk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "name": "Jane Doe",
    "phone": "+14155550123",
    "tags": ["enterprise", "vip"],
    "custom_attributes": {
      "plan": "Enterprise",
      "company": "Acme Corp",
      "mrr": 2400
    }
  }'

Request body parameters

ParameterTypeRequiredDescription
emailstringYes*Contact email address. *Required unless phone is provided.
phonestringYes*E.164 format phone number. *Required unless email is provided.
namestringNoContact's display name
avatar_urlstringNoURL to the contact's avatar image
tagsstring[]NoArray of tag strings
custom_attributesobjectNoKey/value pairs for any custom fields

Response

json
{
  "id": "cnt_01JXYZ789",
  "email": "[email protected]",
  "name": "Jane Doe",
  "phone": "+14155550123",
  "avatar_url": null,
  "tags": ["enterprise", "vip"],
  "custom_attributes": {
    "plan": "Enterprise",
    "company": "Acme Corp",
    "mrr": 2400
  },
  "conversation_count": 7,
  "last_seen_at": "2026-07-03T10:14:00Z",
  "created_at": "2025-09-01T08:00:00Z",
  "updated_at": "2026-07-03T10:14:00Z"
}

Contact merging

When the same customer contacts you with different emails or phone numbers, you may end up with duplicate contact records. Merge them via:

bash
curl -X POST https://api.liyasupport.com/v1/contacts/cnt_PRIMARY/merge \
  -H "Authorization: Bearer lsk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "merge_contact_id": "cnt_DUPLICATE" }'

The duplicate contact's conversations and attributes are merged into the primary contact. The duplicate record is then permanently deleted.

Custom attributes

Custom attributes allow you to store arbitrary structured data on contact records — for example, CRM account ID, subscription plan, MRR, or churn risk score. They are visible in the conversation sidebar and can be used as conditions in routing and automation rules.

Define your custom attribute schema in Settings → Contacts → Custom attributesbefore setting values via the API. Supported types: string, number,boolean, date.

Custom attribute keys must be predefined in your workspace settings. Attempting to set an undefined key via the API returns a 422 Validation Error.