Crescendo Lab CDH OpenAPI (2.0.1)

Download OpenAPI specification:

If you would like to integrate with CDH API, please contact our support: help@cresclab.com

Crescendo Lab CDH OpenAPI is used to query unified contact profile, engagement history, and subscribe webhook events from Crescendo Lab Customer Data Hub (CDH).

If you are using Crescendo Lab product in the Taiwan or Thailand region, please use https://api.user360.cresclab.com
If you are using Crescendo Lab product in the Japan region, please use https://api.user360.jp.cresclab.com

Authentication

Bring the apikey parameter in the HTTP header to call CDH OpenAPI

header key	value
apikey	`{API key}`

Webhook

CDH API supports webhooks to notify you when events happen in CDH. When something triggers that event, CDH sends an HTTP POST request to your URL with a payload containing information about the event.

Setup Webhooks

To setup or configure your webhook endpoint, please contact our support.

Consuming Webhooks

Webhooks are delivered with a Content-Type of application/json, with the event payload as JSON in the request body. We also send the following headers:

CrescLab-Idempotency-Key - an unique ID of the event
CrescLab-Signature - the HMAC hex digest of the request body, used to secure your webhooks and ensure the request did come from CDH
User-Agent - identifies the origin of the request, e.g., cresclab-harmony/1.0

Considerations

Process events asynchronously to prevent HTTP POST requests from delaying subsequent ones.
Ensure server confirms signatures before processing webhook events, to avoid attacks that don't originate from CDH.
Ensure the stability of your webhook endpoint. We offer retry mechanism but don't save all event records.

Response

Your webhook endpoint must returns status code 200 within 5 second of receiving the webook request.

Retry policy

If a webhook POST to an endpoint receives the following responses, we will retry up to 3 times.

HTTP 408, 429, and 5xx response codes.
Socket timeouts and TCP disconnects.

You can detect duplicate webhook events by comparing the CrescLab-Idempotency-Key header to previous events.

Validating Payloads

All webhook events sent to your endpoint have a CrescLab-Signature header, which contains the hash signature for the transport. This enables you to verify the events are delivered from CDH, not from an unauthorized third party.

The signature is a HMAC-SHA256 hexadecimal digest, produced from the request body using your secret key. You should get your secret key from our customer support team.

We provide the following Python snippet as a reference implementation for signature validation.

import hashlib
import hmac

share_secret = "..."  # share secret string
header_signature = "..."  # CrescLab-Signature in request header
body = "..."  # Request body string
signature = hmac.new(
    share_secret.encode("utf-8"), body.encode("utf-8"), hashlib.sha256
).hexdigest()
assert hmac.compare_digest(signature, header_signature)

message.send Webhook

An event when sending message to a contact

Request Body schema: application/json

event required	string the event type
timestamp required	string the timestamp that event happened and in ISO format
source required	string Enum: "maac" "caac" the event source
required	object

Responses

Request samples

Payload

Content type

application/json

{"event": "message.send",
"timestamp": "2023-09-20T12:00:16.850000+00:00",
"source": "maac",
"data": {"campaign_id": 191914,
"campaign_type": "broadcast",
"campaign_name": "summer sell",
"customer_id": "C1234567",
"line_uid": "U8e654ca50c5b36a2411a9d1acefc3cd5"
}
}

message.open Webhook

An event when a contact opens message

Messages sent via the MAAC Enhanced Multicast API do not support personalized tracking so that it will not trigger this event.

Request Body schema: application/json

event required	string the event type
timestamp required	string the timestamp that event happened and in ISO format
source required	string Enum: "maac" "caac" the event source
required	object

Responses

Request samples

Payload

Content type

application/json

{"event": "message.open",
"timestamp": "2023-09-20T12:00:16.850000+00:00",
"source": "maac",
"data": {"campaign_id": 191914,
"campaign_type": "broadcast",
"campaign_name": "summer sell",
"customer_id": null,
"line_uid": "U8e654ca50c5b36a2411a9d1acefc3cd5"
}
}

message.click Webhook

An event when a contact clicks a link

Messages sent via the MAAC Enhanced Multicast API do not support personalized tracking so that it will not trigger this event.

Request Body schema: application/json

event required	string the event type
timestamp required	string the timestamp that event happened and in ISO format
source required	string Enum: "maac" "caac" the event source
required	object

Responses

Request samples

Payload

Content type

application/json

{"event": "message.click",
"timestamp": "2023-09-20T12:00:16.850000+00:00",
"source": "maac",
"data": {"campaign_id": 191914,
"campaign_type": "broadcast",
"campaign_name": "summer sell",
"customer_id": null,
"line_uid": "U8e654ca50c5b36a2411a9d1acefc3cd5",
"link": "https://example.com"
}
}

prize.send Webhook

An event when a prize is sent to a contact

Request Body schema: application/json

event required	string the event type
timestamp required	string the timestamp that event happened and in ISO format
source required	string Enum: "maac" "caac" the event source
required	object

Responses

Request samples

Payload

Content type

application/json

{"event": "prize.send",
"timestamp": "2023-09-20T12:00:16.850000+00:00",
"source": "maac",
"data": {"campaign_id": 191914,
"campaign_type": "prize",
"campaign_name": "prize campaign name",
"customer_id": "C1234567",
"line_uid": "U8e654ca50c5b36a2411a9d1acefc3cd5"
}
}

prize.claim Webhook

An event when a prize is claimed by a contact

Request Body schema: application/json

event required	string the event type
timestamp required	string the timestamp that event happened and in ISO format
source required	string Enum: "maac" "caac" the event source
required	object

Responses

Request samples

Payload

Content type

application/json

{"event": "prize.claim",
"timestamp": "2023-09-20T12:00:16.850000+00:00",
"source": "maac",
"data": {"campaign_id": 191914,
"campaign_type": "prize",
"campaign_name": "prize campaign name",
"customer_id": "C1234567",
"line_uid": "U8e654ca50c5b36a2411a9d1acefc3cd5",
"code": "Code-0001"
}
}

prize.redeem Webhook

An event when a prize is redeemed by a contact

Request Body schema: application/json

event required	string the event type
timestamp required	string the timestamp that event happened and in ISO format
source required	string Enum: "maac" "caac" the event source
required	object

Responses

Request samples

Payload

Content type

application/json

{"event": "prize.redeem",
"timestamp": "2023-09-20T12:00:16.850000+00:00",
"source": "maac",
"data": {"campaign_id": 191914,
"campaign_type": "prize",
"campaign_name": "prize campaign name",
"customer_id": "C1234567",
"line_uid": "U8e654ca50c5b36a2411a9d1acefc3cd5",
"code": "Code-0001"
}
}

contact.profile.customer_id.update Webhook

An event when a contact's customer_id is updated

Request Body schema: application/json

event required	string the event type
timestamp required	string the timestamp that event happened
source required	string Enum: "maac" "caac" the event source
required	object

Responses

Request samples

Payload

Content type

application/json

{"event": "contact.profile.customer_id.update",
"timestamp": "2023-09-20T12:00:16.850000+00:00",
"source": "maac",
"data": {"customer_id": null,
"line_uid": "U8e654ca50c5b36a2411a9d1acefc3cd5"
}
}

contact.profile.connect_id.update Webhook

An event when a contact's connect_id is updated

Request Body schema: application/json

event required	string The event type
timestamp required	string The timestamp that event happened
source required	string Enum: "maac" "caac" The event source
required	object

Responses

Request samples

Payload

Content type

application/json

{"event": "contact.profile.connect_id.update",
"timestamp": "2025-06-30T05:52:09.108Z",
"source": "maac",
"data": {"external_member_id": "U315df4d06394696a3c7cf71e4a0b51f3",
"channel_type": "line",
"customer_id": null,
"connect_id": "connect_id_example"
}
}

contact.profile.full_name.update Webhook

An event when a contact's full_name is updated

Request Body schema: application/json

event required	string The event type
timestamp required	string The timestamp that event happened
source required	string Enum: "maac" "caac" The event source
required	object

Responses

Request samples

Payload

Content type

application/json

{"event": "contact.profile.full_name.update",
"timestamp": "2025-06-30T05:52:09.108Z",
"source": "maac",
"data": {"external_member_id": "U315df4d06394696a3c7cf71e4a0b51f3",
"channel_type": "line",
"customer_id": null,
"full_name": "John Doe"
}
}

contact.profile.display_email.update Webhook

An event when a contact's display_email is updated

Request Body schema: application/json

event required	string The event type
timestamp required	string The timestamp that event happened
source required	string Enum: "maac" "caac" The event source
required	object

Responses

Request samples

Payload

Content type

application/json

{"event": "contact.profile.display_email.update",
"timestamp": "2025-06-30T05:52:09.108Z",
"source": "maac",
"data": {"external_member_id": "U315df4d06394696a3c7cf71e4a0b51f3",
"channel_type": "line",
"customer_id": null,
"display_email": "john.doe@example.com"
}
}

contact.profile.display_mobile.update Webhook

An event when a contact's display_mobile is updated

Request Body schema: application/json

event required	string The event type
timestamp required	string The timestamp that event happened
source required	string Enum: "maac" "caac" The event source
required	object

Responses

Request samples

Payload

Content type

application/json

{"event": "contact.profile.display_mobile.update",
"timestamp": "2025-06-30T05:52:09.108Z",
"source": "maac",
"data": {"external_member_id": "U315df4d06394696a3c7cf71e4a0b51f3",
"channel_type": "line",
"customer_id": null,
"display_mobile": "+886911000008"
}
}

contact.profile.display_name.update Webhook

An event when a contact's display_name is updated

Request Body schema: application/json

event required	string The event type
timestamp required	string The timestamp that event happened
source required	string Enum: "maac" "caac" The event source
required	object

Responses

Request samples

Payload

Content type

application/json

{"event": "contact.profile.display_name.update",
"timestamp": "2025-06-30T05:52:09.108Z",
"source": "maac",
"data": {"external_member_id": "U315df4d06394696a3c7cf71e4a0b51f3",
"channel_type": "line",
"customer_id": null,
"display_name": "Johnny"
}
}

contact.profile.gender.update Webhook

An event when a contact's gender is updated

Request Body schema: application/json

event required	string The event type
timestamp required	string The timestamp that event happened
source required	string Enum: "maac" "caac" The event source
required	object

Responses

Request samples

Payload

Content type

application/json

{"event": "contact.profile.gender.update",
"timestamp": "2025-06-30T05:52:09.108Z",
"source": "maac",
"data": {"external_member_id": "U315df4d06394696a3c7cf71e4a0b51f3",
"channel_type": "line",
"customer_id": null,
"gender": "male"
}
}

contact.profile.birthday.update Webhook

An event when a contact's birthday is updated

Request Body schema: application/json

event required	string The event type
timestamp required	string The timestamp that event happened
source required	string Enum: "maac" "caac" The event source
required	object

Responses

Request samples

Payload

Content type

application/json

{"event": "contact.profile.birthday.update",
"timestamp": "2025-06-30T05:52:09.108Z",
"source": "maac",
"data": {"external_member_id": "U315df4d06394696a3c7cf71e4a0b51f3",
"channel_type": "line",
"customer_id": null,
"birthday": "2000-01-01"
}
}

contact.profile.region.update Webhook

An event when a contact's region is updated

Request Body schema: application/json

event required	string The event type
timestamp required	string The timestamp that event happened
source required	string Enum: "maac" "caac" The event source
required	object

Responses

Request samples

Payload

Content type

application/json

{"event": "contact.profile.region.update",
"timestamp": "2025-06-30T05:52:09.108Z",
"source": "maac",
"data": {"external_member_id": "U315df4d06394696a3c7cf71e4a0b51f3",
"channel_type": "line",
"customer_id": null,
"region": "TW"
}
}

contact.profile.city.update Webhook

An event when a contact's city is updated

Request Body schema: application/json

event required	string The event type
timestamp required	string The timestamp that event happened
source required	string Enum: "maac" "caac" The event source
required	object

Responses

Request samples

Payload

Content type

application/json

{"event": "contact.profile.city.update",
"timestamp": "2025-06-30T05:52:09.108Z",
"source": "maac",
"data": {"external_member_id": "U315df4d06394696a3c7cf71e4a0b51f3",
"channel_type": "line",
"customer_id": null,
"city": "Taipei"
}
}

contact.profile.address.update Webhook

An event when a contact's address is updated

Request Body schema: application/json

event required	string The event type
timestamp required	string The timestamp that event happened
source required	string Enum: "maac" "caac" The event source
required	object

Responses

Request samples

Payload

Content type

application/json

{"event": "contact.profile.address.update",
"timestamp": "2025-06-30T05:52:09.108Z",
"source": "maac",
"data": {"external_member_id": "U315df4d06394696a3c7cf71e4a0b51f3",
"channel_type": "line",
"customer_id": null,
"address": "123 Main St"
}
}

contact.profile.company.update Webhook

An event when a contact's company is updated

Request Body schema: application/json

event required	string The event type
timestamp required	string The timestamp that event happened
source required	string Enum: "maac" "caac" The event source
required	object

Responses

Request samples

Payload

Content type

application/json

{"event": "contact.profile.company.update",
"timestamp": "2025-06-30T05:52:09.108Z",
"source": "maac",
"data": {"external_member_id": "U315df4d06394696a3c7cf71e4a0b51f3",
"channel_type": "line",
"customer_id": null,
"company": "Crescendo Lab"
}
}

contact.profile.member_level.update Webhook

An event when a contact's member_level is updated

Request Body schema: application/json

event required	string The event type
timestamp required	string The timestamp that event happened
source required	string Enum: "maac" "caac" The event source
required	object

Responses

Request samples

Payload

Content type

application/json

{"event": "contact.profile.member_level.update",
"timestamp": "2025-06-30T05:52:09.108Z",
"source": "maac",
"data": {"external_member_id": "U315df4d06394696a3c7cf71e4a0b51f3",
"channel_type": "line",
"customer_id": null,
"member_level": "VIP"
}
}

contact.profile.account_manager.update Webhook

An event when a contact's account_manager is updated

Request Body schema: application/json

event required	string The event type
timestamp required	string The timestamp that event happened
source required	string Enum: "maac" "caac" The event source
required	object

Responses

Request samples

Payload

Content type

application/json

{"event": "contact.profile.account_manager.update",
"timestamp": "2025-06-30T05:52:09.108Z",
"source": "maac",
"data": {"external_member_id": "U315df4d06394696a3c7cf71e4a0b51f3",
"channel_type": "line",
"customer_id": null,
"account_manager": "AM-007"
}
}

contact.tag.add Webhook

An event when a tag is attached to a contact. Even if the contact already has that tag, the event will still be triggered.

Request Body schema: application/json

event required	string the event type
timestamp required	string the timestamp that event happened
source required	string Enum: "maac" "caac" the event source
required	object

Responses

Request samples

Payload

Content type

application/json

{"event": "contact.tag.add",
"timestamp": "2023-09-20T12:00:16.850000+00:00",
"source": "maac",
"data": {"campaign_id": null,
"campaign_type": "contact360",
"campaign_name": null,
"customer_id": "C1234567",
"line_uid": "U8e654ca50c5b36a2411a9d1acefc3cd5",
"external_member_id": "U8e654ca50c5b36a2411a9d1acefc3cd5",
"channel_type": "line",
"tag_id": 14244,
"tag_name": "LINE test tag"
}
}

contact.tag.remove Webhook

An event when a tag is removed from a contact.

Request Body schema: application/json

event required	string the event type
timestamp required	string the timestamp that event happened
source required	string Enum: "maac" "caac" the event source
required	object

Responses

Request samples

Payload

Content type

application/json

{"event": "contact.tag.remove",
"timestamp": "2023-09-20T12:00:16.850000+00:00",
"source": "maac",
"data": {"customer_id": null,
"line_uid": "U8e654ca50c5b36a2411a9d1acefc3cd5",
"external_member_id": "U8e654ca50c5b36a2411a9d1acefc3cd5",
"channel_type": "line",
"tag_id": 14244,
"tag_name": "LINE test tag"
}
}

sms_plus.status.update Webhook

An event when a SMS+ message status is updated

Request Body schema: application/json

event required	string The event type
timestamp required	string <date-time> The timestamp that event happened
source required	string Value: "maac" The event source
required	object

Responses

Request samples

Payload

Content type

application/json

{"timestamp": "2021-11-30T17:51:26.018507+08:00",
"data": {"event_id": 123,
"sms_delivered_at": null,
"status": "sms_accepted",
"line_push_status": null,
"line_push_delivered_at": null,
"pnp_delivered_at": null,
"sms_status": "sms_accepted",
"pnp_setting_name": "testing name",
"pnp_message_id": 0,
"phone_number"": "+886123456789",
"line_push_template_id": null,
"line_push_error_category": null,
"pnp_status": null,
"sms_error_category": null,
"pnp_setting_id": 0
},
"event": "sms_plus.status.update",
"source": "maac"
}

coupon.sync Webhook

An event when a coupon record is created or updated.

Request Body schema: application/json

event required	string The event type
timestamp required	string <date-time> The timestamp that event happened (ISO 8601)
source required	string Enum: "maac" "caac" The event source
event_id required	string <uuid> Unique event identifier
required	object

Responses

Request samples

Payload

Content type

application/json

{"event": "coupon.sync",
"timestamp": "2026-01-15T08:00:00+00:00",
"source": "maac",
"event_id": "e4a6272e-af9f-4574-8ed0-23ba0d0e112f",
"data": {"id": "CPN_2025_SUMMER_10OFF",
"name": "2025 Summer Sale",
"url": "https://example.com/product-page?code=SUMMER25",
"code": "SUMMER10FREESHIP",
"is_redeemable": true,
"status": "active",
"discount_type": "percentage",
"discount_value": 10,
"source_platform_name": "Shopee",
"source_platform_customer_id": "189234567",
"source_store_type": "online_store",
"source_store_id": "EC-TW-001"
}
}

order.sync Webhook

An event when an order record is created or updated.

Request Body schema: application/json

event required	string The event type
timestamp required	string <date-time> The timestamp that event happened (ISO 8601)
source required	string Enum: "maac" "caac" The event source
event_id required	string <uuid> Unique event identifier
required	object

Responses

Request samples

Payload

Content type

application/json

{"event": "order.sync",
"timestamp": "2026-01-18T15:45:30+00:00",
"source": "maac",
"event_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"data": {"id": "ORD_20260115001",
"status": "created",
"total_amount": 1999,
"currency": "TWD",
"items": [{"id": "r1ac123",
"name": "Product 1",
"price": 200,
"count": 9,
"category": "Beauty > Skincare",
"variant": "50ml / Normal Skin"
}
],
"payment_method": "credit_card",
"delivery_method": "home_delivery",
"shipping_location": "Taipei City",
"source_platform_name": "Shopee",
"source_platform_customer_id": "189234567",
"source_store_type": "online_store",
"source_store_id": "EC-TW-001"
}
}

order_fulfillment.sync Webhook

An event when an order fulfillment record is created or updated.

Request Body schema: application/json

event required	string The event type
timestamp required	string <date-time> The timestamp that event happened (ISO 8601)
source required	string Enum: "maac" "caac" The event source
event_id required	string <uuid> Unique event identifier
required	object

Responses

Request samples

Payload

Content type

application/json

{"event": "order_fulfillment.sync",
"timestamp": "2026-01-18T15:45:30+00:00",
"source": "maac",
"event_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"data": {"order_id": "ORD_20260115001",
"fulfillment_status": "unfulfilled",
"shipping_location": "Xinyi pickup counter",
"shipping_status": "pending",
"estimated_delivery_date": "2026-01-20",
"pickup_store_id": "TW-STORE-099",
"source_platform_name": "Shopee",
"source_platform_customer_id": "189234567",
"source_store_type": "online_store",
"source_store_id": "EC-TW-001"
}
}

membership.sync Webhook

An event when a membership tier record is created or updated.

Request Body schema: application/json

event required	string The event type
timestamp required	string <date-time> The timestamp that event happened (ISO 8601)
source required	string Enum: "maac" "caac" The event source
event_id required	string <uuid> Unique event identifier
required	object

Responses

Request samples

Payload

Content type

application/json

{"event": "membership.sync",
"timestamp": "2026-01-20T10:15:00+00:00",
"source": "maac",
"event_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
"data": {"tier_id": "MBR01_Silver",
"tier_name": "Silver",
"tier_status": "active",
"tier_effective_from": "2025-12-01T00:00:00Z",
"tier_expiry_at": "2026-12-31T23:59:59Z",
"lifetime_spend_amount": 12850.75,
"currency": "TWD",
"source_platform_name": "Salesforce",
"source_platform_customer_id": "0035g00000ABCDEFAA",
"source_store_type": "online_store",
"source_store_id": "EC-TW-001"
}
}

point.sync Webhook

An event when a point/credit balance record is created or updated.

Request Body schema: application/json

event required	string The event type
timestamp required	string <date-time> The timestamp that event happened (ISO 8601)
source required	string Enum: "maac" "caac" The event source
event_id required	string <uuid> Unique event identifier
required	object

Responses

Request samples

Payload

Content type

application/json

{"event": "point.sync",
"timestamp": "2026-01-22T11:20:00+00:00",
"source": "maac",
"event_id": "d4e5f6a7-b8c9-0123-defa-234567890123",
"data": {"balance": 1200,
"type": "loyalty_point",
"currency": "TWD",
"expiry_at": "2026-03-31T23:59:59Z",
"source_platform_name": "Treasure Data",
"source_platform_customer_id": "td_global_id_9f3a2c7e8d1b4a6c",
"source_store_type": "online_store",
"source_store_id": "EC-TW-001"
}
}

reservation.sync Webhook

An event when a reservation/appointment record is created or updated.

Request Body schema: application/json

event required	string The event type
timestamp required	string <date-time> The timestamp that event happened (ISO 8601)
source required	string Enum: "maac" "caac" The event source
event_id required	string <uuid> Unique event identifier
required	object

Responses

Request samples

Payload

Content type

application/json

{"event": "reservation.sync",
"timestamp": "2026-02-10T09:30:00+00:00",
"source": "maac",
"event_id": "e4a6272e-af9f-4574-8ed0-23ba0d0e112f",
"data": {"id": "APT_20260215001",
"status": "scheduled",
"start_at": "2026-02-15T14:00:00Z",
"end_at": "2026-02-15T15:00:00Z",
"description": "1 hour consultation",
"service_type": "Facial Treatment",
"service_id": "SVC-HAIR-001",
"service_name": "Women's Haircut & Styling",
"address": "5th Floor, No. 156, Jiankang Rd., Songshan District, Taipei City",
"staff_id": "EMP-10234",
"staff_name": "Amy Chen",
"source_platform_name": "Inline",
"source_platform_customer_id": "DOIFUIFHJOSD8763ODS24",
"source_store_type": "offline_store",
"source_store_id": "TW-STORE-099"
}
}

Member

Update Member

Update profile fields for a specific channel-level contact.

This API follows the External Platform architecture, allowing channel-level profile updates including both predefined and custom fields.

Key Features:

Partial Update (PATCH semantics): Only fields provided in the request body are updated. Fields not included remain unchanged.
Field Clearing: To clear a field value, explicitly set it to null.
Custom Fields: Custom fields are nested within the data object under the custom_fields key.

Supported Channel Types:

line: LINE
fb: Facebook Messenger
ig: Instagram
whatsapp: WhatsApp
wccs: Web Communication Channel Server

Request Structure: The data object contains both predefined fields and custom fields. Custom fields are nested within the custom_fields key.

Profile Fields (in data):

Field	Description
`customer_id`	Client's CRM customer ID
`full_name`	Full name of the contact
`display_name`	Display name
`display_email`	Email address
`display_mobile`	Phone number in E.164 format
`gender`	Gender: male, female, unknown, other
`birthday`	Birth date (YYYY-MM-DD)
`region`	Region/country code
`city`	City name
`address`	Full address
`company`	Company name
`member_level`	Loyalty/membership level
`custom_fields`	Object containing custom fields (see below)

Custom Fields (in data.custom_fields): Custom fields are provided in the custom_fields object within data. Field keys must start with cl_custom_ prefix and types are defined per organization.

Field key format: cl_custom_{key} (e.g., cl_custom_total_purchase, cl_custom_membership_expiry)
Supported types:
- Text: string value (<= 255 characters)
- Number: numeric value (supports both integer and float types, range: ±2147483647, up to 15 significant digits)
- Date: ISO 8601 format date string (YYYY-MM-DD)
- DateTime: ISO 8601 format string with timezone (e.g., "2025-12-31T23:59:59Z")

Authorizations:

apikey

Request Body schema: application/json
required

channel_type required	string (ChannelType) Enum: "line" "fb" "ig" "whatsapp" "email" "wccs" "others" External channel type. Supported: line, fb, ig, whatsapp, wccs
external_channel_id required	string (External Channel Id) External channel identifier (e.g., LINE OA ID)
external_member_id required	string (External Member Id) External member identifier on the channel (e.g., LINE UID)
required	object (UpdateMemberData) Profile fields to update (partial update - only provided fields are updated)

Responses

Request samples

Payload

Content type

application/json

{"channel_type": "line",
"external_channel_id": "string",
"external_member_id": "string",
"data": {"customer_id": "string",
"full_name": "string",
"display_name": "string",
"display_email": "user@example.com",
"display_mobile": "string",
"gender": "male",
"birthday": "2019-08-24",
"region": "kh",
"city": "string",
"address": "string",
"company": "string",
"member_level": "string",
"custom_fields": {"cl_custom_date_field": "2025-12-31",
"cl_custom_datetime_field": "2025-12-31T23:59:59+08:00",
"cl_custom_number_field": 15000,
"cl_custom_text_field": "台北101店"
}
}
}

Response samples

200
404
422

Content type

application/json

{"updated_fields": ["customer_id",
"full_name",
"cl_custom_total_purchase"
]
}

Import Member

The API allows users to import and integrate their data across multiple platforms. This functionality is designed to enrich the CAAC/MAAC contact datasets by incorporating external data sources, thus offering a unified view of contact information.

Key Features:

Concurrency Control: Up to 10 import operations can be executed concurrently per organization to ensure system stability.
Data Overwrite: For contacts that are successfully matched, the imported data will overwrite existing CAAC/MAAC contact profile.
- Fields not provided in the import data remain unchanged.
- Fields explicitly set to null will be cleared in the contact profile.
Task-Based Processing: Import operations are processed asynchronously using a task queue system.
Timeout Protection: Import tasks automatically fail after 3 hours if not completed.

Import Key: The system uses the import key to:

Match imported records with existing contacts in the system
Only update contacts that have a matching import key value
Skip records that don't match any existing contacts

Upon a successful request, the system will return a task object with task_id, which can be used to track the status of the import execution via GET /task/{task_id}.

Task Status Values:

pending: Task is queued and waiting to be processed
processing: Task is currently being executed
success: Task completed successfully
failed: Task failed (system error details are not exposed to clients for security reasons)

Error Handling:

Task Conflict (409): If the maximum concurrent import tasks (10) is reached, the API returns a 409 Conflict error.
Timeout: Tasks that exceed 3 hours are automatically marked as failed.
Validation Errors: Invalid data may cause individual rows to be skipped (error count is tracked).

Authorizations:

apikey

Request Body schema: application/json
required

import_key required	string (UnifyKeyAttributeImportKey) Enum: "line_uid" "display_email" "display_mobile" "connect_id" "customer_id" The external official name of the fields. Importing the import_key to identify the attribute.
required	Array of objects (Data) [ 1 .. 10000 ] items

Responses

Request samples

Payload

Content type

application/json

{"import_key": "line_uid",
"data": [{"line_uid": "string",
"customer_id": "string",
"connect_id": "string",
"full_name": "string",
"display_name": "string",
"display_email": "user@example.com",
"display_mobile": "string",
"gender": "male",
"birthday": "2019-08-24",
"region": "kh",
"city": "string",
"address": "string",
"company": "string",
"member_level": "string"
}
]
}

Response samples

200
409
422

Content type

application/json

{"id": 0,
"category": "import_member",
"status": "pending",
"result": { },
"updated_at": "2024-06-25T07:56:39.815Z",
"created_at": "2024-06-25T07:56:39.815Z"
}

Export Member

This API enables users to export member profiles from the CDH system, facilitating synchronization with external systems.

Key Features:

Concurrency Control: Only one export operation is permitted at a time to maintain system stability.
Temporary Storage: Exported data is stored temporarily and available for download for 7 days.
Latency: Data provided through this API is not real-time and may have a maximum latency of up to 24 hours. Consider this delay for time-sensitive applications.

Format: Data is exported in CSV format.

Field	Description
`source`	Show the member belongs to MAAC or CAAC
`member_id`	Unique identifier in MAAC or CAAC
`line_uid`	Unique identifier for the contact in LINE.
`channel_type`	External Channel Type.
`external_member_id`	External Channel Member ID.
`customer_id`	The client's CRM customer ID.
`connect_id`	A manual input used as a unified key to specify which channel entities are the same contact.
`full_name`	The full name of the contact.
`display_name`	Display name of the contact.
`display_email`	Display email of the contact.
`display_mobile`	Display mobile number of the contact.
`gender`	Gender of the contact.
`birthday`	Birth date of the contact.
`region`	Region or country of the contact.
`city`	City of the contact.
`address`	Address of the contact.
`company`	Company associated with the contact.
`member_level`	Indicates the loyalty level of the customer.
`account_manager`	The account manager responsible for the contact

How to Use:

Initiate Export: Send a request to initiate the export. On success, you will receive a task_id.
Track Status: Use the task_id to monitor the progress of the export.
Download Data: Once the export is complete, you will receive a download link to access the CSV file.

Authorizations:

apikey

Responses

Response samples

200

Content type

application/json

{"id": 0,
"category": "export_member",
"status": "pending",
"result": { },
"updated_at": "2024-06-25T07:56:39.815Z",
"created_at": "2024-06-25T07:56:39.815Z"
}

Task

Get Task

Authorizations:

apikey

path Parameters

task_id

required

integer (Task Id)

Responses

Response samples

200
422

Content type

application/json

Example

import_member

{"id": 423,
"category": "import_member",
"status": "done",
"result": {"updated_contact_size": 1
},
"updated_at": "2024-06-12T03:16:16.589363+00:00",
"created_at": "2024-06-12T03:14:59.798680+00:00"
}

Engagement

Submit Event

The submit_event API is designed to handle various user interactions and behaviors on a platform, capturing relevant event data for analysis and reporting. This API allows the client to send event data in a structured format, ensuring that user actions are recorded consistently. It supports multiple event types, including page views, product interactions, and checkout processes. Here is the updated documentation for the create_event API without the description field in the behavior table:

Scenario

Behavior	Scenario
`page_view`	A user navigates to a specific page on your website or app. The event records the page path and title, helping understand page popularity and user navigation patterns.
`view_item`	A user views details of a specific product. This event logs product ID, name, price, and quantity, useful for analyzing product interest and user engagement with specific items.
`add_to_cart`	A user adds a product to their shopping cart. This event captures the product details and currency, helping track items of interest and potential purchases.
`remove_from_cart`	A user removes a product from their shopping cart. This event logs the removed product details, helping understand user preferences and friction points in the purchasing process.
`begin_checkout`	A user initiates the checkout process. This event records the products in the cart at the start of the checkout, useful for analyzing drop-offs and checkout behavior.
`purchase`	A user completes a purchase. This event captures transaction ID, revenue, tax, shipping, and the list of purchased products, helping track successful sales and revenue generation.
`user_engagement`	A user spends time on a page. The event records engagement duration in milliseconds and optionally references the original page_view event via page_view_id.

Notes:

Each behavior type is accompanied by a scenario outlining typical use cases.
The params field in each example contains specific details relevant to the event type, such as product information or page details.
The example and the schema of the params field show the required field of the each behavior type. However, we allow additional fields in the params field for flexibility.

Authorizations:

apikey

Request Body schema: application/json
required

required	EngagementBehavior (string) or Behavior (string) (Behavior) [ 1 .. 256 ] characters
utm_campaign	string or null (Utm Campaign) [ 1 .. 256 ] characters
utm_source	string or null (Utm Source) [ 1 .. 256 ] characters
utm_medium	string or null (Utm Medium) [ 1 .. 256 ] characters
utm_content	string or null (Utm Content) [ 1 .. 256 ] characters
utm_term required	string (Utm Term) ^(lm:\d+\|[\w-]+:\d+:\d+:\d:\d:\d+)$
language	string or null (Language)
geography	string or null (Geography)
required	Params (object) or PageParam (object) or ItemsParam (object) or TransactionParam (object) or UserEngagementParam (object) (Params)

Responses

Request samples

Payload

Content type

application/json

Example

page_view

{"behavior": "page_view",
"utm_source": "google",
"utm_medium": "cpc",
"utm_campaign": "summer_sale",
"utm_content": "new_arrivals",
"utm_term": "lm:1",
"language": "zh-TW",
"geography": "TW",
"params": {"page_path": "/tw/channels/acquire",
"page_title": "/tw/channels/acquire",
"page_view_id": "550e8400-e29b-41d4-a716-446655440000"
}
}

Response samples

200
422

Content type

application/json

{"event_id": "7f9b3c47-d198-49b7-8e8f-1ae6f2bcb6dc"
}

Submit coupon

Authorizations:

apikey

Request Body schema: application/json
required

timestamp required	string <date-time> (Timestamp) ISO 8601 format with timezone.
source_platform_name required	string (Source Platform Name) [ 1 .. 64 ] characters
source_store_type required	string (StoreType) Enum: "online_store" "offline_store"
source_store_id required	string (Source Store Id) [ 1 .. 64 ] characters
source_platform_customer_id required	string (Source Platform Customer Id) [ 1 .. 128 ] characters
source_store_name	string or null (Source Store Name) <= 255 characters
channel_type	string or null (ChannelType) Enum: "line" "fb" "ig" "whatsapp" "email" "wccs" "others" Internal channel type as stored in the `channel.type` column. Internal code paths (engagement_history, profile lookups, member endpoints v1) consume these values directly. The v2 external API exposes a renamed view via `ChannelTypeApi`.
external_channel_id	string or null (External Channel Id) <= 128 characters
external_member_id	string or null (External Member Id) <= 128 characters
id required	string (Id) [ 1 .. 64 ] characters
name required	string (Name) [ 1 .. 255 ] characters
url required	string <uri> (Url) [ 1 .. 2083 ] characters
code required	string (Code) [ 1 .. 64 ] characters
is_redeemable required	boolean (Is Redeemable)
status required	string (CouponStatus) Enum: "active" "scheduled" "redeemed" "expired" "inactive" "revoked" "unknown"
description	string or null (Description) <= 2000 characters
source_status	string or null (Source Status) <= 255 characters Original status value from the source platform (e.g., the merchant's own e-commerce system)
valid_from	string or null <date-time> (Valid From) ISO 8601 format with timezone.
valid_to	string or null <date-time> (Valid To) ISO 8601 format with timezone.
applicable_store_ids	Array of strings or null (Applicable Store Ids) <= 100 items [ items <= 64 characters ]
applicable_item_ids	Array of strings or null (Applicable Item Ids) <= 500 items [ items <= 64 characters ]
applicable_item_category_ids	Array of strings or null (Applicable Item Category Ids) <= 200 items [ items <= 64 characters ]
discount_type required	string (DiscountType) Enum: "percentage" "fixed_amount" "free_shipping"
source_discount_type	string or null (Source Discount Type) <= 255 characters Original discount type value from the source platform (e.g., the merchant's own e-commerce system)
discount_value required	number (Discount Value)

Responses

Request samples

Payload

Content type

application/json

{"timestamp": "2024-01-15T08:30:00+08:00",
"source_platform_name": "string",
"source_store_type": "online_store",
"source_store_id": "string",
"source_platform_customer_id": "string",
"source_store_name": "string",
"channel_type": "line",
"external_channel_id": "string",
"external_member_id": "string",
"id": "string",
"name": "string",
"url": "http://example.com",
"code": "string",
"is_redeemable": true,
"status": "active",
"description": "string",
"source_status": "string",
"valid_from": "2019-08-24T14:15:22Z",
"valid_to": "2019-08-24T14:15:22Z",
"applicable_store_ids": ["string"
],
"applicable_item_ids": ["string"
],
"applicable_item_category_ids": ["string"
],
"discount_type": "percentage",
"source_discount_type": "string",
"discount_value": 0
}

Response samples

200
422

Content type

application/json

{"event_id": "a7a26ff2-e851-45b6-9634-d595f45458b7"
}

Submit order

Authorizations:

apikey

Request Body schema: application/json
required

timestamp required	string <date-time> (Timestamp) ISO 8601 format with timezone.
source_platform_name required	string (Source Platform Name) [ 1 .. 64 ] characters
source_store_type required	string (StoreType) Enum: "online_store" "offline_store"
source_store_id required	string (Source Store Id) [ 1 .. 64 ] characters
source_platform_customer_id required	string (Source Platform Customer Id) [ 1 .. 128 ] characters
source_store_name	string or null (Source Store Name) <= 255 characters
channel_type	string or null (ChannelType) Enum: "line" "fb" "ig" "whatsapp" "email" "wccs" "others" Internal channel type as stored in the `channel.type` column. Internal code paths (engagement_history, profile lookups, member endpoints v1) consume these values directly. The v2 external API exposes a renamed view via `ChannelTypeApi`.
external_channel_id	string or null (External Channel Id) <= 128 characters
external_member_id	string or null (External Member Id) <= 128 characters
id required	string (Id) [ 1 .. 64 ] characters
status required	string (OrderStatus) Enum: "created" "confirmed" "processing" "completed" "cancelled" "returned" "unknown"
total_amount required	number (Total Amount) Total amount payable after all calculations
currency required	string (Currency) = 3 characters
required	Array of objects (Items) [ 1 .. 200 ] items
payment_method required	string (Payment Method) [ 1 .. 255 ] characters
delivery_method required	string (Delivery Method) [ 1 .. 255 ] characters
shipping_location required	string (Shipping Location) [ 1 .. 255 ] characters
source_status	string or null (Source Status) <= 255 characters Original status value from the source platform (e.g., the merchant's own e-commerce system)
description	string or null (Description) <= 2000 characters
store_description	string or null (Store Description) <= 1000 characters
shipping_address	string or null (Shipping Address) <= 500 characters
subtotal_amount	number or null (Subtotal Amount) Sum of all item prices × quantities. Includes item prices; excludes discounts, shipping, and tax
total_discount	number or null (Total Discount) Total order discount (coupons, promotions, manual discounts). Excludes shipping and tax
shipping_amount	number or null (Shipping Amount) Shipping fee only
tax_amount	number or null (Tax Amount) Total tax amount only
paid_amount	number or null (Paid Amount) Actual amount paid
coupon_id	string or null (Coupon Id) <= 64 characters
promotion_name	string or null (Promotion Name) <= 255 characters
promotion_id	string or null (Promotion Id) <= 64 characters
payment_transaction_id	string or null (Payment Transaction Id) <= 128 characters
payment_provider	string or null (Payment Provider) <= 64 characters
pickup_store_id	string or null (Pickup Store Id) <= 64 characters
pickup_store_name	string or null (Pickup Store Name) <= 255 characters

Responses

Request samples

Payload

Content type

application/json

{"timestamp": "2024-01-15T08:30:00+08:00",
"source_platform_name": "string",
"source_store_type": "online_store",
"source_store_id": "string",
"source_platform_customer_id": "string",
"source_store_name": "string",
"channel_type": "line",
"external_channel_id": "string",
"external_member_id": "string",
"id": "string",
"status": "created",
"total_amount": 0,
"currency": "str",
"items": [{"id": "string",
"name": "string",
"price": 0,
"count": 0,
"category": "string",
"variant": "string",
"discount": 0,
"coupon_id": "string"
}
],
"payment_method": "string",
"delivery_method": "string",
"shipping_location": "string",
"source_status": "string",
"description": "string",
"store_description": "string",
"shipping_address": "string",
"subtotal_amount": 0,
"total_discount": 0,
"shipping_amount": 0,
"tax_amount": 0,
"paid_amount": 0,
"coupon_id": "string",
"promotion_name": "string",
"promotion_id": "string",
"payment_transaction_id": "string",
"payment_provider": "string",
"pickup_store_id": "string",
"pickup_store_name": "string"
}

Response samples

200
422

Content type

application/json

{"event_id": "a7a26ff2-e851-45b6-9634-d595f45458b7"
}

Submit order fulfillment

Authorizations:

apikey

Request Body schema: application/json
required

timestamp required	string <date-time> (Timestamp) ISO 8601 format with timezone.
source_platform_name required	string (Source Platform Name) [ 1 .. 64 ] characters
source_store_type required	string (StoreType) Enum: "online_store" "offline_store"
source_store_id required	string (Source Store Id) [ 1 .. 64 ] characters
source_platform_customer_id required	string (Source Platform Customer Id) [ 1 .. 128 ] characters
source_store_name	string or null (Source Store Name) <= 255 characters
channel_type	string or null (ChannelType) Enum: "line" "fb" "ig" "whatsapp" "email" "wccs" "others" Internal channel type as stored in the `channel.type` column. Internal code paths (engagement_history, profile lookups, member endpoints v1) consume these values directly. The v2 external API exposes a renamed view via `ChannelTypeApi`.
external_channel_id	string or null (External Channel Id) <= 128 characters
external_member_id	string or null (External Member Id) <= 128 characters
order_id required	string (Order Id) [ 1 .. 64 ] characters
fulfillment_status required	string (FulfillmentStatus) Enum: "unfulfilled" "partially_fulfilled" "fulfilled" "cancelled" "returned" "unknown"
shipping_location required	string (Shipping Location) [ 1 .. 255 ] characters
shipping_status required	string (ShippingStatus) Enum: "pending" "label_created" "in_transit" "out_for_delivery" "delivered" "delivery_failed" "exception" "returned_to_sender" "unknown"
fulfillment_source_status	string or null (Fulfillment Source Status) <= 255 characters Original fulfillment status value from the source platform
shipping_source_status	string or null (Shipping Source Status) <= 255 characters Original shipping status value from the source platform
delivery_method	string or null (Delivery Method) <= 255 characters
shipping_address	string or null (Shipping Address) <= 500 characters
shipping_carrier	string or null (Shipping Carrier) <= 128 characters
shipping_tracking_id	string or null (Shipping Tracking Id) <= 128 characters
shipping_tracking_url	string or null <uri> (Shipping Tracking Url) [ 1 .. 2083 ] characters
estimated_delivery_date	string or null <date> (Estimated Delivery Date) ISO-8601 date (YYYY-MM-DD).
pickup_store_id	string or null (Pickup Store Id) <= 64 characters
pickup_store_name	string or null (Pickup Store Name) <= 255 characters
shipped_at	string or null <date-time> (Shipped At) ISO 8601 format with timezone.
delivered_at	string or null <date-time> (Delivered At) ISO 8601 format with timezone.

Responses

Request samples

Payload

Content type

application/json

{"timestamp": "2024-01-15T08:30:00+08:00",
"source_platform_name": "string",
"source_store_type": "online_store",
"source_store_id": "string",
"source_platform_customer_id": "string",
"source_store_name": "string",
"channel_type": "line",
"external_channel_id": "string",
"external_member_id": "string",
"order_id": "string",
"fulfillment_status": "unfulfilled",
"shipping_location": "string",
"shipping_status": "pending",
"fulfillment_source_status": "string",
"shipping_source_status": "string",
"delivery_method": "string",
"shipping_address": "string",
"shipping_carrier": "string",
"shipping_tracking_id": "string",
"shipping_tracking_url": "http://example.com",
"estimated_delivery_date": "2019-08-24",
"pickup_store_id": "string",
"pickup_store_name": "string",
"shipped_at": "2019-08-24T14:15:22Z",
"delivered_at": "2019-08-24T14:15:22Z"
}

Response samples

200
422

Content type

application/json

{"event_id": "a7a26ff2-e851-45b6-9634-d595f45458b7"
}

Submit membership

Authorizations:

apikey

Request Body schema: application/json
required

timestamp required	string <date-time> (Timestamp) ISO 8601 format with timezone.
source_platform_name required	string (Source Platform Name) [ 1 .. 64 ] characters
source_store_type required	string (StoreType) Enum: "online_store" "offline_store"
source_store_id required	string (Source Store Id) [ 1 .. 64 ] characters
source_platform_customer_id required	string (Source Platform Customer Id) [ 1 .. 128 ] characters
source_store_name	string or null (Source Store Name) <= 255 characters
channel_type	string or null (ChannelType) Enum: "line" "fb" "ig" "whatsapp" "email" "wccs" "others" Internal channel type as stored in the `channel.type` column. Internal code paths (engagement_history, profile lookups, member endpoints v1) consume these values directly. The v2 external API exposes a renamed view via `ChannelTypeApi`.
external_channel_id	string or null (External Channel Id) <= 128 characters
external_member_id	string or null (External Member Id) <= 128 characters
tier_id required	string (Tier Id) [ 1 .. 64 ] characters
tier_name required	string (Tier Name) [ 1 .. 255 ] characters
tier_status required	string (MembershipTierStatus) Enum: "active" "grace_period" "expired" "suspended" "cancelled" "pending" "unknown"
tier_description	string or null (Tier Description) <= 2000 characters
tier_source_status	string or null (Tier Source Status) <= 255 characters Original tier status value from the source platform
tier_effective_from	string or null <date-time> (Tier Effective From) ISO 8601 format with timezone.
tier_expiry_at	string or null <date-time> (Tier Expiry At) ISO 8601 format with timezone.
currency	string or null (Currency) = 3 characters ISO 4217 currency code for spend amounts
lifetime_spend_amount	number or null (Lifetime Spend Amount)
lifetime_spend_updated_at	string or null <date-time> (Lifetime Spend Updated At) ISO 8601 format with timezone.
tier_spend_amount	number or null (Tier Spend Amount)

Responses

Request samples

Payload

Content type

application/json

{"timestamp": "2024-01-15T08:30:00+08:00",
"source_platform_name": "string",
"source_store_type": "online_store",
"source_store_id": "string",
"source_platform_customer_id": "string",
"source_store_name": "string",
"channel_type": "line",
"external_channel_id": "string",
"external_member_id": "string",
"tier_id": "string",
"tier_name": "string",
"tier_status": "active",
"tier_description": "string",
"tier_source_status": "string",
"tier_effective_from": "2019-08-24T14:15:22Z",
"tier_expiry_at": "2019-08-24T14:15:22Z",
"currency": "str",
"lifetime_spend_amount": 0,
"lifetime_spend_updated_at": "2019-08-24T14:15:22Z",
"tier_spend_amount": 0
}

Response samples

200
422

Content type

application/json

{"event_id": "a7a26ff2-e851-45b6-9634-d595f45458b7"
}

Submit point

Authorizations:

apikey

Request Body schema: application/json
required

timestamp required	string <date-time> (Timestamp) ISO 8601 format with timezone.
source_platform_name required	string (Source Platform Name) [ 1 .. 64 ] characters
source_store_type required	string (StoreType) Enum: "online_store" "offline_store"
source_store_id required	string (Source Store Id) [ 1 .. 64 ] characters
source_platform_customer_id required	string (Source Platform Customer Id) [ 1 .. 128 ] characters
source_store_name	string or null (Source Store Name) <= 255 characters
channel_type	string or null (ChannelType) Enum: "line" "fb" "ig" "whatsapp" "email" "wccs" "others" Internal channel type as stored in the `channel.type` column. Internal code paths (engagement_history, profile lookups, member endpoints v1) consume these values directly. The v2 external API exposes a renamed view via `ChannelTypeApi`.
external_channel_id	string or null (External Channel Id) <= 128 characters
external_member_id	string or null (External Member Id) <= 128 characters
balance required	number (Balance)
type required	string (PointType) Enum: "loyalty_point" "store_credit"
currency	string or null (Currency) = 3 characters
expiry_at	string or null <date-time> (Expiry At) ISO 8601 format with timezone.

Responses

Request samples

Payload

Content type

application/json

{"timestamp": "2024-01-15T08:30:00+08:00",
"source_platform_name": "string",
"source_store_type": "online_store",
"source_store_id": "string",
"source_platform_customer_id": "string",
"source_store_name": "string",
"channel_type": "line",
"external_channel_id": "string",
"external_member_id": "string",
"balance": 0,
"type": "loyalty_point",
"currency": "str",
"expiry_at": "2019-08-24T14:15:22Z"
}

Response samples

200
422

Content type

application/json

{"event_id": "a7a26ff2-e851-45b6-9634-d595f45458b7"
}

Submit reservation

Authorizations:

apikey

Request Body schema: application/json
required

timestamp required	string <date-time> (Timestamp) ISO 8601 format with timezone.
source_platform_name required	string (Source Platform Name) [ 1 .. 64 ] characters
source_store_type required	string (StoreType) Enum: "online_store" "offline_store"
source_store_id required	string (Source Store Id) [ 1 .. 64 ] characters
source_platform_customer_id required	string (Source Platform Customer Id) [ 1 .. 128 ] characters
source_store_name	string or null (Source Store Name) <= 255 characters
channel_type	string or null (ChannelType) Enum: "line" "fb" "ig" "whatsapp" "email" "wccs" "others" Internal channel type as stored in the `channel.type` column. Internal code paths (engagement_history, profile lookups, member endpoints v1) consume these values directly. The v2 external API exposes a renamed view via `ChannelTypeApi`.
external_channel_id	string or null (External Channel Id) <= 128 characters
external_member_id	string or null (External Member Id) <= 128 characters
id required	string (Id) [ 1 .. 64 ] characters
status required	string (ReservationStatus) Enum: "scheduled" "confirmed" "checked_in" "completed" "cancelled" "no_show" "rescheduled" "unknown"
start_at required	string <date-time> (Start At) ISO 8601 format with timezone.
end_at required	string <date-time> (End At) ISO 8601 format with timezone.
description required	string (Description) [ 1 .. 2000 ] characters
service_type required	string (Service Type) [ 1 .. 128 ] characters
service_id required	string (Service Id) [ 1 .. 64 ] characters
service_name required	string (Service Name) [ 1 .. 255 ] characters
source_status	string or null (Source Status) <= 255 characters Original status value from the source platform
address	string or null (Address) <= 500 characters
staff_id	string or null (Staff Id) <= 64 characters
staff_name	string or null (Staff Name) <= 255 characters

Responses

Request samples

Payload

Content type

application/json

{"timestamp": "2024-01-15T08:30:00+08:00",
"source_platform_name": "string",
"source_store_type": "online_store",
"source_store_id": "string",
"source_platform_customer_id": "string",
"source_store_name": "string",
"channel_type": "line",
"external_channel_id": "string",
"external_member_id": "string",
"id": "string",
"status": "scheduled",
"start_at": "2019-08-24T14:15:22Z",
"end_at": "2019-08-24T14:15:22Z",
"description": "string",
"service_type": "string",
"service_id": "string",
"service_name": "string",
"source_status": "string",
"address": "string",
"staff_id": "string",
"staff_name": "string"
}

Response samples

200
422

Content type

application/json

{"event_id": "a7a26ff2-e851-45b6-9634-d595f45458b7"
}

Broadcast

Get Broadcast Report By Broadcast Id

The API allows users to retrieve broadcast reports for a specific broadcast ID. This functionality is designed to provide insights into the performance of a broadcast campaign, the input date range is limited to 60 days. the input date range is limited to 60 days.

The response will include the following fields:

name: The name of the broadcast.
source: The source of the broadcast.
sent_date: The date the broadcast was sent.
segment_name: The segment name of the broadcast.
sent: The number of messages sent.
open_count: The number of unrepeated opens.
clicks: The number of repeated clicks.
urls: The list of URLs used in the broadcast.

Authorizations:

apikey

path Parameters

broadcast_id

required

integer (Broadcast Id)

query Parameters

start_date required	string <date> (Start Date) Start date in YYYY-MM-DD format
end_date required	string <date> (End Date) End date in YYYY-MM-DD format

Responses

Response samples

200
422

Content type

application/json

{"name": "Test Broadcast",
"source": "maac",
"sent_date": "2024-06-25T07:56:39.815Z",
"segment_name": "Test Segment",
"sent": 0,
"open_count": 0,
"clicks": 0,
"urls": ["https://www.cresclab.com"
]
}

Get Broadcasts List

The API allows users to retrieve a list of broadcasts of user's org.

Authorizations:

apikey

Responses

Response samples

200

Content type

application/json

[{"id": 1,
"source": "maac",
"name": "Test Broadcast",
"sent_date": "2024-06-25T07:56:39.815Z",
"status": "sent",
"created_at": "2024-06-25T07:56:39.815Z"
}
]

Rich menu

Get Richmenus List

The API allows users to retrieve a list of richmenu for user's org.

The response will include the following fields:
- id: The ID of the richmenu.
- name: The name of the richmenu.
- status: The status of the richmenu, including SCHEDULED, ACTIVATE, FINISHED, DRAFT, ERROR, and PAUSE.
- actions: A list of actions associated with the richmenu.
    - idx: The index of the action (1-based).
    - tags: A list of tags associated with the action.
    - type: The type of action, which can be uri, message, or postback.
        - uri:
            - uri: The URI for the action.
        - message:
            - text: The message text for the action.
        - postback:
            - displayText: The text displayed for the postback action.
            - category: The category of the postback action, currently only support category=richmenu in API.
            - postback_action: The action to be performed on postback, should be link_richmenu for richmenu.
            - postback_action_id: The ID of the postback action, if category is richmenu, it should be linked richmenu_id.

Authorizations:

apikey

Responses

Response samples

200

Content type

application/json

[{"id": 1,
"name": "Test Richmenu",
"actions": [{"type": "uri",
"idx": 0,
"tags": ["tag1",
"tag2"
],
"uri": "https://example.com"
},
{"type": "message",
"idx": 1,
"tags": [ ],
"text": "Hello"
},
{"type": "postback",
"idx": 2,
"tags": ["tag3"
],
"displayText": "Postback",
"category": "richmenu",
"postback_action": "link_richmenu",
"postback_action_id": "link_richmenu_id"
}
]
}
]

Get Richmenu Report By Id And Date Range

The API allows users to retrieve richmenu reports for a specific richmenu ID. This functionality is designed to provide insights into the performance of a richmenu campaign, the input date range is limited to 60 days.

The response will include the following fields:
- id: The ID of the richmenu.
- name: The name of the richmenu.
- status: The status of the richmenu, including SCHEDULED, ACTIVATE, FINISHED, DRAFT, ERROR, and PAUSE.
- actions: A list of actions associated with the richmenu.
    - idx: The index of the action (1-based).
    - tags: A list of tags associated with the action.
    - type: The type of action, which can be uri, message, or postback.
        - uri:
            - uri: The URI for the action.
        - message:
            - text: The message text for the action.
        - postback:
            - displayText: The text displayed for the postback action.
            - category: The category of the postback action, currently only support category=richmenu in API.
            - postback_action: The action to be performed on postback, should be link_richmenu for richmenu.
            - postback_action_id: The ID of the postback action, if category is richmenu, it should be linked richmenu_id.
- clicks: The number of clicks on the richmenu.
- orders: The number of orders associated with the richmenu.
- revenue: The revenue generated from the richmenu.

Authorizations:

apikey

path Parameters

richmenu_id

required

integer (Richmenu Id)

query Parameters

start_date required	string <date> (Start Date) Start date in YYYY-MM-DD format
end_date required	string <date> (End Date) End date in YYYY-MM-DD format

Responses

Response samples

200
422

Content type

application/json

{"id": 1,
"name": "Test Richmenu",
"status": "ACTIVATE",
"actions": [{"type": "uri",
"idx": 1,
"tags": ["tag1",
"tag2"
],
"uri": "https://example.com"
},
{"type": "message",
"idx": 2,
"tags": [ ],
"text": "Hello"
},
{"type": "postback",
"idx": 3,
"tags": ["tag3"
],
"displayText": "Postback",
"category": "richmenu",
"postback_action": "link_richmenu",
"postback_action_id": "link_richmenu_id"
}
],
"clicks": 100,
"orders": 10,
"revenue": 1000
}

CustomField

List Custom Fields

List custom fields for the given organization.

Authorizations:

apikey

query Parameters

active

boolean or null (Active)

Filter by active status. true for active only, false for archived only, null for all.

Responses

Response samples

200
422

Content type

application/json

[{"id": 0,
"name": "string",
"key": "string",
"type": "text",
"description": "string",
"slot_number": 0,
"active": true
}
]