> ## Documentation Index > Fetch the complete documentation index at: https://woku.app/docs/llms.txt > Use this file to discover all available pages before exploring further. # Assign a tracker value to a VoC entity by tracker name (upsert) > Idempotent. If `(entityType, id, trackerName)` already has a value, it is **overwritten**. The server resolves the tracker by name within the caller's company. Fails with 404 if the tracker name is unknown to the company, 400 if the entity type is unsupported or the tracker is inactive, 403 if the entity belongs to another company. ## OpenAPI ````yaml /openapi-v1.json post /v1/external-trackers/{entityType}/{id} openapi: 3.0.3 info: title: Woku Client API v1 description: >- Public Woku Client API. Switch the version selector at the top to view the v0 reference. This spec covers: - **Wokus** — create wokus, fetch review data, submit text/voice reviews, share by email. - **Companies** — `GET /companies/me` returns the caller company. - **Reports** — company-wide and per-tool NPS reports. - **External Trackers** — tag your Wokus with identifiers from third-party systems (CRM transaction id, ERP order id, etc.) and look them up later. ## Authentication All endpoints require a Bearer token in the `Authorization` header. Obtain your company API key from the Woku dashboard. ``` Authorization: Bearer your_api_key_here ``` ## Base URL Production: `https://clientapi.woku.app` ## Model (External Trackers) - **Tracker definition** (`ExternalTracker`): a per-company catalog entry like `{ name: 'trr', system: 'crm interno', description: '...' }`. Defined by an admin in the Woku dashboard. - **Tracker value** (`WokuExternalTrackerValue`): a string value bound to a (Woku, Tracker) pair. Multiple Wokus may share the same value. version: 1.0.0 contact: name: Woku Support url: https://woku.app email: team@woku.app servers: - url: https://clientapi.woku.app description: Production server security: [] tags: - name: Wokus description: >- Create wokus, fetch review data, submit text and voice reviews, share review links by email. - name: Companies description: Caller-company endpoint. - name: Reports description: NPS reports for the caller company and individual NPS tools. - name: NPS description: >- Capture NPS scores (company-level or per NPS tool) and fetch NPS tool definitions. - name: CSAT description: >- Capture CSAT (1-5 satisfaction) scores company-level or per CSAT tool, fetch tool definitions and responses, and submit text and voice feedback. - name: CES description: >- Capture CES (effort) scores company-level or per CES tool, fetch tool definitions and responses, and submit text and voice feedback. - name: External Trackers description: >- Tag Wokus with identifiers from external systems and look them up by name + value. - name: Quarantines description: >- Check whether a respondent is currently quarantined before prompting for feedback. - name: Invitations description: >- Survey distribution: send NPS surveys, forms and woku review invitations by email or WhatsApp. - name: Forms description: Fetch form definitions and submit responses from your own UI. - name: Flows description: Render flow journeys (ordered wokus with an optional NPS) in your own app. - name: Captures description: Mobile SDK capture ingestion paths: /v1/external-trackers/{entityType}/{id}: post: tags: - External Trackers summary: Assign a tracker value to a VoC entity by tracker name (upsert) description: >- Idempotent. If `(entityType, id, trackerName)` already has a value, it is **overwritten**. The server resolves the tracker by name within the caller's company. Fails with 404 if the tracker name is unknown to the company, 400 if the entity type is unsupported or the tracker is inactive, 403 if the entity belongs to another company. operationId: v1AssignEntityExternalTracker parameters: - name: entityType in: path required: true description: >- VoC entity type that carries the tracker value. `woku` is not allowed here; use the dedicated `/v1/external-trackers/wokus/{wokuId}` routes. schema: type: string enum: - nps - csat - ces - form - flow example: nps - name: id in: path required: true description: MongoDB ObjectId of the VoC entity. schema: type: string pattern: ^[0-9a-fA-F]{24}$ example: 507f1f77bcf86cd799439abc requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AssignExternalTrackerRequest' examples: trr: summary: Tag an NPS response with a CRM transaction id value: name: trr value: TX-2026-00043 sku: summary: Tag a CES response with a product SKU value: name: sku value: WK-PRO-2024-BLUE responses: '201': description: Value assigned (created) or updated content: application/json: schema: $ref: '#/components/schemas/V1EntityExternalTrackerValue' '400': description: Unsupported entity type, tracker inactive or validation error content: application/json: schema: $ref: '#/components/schemas/ValidationError' '403': description: Entity does not belong to the caller's company content: application/json: schema: $ref: '#/components/schemas/ForbiddenError' '404': description: Tracker name not found or entity not found content: application/json: schema: $ref: '#/components/schemas/NotFoundError' security: - BearerAuth: [] components: schemas: AssignExternalTrackerRequest: type: object required: - name - value properties: name: type: string description: Name of the company-level tracker definition the value belongs to. example: trr maxLength: 60 value: type: string description: External identifier value (always stored as string). example: TX-2026-00043 maxLength: 500 V1EntityExternalTrackerValue: type: object description: >- Value of a tracker bound to a specific VoC entity (NPS/CSAT/CES tool, Form or Flow). The polymorphic `(entityType, entityId)` pair generalizes what `WokuExternalTrackerValue` does for Wokus. required: - _id - companyId - entityType - entityId - trackerId - value properties: _id: type: string example: 507f1f77bcf86cd799439015 companyId: type: string example: 507f1f77bcf86cd799439012 entityType: type: string description: VoC entity type that carries this value. enum: - nps - csat - ces - form - flow example: nps entityId: type: string description: VoC entity this value belongs to. example: 507f1f77bcf86cd799439abc trackerId: type: string description: Reference to the company-level tracker definition. example: 507f1f77bcf86cd799439014 value: type: string description: External identifier (e.g. CRM transaction id). example: TX-2026-00043 maxLength: 500 createdAt: type: string format: date-time updatedAt: type: string format: date-time ValidationError: type: object properties: statusCode: type: integer example: 400 message: oneOf: - type: string - type: array items: type: string error: type: string example: Bad Request ForbiddenError: type: object properties: statusCode: type: integer example: 403 message: type: string example: Authentication required error: type: string example: Forbidden NotFoundError: type: object properties: statusCode: type: integer example: 404 message: type: string example: External tracker not found error: type: string example: Not Found securitySchemes: BearerAuth: type: http scheme: bearer description: >- Company API key. Obtain this from your Woku dashboard under Settings > API Keys. The same key used for the v0 endpoints. ````