Developer platform

One request. The whole feedback loop.

Send a completed booking once, then get back to building your product. Reply Kindly handles the follow-up from there.

REST APISigned webhooksTest mode

Public endpoints are versioned under /v1. Built for a smooth path from first request to production.

Quickstart
API_BASE_URL="https://replykindly.com"
API_KEY="nps_test_..."

curl "$API_BASE_URL/v1/follow-ups" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: appointment-booking_83921" \
  -d '{
    "externalAppointmentId": "booking_83921",
    "customer": {
      "externalId": "customer_281",
      "name": "Jane Smith",
      "email": "jane@example.com"
    },
    "completedAt": "2026-08-21T02:30:00Z"
  }'
✓
201 CreatedFollow-up scheduled
fup_7Bj3Kd92

Built for the real world

Everything around the request is already considered.

Your first integration

Create a test API key in the dashboard, then send one completed booking. The loop has everything it needs to get moving.

  • timing
  • email delivery
  • reminders
  • response collection
  • NPS classification

Idempotent by default

Follow-up creation and consent requests support Idempotency-Key. Cancellation and delivery replay are naturally idempotent.

Test and live modes

A test API key never touches live customer emails or live feedback.

Webhooks

Subscribe to feedback.created, feedback.comment_added, feedback.testimonial_approved, and feedback.testimonial_rejected.

Your data stays yours

Structured feedback records with external booking and customer references. Read them through the API, receive them by signed webhook, or download a CSV from the dashboard.

Safe to retry

Authentication that stays out of your way.

Send your API key as a bearer token. Test keys use the test environment; live keys send real customer emails.

Use Idempotency-Key when creating follow-ups or requesting testimonial consent. Reusing it with the same request returns the original result; a different request returns a conflict. Cancellation and delivery replay can also be safely repeated.

Request header
Authorization: Bearer nps_live_k7P3_...
Test keys never contact real customers.

API reference

Read and write the feedback loop without guesswork.

Every endpoint below includes its access requirement, typed parameters, an immediately usable request, and the response shape you should expect.

POST /v1/follow-ups Create a follow-upTell Reply Kindly that a visit is complete. We schedule the customer follow-up using the settings for that account.
AccessAPI key with followups:writeAvailable toDirect and platform keys

Parameters

HeaderAuthorization
stringRequired

Bearer API key, for example Bearer nps_test_….

HeaderContent-Type
application/jsonRequired

Required for the JSON request body.

HeaderIdempotency-Key
stringOptional

Strongly recommended. Reuse it only when retrying the identical request.

BodyexternalAppointmentId
stringRequired

Your stable identifier for the completed booking.

Bodycustomer.email
stringRequired

The customer address used for the follow-up.

BodycompletedAt
ISO-8601 datetimeRequired

When the visit finished.

BodyexternalAccountId
stringOptional

Required for a platform key; omit for a direct key.

Bodycustomer.externalId / customer.name
stringOptional

Your customer reference and a customer-facing name.

Bodymetadata
objectOptional

Extra booking context. Top-level string, number, and boolean values can later be used as exact-match report filters.

Example request

curl "$API_BASE_URL/v1/follow-ups" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: appointment-booking_83921" \
  -d '{
    "externalAppointmentId": "booking_83921",
    "customer": { "externalId": "customer_281", "name": "Jane Smith", "email": "jane@example.com" },
    "completedAt": "2026-08-21T02:30:00Z",
    "metadata": { "locationId": "auckland-central", "service": "colour" }
  }'

201 Created

{
  "id": "fup_7Bj3Kd92",
  "externalAppointmentId": "booking_83921",
  "metadata": { "locationId": "auckland-central", "service": "colour" },
  "status": "scheduled",
  "livemode": false,
  "createdAt": "2026-08-21T02:30:01.000Z",
  "updatedAt": "2026-08-21T02:30:01.000Z"
}
  • A test key records the workflow but never emails the supplied customer.
  • The same idempotency key and identical request returns the original result; reusing a key with different content returns 409.
GET /v1/follow-ups/:id Read a follow-upRetrieve the current scheduled follow-up by the ID returned when it was created.
AccessAPI key with followups:readAvailable toDirect and platform keys

Parameters

Pathid
stringRequired

The follow-up ID, such as fup_7Bj3Kd92.

QueryexternalAccountId
stringOptional

Required for a platform key; omit for a direct key.

Example request

curl "$API_BASE_URL/v1/follow-ups/fup_7Bj3Kd92" \
  -H "Authorization: Bearer $API_KEY"

200 OK

{
  "id": "fup_7Bj3Kd92",
  "externalAppointmentId": "booking_83921",
  "metadata": null,
  "status": "scheduled",
  "livemode": true,
  "createdAt": "2026-08-21T02:30:01.000Z",
  "updatedAt": "2026-08-21T02:30:01.000Z"
}
  • Returns 404 when the follow-up does not exist in the account and environment selected by the API key.
GET /v1/feedback List feedbackRead customer responses with cursor pagination and filters that map to the data your integration already owns.
AccessAPI key with feedback:readAvailable toDirect and platform keys

Parameters

QuerystartDate / endDate
ISO-8601 date or datetimeOptional

Inclusive response window. A date covers its full UTC day. from and to remain supported aliases.

Querysegment
promoter | passive | detractorOptional

Return only one NPS segment.

QueryupdatedSince
ISO-8601 date or datetimeOptional

Return feedback updated at or after this timestamp, ordered by updatedAt then id ascending. Includes later comments and consent changes on older responses.

QuerytestimonialStatus
pending | approved | rejectedOptional

Filter by testimonial consent. Use approved to retrieve testimonials with customer permission. Invalid values return 400.

QueryexternalCustomerId / externalAppointmentId
stringOptional

Exact-match one of your identifiers.

Querymetadata.key
stringOptional

Exact-match a top-level metadata value, for example metadata.locationId=auckland-central.

Querylimit
integerOptional

Responses per page. Defaults to 50; values above 100 are capped at 100.

Querycursor
stringOptional

Use pagination.nextCursor from the preceding response.

QueryexternalAccountId
stringOptional

Required for a platform key; omit for a direct key.

Example request

curl --get "$API_BASE_URL/v1/feedback" \
  -H "Authorization: Bearer $API_KEY" \
  --data-urlencode "startDate=2026-08-01" \
  --data-urlencode "endDate=2026-08-31" \
  --data-urlencode "segment=detractor" \
  --data-urlencode "metadata.locationId=auckland-central"

200 OK

{
  "data": [{
    "id": "fbk_H7ks82",
    "externalAppointmentId": "booking_83921",
    "followUpId": "fup_7Bj3Kd92",
    "metadata": { "locationId": "auckland-central" },
    "externalCustomerId": "customer_281",
    "customerName": "Jane Smith",
    "score": 4,
    "segment": "detractor",
    "comment": "The appointment started late.",
    "testimonialStatus": null,
    "testimonialComment": null,
    "testimonialName": null,
    "testimonialRequestedAt": null,
    "testimonialExpiresAt": null,
    "testimonialRespondedAt": null,
    "respondedAt": "2026-08-21T04:01:00.000Z",
    "commentSubmittedAt": "2026-08-21T04:02:00.000Z",
    "livemode": true
  }],
  "pagination": { "hasMore": false, "nextCursor": null }
}
  • Combine filters to require every value to match. Results are newest first.
  • Feedback list and detail responses include testimonialStatus, testimonialComment, and testimonialName. These are null before a consent request. Publish only approved testimonials, using testimonialComment and testimonialName rather than the original comment or customerName; a null testimonialName means Anonymous.
  • For approved testimonials, request GET /v1/feedback?testimonialStatus=approved.
  • For incremental sync, use updatedSince without a response-date filter. Keep all filters unchanged while following nextCursor. Each page returns the same pagination.syncUntil watermark. After the final page, save that watermark and use it as the next updatedSince; upsert records by id because the boundary is inclusive. This sync does not report deleted records.
GET /v1/feedback/:id Read one feedback responseRetrieve the full structured record for one feedback response.
AccessAPI key with feedback:readAvailable toDirect and platform keys

Parameters

Pathid
stringRequired

The feedback ID, such as fbk_H7ks82.

QueryexternalAccountId
stringOptional

Required for a platform key; omit for a direct key.

Example request

curl "$API_BASE_URL/v1/feedback/fbk_H7ks82" \
  -H "Authorization: Bearer $API_KEY"

200 OK

{
  "id": "fbk_H7ks82",
  "externalAppointmentId": "booking_83921",
  "followUpId": "fup_7Bj3Kd92",
  "metadata": { "locationId": "auckland-central" },
  "externalCustomerId": "customer_281",
  "customerName": "Jane Smith",
  "score": 4,
  "segment": "detractor",
  "comment": "The appointment started late.",
  "testimonialStatus": null,
  "testimonialComment": null,
  "testimonialName": null,
  "testimonialRequestedAt": null,
  "testimonialExpiresAt": null,
  "testimonialRespondedAt": null,
  "respondedAt": "2026-08-21T04:01:00.000Z",
  "commentSubmittedAt": "2026-08-21T04:02:00.000Z",
  "livemode": true
}
  • Returns 404 when the record does not belong to the API key’s account or environment.
POST /v1/feedback/:id/testimonial-request Request testimonial consentEmail the proposed wording and attribution to the original customer for approval.
AccessAPI key with testimonials:writeAvailable toDirect and platform keys

Parameters

Pathid
stringRequired

The feedback ID.

HeaderIdempotency-Key
stringOptional

Strongly recommended. Replays the same response for 24 hours without sending another email; changed input with the same key returns 409.

BodytestimonialComment
stringRequired

Proposed testimonial wording, 1–2000 characters after trimming. The original response must have a comment.

BodytestimonialName
string or nullOptional

Proposed display name, up to 255 characters. Omit, use null, or leave blank for Anonymous. The customer can change it.

BodyexternalAccountId
stringOptional

Required for a platform key; omit for a direct key.

Example request

curl "$API_BASE_URL/v1/feedback/fbk_H7ks82/testimonial-request" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: testimonial-booking-83921-v1" \
  -d '{"testimonialComment":"A wonderful experience.","testimonialName":"Jane B."}'

200 OK (feedback record; excerpt)

{
  "id": "fbk_H7ks82",
  "testimonialStatus": "pending",
  "testimonialComment": "A wonderful experience.",
  "testimonialName": "Jane B.",
  "testimonialRequestedAt": "2026-10-22T00:00:00.000Z",
  "testimonialExpiresAt": "2026-11-21T00:00:00.000Z",
  "testimonialRespondedAt": null
}
  • New dashboard-generated API keys include testimonials:write. Existing keys retain their scopes; create a new key if yours lacks this permission.
  • A pending request can be updated and resent with a new idempotency key. This invalidates its earlier consent link. Approved or rejected requests are final and return 409.
  • Live mode emails the original booking contact. Test mode records the proposal without sending email. No consent token or review URL is returned.
  • Subscribe to feedback.testimonial_approved and feedback.testimonial_rejected for decisions. Webhook data includes the consent fields, decision timestamp, and updatedAt. Create a subscription for the new events; existing subscriptions are unchanged, and only decisions made after this feature is installed emit them.
  • Invalid input returns 400, missing or out-of-scope feedback returns 404, a missing write scope returns 403, and a send failure returns 503 with the previous proposal restored. Retry a failed send with the same idempotency key.
GET /v1/nps Calculate NPSCalculate NPS from the feedback matching your response window and optional filters.
AccessAPI key with nps:readAvailable toDirect and platform keys

Parameters

QuerystartDate / endDate
ISO-8601 date or datetimeOptional

Inclusive reporting window. Defaults to the last 30 days. from and to remain supported aliases.

QueryincludeAverage
booleanOptional

Set true (or use the average alias) to include the 0–10 averageScore.

Querysegment, testimonialStatus, updatedSince, externalCustomerId, externalAppointmentId, metadata.key
stringOptional

Use the same filters as the feedback endpoint. updatedSince filters by last update; the normal response-date window still applies.

QueryexternalAccountId
stringOptional

Required for a platform key; omit for a direct key.

Example request

curl --get "$API_BASE_URL/v1/nps" \
  -H "Authorization: Bearer $API_KEY" \
  --data-urlencode "startDate=2026-08-01" \
  --data-urlencode "endDate=2026-08-31" \
  --data-urlencode "includeAverage=true"

200 OK

{
  "from": "2026-08-01T00:00:00.000Z",
  "to": "2026-08-31T23:59:59.999Z",
  "nps": 62,
  "responseCount": 184,
  "promoters": 132,
  "passives": 34,
  "detractors": 18,
  "averageScore": 8.7,
  "livemode": true
}
  • NPS is a whole number from -100 to 100. With no matching responses, nps is null and averageScore is null when requested.
POST /v1/accounts Create a downstream accountFor platforms only: create the customer account that owns its own feedback settings and branding.
AccessPlatform API keyAvailable toPlatform keys only

Parameters

HeaderContent-Type
application/jsonRequired

Required for the JSON request body.

BodyexternalAccountId
stringRequired

Your stable ID for the downstream business. Must be unique in your platform.

Bodyname
stringRequired

The client business name; 1–255 characters.

Bodysettings.followUp
objectOptional

Optional overrides for send delay, reminders, expiry, and detractor alerts.

Bodysettings.branding
objectOptional

Optional sender name and logo URL overrides.

Example request

curl "$API_BASE_URL/v1/accounts" \
  -H "Authorization: Bearer $PLATFORM_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalAccountId": "salon_882",
    "name": "Central Salon",
    "settings": { "branding": { "fromName": "Central Salon" } }
  }'

201 Created

{
  "id": "acc_4q0Wn",
  "externalAccountId": "salon_882",
  "name": "Central Salon",
  "status": "active",
  "settings": { "branding": { "fromName": "Central Salon" } },
  "createdAt": "2026-08-21T02:30:01.000Z",
  "updatedAt": "2026-08-21T02:30:01.000Z"
}
  • Use this externalAccountId in platform follow-up, feedback, NPS, and webhook-endpoint requests.
  • A duplicate externalAccountId returns 409.
GET /v1/follow-ups Find follow-upsList follow-ups or find the record for your booking or customer reference.
AccessAPI key with followups:readAvailable toDirect and platform keys

Parameters

QueryexternalAccountId
stringOptional

Required for platform keys; omit for direct keys.

Querylimit
integerOptional

Positive page size, capped at 100. Defaults to 50, or 100 for accounts.

Querycursor
stringOptional

Follow pagination.nextCursor with the same filters until pagination.hasMore is false.

QueryexternalAppointmentId / externalCustomerId
stringOptional

Exact-match your booking or customer identifier. Supplied filters combine with AND.

Example request

curl "$API_BASE_URL/v1/follow-ups?externalAppointmentId=booking_83921" \
  -H "Authorization: Bearer $API_KEY"

200 OK (record excerpt)

{
  "data": [{ "id": "fup_7Bj3Kd92", "externalAppointmentId": "booking_83921", "status": "scheduled", "surveyQueuedAt": null, "surveySentAt": null }],
  "pagination": { "hasMore": false, "nextCursor": null }
}
  • Results are newest first by creation time, then ID. Records have the same fields as GET /v1/follow-ups/:id.
  • surveyQueuedAt and reminderQueuedAt record queue acceptance. surveySentAt and reminderSentAt record email-provider acceptance, not inbox delivery. Also returns expiresAt, nextAction, nextActionAt, cancelledAt, cancelReason, lastDeliveryAttemptAt, and lastDeliveryError. Missing workflow state is provisioning; unavailable historical timestamps are null.
POST /v1/follow-ups/:id/cancel Cancel a follow-upStop future survey and reminder delivery for a scheduled follow-up.
AccessAPI key with followups:writeAvailable toDirect and platform keys

Parameters

Pathid
stringRequired

The follow-up ID.

Bodyreason
stringOptional

Optional cancellation reason, up to 500 characters.

BodyexternalAccountId
stringOptional

Required for a platform key.

Example request

curl "$API_BASE_URL/v1/follow-ups/fup_7Bj3Kd92/cancel" \
  -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
  -d '{"reason":"Booking corrected"}'

200 OK (record excerpt)

{ "id": "fup_7Bj3Kd92", "status": "cancelled", "cancelReason": "Booking corrected", "nextAction": null, "nextActionAt": null }
  • Cancellation is naturally idempotent: repeating it preserves the original cancellation time and reason. It does not refund usage. Completed responses, expired follow-ups, and records still provisioning return 409; missing or out-of-scope IDs return 404.
  • Queued messages check cancellation before sending. An email already being sent or accepted by the provider cannot be recalled.
GET /v1/webhook-deliveries List webhook deliveriesInspect delivery attempts and failures for the selected account and key environment.
AccessAPI key with webhooks:readAvailable toDirect and platform keys

Parameters

QueryexternalAccountId
stringOptional

Required for platform keys; omit for direct keys.

Querylimit
integerOptional

Positive page size, capped at 100. Defaults to 50, or 100 for accounts.

Querycursor
stringOptional

Follow pagination.nextCursor with the same filters until pagination.hasMore is false.

Querystatus
pending | failed | succeededOptional

Filter by delivery status.

QuerywebhookEndpointId / webhookEventId
stringOptional

Exact-match an endpoint or event ID.

Example request

curl "$API_BASE_URL/v1/webhook-deliveries?status=failed" \
  -H "Authorization: Bearer $API_KEY"

200 OK (record excerpt)

{ "data": [{ "id": "wdl_example", "status": "failed", "attemptCount": 2, "responseStatus": 503, "lastError": "Endpoint responded with HTTP 503" }], "pagination": { "hasMore": false, "nextCursor": null } }
  • Results are newest first. Records also include webhookEventId, webhookEndpointId, eventType, endpointUrl, endpointStatus, lastAttemptAt, deliveredAt, resolvedAt, and resolution. Signing secrets and response bodies are excluded.
GET /v1/webhook-deliveries/:id Read delivery detailsRead status, attempt count, failure details, and the resolution of one webhook delivery.
AccessAPI key with webhooks:readAvailable toDirect and platform keys

Parameters

QueryexternalAccountId
stringOptional

Required for platform keys; omit for direct keys.

Pathid
stringRequired

The webhook delivery ID.

Example request

curl "$API_BASE_URL/v1/webhook-deliveries/wdl_example" \
  -H "Authorization: Bearer $API_KEY"

200 OK (record excerpt)

{ "id": "wdl_example", "status": "failed", "attemptCount": 2, "responseStatus": 503, "lastError": "Endpoint responded with HTTP 503", "resolvedAt": null, "resolution": null }
  • Returns 404 when the delivery is outside the selected account or key environment. The original record stays available after replay.
POST /v1/webhook-deliveries/:id/replay Retry a failed deliveryCreate one durable replacement delivery and retain the original failure for audit.
AccessAPI key with webhooks:writeAvailable toDirect and platform keys

Parameters

QueryexternalAccountId
stringOptional

Required for platform keys; omit for direct keys.

Pathid
stringRequired

A failed delivery or a pending delivery with an enqueue error.

HeaderIdempotency-Key
stringOptional

Optional 24-hour response replay. Repeating a replay for the same original delivery also naturally returns its existing replacement.

Example request

curl -X POST "$API_BASE_URL/v1/webhook-deliveries/wdl_example/replay" \
  -H "Authorization: Bearer $API_KEY" -H "Idempotency-Key: retry-wdl-example"

202 Accepted (record excerpt)

{ "id": "wdl_replay_wdl_example", "replayOf": "wdl_example", "status": "pending", "attemptCount": 0, "lastError": null }
  • A 202 means the replacement is durably recorded. Maintenance retries queueing if lastError is present. No signing secret or event payload is returned.
  • Disabled endpoints and deliveries that are not replayable return 409. A replacement can itself be replayed if it later fails. Use the event ID to deduplicate processing at your receiver.
GET /v1/reports/nps Read NPS trends and response ratesGroup UTC trends by a metadata location or service and measure responses to invitations actually sent.
AccessAPI key with nps:readAvailable toDirect and platform keys

Parameters

QueryexternalAccountId
stringOptional

Required for platform keys; omit for direct keys.

QuerystartDate / endDate
ISO-8601 date or datetimeOptional

Inclusive period, at most 366 days. Defaults to the last 30 days. from and to are aliases.

Queryinterval
day | week | monthOptional

Defaults to month. Weekly buckets start on Monday; all buckets use UTC.

QuerygroupBy / metadataKey
stringOptional

Use groupBy=metadata with metadataKey=locationId or service. Omit groupBy for one overall trend. Missing metadata forms a null group.

Querymetadata.key
stringOptional

Exact-match a top-level scalar metadata value; bracket notation is also supported. Keys use letters, digits, underscores or hyphens.

Example request

curl "$API_BASE_URL/v1/reports/nps?startDate=2026-09-01&endDate=2026-09-30&interval=week&groupBy=metadata&metadataKey=locationId" \
  -H "Authorization: Bearer $API_KEY"

200 OK (summary excerpt)

{ "interval": "week", "groupBy": "metadata", "metadataKey": "locationId", "summary": { "responseCount": 2, "nps": 50, "averageScore": 9, "invitationCount": 3, "invitationResponseCount": 1, "responseRate": 33.33 }, "groups": [] }
  • The response includes from, to, livemode, an overall summary, and groups. Each group contains a key, summary, and buckets with date and the same metric fields. Empty buckets have zero counts and null NPS/average/rate.
  • responseCount and NPS use responses received in the period. invitationCount counts survey emails accepted by the provider in the period; invitationResponseCount counts those invitations answered by the end of the period. responseRate is 100 × invitationResponseCount / invitationCount, or null with no invitations. Bucket invitation metrics use the invitation date; response metrics use the response date.
  • Up to 100 groups and 5000 group/bucket cells are returned. Narrow the period or add a metadata filter if the report exceeds these limits. Invalid parameters return 400.
GET /v1/usage Read usage and remaining allowanceRead organisation-wide activity and the current follow-up allowance without consuming it.
AccessAPI key with usage:readAvailable toDirect and platform keys

Parameters

Example request

curl "$API_BASE_URL/v1/usage" \
  -H "Authorization: Bearer $API_KEY"

200 OK (allowance excerpt)

{ "scope": "organisation", "livemode": true, "allowance": { "enforced": true, "periodKey": "trial", "limit": 100, "used": 12, "remaining": 88, "canCreateFollowUp": true, "reason": null } }
  • Includes plan, billingStatus, and all-time usage counts for follow-ups created, surveys sent, reminders sent, and responses in the key environment. Platform usage covers all downstream accounts in its organisation.
  • Trial allowances use the existing reserved-usage counter, with trial expiry and billing restrictions respected. A null limit/remaining means there is no numeric cap; check canCreateFollowUp and reason for billing eligibility. Test mode does not consume or enforce live allowance.
  • New dashboard-generated keys include usage:read, webhooks:read, and webhooks:write. Existing keys retain their scopes; create a new key if needed.
GET /v1/accounts List downstream accountsTraverse every downstream account with cursor pagination, including platforms with more than 100 accounts.
AccessPlatform API keyAvailable toPlatform keys only

Parameters

Querylimit
integerOptional

Positive page size, capped at 100. Defaults to 50, or 100 for accounts.

Querycursor
stringOptional

Follow pagination.nextCursor with the same filters until pagination.hasMore is false.

Example request

curl "$API_BASE_URL/v1/accounts?limit=100" \
  -H "Authorization: Bearer $API_KEY"

200 OK (record excerpt)

{ "data": [{ "id": "acc_example", "externalAccountId": "salon_882", "name": "Central Salon" }], "pagination": { "hasMore": true, "nextCursor": "opaque-cursor" } }
  • Defaults to 100 accounts per page, newest first by creation time and ID. Account records retain their current fields. Direct keys return 403; invalid limits or cursors return 400.

Errors

Clear, structured errors

Every error has a stable code, a human-readable message, and a request ID when an unexpected error needs support.

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "customer.email is required",
    "requestId": "req_..."
  }
}

For platforms

One platform key. Clearly isolated customer accounts.

Platform keys keep each downstream business isolated with externalAccountId. Create the mapping once, then include the same value when submitting completed bookings and reading their follow-ups, feedback, or NPS.

Create an account
POST /v1/accounts

{
  "externalAccountId": "salon_882",
  "name": "Central Salon",
  "settings": {
    "followUp": { "sendDelayMinutes": 120 },
    "branding": { "fromName": "Central Salon" }
  }
}
1

Set the account

POST /v1/follow-ups

{
  "externalAccountId": "salon_882",
  "externalAppointmentId": "booking_83921",
  "customer": { "email": "jane@example.com" },
  "completedAt": "2026-08-21T02:30:00Z"
}
2

Make it recognisable

Upload a client logo and optionally set its sender name.

POST /v1/accounts/salon_882/logo

Content-Type: multipart/form-data

logoFile=@central-salon-logo.png
fromName=Central Salon
3

Read account feedback

curl "$API_BASE_URL/v1/feedback?externalAccountId=salon_882" \
  -H "Authorization: Bearer nps_platform_test_..."

Events, when they happen

Let feedback come to you.

Verify Reply-Kindly-Signature against the exact request body. The header uses t=<unix seconds>,v1=<HMAC-SHA256 of "timestamp.body">. Use Reply-Kindly-Event-Id to deduplicate events. Failed deliveries retry automatically and can be replayed from the dashboard.

feedback.createdjust now
{
  "id": "evt_8Ks921",
  "type": "feedback.created",
  "livemode": true,
  "data": {
    "id": "fbk_H7ks82",
    "followUpId": "fup_7Bj3Kd92",
    "metadata": { "locationId": "auckland-central" },
    "score": 4,
    "segment": "detractor"
  }
}

Delivery contract

Verify, deduplicate, then process.

The signature is calculated over the raw bytes, not a re-serialised JSON object. Keep the original body until the signature has passed.

  1. Verify firstRead the unmodified request body, then verify Reply-Kindly-Signature before parsing JSON.
  2. Deduplicate secondStore Reply-Kindly-Event-Id before processing. A replay may deliver the same event again.
  3. Recover deliberatelyReturn a 2xx once accepted. Failed deliveries retry automatically and remain replayable from the dashboard.
Node.js exampleExact raw-body verification
import { createHmac, timingSafeEqual } from "node:crypto";

const rawBody = await request.text();
const signature = request.headers.get("Reply-Kindly-Signature") ?? "";
const eventId = request.headers.get("Reply-Kindly-Event-Id");
const parts = Object.fromEntries(signature.split(",").map((part) => part.split("=")));

const expected = createHmac("sha256", process.env.REPLY_KINDLY_WEBHOOK_SECRET)
  .update(`${parts.t}.${rawBody}`)
  .digest();
const received = Buffer.from(parts.v1 ?? "", "hex");

if (!parts.t || received.length !== expected.length || !timingSafeEqual(received, expected)) {
  return new Response("Invalid signature", { status: 401 });
}

if (await alreadyProcessed(eventId)) return new Response(null, { status: 204 });
await markProcessed(eventId);
const event = JSON.parse(rawBody);