REST API
Read and add praise, and ask customers for praise, from your own code.
Base URL: https://kikopraise.com/api/v1
Authentication
Create a key under Developers, API keys. Send it on every request:
Authorization: Bearer cp_live_...- The key is shown once. Only a fingerprint is stored.
- Read only keys can call
GETendpoints. Read and write keys can alsoPOSTandPATCH. - A key belongs to one workspace and cannot see another.
- Revoking a key stops it on its next request.
Limits and errors
120 requests per minute per key. Over that you get 429 with a Retry-After header. Errors are JSON, { "error": "What went wrong" }, with a matching status: 400, 401, 403, 404, 429 or 500.
Ask a customer for praise
POST /requests is the one to call when a customer is happy: a ticket closes with a 5-star rating, an order is delivered, a deal is won.
curl https://kikopraise.com/api/v1/requests \
-H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
-d '{
"email": "alex@company.com",
"name": "Alex Kim",
"source": "Zendesk",
"reference": "ticket-4192",
"message": "Thanks for your patience on ticket 4192!"
}'| Field | Notes |
|---|---|
email | Required for one person. Or send recipients with up to 25 entries of email and name. |
name | Optional, used in the greeting. |
formId | Optional. Defaults to your first active form. |
message | Optional personal note, up to 600 characters. |
source | Optional label shown on the Requests page. Default API. |
reference | Optional id from your system. Sending the same source and reference again returns the original request and sends nothing, so retries are safe. |
send | false creates a tracked link without emailing. |
Each result is one of sent, link_created, skipped_recent, skipped_responded, invalid, daily_limit or failed, and includes the customer's tracked link.
GET /requests?status=SENT|OPENED|SUBMITTED&limit=25 lists your requests, newest first.
Praise
| Endpoint | What it does |
|---|---|
GET /testimonials | List. Filters: status, type, tag, minRating, search, limit (max 50), cursor |
POST /testimonials | Add a text testimonial. authorName and content are required |
GET /testimonials/ID | One testimonial |
PATCH /testimonials/ID | Edit fields, or send { "status": "APPROVED" } on its own |
New testimonials are PENDING unless you say otherwise. Creating the same author and text twice returns the first one with "duplicate": true.
When nextCursor is not null, pass it as cursor for the next page.
Other reads
GET /tags, GET /forms (with share links), GET /widgets, and GET /me (counts by status, average rating, top tags).
Not in v1
Deleting testimonials, creating forms or widgets, uploading files, and video testimonials.