Feedback

Feedback as the main entity of our platform, it allows you to manage and get detailed analytical reports. On this page, we'll dive into the different feedback endpoints.

The feedback model

The feedback model contains all the information about the feedback itself. It also contains references to the associated items, attributes...

Properties

Name
id
Type
integer
Description
Unique identifier for the feedback.
Name
carrier_id
Type
integer
Description
The unique identifier linked to the source this feedback belongs to.
Name
fingerprint
Type
string
Description
A unique identifier for the feedback within a given source. The fingerprint remains unique even if the feedback is deleted, another feedback cannot be created with the same fingerprint.
Name
source
Type
string | object
Description
The source where the feedback is coming from.
The shape of this field depends on the API version used in the request. In v3, source is a string representing the channel the feedback came from (e.g. trustpilot, email, csv). In v4, source is an object containing the name of the source the feedback belongs to (e.g. { "name": "My Source" }).
Name
created_at
Type
timestamp
Description
The date where the feedback has been created.
Name
completed_at
Type
timestamp
Description
The date where the feedback has been fully completed (all items has been answered).
Name
nps_profile
Type
string
Description
The NPS Profile of the feedback (positive, neutral or negative).
Name
satisfaction_ratio
Type
integer
Description
The Satisfaction Ratio of the feedback (0-100%).

Relations

Name
attributes
Type
Attribute[]
Description
List of all the attributes attached to the feedback.
Name
items
Type
Item[]
Description
List of all the items attached to this feedback.

GET/v4/feedback

This endpoint allows you to retrieve a list of your feedback. By default, a maximum of ten feedback are shown per page. The ordering is always done by most recent feedback first and cannot be changed.

Optional attributes

Name
per_page
Type
integer
Description
Number of items to display per page - 10 by default (max: 100).
Name
order
Type
string
Description
Ordering of your feedback, can be desc or asc (default: desc).
Name
fql
Type
string
Description
Narrow your search by using our Feedback Query Language. More information in our FQL documentation.
Name
search_after
Type
integer
Description
Provide the ID of the last Feedback item retrieved, to be used as a starting point for fetching the next set of results.
We use search_after instead of standard pagination for performance optimization. You can find the key for the next query in the meta.next_search_after field of the response.
Name
include[]
Type
array[string]
Description
Use this parameter to include related data. Allowed values: items items.topics items.question items.spans attributes
items.spans is only available on the v4 API version. Each span is a portion of the answer text with its own sentiment and topics.

Request

GET

/v4/feedback

curl -G https://api.bx.feedier.com/v4/feedback \
    -H "Authorization: Bearer {token}" \
    -d "include[]"=items.question \
    -d "include[]"=items.topics

Response

{
    "data": [
        {
            "id": 26800,
            "carrier_id": 91,
            "fingerprint": "abc123def456",
            "source": "trustpilot",
            "created_at": "2024-11-06T15:23:02.000000Z",
            "completed_at": null,
            "nps_profile": null,
            "satisfaction_ratio": 45.0,
            "attributes": [
                {
                    "name": "city",
                    "label": "City",
                    "value": "Lille"
                },
                // ...
            ],
            "items": [
                {
                    "option": null,
                    "value": "My experience was awesome during this car demonstration!",
                    "created_at": "2020-01-28T13:50:20.000000Z",
                    "question_id": 1111345,
                    "question": {
                        "name": "Comments",
                        "order": 3,
                        "type": "textarea",
                        "required": 0
                    },
                    "topics": ["service", "property"]
                },
                // ...
            ]
        }
        // ...
    ],
    "meta": {
        "total": 151815,
        "next_search_after": 26800
    }
}

POST/v4/feedback

Receive a feedback

This endpoint allows you to create a new feedback attached to a source into the Dashboard.

Required attributes

Name
carrier_id
Type
integer
Description
The unique identifier of the source.
Name
source
Type
string
Description
The source where this feedback came from. Allowed Values: trustpilot easiware bigquery email chat review google_review google_reviews_competitor csv facebook linkedin letter document glassdoor homeviews survey sms facetoface feedback_box whatsapp instagram call_center amazon_reviews hubspot

Optional attributes

Name
created_at
Type
string
Description
The date and time when this feedback has been received. Format: MM/dd/yyyy HH:mm:ss (e.g., 03/13/2025 14:30:45).
Name
fingerprint
Type
string
Description
A unique identifier for the feedback within a given source. The fingerprint remains unique even if the feedback is deleted, another feedback cannot be created with the same fingerprint.
Name
attributes
Type
array[object]
Description
An array of objects containing the list of attributes with the corresponding values — like on the example bellow. A value can be a single value or an array of values. If the attribute name doesn't exist, it will be automatically created.
[ { "name": "attribute_name", "value": "attribute_value" }, { "name": "city", "value": ["lille", "rennes"] }, { "name": "car", "value": "Toyota" }, { "name": "age", "value": 30 } ]
The legacy object format { "attribute_name": "attribute_value" } is still accepted for backward compatibility.
Name
items
Type
array
Description
An array containing a list of items following the schema bellow:
[ { "question_id": 3, "value": "My Answer" }, ]
Each item requires: question_id (required) and value (required). The question_option_id field is optional and only needed for specific question types.
Ensure careful attention when using the specific questions below, as incorrect configurations might result in API errors.
Ratings Table
Choices

Request

POST

/v4/feedback

curl https://api.bx.feedier.com/v4/feedback \
    -H "Authorization: Bearer {token}" \
    -d carrier_id=91 \
    -d source="trustpilot" \
    -d attributes[0][name]="city" \
    -d attributes[0][value]="Lille" \
    -d attributes[1][name]="car" \
    -d attributes[1][value]="Toyota" \
    -d attributes[2][name]="age" \
    -d attributes[2][value]=30 \
    -d items[0][question_id]=344 \
    -d items[0][value]="My experience was awesome during this car demonstration!"

Response

{
    "id": 26800,
    "carrier_id": 91,
    "fingerprint": "abc123def456",
    "source": "trustpilot",
    "created_at": "2024-11-06T15:23:02.000000Z",
    "completed_at": null,
    "nps_profile": null,
    "satisfaction_ratio": 45.0,
    "attributes": [
        {
            "name": "City",
            "label": "City",
            "value": "Lille"
        },
        // ...
    ],
    "items": [
        {
            "option": null,
            "value": "My experience was awesome during this car demonstration!",
            "created_at": "2020-01-28T13:50:20.000000Z"
        },
        // ...
    ]
}

GET/v4/feedback/:id

Retrieve a feedback

This endpoint allows you to retrieve a feedback by providing its unique identifier. Refer to the feedback model at the top of this page to see which properties are included.

Optional attributes

Name
include[]
Type
array[string]
Description
Use this parameter to include related data. Allowed values: items items.topics items.question items.spans attributes
items.spans is only available on the v4 API version. Each span is a portion of the answer text with its own sentiment and topics.

Request

GET

/v4/feedback/26800

curl -G https://api.bx.feedier.com/v4/feedback/26800 \
     -H "Authorization: Bearer {token}" \
     -d "include[]"=items.question \
     -d "include[]"=items.topics

Response

{
    "id": 26800,
    "carrier_id": 91,
    "fingerprint": "abc123def456",
    "source": {
        "name": "My Source"
    },
    "import": null,
    "created_at": "2024-11-06T15:23:02.000000Z",
    "completed_at": null,
    "nps_profile": null,
    "satisfaction_ratio": 45.0,
    "status": "todo",
    "attributes": [
        {
            "name": "city",
            "label": "City",
            "value": "Lille"
        },
    ],
    "items": [
        {
            "id": 242565,
            "feedback_id": 26800,
            "question_id": 344,
            "question_option_id": null,
            "value": "My experience was awesome during this car demonstration!",
            "created_at": "2020-01-28T13:50:20.000000Z",
            "question": {
                "name": "Comments",
                "order": 3,
                "type": "textarea",
                "required": 0
            },
            "topics": ["service", "property"],
            "spans": [
                {
                    "start_offset": 0,
                    "length": 25,
                    "text": "My experience was awesome",
                    "sentiment_score": 0.92,
                    "sentiment_string": "positive",
                    "topics": ["service"]
                }
            ]
        },
    ]
}

PUT/v4/feedback/:id

Update a feedback

This endpoint allows you to update an existing feedback record.

Optional attributes

Name
status
Type
string
Description
The new status to apply. Allowed values: todo progress contacted resolved abandoned.

Request

PUT

/v4/feedback/26800

curl -X PUT https://api.bx.feedier.com/v4/feedback/26800 \
    -H "Authorization: Bearer {token}" \
    -d status="resolved"

Response

{
    "id": 26800,
    "carrier_id": 91,
    "source": "trustpilot",
    "created_at": "2024-11-06T15:23:02.000000Z",
    "completed_at": null,
    "nps_profile": null,
    "satisfaction_ratio": 45.0,
    "attributes": [],
    "items": []
}

POST/v4/feedback/:id/attributes/attach

Attach attributes to a feedback

This endpoint allows you to attach attribute values to a single feedback identified by its ID. Unlike the bulk attach endpoint, no FQL filter is required.

If the attribute name does not exist, it will be automatically created. To replace existing values for an attribute, use the sync endpoint.

Required attributes

Name
attributes[]
Type
array[object]
Description
An array of objects containing the attribute name and value(s).
[ { "name": "city", "value": "lille" }, { "name": "tags", "value": ["premium", "vip"] } ]
The value field accepts a string or an array of strings.

Request

POST

/v4/feedback/26800/attributes/attach

curl https://api.bx.feedier.com/v4/feedback/26800/attributes/attach \
    -H "Authorization: Bearer {token}" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -d '{"attributes":[{"name":"city","value":"lille"},{"name":"tags","value":["premium","vip"]}]}'

Response

{
    "type": "success",
    "message": "Attributes attached to feedback"
}

PUT/v4/feedback/:id/attributes/sync

Sync attributes on a feedback

This endpoint allows you to replace attribute values on a single feedback identified by its ID. For each attribute name provided, only the listed values are kept — any existing values not included are detached.

If the attribute name does not exist, it will be automatically created.

Required attributes

Name
attributes[]
Type
array[object]
Description
An array of objects containing the attribute name and the value(s) to keep.
[ { "name": "city", "value": "lille" }, { "name": "tags", "value": ["premium"] } ]
The value field accepts a string or an array of strings.

Request

PUT

/v4/feedback/26800/attributes/sync

curl -X PUT https://api.bx.feedier.com/v4/feedback/26800/attributes/sync \
    -H "Authorization: Bearer {token}" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -d '{"attributes":[{"name":"city","value":"lille"},{"name":"tags","value":["premium"]}]}'

Response

{
    "type": "success",
    "message": "Attributes synced to feedback"
}

DELETE/v4/feedback/:id/attributes/detach

Detach attributes from a feedback

This endpoint allows you to detach attribute values from a single feedback identified by its ID.

Required attributes

Name
attributes[]
Type
array[object]
Description
An array of objects containing the attribute name and, optionally, the value(s) to detach.
[ { "name": "city", "value": "lille" }, { "name": "tags" } ]
When value is omitted, all values for the given attribute name are detached from the feedback.

Request

DELETE

/v4/feedback/26800/attributes/detach

curl -X DELETE https://api.bx.feedier.com/v4/feedback/26800/attributes/detach \
    -H "Authorization: Bearer {token}" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -d '{"attributes":[{"name":"city","value":"lille"},{"name":"tags"}]}'

Response

{
    "type": "success",
    "message": "Attributes detached from feedback"
}

POST/v4/feedback/attributes/attach

Attach attributes in bulk

This endpoint allows you to attach attribute values to every feedback matching an FQL filter. To target a single feedback by its ID, use the single feedback endpoint instead.

If the attribute name does not exist, it will be automatically created. Attaching adds values to the ones already present — to replace them, use the sync endpoint.

If more than 10 feedback match the filter, the update runs asynchronously and the response contains "async": true.

Required attributes

Name
fql
Type
string
Description
A JSON-encoded FQL query selecting the feedback to update. More information in our FQL documentation.
"[{\"Id\":{\"$in\":[61517],\"$type\":\"and\"}}]"
Name
attributes[]
Type
array[object]
Description
An array of objects containing the attribute name and value(s).
[ { "name": "city", "value": "lille" }, { "name": "tags", "value": ["premium", "vip"] } ]
The value field is required and accepts a string or an array of strings.

Request

POST

/v4/feedback/attributes/attach

curl https://api.bx.feedier.com/v4/feedback/attributes/attach \
    -H "Authorization: Bearer {token}" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -d '{
        "fql": "[{\"Id\":{\"$in\":[61517],\"$type\":\"and\"}}]",
        "attributes": [
            {"name": "city", "value": "lille"},
            {"name": "tags", "value": ["premium", "vip"]}
        ]
    }'

Response

{
    "feedback_count": 1
}

PUT/v4/feedback/attributes/sync

Sync attributes in bulk

This endpoint allows you to replace attribute values on every feedback matching an FQL filter. For each attribute name provided, only the listed values are kept — any existing value not included is detached. To target a single feedback by its ID, use the single feedback endpoint instead.

If the attribute name does not exist, it will be automatically created.

If more than 10 feedback match the filter, the update runs asynchronously and the response contains "async": true.

Required attributes

Name
fql
Type
string
Description
A JSON-encoded FQL query selecting the feedback to update. More information in our FQL documentation.
"[{\"Id\":{\"$in\":[61517],\"$type\":\"and\"}}]"
Name
attributes[]
Type
array[object]
Description
An array of objects containing the attribute name and the value(s) to keep.
[ { "name": "city", "value": "lille" }, { "name": "tags", "value": ["premium"] } ]
The value field is required and accepts a string or an array of strings.

Request

PUT

/v4/feedback/attributes/sync

curl -X PUT https://api.bx.feedier.com/v4/feedback/attributes/sync \
    -H "Authorization: Bearer {token}" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -d '{
        "fql": "[{\"Id\":{\"$in\":[61517],\"$type\":\"and\"}}]",
        "attributes": [
            {"name": "city", "value": "lille"},
            {"name": "tags", "value": ["premium"]}
        ]
    }'

Response

{
    "feedback_count": 1
}

DELETE/v4/feedback/attributes/detach

Detach attributes in bulk

This endpoint allows you to detach attribute values from every feedback matching an FQL filter. To target a single feedback by its ID, use the single feedback endpoint instead.

If the attribute name does not exist, nothing is detached.

If more than 10 feedback match the filter, the update runs asynchronously and the response contains "async": true.

Required attributes

Name
fql
Type
string
Description
A JSON-encoded FQL query selecting the feedback to update. More information in our FQL documentation.
"[{\"Id\":{\"$in\":[61517],\"$type\":\"and\"}}]"
Name
attributes[]
Type
array[object]
Description
An array of objects containing the attribute name and, optionally, the value(s) to detach.
[ { "name": "city", "value": "lille" }, { "name": "tags" } ]
When value is omitted, all values for the given attribute name are detached.

Request

DELETE

/v4/feedback/attributes/detach

curl -X DELETE https://api.bx.feedier.com/v4/feedback/attributes/detach \
    -H "Authorization: Bearer {token}" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -d '{
        "fql": "[{\"Id\":{\"$in\":[61517],\"$type\":\"and\"}}]",
        "attributes": [
            {"name": "city", "value": "lille"},
            {"name": "tags"}
        ]
    }'

Response

{
    "feedback_count": 1
}

POST/v4/feedback/bulk-update

Bulk update feedback

This endpoint allows you to bulk update the status of feedback matching an FQL filter.

If more than 10 feedbacks match the filter, the update will run asynchronously.

Required attributes

Name
fql
Type
string
Description
Narrow your search by using our Feedback Query Language. More information in our FQL documentation.
Name
status
Type
string
Description
The new status to apply. Allowed values: todo progress contacted resolved abandoned.

Request

POST

/v4/feedback/bulk-update

curl https://api.bx.feedier.com/v4/feedback/bulk-update \
    -H "Authorization: Bearer {token}" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -d '{
        "fql": "[{\"Id\":{\"$in\":[61517],\"$type\":\"and\"}}]",
        "status": "resolved"
    }'

Response

{
    "type": "success",
    "message": "Request successful",
    "feedback_count": 1
}

Async Response

{
    "feedback_count": 150,
    "async": true
}

POST/v4/feedback/:id/attach/owner

Attach owners to feedback

This endpoint allows you to assign one or more users as owners of a feedback. The users must already exist in your organization.

Required attributes

Name
emails
Type
array[string]
Description
An array of email addresses of the users to assign as owners. Each email must belong to a user within your organization.

Request

POST

/v4/feedback/26800/attach/owner

curl https://api.bx.feedier.com/v4/feedback/26800/attach/owner \
    -H "Authorization: Bearer {token}" \
    -d "emails[]=john@example.com" \
    -d "emails[]=jane@example.com"

Response

{
    "type": "success",
    "message": "Users assigned to feedback"
}

POST/v4/feedback/:id/detach/owner

Detach owner from feedback

This endpoint allows you to remove a user from the owners of a feedback. The user must exist in your organization.

Required attributes

Name
email
Type
string
Description
The email address of the user to remove as owner.

Request

POST

/v4/feedback/26800/detach/owner

curl https://api.bx.feedier.com/v4/feedback/26800/detach/owner \
    -H "Authorization: Bearer {token}" \
    -d email="john@example.com"

Response

{
    "type": "success",
    "message": "User removed from feedback"
}

DELETE/v4/feedback

Delete feedback

This endpoint allows you to permanently delete one or more feedback records. Use the Feedback Query Language (FQL) to target specific feedback for deletion.

This action is irreversible. Once deleted, feedback records cannot be recovered.

Required attributes

Name
fql
Type
string
Description
A JSON-encoded FQL query to select the feedback to delete. More information in our FQL documentation.
"[{\"Id\":{\"$in\":[89546],\"$type\":\"and\"}}]"

Optional attributes

Name
limit
Type
integer
Description
Optional. Maximum number of feedback records to delete in a single request. Default: 1000.

Request

DELETE

/v4/feedback

curl -X DELETE https://api.bx.feedier.com/v4/feedback \
    -H "Authorization: Bearer {token}" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -d '{
        "fql": "[{\"Id\":{\"$in\":[89546],\"$type\":\"and\"}}]",
        "limit": 1000
    }'

Response

{
    "type": "success",
    "message": "All matching feedbacks have been deleted.",
    "meta": {
        "total_matching": 1,
        "deleted": 1,
        "remaining": 0
    }
}

Feedback

Properties

Relations

Optional attributes

Request

Response

Required attributes

Optional attributes

Ratings Table

Choices

Request

Response

Optional attributes

Request

Response

Optional attributes

Request

Response

Required attributes

Request

Response

Required attributes

Request

Response

Required attributes

Request

Response

Required attributes

Request

Response

Required attributes

Request

Response

Required attributes

Request

Response

Required attributes

Request

Response

Async Response

Required attributes

Request

Response

Required attributes

Request

Response

Required attributes

Optional attributes

Request

Response