Sign in

8d06d9728138

latestOpenAPI 3.1.0Apache-2.0raw.githubusercontent.com2026-08-053042165.2 KB
Feedback Records

Create a new feedback record

Creates a new feedback record data point

post/v1/feedback-records

Request body

collected_atstring date-time

When the feedback was collected (defaults to now). Must be between 1970-01-01 and 2080-12-31.

field_idstring required

Identifier for the question/field. NULL bytes not allowed.

field_labelstring nullable

The actual question text

field_group_idstring

Stable identifier grouping related fields (for ranking, matrix, grid questions). NULL bytes not allowed.

field_group_labelstring nullable

Human-readable question text for the group

field_type'text' | 'categorical' | 'nps' | 'csat' | 'ces' | 'rating' | 'number' | 'boolean' | 'date' required

Field type: text (enrichable), categorical, nps, csat, ces, rating, number, boolean, date

languagestring

ISO language code. NULL bytes not allowed.

metadataobject

User agent, device, location, referrer, tags, etc. NULL bytes (\x00 or \u0000) are not allowed in JSON keys or values.

source_idstring nullable

Reference to survey/form/ticket ID

source_namestring nullable

Human-readable name

source_typestring required

Type of feedback source (e.g., survey, review, feedback_form). NULL bytes not allowed.

submission_idstring required

Identifier for the logical submission this record belongs to (tenant-scoped). Required. Enables grouping multi-field submissions and idempotent ingestion. Unique per (tenant_id, submission_id, field_id). If a record has no logical submission, use e.g. field_id.

tenant_idstring required

Tenant/organization identifier for multi-tenancy. Required.

user_idstring

User ID (e.g., anonymous ID or email hash)

value_booleanboolean

For yes/no questions

value_datestring date-time

For date responses. Must be between 1970-01-01 and 2080-12-31.

value_numbernumber double

For ratings, NPS scores, numeric responses. Must be between -1e15 and +1e15.

value_textstring nullable

For open-ended text responses. Omit or null if not applicable. NULL bytes not allowed when present.

value_idstring nullable

Stable id of the selected option in the source system (e.g. a survey choice id or matrix column id), stored alongside value_text so selected-choice answers keep a durable identity across label edits and languages. Opaque to Hub (not validated). Null for free-text/"other" answers, non-choice fields, and sources without option ids. NULL bytes not allowed when present.

Example request

{
  "field_id": "q1",
  "field_label": "How satisfied are you?",
  "field_group_id": "feature_priority",
  "field_group_label": "Rank these features by importance",
  "field_type": "rating",
  "language": "en",
  "source_id": "survey-123",
  "source_name": "Q1 NPS Survey",
  "source_type": "survey",
  "submission_id": "550e8400-e29b-41d4-a716-446655440000",
  "tenant_id": "org-123",
  "user_id": "user-abc-123",
  "value_boolean": true,
  "value_number": 9,
  "value_text": "Great service!",
  "value_id": "opt_very_satisfied"
}

Response

Created

collected_atstring date-time required

When the feedback was collected

created_atstring date-time required

When this record was created

field_idstring required

Identifier for the question/field

field_labelstring

The actual question text

field_group_idstring

Stable identifier grouping related fields (for ranking, matrix, grid questions)

field_group_labelstring

Human-readable question text for the group

field_type'text' | 'categorical' | 'nps' | 'csat' | 'ces' | 'rating' | 'number' | 'boolean' | 'date' required

Type of field

idstring uuid required

UUIDv7 primary key

languagestring

ISO language code. NULL bytes not allowed.

metadataobject

Additional context

sentiment'very_negative' | 'negative' | 'neutral' | 'positive' | 'very_positive' | 'mixed'

Sentiment polarity inferred from value_text (sentiment enrichment). Read-only; absent until the record is enriched.

sentiment_scorenumber double

Signed sentiment polarity from -1.0 (very negative) to 1.0 (very positive) (sentiment enrichment). Read-only; absent until the record is enriched.

emotionsstring[]

Emotions inferred from value_text (emotion enrichment); multi-label from a fixed set. Read-only; absent until the record is enriched, and never an empty array.

source_idstring

Reference to survey/form/ticket ID

source_namestring

Human-readable name

source_typestring required

Type of feedback source

submission_idstring required

Identifier for the logical submission this record belongs to (required).

tenant_idstring required

Tenant/organization identifier. NULL bytes not allowed.

translation_lang_keystring

BCP-47 target locale that value_text_translated was produced in (language enrichment). Read-only; absent until the record is enriched.

updated_atstring date-time required

When this record was last updated

user_idstring

User ID (e.g., anonymous ID or email hash)

value_booleanboolean

Boolean response

value_datestring date-time

Date response

value_numbernumber double

Numeric response

value_textstring

Text response. NULL bytes not allowed.

value_idstring

Stable id of the selected option in the source system (e.g. a survey choice id), stored alongside value_text for durable option identity. Opaque to Hub. Absent for free-text/non-choice answers. NULL bytes not allowed.

value_text_translatedstring

value_text translated into the tenant's configured target language (language enrichment). Read-only; absent until the record is enriched.