FOformbricks
Feedback Records

Create a new feedback record

Changed on

Creates a new feedback record data point

post/v1/feedback-records

Request

  • Base URL
    http://localhost:8080
  • URL
    http://localhost:8080/v1/feedback-records
  • Auth
    HTTP bearer

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 nullable

Arbitrary context for this record, stored as JSON and returned with equivalent values (key order and number formatting are normalized): the dimensions you want to slice a dashboard by, such as channel, device, browser, OS, country, referrer, campaign, plan or tags. Values may be strings, numbers, booleans, null, or nested objects and arrays. Use snake_case keys and keep them stable across records, since a key is what a dashboard groups by: customer_tier, not a mix of customerTier and tier. Numbers keep full precision in storage (unlike value_number, which is a float64), so a large integer id round-trips exactly through this API — though a JavaScript client will still lose precision above 2^53 when it parses the response. Nothing here is redacted. Metadata is not sent to the LLM or embedding enrichment providers, unlike value_text — but it is included in the feedback_record.created and feedback_record.updated webhook payloads, so it reaches whatever URL a tenant has configured. Erasure covers metadata, with one precondition worth knowing: DELETE /v1/feedback-records matches on user_id and hard-deletes the whole row, metadata included — so a record written without a user_id cannot be reached that way. Set user_id on anything you may later have to erase. Three kinds of content are rejected with 400, because none of them can be stored: invalid UTF-8; NULL bytes or unpaired UTF-16 surrogates, in keys or values; and numbers outside the storable numeric range.

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. U+FFFD is not allowed (it stands in for invalid UTF-8 or an unpaired surrogate).

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

The type of a feedback field, which determines which value_* member carries the answer. Mirrors the field_type_enum database type; keep the three in sync.

idstring uuid required

UUIDv7 primary key

languagestring

ISO language code. NULL bytes not allowed.

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

Sentiment polarity label inferred from value_text by the sentiment enrichment: the five ordinal levels plus a distinct "mixed". Server-generated and read-only.

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.

emotionsEmotionValue[]

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.

Changes

  • ac72ae0de955Revision changes
    • warning

      changed the pattern of the request property from ^[^\x00]*$ to ^[^\x00\uFFFD]*$

    • info

      added the non-success response with the status

  • f6b8121982f4Revision changes
    • info

      added the optional property to the response with the status