Saltar al contenido principal
Available on every plan, including the free one. The v1 API and the official SDKs are enabled for every woku account. See the plans.
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.

Official SDKs

If you work in JavaScript/TypeScript or Python, you do not need to build the requests by hand. The official server-side SDKs wrap this same v1 API with a typed client that adds retries, idempotency and automatic pagination. You initialize the client with your Company Key once:
Both authenticate with the same Company Key described in Authentication.

Introduction

The woku API lets you operate all feedback tools programmatically: wokus, NPS, CSAT, CES, forms and flows, as well as invitations, external trackers, ticket destinations and action plans. The typical use cases:
  1. Create wokus automatically when an event occurs in your application (for example, closing a sale, ending a training session, delivering a product).
  2. 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.
  3. Send surveys by email or WhatsApp to recipient lists from your backend.
  4. Capture feedback from your mobile app with a single idempotent endpoint, designed for the React Native SDK.
  5. Tag tools with identifiers from your systems (CRM, ERP, ticketing) to later search across them.
  6. Extract responses and reports into your dashboards and internal systems.
  7. Configure where support tickets land (Zendesk, your own service or email) and how they are routed based on your trackers.
  8. Manage AI-generated action plans: approve them and work them inside woku.
All calls are HTTP with JSON or multipart/form-data and respond with consistent structures.

Base URL

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:
The key is obtained by the company owner from the company’s Information section, in the admin application: https://admin.woku.app woku application interface in the company's 'Information' section. It shows the company data, including the logo, name, website, and links to social networks such as Instagram, Facebook, LinkedIn, X (formerly Twitter), TikTok, and GitHub. At the bottom, the 'Get Key' option is highlighted, which copies the company key for clientapi.woku.app.
View of the company information window.
A missing or invalid key returns 401 Unauthorized. A valid key without access to the resource returns 403 Forbidden.
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
Headers
  • Authorization: Bearer <Company-Key>
Responses
  • 200 OK: Returns the company object.
  • 401 Unauthorized: Missing or invalid key.
  • 403 Forbidden: The key is valid but the company has no access (for example, an inactive subscription or an IP outside the allowlist).

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
Headers
  • Content-Type: application/json
  • Authorization: Bearer <Company-Key>
Body
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.
  • 401 Unauthorized: Missing or 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
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).
  • 401 Unauthorized: Missing or invalid key.

Upload media for reuse in a Woku or journey

If you need a fileId before creating an instrument, send the file in the file field to POST /v1/woku-media with multipart/form-data and your Company Key. The 201 response contains fileId, filename, and type (image or video). Use that fileId with the MCP create_woku or set_journey_moment_media tool, or as toolSpec.fileId on an API Woku moment. Real JPEG, PNG, WebP, or GIF images up to 10 MB are normalized to WebP within 1080 × 1080 pixels while preserving aspect ratio; MP4 videos can be up to 25 MB. The service inspects the contents instead of trusting the supplied extension or Content-Type. An MP4 must contain a decodable video frame. Invalid media returns 400; a multipart upload exceeding 25 MB returns 413. Codex or Claude Code can upload a local file from its terminal; see the example.

Get the data of a woku

Retrieves the woku along with its ratings and reviews. Endpoint
Headers
  • Authorization: Bearer <Company-Key>
Path params
  • id (string, required): Woku identifier.
Responses
  • 200 OK: Woku object with its reviews.
  • 401 Unauthorized: Missing or 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
Query params
  • page (number, optional): Defaults to 1.
  • limit (number, optional): Defaults to 20.
Responses
  • 200 OK: Paginated list of wokus.
  • 401 Unauthorized: Missing or invalid key.

Get a woku with statistics

Returns a woku with its aggregated review statistics. Endpoint
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. Each review includes responseChannel: the channel it came through (whatsapp, email, review-app, widget-web, mobile-sdk, api, or a custom value you define); it is null on historical responses. Endpoint
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
Headers
  • Content-Type: application/json
  • Authorization: Bearer <Company-Key>
Body
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.
  • responseChannel (string, optional, max 48): Channel the response came through. Canonical values: whatsapp, email, review-app, widget-web, mobile-sdk, api. You can also send your own custom value, which replaces the default. Defaults to api.
Responses
  • 201 Created: Review recorded (held: false). If the company has no opinion credits left, the response carries held: true: the opinion is kept on hold, the id belongs to that hold and not to a review, and it is recorded automatically once the company tops up its credits.
  • 400 Bad Request: Validation failed.
  • 401 Unauthorized: Missing or invalid key.
  • 404 Not Found: The woku does not exist.

Rate with an audio review

Upload an audio file along with the rating. Endpoint
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).
  • responseChannel (string, optional, max 48): Channel the response came through. Canonical values: whatsapp, email, review-app, widget-web, mobile-sdk, api. You can also send your own custom value, which replaces the default. Defaults to api.
Responses
  • 201 Created: Review recorded (held: false). If the company has no opinion credits left, the response carries held: true: the opinion is kept on hold, the id belongs to that hold and not to a review, and it is recorded automatically once the company tops up its credits.
  • 400 Bad Request: Validation failed.
  • 401 Unauthorized: Missing or invalid key.
  • 404 Not Found: The woku does not exist.

Share a woku by email

Sends the woku to one or more recipients. It is the same flow that starts from the share interface. Endpoint
Headers
  • Content-Type: application/json
  • Authorization: Bearer <Company-Key>
Body (single recipient)
Body (multiple recipients)
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.).
  • 401 Unauthorized: Missing or 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
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)
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).
  • 401 Unauthorized: Missing or invalid key.
  • 409 Conflict: The tool accepts one response per client and this client already answered (code: "ALREADY_RESPONDED").

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
Body
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): Channel the response came through. Canonical values: whatsapp, email, review-app, widget-web, mobile-sdk, api. You can also send your own custom value, which replaces the default. 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.
  • 409 Conflict: The tool accepts one response per client and this client already answered (code: "ALREADY_RESPONDED").

Add a review to an NPS score

Once the score is created, you can attach an optional text or audio review to it. Endpoints
  • 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. Each response includes responseChannel: the channel it came through (whatsapp, email, review-app, widget-web, mobile-sdk, api, or a custom value you define); it is null on historical responses.

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
Body
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): Channel the response came through. Canonical values: whatsapp, email, review-app, widget-web, mobile-sdk, api. You can also send your own custom value, which replaces the default. 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.
  • 409 Conflict: The tool accepts one response per client and this client already answered (code: "ALREADY_RESPONDED").

Add a comment to a CSAT response

Endpoints
  • 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.
Each response includes responseChannel: the channel it came through (whatsapp, email, review-app, widget-web, mobile-sdk, api, or a custom value you define); it is null on historical responses. 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.

NPS, CSAT and CES response settings

POST /v1/{nps,csat,ces}-tools and PATCH /v1/{nps,csat,ces}-tools/:id take two settings, and every tool returns them:
  • anonymousDisabled (boolean): only identified responses (email or phone) are accepted.
  • onlyOneResponsePerClient (boolean): each identified client answers only once. A second answer gets 409 Conflict with code: "ALREADY_RESPONDED". Anonymous answers do not count.
Both can change even after the tool has responses. Then the PATCH must carry only these fields, because the survey text is fixed.

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
Query params
  • page (number, optional).
  • limit (number, optional).
Responses
  • 200 OK: Paginated list of forms.
  • 401 Unauthorized: Missing or 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
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
Body
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): Channel the response came through. Canonical values: whatsapp, email, review-app, widget-web, mobile-sdk, api. You can also send your own custom value, which replaces the default. 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. Each response includes responseChannel: the channel it came through (whatsapp, email, review-app, widget-web, mobile-sdk, api, or a custom value you define); it is null on historical responses. Endpoint
Responses
  • 200 OK: Paginated list of responses.
  • 403 Forbidden: The form belongs to another company.
  • 404 Not Found: The form does not exist.

Flows

A flow chains ordered steps, each a woku or an NPS, CSAT or CES tool, into a survey sequence. It differs from Customer journeys, which evaluate business moments and can advance by delays or webhooks. With the flow data you can render its sequence in your application and capture with the existing endpoints (POST /v1/wokus/:id/textnotes, POST /v1/nps, POST /v1/csat, etc.). A flow does not live inside folders.
  • GET /v1/flows: Paginated list of your company’s flows, each with its steps.
  • GET /v1/flows/:id: Flow data: ordered steps with their tools, branding and linked NPS.
  • POST /v1/flows: Creates a flow with a name and 1 to 20 steps. Accepts X-Woku-Idempotency-Key.
  • PATCH /v1/flows/:id: Changes the name or replaces the full list of steps.
  • DELETE /v1/flows/:id: Deletes the flow. Its tools and responses are kept.
Each step is { "type": "woku" | "nps" | "csat" | "ces", "toolId": "<id>" }. A tool appears once, all of them must belong to your company, and a closed woku or one-review-per-customer woku cannot be a step. For an nps step, your company id as toolId is the company-level NPS.
Responses
  • 200 OK or 201 Created: Flow data or paginated list.
  • 400 Bad Request: Invalid steps (repeated, too many or a tool that is not allowed).
  • 403 Forbidden: The flow belongs to another company.
  • 404 Not Found: The flow or a tool of the steps 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
Body
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.

Folders and tools

One folder tree holds wokus and NPS, CSAT and CES tools. The Folders and tools guide explains the model; this section summarizes the endpoints. All of them use your Company Key.

Folders

  • GET /v1/folders: lists every folder, or only the subfolders of parentFolderId. Accepts q to search by name.
  • POST /v1/folders: creates a folder (name, and optionally parentFolderId and color). Accepts X-Woku-Idempotency-Key.
  • GET /v1/folders/:id: one folder with its path, its origin (and integrationProvider on integration folders) and the stats of its subtree.
  • PATCH /v1/folders/:id: changes name, color (null clears the color) or whatsappAlertRecipients (replaces the WhatsApp numbers alerted on improvement comments of the folder, or on every review with allReviews: true; [] clears them).
  • PATCH /v1/folders/:id/move: moves the folder under parentFolderId, or to the root with null.
  • DELETE /v1/folders/:id: deletes the folder. Its content moves up to the parent folder. If ticket destinations or plan groups are configured on that folder, they are deleted with it together with their tickets and plans: without ?confirmDependents=true the response is 409 with code: "FOLDER_HAS_DEPENDENTS" and the list in dependents.
  • GET /v1/folders/:id/report: AI report over every tool of the folder and its subfolders (regenerate, lang).
  • GET /v1/folders/:id/metrics: figures of each tool of the folder and its subfolders over a period (days: 7, 30, 90 or 0 for the whole history) against the previous period, with the daily sums and the histogram of scores.
  • GET /v1/folders/:id/csv: CSV with one row per response, or only those of a period with from and to (ISO 8601, to exclusive).
  • GET /v1/folders/:id/pdf: the folder report as a PDF, with a breakdown per type (lang).

Tools

  • GET /v1/tools: folders and tools of every type in a cursor-paginated list, with search (q), filters (types, folderId, scope, dates, trackers), sorting (sort, also by the latest response with lastResponse) and counts per type. foldersLimit and foldersCursor page the folders (“see more”; the response carries foldersNextCursor).
  • GET /v1/tools/stats: figures per type on their native scale, for the company or a folder (folderId) and a period (from, to).
  • GET /v1/tools/metrics: the metrics of the company report of one type (type: woku, nps, csat or ces), with the same per-tool figures as GET /v1/folders/:id/metrics for every tool of that type in the company (root and folders), over a period (days or from/to) against the previous one.
  • POST /v1/tools/move: moves up to 200 items of mixed types to a folder (folderId) or to the root (null).
  • folderId when creating with POST /v1/nps-tools, POST /v1/csat-tools and POST /v1/ces-tools, and PATCH /v1/{nps,csat,ces}-tools/:id/move to move them.

Folder participants

The list of people who should answer the tools of the folder and who already did. Details in Folder participants.
  • GET /v1/folders/:id/participants: the list and, per tool, responded, missing, repeated, outsideList and anonymousAllowed.
  • PUT /v1/folders/:id/participants and POST /v1/folders/:id/participants: replace the list or add people to it (text, one person per line, up to 500).
  • DELETE /v1/folders/:id/participants/:participantId and DELETE /v1/folders/:id/participants: remove one person or delete the list.
  • POST /v1/folders/:id/participants/resend: resends a tool to the missing, by email or WhatsApp.

Scheduled report emails

The PDF report of a folder or of a tool by email, every month, every two weeks, every week or once. Details in Scheduled report emails.
  • GET /v1/report-subscriptions and POST /v1/report-subscriptions: list and create scheduled reports.
  • PATCH /v1/report-subscriptions/:id: edits, pauses or resumes a recurring one.
  • DELETE /v1/report-subscriptions/:id: deletes it.
  • POST /v1/report-subscriptions/:id/send: sends it now.

Journeys in folders

  • GET /v1/journey-folders: status of the journey folder organization (enabled, organizing, pending).
  • POST /v1/journey-folders/organize: switches it on and runs a one-off pass in the background (202; 409 if one is already running).
  • folderId and momentFolders on GET /v1/journeys and GET /v1/journeys/:id, and origin on the folders of GET /v1/folders and GET /v1/tools.

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
Headers
  • Authorization: Bearer <Company-Key>
Responses
  • 200 OK: Report with the distribution of promoters, passives and detractors, and the resulting NPS score.
  • 401 Unauthorized: Missing or invalid key.

Company woku report

Returns the AI report over every woku of your company, at the root and in every folder, with the same text sections as a folder report. Endpoint
Headers
  • Authorization: Bearer <Company-Key>
Responses
  • 200 OK: Company woku report.
  • 401 Unauthorized: Missing or 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
Headers
  • Authorization: Bearer <Company-Key>
Path params
  • id (string, required): NPS Tool identifier.
Responses
  • 200 OK: NPS Tool report.
  • 400 Bad Request: Malformed id.
  • 401 Unauthorized: Missing or 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
Query params
  • page (number, optional).
  • limit (number, optional).
Responses
  • 200 OK: Paginated list of tracker definitions.
  • 401 Unauthorized: Missing or invalid key.

List trackers assigned to a woku

Endpoint
Responses
  • 200 OK: Trackers assigned to the woku.
  • 401 Unauthorized: Missing or invalid key.

Assign a tracker value to a woku

Creates or updates (upsert) the value of a tracker on a woku. Endpoint
Body
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.
  • 401 Unauthorized: Missing or invalid key.
  • 404 Not Found: The woku or the tracker does not exist.

Delete a tracker value from a woku

Endpoint
Responses
  • 200 OK: Deleted.
  • 401 Unauthorized: Missing or 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
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.
  • 401 Unauthorized: Missing or 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
Example: GET /v1/external-trackers/nps/671000000000000000000001. Responses
  • 200 OK: Trackers assigned to the tool.
  • 400 Bad Request: Unsupported tool type.
  • 401 Unauthorized: Missing or invalid key.

Assign a tracker value to a tool

Creates or updates (upsert) the value of a tracker on the tool. Endpoint
Body
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
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: Zendesk, 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, 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.
    • 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 authenticates 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.
  • scopeKind (optional, trackers by default): trackers routes by routingConditions; folder routes by a tool folder and receives the tickets of every tool inside it, at any depth. Never both: with folder no conditions are sent, and switching to folder clears the existing ones.
  • folderId (required with scopeKind: "folder"): id of the folder. If you delete that folder, the destination is deleted with it, together with its tickets.

List the ticket destinations

Endpoint
Query params
  • folderId (string, optional): only destinations by folder that listen to that folder (configured on it or on a parent folder).
Responses
  • 200 OK: List of destinations (without credentials).
  • 401 Unauthorized: Missing or invalid key.

Get a ticket destination

Endpoint
Responses
  • 200 OK: Destination.
  • 401 Unauthorized: Missing or invalid key.
  • 404 Not Found: The destination does not exist.

Create a ticket destination

Endpoint
Headers
  • Content-Type: application/json
  • Authorization: Bearer <Company-Key>
Body (example with Zendesk, routed by any value of a tracker)
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.
  • 401 Unauthorized: Missing or invalid key.

Update a ticket destination

Endpoint
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)
Responses
  • 200 OK: Destination updated.
  • 400 Bad Request: Validation failed.
  • 401 Unauthorized: Missing or invalid key.
  • 404 Not Found: The destination does not exist.

Delete a ticket destination

Endpoint
Its routing conditions live on the destination and disappear with it. Responses
  • 200 OK: { "deleted": true }.
  • 401 Unauthorized: Missing or 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

  • scopeKind (optional, trackers by default): trackers listens by conditions; folder listens to every tool inside a folder, at any depth. Never both.
  • conditions (required with scopeKind: "trackers", minimum 1 row, up to 20; not sent with folder): same rules as the routingConditions of ticket destinations (operator equals or any, relationToPrevious to build AND/OR).
  • folderId (required with scopeKind: "folder"): id of the folder. If you delete that folder, the group is deleted with it, together with its plans.
  • 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
Query params
  • search (string, optional): free search by name, description and condition values.
  • folderId (string, optional): only groups by folder that listen to that folder (configured on it or on a parent folder).
Responses
  • 200 OK: List of groups.
  • 401 Unauthorized: Missing or invalid key.

Get an action plan group

Endpoint
Responses
  • 200 OK: Group.
  • 401 Unauthorized: Missing or invalid key.
  • 404 Not Found: The group does not exist.

Create an action plan group

Endpoint
Headers
  • Content-Type: application/json
  • Authorization: Bearer <Company-Key>
Body
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.
  • 401 Unauthorized: Missing or invalid key.

Update an action plan group

Endpoint
All fields are optional; sending description: "" clears it. Responses
  • 200 OK: Group updated.
  • 400 Bad Request: Validation failed.
  • 401 Unauthorized: Missing or invalid key.
  • 404 Not Found: The group does not exist.

Enable or disable a group

Endpoint
Body
Responses
  • 200 OK: Group updated.
  • 401 Unauthorized: Missing or invalid key.
  • 404 Not Found: The group does not exist.

Delete an action plan group

Endpoint
The already-generated plans keep their own frozen detail and only reference the group by id. Responses
  • 200 OK: { "deleted": true }.
  • 401 Unauthorized: Missing or 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 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
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.
  • 401 Unauthorized: Missing or invalid key.

Get an action plan

Endpoint
Returns the complete plan, including the frozen evidence detail and the send status. Responses
  • 200 OK: Plan.
  • 401 Unauthorized: Missing or invalid key.
  • 404 Not Found: The plan does not exist.

Manage a plan inside woku

Endpoint
The plan must be approved (or delivery_error to retry). With provider: "internal" the plan is managed inside woku: it carries no target and applies immediately (the plan moves to in_progress). Body
Fields
  • provider (string, required): internal (manage the plan inside woku). It is the only provider available on the public API.
  • resourceLabel (string, optional, max 300): human-readable description of the destination.
Responses
  • 202 Accepted: { "status": "managed" }.
  • 401 Unauthorized: Missing or 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
  • 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.
  • 401 Unauthorized: Missing or 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
No body. Each action requires the plan to be in a specific source state: Responses
  • 200 OK: Plan updated.
  • 401 Unauthorized: Missing or 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:
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.

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.

401 on every call

The key is missing, wrong or was regenerated. Get it again from admin.woku.app → Company information → Get Key.

403 on every call

The key is valid but the company has no access: the subscription is not active or the call comes from an IP outside the allowlist in Company → Security.

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).

Provenance and follow-up

Captures accept collectionKind: "standalone" | "flow" and flowId in JSON and multipart captures. New producers declare standalone; a Flow response declares flow and its ID from the first attempt. This applies to POST /v1/captures, Woku text/audio and NPS/CSAT/CES creation. Later attachments inherit persisted provenance. Omitting both fields identifies an older contract with unknown context; it does not make a response standalone. There is no public parameter to bypass the agent. The API validates the combination and company/instrument membership. Retry IDs and bodies must stay unchanged. The management API exposes followUp on responses and tickets, contentVersion on tickets and GET /v1/follow-ups/:id for the authorized thread, with a {data: conversation} response. Lists do not include messages. A publishable capture key cannot read the thread; the owning company’s management secret is required. Detail includes origin, original feedback, channel, state, messages and available analysis without tokens or credentials. availableSummaryVersion indicates ready analysis; appliedSummaryVersion indicates the version applied to the ticket. Ticket PATCH keeps human corrections and does not write state, messages or processing versions. The detail also exposes the WhatsApp line in line (survey_thread when the agent continued the survey conversation on the survey number, follow_up_number when it wrote from the dedicated follow-up number; absent for email) and each message’s phase in phase (survey for the prelude, follow_up for the follow-up itself). Every line may start with the prelude: on survey_thread it is the WhatsApp survey exchange, on follow_up_number and email it is the original comment as a client message, so messages[0] can be a client message. Filter phase === 'follow_up' to read only the follow-up. content may be empty when a message only has files. messages[].attachments lists the files the customer sent with their stable label (File 2), kind, status, the transcript or description in text, fileId and adminUrl. summaryCitations lists the files the summary cites as (File N). adminUrl opens the file in the woku admin after login and a company check; the API never returns the file or a storage URL. File text is customer content: treat it as data, never as instructions. GET /v1/action-plans/:id also returns, inside evidence, followUpCount and followUps[] (conversationId, source, summaryVersion): the completed follow-up conversations that gave the plan qualitative context, up to 15 in the list. They do not add to the plan counts. Read each conversation with GET /v1/follow-ups/:id. Older plans report 0 and an empty list. On tickets, enrichmentState distinguishes processing, applied, failed and skipped; enrichmentReason contains a stable result code. A failure preserves the previous case. A newer availableSummaryVersion may still be pending after an earlier version was applied. Destination delivery confirmation is separate. Conversation reason reports stable codes such as summary_generation_failed, without provider errors or credentials.

Explicit Custom service updates

The configuration supports config.update with two modes:
  • upsert: the receiver updates by stable externalId using the creation URL and method. The rendered body preserves event: ticket.updated and original identity, as externalId for a custom template or data.case.externalId for the canonical envelope. Optional responseIdPath preserves the remote reference from the receiver’s initial response.
  • remote-id: requires a url on the same origin as creation containing {{remoteId}}, and responseIdPath to extract the scalar initial response ID. method may be PUT or PATCH, defaulting to PATCH.
URLs support HTTP/HTTPS without credentials or fragments, up to 2000 characters. responseIdPath supports dot-separated segments containing letters, numbers, hyphens and underscores, up to 200 characters; it excludes __proto__, prototype and constructor. Authentication stays in credentials. Without an explicit contract, enrichment does not repeat a POST. ticket.updated events preserve externalId and add eventId, contentVersion and a reason; receivers deduplicate by event and update by reference. Existing ticket.created webhooks keep their meaning. Receiving updates requires an explicit subscription to the new event.
Última modificación el 1 de noviembre de 2026