> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gotohuman.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Reviews API

> To create self-improving AI workflows and agents, use previously submitted human review responses as examples in your prompts. This is also called .

You can fetch this dataset via API.

### Fetch

**Endpoint:**

```
GET https://api.gotohuman.com/fetchResponses
```

**Auth Header:**

```
x-api-key: YOUR_API_KEY
```

**Query Parameters:**

* `formId` (string, **required**): The ID of the tool review / form.
* `fieldIds` (string, **required**): The comma-separated IDs of the fields you are interested in.
* `filterResponse` (string, *optional*): Filter by review status. Possible values: `approved`, `rejected`.
* `filterResponseValues` (string, *optional*): Filter by response values. See [Filtering Response Values](#filtering-response-values) for more details.
* `groupByField` (boolean, *optional*, default: `false`): Whether to group the responses by field. If not, grouped by review.
* `approvedValuesOnly` (boolean, *optional*, default: `false`): Lists only the response values for approved reviews.
* `rejectedValuesOnly` (boolean, *optional*, default: `false`): Lists only the request values for rejected reviews.
* `limit` (number, *optional*, max: 500 (Team: 100, Starter: limited)): The number of responses to return.

Example:

```
https://api.gotohuman.com/fetchResponses?formId=FORM_ID&fieldIds=FIELD_ID1,FIELD_ID2&filterResponse=approved
```

### Response

Receive the values of the given fields for past submitted reviews.

* `groupByField=false`

```json theme={null}
[
  {
    "reviewId": "abc123456",
    "createdAt": "2025-03-12T22:25:42.415Z",
    "respondedAt": "2025-03-12T22:26:15.253Z",
    "response": "approved",
    "fields": {
      "yourFieldId1": {
        "suggestedValue": "Hi Lenny, I saw the news about your latest model. Given your momentum in the AI space, influencer marketing could be a powerful tool to further engage and expand your developer community...",
        "approvedValue": "Hello Lenny, I tested your latest model and it looks really promising. Given your momentum in the AI space, influencer marketing could be a powerful tool to further engage and expand your developer community..."
      },
      "yourFieldId2": {
        "suggestedValue": "...",
        "approvedValue": "..."
      }
    }
  },
  ...
]
```

* `groupByField=true`

```json theme={null}
{
  "yourFieldId1": [
    {
      "reviewId": "abc123456",
      "createdAt": "2025-03-12T22:25:42.415Z",
      "respondedAt": "2025-03-12T22:26:15.253Z",
      "response": "approved",
      "suggestedValue": "Hi Lenny, I saw the news about your latest model. Given your momentum in the AI space, influencer marketing could be a powerful tool to further engage and expand your developer community...",
      "approvedValue": "Hello Lenny, I tested your latest model and it looks really promising. Given your momentum in the AI space, influencer marketing could be a powerful tool to further engage and expand your developer community..."
    },
    ...
  ]
}
```

* `approvedValuesOnly=true` `groupByField=false` (works the same for `rejectedValuesOnly=true` but would include suggested values)

```json theme={null}
[
  {
    "yourFieldId1": "Hello Lenny, I tested your latest model and it looks really promising. Given your momentum in the AI space, influencer marketing could be a powerful tool to further engage and expand your developer community...",
    "yourFieldId2": "..."
  },
  ...
]
```

* `approvedValuesOnly=true` `groupByField=true` (works the same for `rejectedValuesOnly=true` but would include suggested values)

```json theme={null}
{
  "yourFieldId1": [
    "Hello Lenny, I tested your latest model and it looks really promising. Given your momentum in the AI space, influencer marketing could be a powerful tool to further engage and expand your developer community...",
    "..."
  ],
  "yourFieldId2": [
    "...",
    "..."
  ]
}
```

## Filtering Response Values

The `filterResponseValues` parameter allows you to filter responses based on their field values. This parameter accepts an array of filter objects that are combined with AND logic.

**Filter Array (as JSON string):**

```json theme={null}
[
  {
    "field": "urgency.value",
    "operation": "==",
    "value": "urgent"
  },
  {
    "field": "rating.value",
    "operation": "\u003E=",
    "value": 4
  }
]
```

The `filterResponseValues` parameter must be passed as a URL-encoded JSON string array. **Important**: Do not pass an actual array object, but a JSON string. In n8n expressions, you can use `yourArray.toJsonString()` to convert an array to a JSON string.

**Full Encoded Request:**

```
GET /fetchResponses?formId=123&filterResponseValues=%5B%7B%22field%22%3A%22urgency.value%22%2C%22operation%22%3A%22equal%22%2C%22value%22%3A%22urgent%22%7D%2C%7B%22field%22%3A%22rating.value%22%2C%22operation%22%3A%22greaterThanOrEqual%22%2C%22value%22%3A4.0%7D%5D
```

### Supported Operations

**Scalar Operations:**

* `==` - Field equals value ([example](#equal-))
* `!=` - Field does not equal value ([example](#not-equal-))
* `>` - Field > value ([example](#greater-than-))
* `>=` - Field >= value ([example](#greater-than-or-equal-))
* `<` - Field \< value ([example](#less-than-))
* `<=` - Field \<= value ([example](#less-than-or-equal-))
* `contains` - Field contains substring ([example](#contains))
* `startsWith` - Field starts with substring ([example](#starts-with))
* `endsWith` - Field ends with substring ([example](#ends-with))
* `isTrue` - Field is true ([example](#is-true))
* `isFalse` - Field is false ([example](#is-false))

**Array Operations:**

* `arrayIncludes` - Array contains value ([example](#array-includes))
* `arrayExcludes` - Array does not contain value ([example](#array-excludes))
* `arrayIsEmpty` - Array is empty ([example](#array-is-empty))
* `arrayIsNotEmpty` - Array is not empty ([example](#array-is-not-empty))

The filtering is done on the `responseValues` field that you receive in your response webhooks:

```
// example structure. Look at your webhook responses to see the structure for your tool review.{  "responseValues": {    "keyword": {      "value": "Lirum Larum Ipsum Dolor Sit Amet",      "wasEdited": false    },    "content": {      "value": "Excepteur sint occaecat cupidatat non proident...",      "wasEdited": false    },    "customerValue": {      "value": 123,      "wasEdited": false    },    "rating": {      "value": 4.5,      "wasEdited": false    },    "urgency": {      "value": "urgent"    },    "categories": {      "value": [        {"id": "ecommerce", "label": "eCommerce"},        {"id": "health", "label": "Health"}      ]    }  },  ...}
```

### Examples

#### Equal (`==`)

**Filter Array (as JSON string):**

```
[  {    "field": "urgency.value",    "operation": "==",    "value": "urgent"  }]
```

**Full Encoded Request:**

```
GET /fetchResponses?formId=123&filterResponseValues=%5B%7B%22field%22%3A%22urgency.value%22%2C%22operation%22%3A%22equal%22%2C%22value%22%3A%22urgent%22%7D%5D
```

#### Not Equal (`!=`)

**Filter Array (as JSON string):**

```
[  {    "field": "urgency.value",    "operation": "!=",    "value": "low"  }]
```

**Full Encoded Request:**

```
GET /fetchResponses?formId=123&filterResponseValues=%5B%7B%22field%22%3A%22urgency.value%22%2C%22operation%22%3A%22notEqual%22%2C%22value%22%3A%22low%22%7D%5D
```

#### Greater Than (`>`)

**Filter Array (as JSON string):**

```
[  {    "field": "customerValue.value",    "operation": ">",    "value": 100  }]
```

**Full Encoded Request:**

```
GET /fetchResponses?formId=123&filterResponseValues=%5B%7B%22field%22%3A%22customerValue.value%22%2C%22operation%22%3A%22greaterThan%22%2C%22value%22%3A100%7D%5D
```

#### Greater Than or Equal (`>=`)

**Filter Array (as JSON string):**

```
[  {    "field": "rating.value",    "operation": ">=",    "value": 4.0  }]
```

**Full Encoded Request:**

```
GET /fetchResponses?formId=123&filterResponseValues=%5B%7B%22field%22%3A%22rating.value%22%2C%22operation%22%3A%22greaterThanOrEqual%22%2C%22value%22%3A4.0%7D%5D
```

#### Less Than (`<`)

**Filter Array (as JSON string):**

```
[  {    "field": "rating.value",    "operation": "<",    "value": 3.0  }]
```

**Full Encoded Request:**

```
GET /fetchResponses?formId=123&filterResponseValues=%5B%7B%22field%22%3A%22rating.value%22%2C%22operation%22%3A%22lessThan%22%2C%22value%22%3A3.0%7D%5D
```

#### Less Than or Equal (`<=`)

**Filter Array (as JSON string):**

```
[  {    "field": "rating.value",    "operation": "<=",    "value": 5.0  }]
```

**Full Encoded Request:**

```
GET /fetchResponses?formId=123&filterResponseValues=%5B%7B%22field%22%3A%22rating.value%22%2C%22operation%22%3A%22lessThanOrEqual%22%2C%22value%22%3A5.0%7D%5D
```

#### Contains

**Filter Array (as JSON string):**

```
[  {    "field": "content.value",    "operation": "contains",    "value": "voluptatem"  }]
```

**Full Encoded Request:**

```
GET /fetchResponses?formId=123&filterResponseValues=%5B%7B%22field%22%3A%22content.value%22%2C%22operation%22%3A%22contains%22%2C%22value%22%3A%22voluptatem%22%7D%5D
```

#### Starts With

**Filter Array (as JSON string):**

```
[  {    "field": "keyword.value",    "operation": "startsWith",    "value": "Lirum"  }]
```

**Full Encoded Request:**

```
GET /fetchResponses?formId=123&filterResponseValues=%5B%7B%22field%22%3A%22keyword.value%22%2C%22operation%22%3A%22startsWith%22%2C%22value%22%3A%22Lirum%22%7D%5D
```

#### Ends With

**Filter Array (as JSON string):**

```
[  {    "field": "content.value",    "operation": "endsWith",    "value": "explicabo"  }]
```

**Full Encoded Request:**

```
GET /fetchResponses?formId=123&filterResponseValues=%5B%7B%22field%22%3A%22content.value%22%2C%22operation%22%3A%22endsWith%22%2C%22value%22%3A%22explicabo%22%7D%5D
```

#### Is True

**Filter Array (as JSON string):**

```
[  {    "field": "keyword.wasEdited",    "operation": "isTrue"  }]
```

**Full Encoded Request:**

```
GET /fetchResponses?formId=123&filterResponseValues=%5B%7B%22field%22%3A%22keyword.wasEdited%22%2C%22operation%22%3A%22isTrue%22%7D%5D
```

#### Is False

**Filter Array (as JSON string):**

```
[  {    "field": "urgency.value",    "operation": "isFalse"  }]
```

**Full Encoded Request:**

```
GET /fetchResponses?formId=123&filterResponseValues=%5B%7B%22field%22%3A%22urgency.value%22%2C%22operation%22%3A%22isFalse%22%7D%5D
```

#### Array Includes

**Filter Array (as JSON string):**

```
[  {    "field": "categories.value",    "operation": "arrayIncludes",    "value": "ecommerce"  }]
```

**Full Encoded Request:**

```
GET /fetchResponses?formId=123&filterResponseValues=%5B%7B%22field%22%3A%22categories.value%22%2C%22operation%22%3A%22arrayIncludes%22%2C%22value%22%3A%22ecommerce%22%7D%5D
```

#### Array Excludes

**Filter Array (as JSON string):**

```
[  {    "field": "categories.value",    "operation": "arrayExcludes",    "value": "health"  }]
```

**Full Encoded Request:**

```
GET /fetchResponses?formId=123&filterResponseValues=%5B%7B%22field%22%3A%22categories.value%22%2C%22operation%22%3A%22arrayNotIncludes%22%2C%22value%22%3A%22health%22%7D%5D
```

#### Array Is Empty

**Filter Array (as JSON string):**

```
[  {    "field": "categories.value",    "operation": "arrayIsEmpty"  }]
```

**Full Encoded Request:**

```
GET /fetchResponses?formId=123&filterResponseValues=%5B%7B%22field%22%3A%22categories.value%22%2C%22operation%22%3A%22arrayIsEmpty%22%7D%5D
```

#### Array Is Not Empty

**Filter Array (as JSON string):**

```
[  {    "field": "categories.value",    "operation": "arrayIsNotEmpty"  }]
```

**Full Encoded Request:**

```
GET /fetchResponses?formId=123&filterResponseValues=%5B%7B%22field%22%3A%22categories.value%22%2C%22operation%22%3A%22arrayIsNotEmpty%22%7D%5D
```

#### Array Property Includes

**Filter Array (as JSON string):**

```
[  {    "field": "categories.value[].id",    "operation": "arrayIncludes",    "value": "ecommerce"  }]
```

**Note**: The `array[].property` syntax is used for filtering by/comparing with a nested property value when the array items are objects. This works like a `.map()` operation, allowing you to access properties within array elements.

**Full Encoded Request:**

```
GET /fetchResponses?formId=123&filterResponseValues=%5B%7B%22field%22%3A%22categories.value%5B%5D.id%22%2C%22operation%22%3A%22arrayIncludes%22%2C%22value%22%3A%22ecommerce%22%7D%5D
```