Documentación de woku - Guía para desarrolladores

Available on the Corporate plan. This functionality is part of woku’s enterprise capabilities. Talk with our sales team.

This guide shows you how to integrate the woku API into your own applications to automate the creation of wokus, capture responses from every feedback tool, send surveys by email or WhatsApp and enrich your data with identifiers from your internal systems.

This guide applies only to the v1 version of the API. It corresponds exactly to the API Reference tab you see at the top of the documentation. For the historical behavior (routes without the /v1/ prefix), switch the version selector to v0.

Interactive reference

The entire API is documented interactively in the API Reference tab of this same documentation. There you can view each endpoint with its full schema, run it live from the browser and copy examples in your preferred language. This guide is complementary: it explains the flow and the “why” of each call so that the integration takes you as little time as possible.

Introduction

The woku API lets you operate all feedback tools programmatically: wokus, NPS, CSAT, CES, forms and flows, as well as invitations, quarantines, external trackers, ticket destinations and action plans. The typical use cases:

Create wokus automatically when an event occurs in your application (for example, closing a sale, ending a training session, delivering a product).
Capture responses directly from your interface or backend, without redirecting the customer to the woku site: woku ratings and reviews, NPS, CSAT and CES scores, and form responses.
Send surveys by email or WhatsApp to recipient lists from your backend.
Capture feedback from your mobile app with a single idempotent endpoint, designed for the React Native SDK.
Tag tools with identifiers from your systems (CRM, ERP, ticketing) to later search across them.
Extract responses and reports into your dashboards and internal systems.
Configure where support tickets land (Zendesk, Salesforce, Slack, your own service or email) and how they are routed based on your trackers.
Manage AI-generated action plans: approve them, send them to Jira, monday.com, ClickUp or Notion, or work them inside woku.

All calls are HTTP with JSON or multipart/form-data and respond with consistent structures.

Base URL

https://clientapi.woku.app

All v1 endpoints live under the /v1/ prefix.

Authentication

Every company registered in woku has a Company Key that is included in the Authorization header of each request:

Authorization: Bearer <Company-Key>

The key is obtained by the company owner from the company’s Information section, in the admin application: https://admin.woku.app

View of the company information window.

The same key you used in v0 works for v1. You do not need to regenerate it to migrate.

Company

Get the current company

Retrieves the data of the company associated with the Company Key. Useful to validate that your integration is authenticating with the correct account. Endpoint

GET /v1/companies/me

Headers

Authorization: Bearer <Company-Key>

Responses

200 OK: Returns the company object.
403 Forbidden: The key is not valid or has no permission.

Wokus

The wokus functions let you create, query, rate and share wokus programmatically.

Create a woku with a file URL

Creates a woku using an image or video hosted at a public URL (CDN, S3, ImageKit, etc.). Endpoint

POST /v1/wokus

Headers

Content-Type: application/json
Authorization: Bearer <Company-Key>

Body

{
  "description": "Customer Service Experience - Store #123",
  "fileUrl": "https://cdn.example.com/images/product-image.jpg",
  "folderSecondaryKey": "store-123",
  "parentFolderSecondaryKey": "region-north",
  "clientEmail": "customer@example.com",
  "clientPhone": 56912345678
}

Fields

description (string, required): Between 3 and 140 characters.
fileUrl (string, required): Public URL of an image or video (preferably .mp4).
folderSecondaryKey (string, optional): Key of the folder where the woku is stored.
parentFolderSecondaryKey (string, optional): Key of the parent folder. It cannot be the same as folderSecondaryKey.
clientEmail (string, optional): Email of the associated customer.
clientPhone (number, optional): WhatsApp number.

Responses

201 Created: Returns the created woku object.
400 Bad Request: The body did not pass validation.
403 Forbidden: Invalid key.

Create a woku with a file (multipart)

When the file is in your own storage or your client uploads the image directly from a form, use the endpoint with multipart/form-data. Endpoint

POST /v1/wokus/form-data

Headers

Content-Type: multipart/form-data
Authorization: Bearer <Company-Key>

Form fields

file (binary, required): Image or video file.
description (string, required): Between 3 and 140 characters.
folderSecondaryKey (string, optional).
parentFolderSecondaryKey (string, optional).
clientEmail (string, optional).
clientPhone (string, optional).

Responses

201 Created: Woku created.
400 Bad Request: Validation failed (file format, size, required fields).
403 Forbidden: Invalid key.

Get the data of a woku

Retrieves the woku along with its ratings and reviews. Endpoint

GET /v1/wokus/:id/review

Headers

Authorization: Bearer <Company-Key>

Path params

id (string, required): Woku identifier.

Responses

200 OK: Woku object with its reviews.
403 Forbidden: Invalid key.
404 Not Found: No woku with that ID exists in your company.

List the company’s wokus

Paginated list of your company’s wokus. Endpoint

GET /v1/wokus

Query params

page (number, optional): Defaults to 1.
limit (number, optional): Defaults to 20.

Responses

200 OK: Paginated list of wokus.
403 Forbidden: Invalid key.

Get a woku with statistics

Returns a woku with its aggregated review statistics. Endpoint

GET /v1/wokus/:id

Responses

200 OK: Woku with statistics.
403 Forbidden: The woku belongs to another company.
404 Not Found: The woku does not exist.

List the reviews of a woku

Text and audio reviews, paginated, from most recent to oldest. Audio reviews expose their transcription. Customer contact data is never included, only clientId. Endpoint

GET /v1/wokus/:id/reviews

Query params

page (number, optional).
limit (number, optional).

Responses

200 OK: Paginated list of reviews.
403 Forbidden: The woku belongs to another company.
404 Not Found: The woku does not exist.

Rate with a text review

Adds a rating of 1 to 5 stars with a written comment. Endpoint

POST /v1/wokus/:id/textnotes

Headers

Content-Type: application/json
Authorization: Bearer <Company-Key>

Body

{
  "qualification": 5,
  "description": "Excellent service! The staff was very helpful.",
  "clientEmail": "customer@example.com",
  "clientPhone": 56912345678,
  "anonymous": false
}

Fields

qualification (integer, required): Value between 1 and 5.
description (string, required): Text review, maximum 3000 characters.
clientEmail (string, optional): If not provided, anonymous must be true.
clientPhone (number, optional).
anonymous (boolean, optional): Defaults to false.

Responses

201 Created: Review recorded.
400 Bad Request: Validation failed.
403 Forbidden: Invalid key.
404 Not Found: The woku does not exist.

Rate with an audio review

Upload an audio file along with the rating. Endpoint

POST /v1/wokus/:id/voicemails

Headers

Content-Type: multipart/form-data
Authorization: Bearer <Company-Key>

Form fields

file (binary, required): Audio. Recommended .mp4 or .wav.
qualification (string "1", "5", required).
clientEmail (string, optional).
clientPhone (string, optional).
anonymous (string "true" or "false", optional).

Responses

201 Created: Review recorded.
400 Bad Request: Validation failed.
403 Forbidden: Invalid key.
404 Not Found: The woku does not exist.

Sends the woku to one or more recipients. It is the same flow that starts from the share interface. Endpoint

POST /v1/wokus/:id/share

Headers

Content-Type: application/json
Authorization: Bearer <Company-Key>

Body (single recipient)

{
  "clientEmail": "customer@example.com"
}

Body (multiple recipients)

{
  "clientEmails": ["customer1@example.com", "customer2@example.com"]
}

You must send one or the other of the two fields, not both.

Responses

200 OK: Send queued.
400 Bad Request: Validation failed (malformed email, both fields empty, etc.).
403 Forbidden: Invalid key.

Mobile SDK captures

A single ingestion endpoint designed for the React Native SDK. It receives a normalized capture and routes it according to its kind: woku (a woku review), nps, csat or ces. The response channel is sealed as mobile-sdk on the server side. Endpoint

POST /v1/captures

It accepts two content types:

application/json: text or rating captures. The body is the capture.
multipart/form-data: captures with audio. The file goes in the file field and the capture as JSON in the payload field. Audio is available for woku and nps; audio comments are not yet supported for csat or ces.

Body (JSON)

{
  "id": "3f2c9a2e-8b1d-4f6a-9c3e-1a2b3c4d5e6f",
  "kind": "woku",
  "targetId": "671000000000000000000001",
  "rating": 5,
  "comment": "Excellent service at the store.",
  "respondent": { "email": "customer@example.com" }
}

Fields

id (string, optional): Identifier generated by the client. It is used as the idempotency key.
kind (string, required): woku, nps, csat or ces.
targetId (string): Id of the woku (required for woku), of the NPS Tool (optional for nps) or of the CSAT/CES Tool (required for csat and ces).
rating (integer, optional): Woku rating, from 1 to 5.
score (integer, optional): NPS score from 0 to 10, or CSAT/CES from 1 to 5.
comment (string, optional, max 3000): Text comment. Required in text captures of a woku.
respondent (object, optional): email, phone, externalId. Without an identifier, the capture stays anonymous.

Idempotency The idempotency key is taken from the X-Woku-Idempotency-Key header or, in its absence, from the id field of the body. If the same send is retried (for example, by the SDK’s offline queue), the API returns the already-recorded result instead of creating a duplicate. Responses

201 Created: Capture accepted. Returns id, kind, remoteId and status: "accepted".
400 Bad Request: Validation failed (missing targetId, audio in csat or ces, malformed payload).
403 Forbidden: Invalid key.

NPS responses

You can capture NPS scores and extract individual responses into your systems. Aggregated reports are in the NPS Reports section.

Capture an NPS score

Endpoint

POST /v1/nps

Body

{
  "score": 9,
  "npsToolId": "671000000000000000000001",
  "clientEmail": "customer@example.com"
}

Fields

score (integer, required): From 0 to 10.
npsToolId (string, optional): Specific NPS Tool. If omitted, the score is recorded at the company level.
clientEmail (string, optional): If not provided, the response stays anonymous.
anonymous (boolean, optional).
responseChannel (string, optional, max 48): Response channel. Defaults to api.

Responses

201 Created: Returns npsId and the response object.
400 Bad Request: Validation failed.
403 Forbidden: The NPS Tool does not belong to your company.

Add a review to an NPS score

Once the score is created, you can attach an optional text or audio review to it. Endpoints

POST /v1/nps/:id/textnotes
POST /v1/nps/:id/voicemails

Text: JSON body { "description": "..." }, maximum 3000 characters.
Audio: multipart/form-data with the file in the file field (m4a, aac or mp4). The transcription is generated on the server.

Responses

201 Created: Review attached.
400 Bad Request: Validation failed.
403 Forbidden: The NPS belongs to another company.
404 Not Found: The NPS does not exist.

Query NPS Tools and responses

Read endpoints to bring NPS data into your systems:

GET /v1/nps-tools: Paginated list of your company’s NPS Tools.
GET /v1/nps-tool/:id: Definition of an NPS Tool (to build the question).
GET /v1/nps: Paginated responses, from most recent to oldest.
GET /v1/nps/:id: An individual response.

GET /v1/nps accepts the filters npsToolId, from and to (ISO dates over the creation date) and withFeedback=true (only responses with a text or audio review), plus page and limit. Responses never include customer contact data, only clientId.

CSAT and CES

The CSAT (satisfaction, scale 1 to 5) and CES (effort, scale 1 to 5) families are exact mirrors. The examples use csat; replace csat with ces and csatToolId with cesToolId to get the CES family. Unlike NPS, the tool id is always required: CSAT and CES are always custom surveys.

Capture a CSAT score

Endpoint

POST /v1/csat

Body

{
  "score": 4,
  "csatToolId": "671000000000000000000002",
  "clientEmail": "customer@example.com"
}

Fields

score (integer, required): From 1 to 5.
csatToolId (string, required): CSAT Tool that answers the survey.
clientEmail (string, optional): If not provided, the response stays anonymous.
anonymous (boolean, optional).
responseChannel (string, optional, max 48): Response channel. Defaults to api.

Responses

201 Created: Returns csatId and the response object.
400 Bad Request: Validation failed.
403 Forbidden: The CSAT Tool does not belong to your company.

Add a comment to a CSAT response

Endpoints

POST /v1/csat/:id/textnotes
POST /v1/csat/:id/voicemails

Text: JSON body { "description": "..." }, maximum 3000 characters.
Audio: multipart/form-data with the file in the file field (m4a, aac or mp4). The transcription is generated on the server.

Responses

201 Created: Comment accepted.
403 Forbidden: The response belongs to another company.
404 Not Found: The CSAT response does not exist.

Query CSAT tools and responses

GET /v1/csat-tools: Paginated list of your company’s CSAT Tools.
GET /v1/csat-tool/:id: Definition of a CSAT Tool (to build the survey).
GET /v1/csat: Paginated responses, with the filters csatToolId, from, to and withFeedback.
GET /v1/csat/:id: An individual response.

The CES family exposes exactly the same endpoints: POST /v1/ces, POST /v1/ces/:id/textnotes, POST /v1/ces/:id/voicemails, GET /v1/ces-tools, GET /v1/ces-tool/:id, GET /v1/ces and GET /v1/ces/:id.

Forms

Query and capture forms from your own systems: render the form with its definition, submit responses and extract the results.

List the company’s forms

Endpoint

GET /v1/forms

Query params

page (number, optional).
limit (number, optional).

Responses

200 OK: Paginated list of forms.
403 Forbidden: Invalid key.

Get the definition of a form

Returns the active form (fields, configuration, localized content) along with the company’s branding, to render it in your own interface. Endpoint

GET /v1/forms/:id

Responses

200 OK: Form definition.
403 Forbidden: The form belongs to another company.
404 Not Found: It does not exist or is inactive.

Submit a form response

Endpoint

POST /v1/forms/:id/responses

Body

{
  "anonymous": false,
  "email": "respondent@example.com",
  "answers": { "field-uuid-1": "John Doe", "field-uuid-2": 5 }
}

Fields

anonymous (boolean, required).
email / phone (string, optional): Required depending on how the form identifies customers, when the response is not anonymous.
answers (object, required): Answers by field id. They are validated against the form definition.
responseChannel (string, optional, max 48): Defaults to api.

Responses

201 Created: Response recorded.
400 Bad Request: Validation failed or the form is closed.
403 Forbidden: The form belongs to another company.
404 Not Found: It does not exist or is inactive.
429 Too Many Requests: The respondent is in quarantine.

List the responses of a form

Paginated, from most recent to oldest. Responses expose the values by field id and never include customer contact data, only clientId. Endpoint

GET /v1/forms/:id/responses

Responses

200 OK: Paginated list of responses.
403 Forbidden: The form belongs to another company.
404 Not Found: The form does not exist.

Flows

Read-only endpoints. A flow chains several wokus (and optionally an NPS) into a single journey; with this data you can render the journey in your application and capture with the existing endpoints (POST /v1/wokus/:id/textnotes, POST /v1/nps, etc.).

GET /v1/flows: Paginated list of your company’s flows.
GET /v1/flows/:id: Flow data: wokus in order, branding and linked NPS.

Responses

200 OK: Flow data or paginated list.
403 Forbidden: The flow belongs to another company.
404 Not Found: The flow does not exist.

Invitations

A homogeneous family of endpoints to send surveys by email or WhatsApp to a list of up to 100 recipients. Sends are asynchronous: the API responds immediately with the per-recipient detail. Endpoints

POST /v1/nps/invitations
POST /v1/csat/invitations
POST /v1/ces/invitations
POST /v1/forms/:id/invitations
POST /v1/wokus/:id/invitations

Body

{
  "channel": "whatsapp",
  "recipients": ["56912345678"],
  "language": "es"
}

Fields

channel (string, required): email or whatsapp.
recipients (string[], required, max 100): Emails for the email channel; numbers with country code (for example 56912345678) for whatsapp.
language (string, optional): es or en.
npsToolId (string, optional, NPS only): If omitted, the company-level NPS survey is sent.
csatToolId / cesToolId (string, required in CSAT and CES).

Responses

202 Accepted: Per-recipient summary: accepted (dispatched or queued) and rejected with the reason (invalid_recipient, quarantined, insufficient_credits_or_blocked, send_failed).
400 Bad Request: Validation failed, or the form or woku is closed.
403 Forbidden: The tool does not belong to your company.
404 Not Found: The form or the woku does not exist.

Malformed recipients do not fail the entire request: they are reported individually in rejected with the reason invalid_recipient.

Quarantines

A read-only query to know whether a respondent is currently in quarantine, before asking them for feedback. It records nothing. The anti-duplicate rules are configured in the admin panel; see Quarantines. Endpoint

GET /v1/quarantines/check?email=<email>

Query params

email (string, optional).
phone (string, optional).

At least one of the two is required. Responses

200 OK: Quarantine status of the respondent.
400 Bad Request: Neither email nor phone was provided.
403 Forbidden: Invalid key.

NPS Reports

If your company uses the NPS tool, you can query the aggregated reports directly from the API to integrate them into your own dashboards.

Company NPS report

Returns the aggregated report of all NPS recorded for your company. Endpoint

GET /v1/reports/company-nps

Headers

Authorization: Bearer <Company-Key>

Responses

200 OK: Report with the distribution of promoters, passives and detractors, and the resulting NPS score.
403 Forbidden: Invalid key.

NPS report for a tool

Returns the report of a specific NPS Tool (for example, “post-event NPS” or “post-purchase NPS”). Endpoint

GET /v1/reports/nps-tool/:id

Headers

Authorization: Bearer <Company-Key>

Path params

id (string, required): NPS Tool identifier.

Responses

200 OK: NPS Tool report.
400 Bad Request: Malformed id.
403 Forbidden: Invalid key.
404 Not Found: The NPS Tool does not exist or does not belong to your company.

External Trackers

External trackers let you associate identifiers from your systems (CRM, ERP, ticketing, OMS) with your feedback tools (wokus, NPS, CSAT, CES, forms and flows) to later search across them. For example: linking a woku to your CRM’s transaction_id or your ERP’s order_id.

Model

Tracker definition: A company-level catalog entry, such as { name: "trr", system: "crm interno", description: "..." }. It is defined in woku’s admin panel, in the Company section.
Tracker value: A string value tied to a (tool, Tracker) pair. Several tools can share the same value.

List the company’s active trackers

Endpoint

GET /v1/external-trackers

Query params

page (number, optional).
limit (number, optional).

Responses

200 OK: Paginated list of tracker definitions.
403 Forbidden: Invalid key.

List trackers assigned to a woku

Endpoint

GET /v1/external-trackers/wokus/:id

Responses

200 OK: Trackers assigned to the woku.
403 Forbidden: Invalid key.

Assign a tracker value to a woku

Creates or updates (upsert) the value of a tracker on a woku. Endpoint

POST /v1/external-trackers/wokus/:id

Body

{
  "name": "trr",
  "value": "TX-2026-00043"
}

Fields

name (string, required, max 60): Name of the tracker defined in your company.
value (string, required, max 500): Value of the external identifier (always stored as a string).

Responses

201 Created: Value assigned or updated.
400 Bad Request: Validation failed.
403 Forbidden: Invalid key.
404 Not Found: The woku or the tracker does not exist.

Delete a tracker value from a woku

Endpoint

DELETE /v1/external-trackers/wokus/:id/:trackerName

Responses

200 OK: Deleted.
403 Forbidden: Invalid key.
404 Not Found: The woku or the tracker does not exist.

Search wokus by tracker

Finds all wokus that have a given (name, value). Useful to get back from your CRM to the corresponding woku. Endpoint

GET /v1/external-trackers/search?name=<tracker>&value=<value>

Query params

name (string, required): Tracker name.
value (string, required): Value to search for.
page (number, optional).
limit (number, optional).

Responses

200 OK: Paginated list of wokus with their tracker values.
403 Forbidden: Invalid key.
404 Not Found: No matches exist.

Trackers on VoC tools (NPS, CSAT, CES, forms, flows)

In addition to wokus, you can assign trackers to the other feedback tools. The tool type goes in the route as :entityType, with one of these values: nps, csat, ces, form, flow. The :id is the tool id (for example npsToolId, csatToolId, cesToolId, formId or flowId). In version 2 of the API these endpoints and the woku ones will be unified into a single polymorphic resource.

List trackers assigned to a tool

Endpoint

GET /v1/external-trackers/:entityType/:id

Example: GET /v1/external-trackers/nps/671000000000000000000001. Responses

200 OK: Trackers assigned to the tool.
400 Bad Request: Unsupported tool type.
403 Forbidden: Invalid key.

Assign a tracker value to a tool

Creates or updates (upsert) the value of a tracker on the tool. Endpoint

POST /v1/external-trackers/:entityType/:id

Body

{
  "name": "trr",
  "value": "TX-2026-00043"
}

Fields

name (string, required, max 60): Name of the tracker defined in your company.
value (string, required, max 500): Value of the external identifier (always stored as a string).

Responses

201 Created: Value assigned or updated.
400 Bad Request: Unsupported type, inactive tracker or validation failed.
403 Forbidden: The tool belongs to another company.
404 Not Found: The tool or the tracker does not exist.

Delete a tracker value from a tool

Endpoint

DELETE /v1/external-trackers/:entityType/:id/:trackerName

Responses

200 OK: Deleted.
404 Not Found: The tracker or the assignment does not exist.

Ticket destinations

Ticket destinations define where the support tickets generated by woku’s AI land: a customer support platform (Zendesk, Salesforce), a Slack channel, your own HTTP service or a list of emails. Each destination has routing rules based on your external trackers that decide which tickets reach it.

Model

kind (required): zendesk, salesforce, slack, custom or email.
config (required): non-sensitive configuration, specific to each kind.
- zendesk: { connectionId, groupId? }. connectionId is the id of your Zendesk Integration connected in the admin panel; groupId is the agent group, optional.
- salesforce: { queueId?, caseOrigin? }. queueId is the Id of a Salesforce Queue ("00G..."); caseOrigin is "Web" by default.
- slack: { connectionId, channelId, channelLabel? }. connectionId is the id of your Slack Integration; channelId is the channel id ("C...").
- custom: { url, method, headers? }. method is POST or PUT; headers are extra non-sensitive headers.
- email: { emails }. Up to 20 recipients.
credentials (required, write-only): never returned in the responses, only its credentialsHint (last 4 masked characters). Zendesk, Salesforce and Slack authenticate with your company’s connected Integration, so you send {}. Custom uses { authType, ... }, with authType none, basic (adds username, password), bearer (adds token) or api-key-header (adds headerName, headerValue). Email also uses no credentials, you send {}.
routingConditions (optional, up to 20 rows): conditions over your external trackers. Each row uses the operator equals (the tracker must have an exact value in value) or any (any value of the tracker, value is omitted). relationToPrevious joins a row with the previous one (AND same group, OR new group); the first row does not include it. The destination receives the ticket when some OR group is fully satisfied.

List the ticket destinations

Endpoint

GET /v1/ticket-destinations

Responses

200 OK: List of destinations (without credentials).
403 Forbidden: Invalid key.

Get a ticket destination

Endpoint

GET /v1/ticket-destinations/:id

Responses

200 OK: Destination.
403 Forbidden: Invalid key.
404 Not Found: The destination does not exist.

Create a ticket destination

Endpoint

POST /v1/ticket-destinations

Headers

Content-Type: application/json
Authorization: Bearer <Company-Key>

Body (example with Slack, routed by any value of a tracker)

{
  "name": "Slack #soporte",
  "kind": "slack",
  "config": {
    "connectionId": "671000000000000000000010",
    "channelId": "C0123ABCD",
    "channelLabel": "#soporte"
  },
  "credentials": {},
  "routingConditions": [
    { "trackerId": "671000000000000000000011", "operator": "any" }
  ]
}

Fields

name (string, required, max 120).
kind, config, credentials, routingConditions: see the Model section of this part.
aiContext (string, optional, max 2000): additional context for the AI triage of this destination.
template (object, optional, only kind: "custom"): { preset, body? }. Without body, the canonical ticket envelope is sent.

Responses

201 Created: Destination created.
400 Bad Request: Validation failed.
403 Forbidden: Invalid key.

Update a ticket destination

Endpoint

PATCH /v1/ticket-destinations/:id

All fields are optional; only the ones you send are changed. Sending credentials rotates the stored secret. Sending kind changes the provider: config and credentials are validated against the new kind. Body (example: disable)

{ "enabled": false }

Responses

200 OK: Destination updated.
400 Bad Request: Validation failed.
403 Forbidden: Invalid key.
404 Not Found: The destination does not exist.

Delete a ticket destination

Endpoint

DELETE /v1/ticket-destinations/:id

Its routing conditions live on the destination and disappear with it. Responses

200 OK: { "deleted": true }.
403 Forbidden: Invalid key.
404 Not Found: The destination does not exist.

Action plan groups

An action plan group defines which feedback (by tracker conditions) generates an improvement plan and who the owners are. When the counter of new improvement-type comments reaches the group’s threshold, woku drafts a plan with AI for its members.

Model

conditions (required, minimum 1 row, up to 20): same rules as the routingConditions of ticket destinations (operator equals or any, relationToPrevious to build AND/OR).
members (required, minimum 1): each with userId and role (admin approves and sends plans, assignee works the tasks). A group needs at least one admin and one assignee.
threshold (integer, optional, minimum 1, defaults to 300): new improvement-type comments that trigger a draft.
enabled: a disabled group stops counting feedback and generating drafts, but keeps its history and statistics.

List the action plan groups

Endpoint

GET /v1/action-plan-groups

Query params

search (string, optional): free search by name, description and condition values.

Responses

200 OK: List of groups.
403 Forbidden: Invalid key.

Get an action plan group

Endpoint

GET /v1/action-plan-groups/:id

Responses

200 OK: Group.
403 Forbidden: Invalid key.
404 Not Found: The group does not exist.

Create an action plan group

Endpoint

POST /v1/action-plan-groups

Headers

Content-Type: application/json
Authorization: Bearer <Company-Key>

Body

{
  "name": "In-store service",
  "description": "Complaints about the physical store experience.",
  "conditions": [
    { "trackerId": "671000000000000000000011", "operator": "any" }
  ],
  "members": [
    { "userId": "671000000000000000000020", "role": "admin" },
    { "userId": "671000000000000000000021", "role": "assignee" }
  ],
  "threshold": 300
}

Fields: see the Model section of this part, plus name (string, required, max 120) and description (string, optional, max 500). Responses

201 Created: Group created.
400 Bad Request: Validation failed.
403 Forbidden: Invalid key.

Update an action plan group

Endpoint

PATCH /v1/action-plan-groups/:id

All fields are optional; sending description: "" clears it. Responses

200 OK: Group updated.
400 Bad Request: Validation failed.
403 Forbidden: Invalid key.
404 Not Found: The group does not exist.

Enable or disable a group

Endpoint

PATCH /v1/action-plan-groups/:id/enabled

Body

{ "enabled": false }

Responses

200 OK: Group updated.
403 Forbidden: Invalid key.
404 Not Found: The group does not exist.

Delete an action plan group

Endpoint

DELETE /v1/action-plan-groups/:id

The already-generated plans keep their own frozen detail and only reference the group by id. Responses

200 OK: { "deleted": true }.
403 Forbidden: Invalid key.
404 Not Found: The group does not exist.

Action plans

Action plans are improvement plans drafted by AI from the feedback of a group. A plan is born in draft state, is approved, and from there it is sent to an external tool (Jira, monday.com, ClickUp or Notion) or worked inside woku with the internal provider (“Manage in woku”, an internal kanban).

Model

status: draft, approved, sent, canceled, delivery_error, in_progress (managed inside woku) or completed.
priority: high, medium or low, calculated by woku (never defined by the AI).
evidence: the slice of feedback frozen at the moment the plan is generated; its numbers are never recalculated.
tasks: the plan’s task list. In a managed plan (in_progress) each task also has status (todo, in_progress, done) and assigneeId.

List the action plans

Endpoint

GET /v1/action-plans

Query params

groupId, status, source (woku, nps, csat or ces), priority, from, to, search, page, limit: all optional.

Responses

200 OK: { "data": [...], "total": 42 }. Unlike other listings in this API, this response does not repeat page or limit.
403 Forbidden: Invalid key.

Get an action plan

Endpoint

GET /v1/action-plans/:id

Returns the complete plan, including the frozen evidence detail and the send status. Responses

200 OK: Plan.
403 Forbidden: Invalid key.
404 Not Found: The plan does not exist.

Send a plan to a destination

Endpoint

POST /v1/action-plans/:id/send

The plan must be approved (or delivery_error to retry) to send it to an external provider. provider: "internal" is the exception: it manages the plan inside woku, carries no target and applies immediately (the plan moves to in_progress). External providers queue the send (202 Accepted); query GET /v1/action-plans/:id to see the result. Body (manage inside woku)

{ "provider": "internal" }

Body (send to Jira)

{
  "provider": "jira",
  "target": { "projectId": "10032", "issueTypeId": "10001" },
  "resourceLabel": "Operaciones CX - Backlog"
}

Fields

provider (string, required): jira, monday, clickup, notion or internal.
target (object, required except for internal): jira is { siteId?, projectId, issueTypeId }; monday is { boardId, groupId }; clickup is { listId }; notion is { databaseId }.
resourceLabel (string, optional, max 300): human-readable description of the destination.

Responses

202 Accepted: { "status": "sending" } for an external provider, { "status": "managed" } for internal.
400 Bad Request: The provider’s target is missing or invalid.
403 Forbidden: Invalid key.
404 Not Found: The plan does not exist.
409 Conflict: The plan is not in a valid state for this transition, or a send is already in progress.

Tasks of a plan

Available while the plan is in draft or in_progress (managed). A task’s status and assigneeId can only be edited in a managed plan. Endpoints

POST /v1/action-plans/:id/tasks
PATCH /v1/action-plans/:id/tasks/reorder
PATCH /v1/action-plans/:id/tasks/:taskId
DELETE /v1/action-plans/:id/tasks/:taskId

Add (POST .../tasks): body { "text": "..." }, maximum 160 characters, up to 100 tasks per plan.
Reorder (PATCH .../tasks/reorder): body { "orderedTaskIds": [...] } with ALL the plan’s task ids, in the desired order.
Edit (PATCH .../tasks/:taskId): body with at least one of text, status or assigneeId.
Delete (DELETE .../tasks/:taskId): no body.

All four return the complete updated plan. Responses

200 OK (201 Created when adding): Plan updated.
400 Bad Request: Validation failed.
403 Forbidden: Invalid key.
404 Not Found: The plan or the task does not exist.
409 Conflict: The plan is not in draft or in_progress, or status/assigneeId was sent in a non-managed plan.

Change the state of a plan

Endpoints

POST /v1/action-plans/:id/approve
POST /v1/action-plans/:id/reopen
POST /v1/action-plans/:id/cancel
POST /v1/action-plans/:id/complete
POST /v1/action-plans/:id/resume

No body. Each action requires the plan to be in a specific source state:

Action	From	To
`approve`	`draft`	`approved`
`reopen`	`approved`, `delivery_error`	`draft`
`cancel`	`draft`, `approved`, `delivery_error`, `in_progress`	`canceled`
`complete`	`in_progress`	`completed`
`resume`	`completed`	`in_progress`

Responses

200 OK: Plan updated.
403 Forbidden: Invalid key.
404 Not Found: The plan does not exist.
409 Conflict: The plan is not in the source state required for that action.

Ingestion and extraction limits

The REST API is documented interactively in the API Reference tab and applies rate and volume limits both for ingestion (creation of wokus, reviews, NPS, tracker assignment) and for extraction (querying wokus, reports and searches). The limits cover the two modes of operation: per event (one call per record) and per batch (batch loads). The limits are applied per Company Key:

Operation	Mode	Limit
Per-event ingestion	Event	600 requests/minute · up to 50 events/sec
Per-batch ingestion	Batch	Up to 5,000 records per batch · 60 batches/minute
Daily ingestion volume	Event + batch	1,000,000 records/day
Extraction (read)	Event	300 requests/minute
Paginated extraction	Batch	Up to 200 records per page

These are the default limits of the Corporate plan. If your integration needs larger windows (seasonal peaks, massive migrations), write to us to expand them.

Handling 429 (Too Many Requests)

When you exceed a rate limit, the API responds with 429 Too Many Requests and includes headers that tell you when to retry:

Retry-After: seconds to wait before the next attempt.
X-RateLimit-Limit: cap of the current window.
X-RateLimit-Remaining: remaining requests in the window.
X-RateLimit-Reset: timestamp at which the window resets.

Implement retries with exponential backoff respecting Retry-After. For batch loads, split the batches that exceed the maximum number of records instead of retrying the whole batch.

Pagination in extraction

The extraction endpoints that return collections are paginated. Control the page with the query params page and limit (for example, in GET /v1/external-trackers or GET /v1/external-trackers/search). To extract large volumes, iterate through the pages sequentially respecting the per-minute extraction limit and the maximum number of records per page.

GET /v1/external-trackers/search?name=trr&value=TX-2026-00043&page=1&limit=200

Common errors

Inaccessible file URL

If you use POST /v1/wokus with fileUrl, make sure the URL is publicly accessible. Our service downloads the file before creating the woku.

Duplicate secondary key

folderSecondaryKey is used to identify a folder within your company. Two folders with the same key cannot exist in the same company. If you need to reuse a key, first delete the existing folder from the admin panel.

403 on every call

It almost always means the key is incorrect, has expired or belongs to another company. Get the key again from admin.woku.app → Company information → Get Key.

Contact and support

Diego Orrego Brito, CTO of woku.
Email: diego@woku.app (include the company name in the subject and mention that it is about the API).

​Interactive reference

​Introduction

​Base URL

​Authentication

​Company

​Get the current company

​Wokus

​Create a woku with a file URL

​Create a woku with a file (multipart)

​Get the data of a woku

​List the company’s wokus

​Get a woku with statistics

​List the reviews of a woku

​Rate with a text review

​Rate with an audio review

​Share a woku by email

​Mobile SDK captures

​NPS responses

​Capture an NPS score

​Add a review to an NPS score

​Query NPS Tools and responses

​CSAT and CES

​Capture a CSAT score

​Add a comment to a CSAT response

​Query CSAT tools and responses

​Forms

​List the company’s forms

​Get the definition of a form

​Submit a form response

​List the responses of a form

​Flows

​Invitations

​Quarantines

​NPS Reports

​Company NPS report

​NPS report for a tool

​External Trackers

​Model

​List the company’s active trackers

​List trackers assigned to a woku

​Assign a tracker value to a woku

​Delete a tracker value from a woku

​Search wokus by tracker

​Trackers on VoC tools (NPS, CSAT, CES, forms, flows)

​List trackers assigned to a tool

​Assign a tracker value to a tool

​Delete a tracker value from a tool

​Ticket destinations

​Model

​List the ticket destinations

​Get a ticket destination

​Create a ticket destination

​Update a ticket destination

​Delete a ticket destination

​Action plan groups

​Model

​List the action plan groups

​Get an action plan group

​Create an action plan group

​Update an action plan group

​Enable or disable a group

​Delete an action plan group

​Action plans

​Model

​List the action plans

​Get an action plan

​Send a plan to a destination

​Tasks of a plan

​Change the state of a plan

​Ingestion and extraction limits

​Handling 429 (Too Many Requests)

​Pagination in extraction

​Common errors

​Inaccessible file URL

​Duplicate secondary key

​403 on every call

​Contact and support

Interactive reference

Introduction

Base URL

Authentication

Company

Get the current company

Wokus

Create a woku with a file URL

Create a woku with a file (multipart)

Get the data of a woku

List the company’s wokus

Get a woku with statistics

List the reviews of a woku

Rate with a text review

Rate with an audio review

Share a woku by email

Mobile SDK captures

NPS responses

Capture an NPS score

Add a review to an NPS score

Query NPS Tools and responses

CSAT and CES

Capture a CSAT score

Add a comment to a CSAT response

Query CSAT tools and responses

Forms

List the company’s forms

Get the definition of a form

Submit a form response

List the responses of a form

Flows

Invitations

Quarantines

NPS Reports

Company NPS report

NPS report for a tool

External Trackers

Model

List the company’s active trackers

List trackers assigned to a woku

Assign a tracker value to a woku

Delete a tracker value from a woku

Search wokus by tracker

Trackers on VoC tools (NPS, CSAT, CES, forms, flows)

List trackers assigned to a tool

Assign a tracker value to a tool

Delete a tracker value from a tool

Ticket destinations

Model

List the ticket destinations

Get a ticket destination

Create a ticket destination

Update a ticket destination

Delete a ticket destination

Action plan groups

Model

List the action plan groups

Get an action plan group

Create an action plan group

Update an action plan group

Enable or disable a group

Delete an action plan group

Action plans

Model

List the action plans

Get an action plan

Send a plan to a destination

Tasks of a plan

Change the state of a plan

Ingestion and extraction limits

Handling 429 (Too Many Requests)

Pagination in extraction

Common errors

Inaccessible file URL

Duplicate secondary key

403 on every call

Contact and support