API integration

API reference · Standard connectors

Specs for the standard connectors Cliptalk provides by industry. Load a standard connector, connect it, then customize operations, paths, and parameters for your own service.

#What a standard connector is

An API spec that already defines the operations an AI bot uses often in that industry: identity check, lookups, and cancel or change. The base URL is filled from your domain on the project, in the form https://www.mydomain.com/api/shop or https://www.mydomain.com/api/fitness.

1
Register your domain
When you create a project, enter your domain (example: www.mydomain.com). You can change it later on the project’s General tab.
2
Load a standard connector
Project → AI bot → Create API spec → Get started, and pick the standard connector for your industry. The base URL is filled from your domain.
3
Implement or map your API
If you build these paths and responses on your server, it works as written. If you already have an API, map the spec to that API in the next step.
4
Customize
Turn off or delete operations you do not need, add new ones, and change paths, parameter names, descriptions, and auth to match your API. Descriptions are how the AI picks a tool, so rewrite them in your service’s own words.
5
Secrets, test, and connect
On the Secrets tab, save the API key. Try a call on the API test tab, then click Save and connect to the AI bot.

To see the flow before you build an API, connect a sample connector in the AI bot settings. Sample connectors call Cliptalk’s demo API with the same spec, so you can try the flow in the widget first.

# Shop
https://www.mydomain.com/api/shop

# Package forwarding and proxy buying
https://www.mydomain.com/api/forwarding

# Travel agency
https://www.mydomain.com/api/travel

# Clinic and salon booking
https://www.mydomain.com/api/clinic

# Subscription (SaaS)
https://www.mydomain.com/api/subscription

# Education and academy
https://www.mydomain.com/api/academy

# Hotel and guesthouse
https://www.mydomain.com/api/stay

# Gym and pilates
https://www.mydomain.com/api/fitness

#Common rules

Field	Description
`Auth`	The default is `Authorization: Bearer` plus the key. In the studio basics you can switch to an API key header, Basic, or a query parameter.
`Format`	Requests and responses are JSON. A success response returns ok: true together with the data.
`Errors`	A status that is not 2xx, and `{ "ok": false, "error", "message" }`. The AI uses message to explain the situation to the customer.
`Identity check`	When `POST /verify` returns `customer.id`, Cliptalk fills `{customer_id}` on later paths. The customer cannot supply someone else’s ID.
`Actions`	Operations that change data, such as cancel or change, are called first with `dry_run: true` for a preview (a `summary` array of strings). If the customer agrees, they are called again without `dry_run`.
`Ownership check`	On any API that handles customer data, also check on your server that the record belongs to that customer_id.

{
  "ok": true,
  "customer": { "id": "cus_1001", "name": "Alex Kim" }
}

#Shop standard connector

Identity check with an order number → order list and detail → shipping lookup → cancel an order before it ships, plus product search for stock and price. The base URL is https://www.mydomain.com/api/shop.

Operation	Request	Description · main parameters
`verify_customer`	POST `/verify`	Identity check `order_no, phone_last4`
`list_orders`	GET `/customers/{customer_id}/orders`	Order list `status`
`get_order`	GET `/customers/{customer_id}/orders/{order_no}`	Order detail and shipping `order_no*`
`cancel_order`	POST `/customers/{customer_id}/orders/{order_no}/cancel`	Cancel order (preview, then confirm) `order_no*, reason`
`search_products`	GET `/products`	Product search `q*`

curl -X POST https://www.mydomain.com/api/shop/verify \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"order_no":"DM-10001","phone_last4":"1234"}'

#Shop · Identity check

POST/verify

Confirms the customer with an order number and the last 4 digits of the phone. customer.id in the response is used as {customer_id} in later operations.

Body	Type	Description
`order_no *`	string	Order number
`phone_last4 *`	string	Last 4 digits of the phone

curl -X POST https://www.mydomain.com/api/shop/verify \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"order_no":"DM-10001","phone_last4":"1234"}'

#Shop · Order list

GET/customers/{customer_id}/orders

The customer’s orders.

Parameter	In	Description
`customer_id *`	path	Customer ID from the identity check
`status`	query	paid \| preparing \| shipped \| delivered \| cancelled

curl https://www.mydomain.com/api/shop/customers/cus_1001/orders \
  -H 'Authorization: Bearer YOUR_API_KEY'

#Shop · Order detail

GET/customers/{customer_id}/orders/{order_no}

One order: items, amount, and shipping (carrier, tracking number, tracking link).

curl https://www.mydomain.com/api/shop/customers/cus_1001/orders/DM-10001 \
  -H 'Authorization: Bearer YOUR_API_KEY'

#Shop · Cancel an order

POST/customers/{customer_id}/orders/{order_no}/cancel

Only paid or preparing orders can be cancelled. dry_run: true returns a refund preview and does not cancel.

Body	Type	Description
`dry_run`	boolean	Preview only
`reason`	string	Cancellation reason

curl -X POST https://www.mydomain.com/api/shop/customers/cus_1001/orders/DM-10002/cancel \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"dry_run":true}'

#Shop · Product search

GET/products

Parameter	In	Description
`q *`	query	Product name or SKU

curl 'https://www.mydomain.com/api/shop/products?q=tumbler' \
  -H 'Authorization: Bearer YOUR_API_KEY'

#Package forwarding and proxy buying standard connector

Identity check with a mailbox number → application list and detail (tracking) → cancel an application, plus estimated shipping cost and overseas warehouse addresses. The base URL is https://www.mydomain.com/api/forwarding.

Operation	Request	Description · main parameters
`verify_customer`	POST `/verify`	Identity check `member_code, name`
`list_applications`	GET `/customers/{customer_id}/applications`	Application list `status`
`get_application`	GET `/customers/{customer_id}/applications/{application_no}`	Application detail and tracking `application_no*`
`cancel_application`	POST `/customers/{customer_id}/applications/{application_no}/cancel`	Cancel application (preview, then confirm) `application_no*, reason`
`estimate_shipping`	GET `/rates`	Estimated shipping `country, weight_kg`
`list_warehouses`	GET `/warehouses`	Overseas warehouse addresses

curl -X POST https://www.mydomain.com/api/forwarding/verify \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"member_code":"CT1001","name":"Sam Ship"}'

#Travel agency standard connector

Identity check with a booking number → booking list and detail → cancel a booking, plus travel search and the cancellation policy. The base URL is https://www.mydomain.com/api/travel.

Operation	Request	Description · main parameters
`verify_customer`	POST `/verify`	Identity check `booking_no, name`
`list_bookings`	GET `/customers/{customer_id}/bookings`	Booking list
`get_booking`	GET `/customers/{customer_id}/bookings/{booking_no}`	Booking detail `booking_no*`
`cancel_booking`	POST `/customers/{customer_id}/bookings/{booking_no}/cancel`	Cancel booking (preview, then confirm) `booking_no*, reason`
`search_products`	GET `/products`	Search trips `city, q`
`get_cancellation_policy`	GET `/cancellation-policy`	Cancellation policy

curl -X POST https://www.mydomain.com/api/travel/verify \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"booking_no":"TR-260001","name":"Jordan Trip"}'

#Clinic and salon booking standard connector

Service and treatment info, open time slots, and new reservations. Identity check with a reservation number → your reservations → change or cancel a reservation. The base URL is https://www.mydomain.com/api/clinic.

Operation	Request	Description · main parameters
`verify_customer`	POST `/verify`	Identity check `reservation_no, name`
`list_services`	GET `/services`	Services and treatments
`find_slots`	GET `/slots`	Open time slots `date*`
`create_reservation`	POST `/reservations`	New reservation (preview, then confirm) `service_code, datetime, name, phone`
`list_reservations`	GET `/customers/{customer_id}/reservations`	Your reservations
`change_reservation`	POST `/customers/{customer_id}/reservations/{reservation_no}/change`	Change reservation (preview, then confirm) `reservation_no, new_datetime`
`cancel_reservation`	POST `/customers/{customer_id}/reservations/{reservation_no}/cancel`	Cancel reservation (preview, then confirm) `reservation_no*`

curl -X POST https://www.mydomain.com/api/clinic/verify \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"reservation_no":"RV-7001","name":"Casey Book"}'

#Subscription (SaaS) standard connector

Plan catalog. Identity check with email and account number → subscription status and invoices → resend a receipt, change plan, or schedule cancellation. The base URL is https://www.mydomain.com/api/subscription.

Operation	Request	Description · main parameters
`verify_customer`	POST `/verify`	Identity check `email, account_no`
`list_plans`	GET `/plans`	Plans
`get_subscription`	GET `/customers/{customer_id}/subscription`	Subscription status
`list_invoices`	GET `/customers/{customer_id}/invoices`	Invoice list
`resend_invoice`	POST `/customers/{customer_id}/invoices/{invoice_no}/resend`	Resend receipt (preview, then confirm) `invoice_no*`
`change_plan`	POST `/customers/{customer_id}/subscription/change-plan`	Change plan (preview, then confirm) `plan*`
`cancel_subscription`	POST `/customers/{customer_id}/subscription/cancel`	Schedule cancellation (preview, then confirm) `reason`

curl -X POST https://www.mydomain.com/api/subscription/verify \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"email":"sub.kim@example.com","account_no":"AC-5001"}'

#Education and academy standard connector

Course catalog. Identity check with a student number → enrollments and detail (estimated refund) → request a refund or postpone. The base URL is https://www.mydomain.com/api/academy.

Operation	Request	Description · main parameters
`verify_customer`	POST `/verify`	Identity check `student_no, name`
`search_courses`	GET `/courses`	Courses `q`
`list_enrollments`	GET `/customers/{customer_id}/enrollments`	Enrollments
`get_enrollment`	GET `/customers/{customer_id}/enrollments/{enrollment_no}`	Enrollment detail and estimated refund `enrollment_no*`
`request_refund`	POST `/customers/{customer_id}/enrollments/{enrollment_no}/refund`	Request a refund (preview, then confirm) `enrollment_no*, reason`
`postpone_enrollment`	POST `/customers/{customer_id}/enrollments/{enrollment_no}/postpone`	Postpone enrollment (preview, then confirm) `enrollment_no, weeks`

curl -X POST https://www.mydomain.com/api/academy/verify \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"student_no":"ST-8001","name":"Riley Course"}'

#Hotel and guesthouse standard connector

Open rooms, rates, and amenities. Identity check with a reservation number → reservation list and detail → request an extra service or cancel. The base URL is https://www.mydomain.com/api/stay.

Operation	Request	Description · main parameters
`verify_customer`	POST `/verify`	Identity check `reservation_no, name`
`find_rooms`	GET `/rooms`	Open rooms and rates `check_in*, nights, guests`
`get_info`	GET `/info`	Amenities
`list_reservations`	GET `/customers/{customer_id}/reservations`	Your reservations
`get_reservation`	GET `/customers/{customer_id}/reservations/{reservation_no}`	Reservation detail `reservation_no*`
`add_request`	POST `/customers/{customer_id}/reservations/{reservation_no}/requests`	Extra service request (preview, then confirm) `reservation_no, type`
`cancel_reservation`	POST `/customers/{customer_id}/reservations/{reservation_no}/cancel`	Cancel reservation (preview, then confirm) `reservation_no*`

curl -X POST https://www.mydomain.com/api/stay/verify \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"reservation_no":"HT-9001","name":"Chris Stay"}'

#Gym and pilates standard connector

Class schedule and seats left. Identity check with a member number → membership and visits remaining → book or cancel a class, or freeze a membership. The base URL is https://www.mydomain.com/api/fitness.

Operation	Request	Description · main parameters
`verify_customer`	POST `/verify`	Identity check `member_no, phone_last4`
`list_classes`	GET `/classes`	Class schedule `date, type`
`get_membership`	GET `/customers/{customer_id}/membership`	Membership
`list_bookings`	GET `/customers/{customer_id}/bookings`	Your class bookings
`book_class`	POST `/customers/{customer_id}/bookings`	Book a class (preview, then confirm) `class_id*`
`cancel_booking`	POST `/customers/{customer_id}/bookings/{booking_id}/cancel`	Cancel a class booking (preview, then confirm) `booking_id*`
`hold_membership`	POST `/customers/{customer_id}/membership/hold`	Freeze membership (preview, then confirm) `start_date, days`

curl -X POST https://www.mydomain.com/api/fitness/verify \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"member_no":"FT-1001","phone_last4":"1234"}'