List properties

Lists the active properties within the brand that your API key can access. Brand-wide discovery — no Kyc-Property-Id header (this is how you discover property IDs). Results are scoped by your key’s authorized properties.

GET https://{service}.{brand}.kych.co/v1/properties

List properties

cURL

curl --request GET \
  --url https://{service}.{brand}.kych.co/v1/properties \
  --header 'Authorization: Bearer <token>' \
  --header 'User-Agent: <user-agent>'

200

{
  "data": [
    {
      "object": "property",
      "id": "4a2f0c10-2e7a-4b9d-9b3a-1f0c9e8d7a6b",
      "name": "Hilton Austin Downtown",
      "code": "ATXDT",
      "status": "active",
      "timezone": "America/Chicago",
      "createdAt": "2025-01-15T09:00:00.000Z",
      "updatedAt": "2026-05-02T14:30:00.000Z"
    }
  ],
  "meta": {
    "requestId": "req_01J9Z3K8Q2X7C5N0",
    "timestamp": "2026-06-26T22:01:01.010Z",
    "pagination": {
      "page": 1,
      "perPage": 50,
      "total": 1
    }
  }
}

Authorizations

Authorization · string · header · required

API key sent as a bearer token: Authorization: Bearer kyc_live_.... Keys are prefixed kyc_live_ (production) or kyc_test_ (test mode). OAuth2 access tokens (also Bearer) may be supported later — the header never changes.

Headers

User-Agent · string · required

Identifies the calling application. 3–255 printable ASCII characters.

Required string length: 3 - 255

Pattern: ^[\x20-\x7E]+$

Kyc-Correlation-Id · string

Optional caller-supplied opaque ID for log correlation. Echoed back and logged. Treated opaquely (never decoded). Must match the pattern below.

Pattern: ^[A-Za-z0-9._=+/-]{1,128}$

traceparent · string

Optional W3C Trace Context header for distributed tracing. A malformed value is ignored and a fresh trace is started (per the W3C spec) — it never causes a 4xx.

Query Parameters

page · integer · default: 1

Page number (1-based).

Required range: x >= 1

perPage · integer · default: 50

Items per page.

Required range: 1 <= x <= 100

Response

200

application/json

A page of properties.

data · object[] · required

Hide child attributes

data. object · string · required

Resource type discriminator.

Allowed value: "property"

data. id · string<uuid> · required

Property UUID (stable, never changes).

data. name · string · required

Property display name.

Example:

"Hilton Austin Downtown"

data. code · string | null · required

Short, human-friendly property code. Public, implementation-agnostic alias — maps from an internal field via the API Resource. TBD: confirm the source and semantics (the internal elasticsearch_id is currently used as a code). NEVER expose internal field names (e.g. elasticsearch_id) to partners. Nullable until source/semantics confirmed.

Example:

"ATXDT"

data. status · enum<string> · required

Whether the property is active.

Available options: active, inactive

data. timezone · string · required

IANA timezone name. Always present — required for correct date/time handling.

Example:

"America/Chicago"

data. createdAt · string<date-time> · required

When the property record was created (UTC).

data. updatedAt · string<date-time> · required

When the property record was last updated (UTC).

meta · object · required

Metadata present on every success response.

Hide child attributes

meta. requestId · string · required

Server-generated ID for this request (mirrors the Kyc-Request-Id header).

Example:

"req_01J9Z3K8Q2X7C5N0"

meta. timestamp · string<date-time> · required

UTC timestamp, ISO 8601 with milliseconds.

Example:

"2026-06-25T22:01:01.010Z"

meta. pagination · object

Present only on list responses.

Hide child attributes

meta.pagination. page · integer · required

Current page number (1-based).

Required range: x >= 1

meta.pagination. perPage · integer · required

Items per page.

Required range: x >= 1

meta.pagination. total · integer · required

Total items across all pages.

Required range: x >= 0