Contact reads

GET /api/v2/contacts/{ghl_contact_id}/summary

All contact read endpoints require the summary scope and take location_id as a query parameter (not in a body). List endpoints accept an optional ?limit= (default 20, max 100). The summary endpoint below returns the richest snapshot; the others return one focused slice.

Summary

Returns a snapshot of a contact’s credits, entitlements, recent ledger, recent appointments, and recent payments.

curl

curl "https://app.<your-domain>/api/v2/contacts/ghl_contact_123/summary?location_id=loc_1" \
  -H "Authorization: Bearer ktly_<your-token>"

JavaScript

const url =
  "https://app.<your-domain>/api/v2/contacts/ghl_contact_123/summary?location_id=loc_1";
const res = await fetch(url, {
  headers: { Authorization: `Bearer ${process.env.KOTALLY_TOKEN}` },
});
const data = await res.json();
// data.summary.credits_available, data.summary.entitlements

Response (200)

{
  "ok": true,
  "reason_code": "summary_loaded",
  "correlation_id": "a1b2c3d4-...",
  "contact": {
    "id": "kotally-contact-uuid",
    "ghl_contact_id": "ghl_contact_123",
    "email": "member@example.com",
    "name": "Member Example"
  },
  "summary": {
    "credits_available": 9,
    "last_paid_at": "2026-04-16T00:00:00.000Z",
    "lifetime_value_cents": 9900,
    "payment_events_count": 1,
    "entitlements": [
      {
        "id": "kotally-entitlement-uuid",
        "product_config_id": "pc_package_1",
        "status": "active",
        "credits_remaining": 9,
        "expires_at": null
      }
    ],
    "recent_ledger": [],
    "recent_appointments": [],
    "recent_payments": []
  }
}

All read endpoints

Every endpoint below takes ?location_id= and requires the summary scope. The list endpoints (ledger, payments, appointments/*) also accept ?limit=.

Method	Path	Returns
GET	/api/v2/contacts/{id}	Contact profile
GET	/api/v2/contacts/{id}/summary	The combined snapshot above
GET	/api/v2/contacts/{id}/credits	Credit balance and entitlement status
GET	/api/v2/contacts/{id}/entitlements	All entitlements with full detail
GET	/api/v2/contacts/{id}/appointments/upcoming	Upcoming appointments
GET	/api/v2/contacts/{id}/appointments/past	Past appointments
GET	/api/v2/contacts/{id}/ledger	Credit ledger entries
GET	/api/v2/contacts/{id}/payments	Payment events
GET	/api/v2/contacts/{id}/timeline	Combined chronological timeline

Failure reason codes

reason_code	Meaning
NOT_FOUND	No contact found for the given ghl_contact_id and location_id

See the Overview for HTTP status codes and the full reason-code list.