# Feedback Records

## List

**get** `/v1/feedback-records`

Lists feedback records with optional filters and pagination

### Query Parameters

- `field_group_id: optional string`

  Filter by field group ID (for ranking/matrix questions). NULL bytes not allowed.

- `field_id: optional string`

  Filter by field ID. NULL bytes not allowed.

- `field_type: optional string`

  Filter by field type. NULL bytes not allowed.

- `limit: optional number`

  Number of results to return (max 1000)

- `offset: optional number`

  Number of results to skip

- `since: optional string`

  Filter by collected_at >= since (ISO 8601 format). Must be between 1970-01-01 and 2080-12-31.

- `source_id: optional string`

  Filter by source ID (NULL bytes not allowed)

- `source_type: optional string`

  Filter by source type. NULL bytes not allowed.

- `tenant_id: optional string`

  Filter by tenant ID (for multi-tenant deployments). NULL bytes not allowed.

- `until: optional string`

  Filter by collected_at <= until (ISO 8601 format). Must be between 1970-01-01 and 2080-12-31.

- `user_identifier: optional string`

  Filter by user identifier. NULL bytes not allowed.

### Returns

- `data: array of FeedbackRecordData`

  List of feedback records

  - `id: string`

    UUIDv7 primary key

  - `collected_at: string`

    When the feedback was collected

  - `created_at: string`

    When this record was created

  - `field_id: string`

    Identifier for the question/field

  - `field_type: string`

    Type of field

  - `source_type: string`

    Type of feedback source

  - `updated_at: string`

    When this record was last updated

  - `field_group_id: optional string`

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

  - `field_group_label: optional string`

    Human-readable question text for the group

  - `field_label: optional string`

    The actual question text

  - `language: optional string`

    ISO language code. NULL bytes not allowed.

  - `metadata: optional map[unknown]`

    Additional context

  - `source_id: optional string`

    Reference to survey/form/ticket ID

  - `source_name: optional string`

    Human-readable name

  - `tenant_id: optional string`

    Tenant/organization identifier. NULL bytes not allowed.

  - `user_identifier: optional string`

    User identifier

  - `value_boolean: optional boolean`

    Boolean response

  - `value_date: optional string`

    Date response

  - `value_number: optional number`

    Numeric response

  - `value_text: optional string`

    Text response. NULL bytes not allowed.

- `limit: number`

  Limit used in query

- `offset: number`

  Offset used in query

- `total: number`

  Total count of feedback records matching filters

### Example

```http
curl http://localhost:8080/v1/feedback-records \
    -H "Authorization: Bearer $HUB_API_KEY"
```

## Create

**post** `/v1/feedback-records`

Creates a new feedback record data point

### Body Parameters

- `field_id: string`

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

- `field_type: "text" or "categorical" or "nps" or 6 more`

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

  - `"text"`

  - `"categorical"`

  - `"nps"`

  - `"csat"`

  - `"ces"`

  - `"rating"`

  - `"number"`

  - `"boolean"`

  - `"date"`

- `source_type: string`

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

- `collected_at: optional string`

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

- `field_group_id: optional string`

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

- `field_group_label: optional string`

  Human-readable question text for the group

- `field_label: optional string`

  The actual question text

- `language: optional string`

  ISO language code. NULL bytes not allowed.

- `metadata: optional map[unknown]`

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

- `source_id: optional string`

  Reference to survey/form/ticket ID

- `source_name: optional string`

  Human-readable name

- `tenant_id: optional string`

  Tenant/organization identifier for multi-tenancy. NULL bytes not allowed.

- `user_identifier: optional string`

  Anonymous ID or email hash

- `value_boolean: optional boolean`

  For yes/no questions

- `value_date: optional string`

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

- `value_number: optional number`

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

- `value_text: optional string`

  For open-ended text responses. NULL bytes not allowed.

### Returns

- `FeedbackRecordData = object { id, collected_at, created_at, 17 more }`

  - `id: string`

    UUIDv7 primary key

  - `collected_at: string`

    When the feedback was collected

  - `created_at: string`

    When this record was created

  - `field_id: string`

    Identifier for the question/field

  - `field_type: string`

    Type of field

  - `source_type: string`

    Type of feedback source

  - `updated_at: string`

    When this record was last updated

  - `field_group_id: optional string`

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

  - `field_group_label: optional string`

    Human-readable question text for the group

  - `field_label: optional string`

    The actual question text

  - `language: optional string`

    ISO language code. NULL bytes not allowed.

  - `metadata: optional map[unknown]`

    Additional context

  - `source_id: optional string`

    Reference to survey/form/ticket ID

  - `source_name: optional string`

    Human-readable name

  - `tenant_id: optional string`

    Tenant/organization identifier. NULL bytes not allowed.

  - `user_identifier: optional string`

    User identifier

  - `value_boolean: optional boolean`

    Boolean response

  - `value_date: optional string`

    Date response

  - `value_number: optional number`

    Numeric response

  - `value_text: optional string`

    Text response. NULL bytes not allowed.

### Example

```http
curl http://localhost:8080/v1/feedback-records \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $HUB_API_KEY" \
    -d '{
          "field_id": "q1",
          "field_type": "rating",
          "source_type": "survey"
        }'
```

## Bulk Delete

**delete** `/v1/feedback-records`

Permanently deletes all feedback record data points matching the specified user_identifier. This endpoint supports GDPR Article 17 (Right to Erasure) requests.

### Query Parameters

- `user_identifier: string`

  Delete all records matching this user identifier (required). NULL bytes not allowed.

- `tenant_id: optional string`

  Filter by tenant ID (optional, for multi-tenant deployments). NULL bytes not allowed.

### Returns

- `deleted_count: number`

  Number of records deleted

- `message: string`

  Human-readable status message

### Example

```http
curl http://localhost:8080/v1/feedback-records \
    -X DELETE \
    -H "Authorization: Bearer $HUB_API_KEY"
```

## Retrieve

**get** `/v1/feedback-records/{id}`

Retrieves a single feedback record data point by its UUID

### Path Parameters

- `id: string`

  Feedback Record ID (UUID)

### Returns

- `FeedbackRecordData = object { id, collected_at, created_at, 17 more }`

  - `id: string`

    UUIDv7 primary key

  - `collected_at: string`

    When the feedback was collected

  - `created_at: string`

    When this record was created

  - `field_id: string`

    Identifier for the question/field

  - `field_type: string`

    Type of field

  - `source_type: string`

    Type of feedback source

  - `updated_at: string`

    When this record was last updated

  - `field_group_id: optional string`

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

  - `field_group_label: optional string`

    Human-readable question text for the group

  - `field_label: optional string`

    The actual question text

  - `language: optional string`

    ISO language code. NULL bytes not allowed.

  - `metadata: optional map[unknown]`

    Additional context

  - `source_id: optional string`

    Reference to survey/form/ticket ID

  - `source_name: optional string`

    Human-readable name

  - `tenant_id: optional string`

    Tenant/organization identifier. NULL bytes not allowed.

  - `user_identifier: optional string`

    User identifier

  - `value_boolean: optional boolean`

    Boolean response

  - `value_date: optional string`

    Date response

  - `value_number: optional number`

    Numeric response

  - `value_text: optional string`

    Text response. NULL bytes not allowed.

### Example

```http
curl http://localhost:8080/v1/feedback-records/$ID \
    -H "Authorization: Bearer $HUB_API_KEY"
```

## Delete

**delete** `/v1/feedback-records/{id}`

Permanently deletes a feedback record data point

### Path Parameters

- `id: string`

  Feedback Record ID (UUID)

### Example

```http
curl http://localhost:8080/v1/feedback-records/$ID \
    -X DELETE \
    -H "Authorization: Bearer $HUB_API_KEY"
```

## Update

**patch** `/v1/feedback-records/{id}`

Updates specific fields of a feedback record data point

### Path Parameters

- `id: string`

  Feedback Record ID (UUID)

### Body Parameters

- `language: optional string`

  Update language. NULL bytes not allowed.

- `metadata: optional map[unknown]`

  Update metadata. NULL bytes (\x00 or \u0000) are not allowed in JSON keys or values.

- `user_identifier: optional string`

  Update user identifier

- `value_boolean: optional boolean`

  Update boolean response

- `value_date: optional string`

  Update date response. Must be between 1970-01-01 and 2080-12-31.

- `value_number: optional number`

  Update numeric response. Must be between -1e15 and +1e15.

- `value_text: optional string`

  Update text response. NULL bytes not allowed.

### Returns

- `FeedbackRecordData = object { id, collected_at, created_at, 17 more }`

  - `id: string`

    UUIDv7 primary key

  - `collected_at: string`

    When the feedback was collected

  - `created_at: string`

    When this record was created

  - `field_id: string`

    Identifier for the question/field

  - `field_type: string`

    Type of field

  - `source_type: string`

    Type of feedback source

  - `updated_at: string`

    When this record was last updated

  - `field_group_id: optional string`

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

  - `field_group_label: optional string`

    Human-readable question text for the group

  - `field_label: optional string`

    The actual question text

  - `language: optional string`

    ISO language code. NULL bytes not allowed.

  - `metadata: optional map[unknown]`

    Additional context

  - `source_id: optional string`

    Reference to survey/form/ticket ID

  - `source_name: optional string`

    Human-readable name

  - `tenant_id: optional string`

    Tenant/organization identifier. NULL bytes not allowed.

  - `user_identifier: optional string`

    User identifier

  - `value_boolean: optional boolean`

    Boolean response

  - `value_date: optional string`

    Date response

  - `value_number: optional number`

    Numeric response

  - `value_text: optional string`

    Text response. NULL bytes not allowed.

### Example

```http
curl http://localhost:8080/v1/feedback-records/$ID \
    -X PATCH \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $HUB_API_KEY" \
    -d '{}'
```

## Domain Types

### Feedback Record Data

- `FeedbackRecordData = object { id, collected_at, created_at, 17 more }`

  - `id: string`

    UUIDv7 primary key

  - `collected_at: string`

    When the feedback was collected

  - `created_at: string`

    When this record was created

  - `field_id: string`

    Identifier for the question/field

  - `field_type: string`

    Type of field

  - `source_type: string`

    Type of feedback source

  - `updated_at: string`

    When this record was last updated

  - `field_group_id: optional string`

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

  - `field_group_label: optional string`

    Human-readable question text for the group

  - `field_label: optional string`

    The actual question text

  - `language: optional string`

    ISO language code. NULL bytes not allowed.

  - `metadata: optional map[unknown]`

    Additional context

  - `source_id: optional string`

    Reference to survey/form/ticket ID

  - `source_name: optional string`

    Human-readable name

  - `tenant_id: optional string`

    Tenant/organization identifier. NULL bytes not allowed.

  - `user_identifier: optional string`

    User identifier

  - `value_boolean: optional boolean`

    Boolean response

  - `value_date: optional string`

    Date response

  - `value_number: optional number`

    Numeric response

  - `value_text: optional string`

    Text response. NULL bytes not allowed.