[← API v2 Overview](https://motordesk.com/api-docs/v2/)

# Reviews

Manage your business customer reviews. Create, update, approve and delete reviews, set the star rating (out of 5), reviewer name, review text, source and review date, and mark reviews as verified. Reviews are approved (live) by default; set the status to pending to hold one for moderation. Only approved reviews appear on the public website. List and read endpoints include pending reviews.

## The Review Object

Generated from the OpenAPI schema. Always matches the live API.

**Fields (9)**

| Attribute | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `id` | integer | - |  | `8821` |
| `rating` | number | - | Star rating out of 5 (0-5, in 0.5 increments). | `4.5` |
| `name` | string | - | Reviewer / customer name. | `John Smith` |
| `review` | string | - | Review text. | `Excellent service, would buy again.` |
| `source` | string | - | Where the review came from (max 32 chars), e.g. Google, AutoTrader. | `Google` |
| `verified` | boolean | - | Whether the review is marked as verified. | `true` |
| `status` | enum | - | Approval status. Only approved reviews appear on the public website. | `approved` |
| `date` | string (date) or null | - | Review date (YYYY-MM-DD). | `2026-05-20` |
| `data` | object | - | Source metadata (e.g. imported review details). Read-only; full view only. |  |

**Example object**

```json
{
    "id": 8821,
    "rating": 4.5,
    "name": "John Smith",
    "review": "Excellent service, would buy again.",
    "source": "Google",
    "verified": true,
    "status": "approved",
    "date": "2026-05-20",
    "data": {}
}
```

## Endpoints

### GET List Reviews

`GET /2.0/reviews` · scope `reviews:read`

List customer reviews with pagination and optional filters (status, source, verified).

**Parameters (8)**

| Parameter | In | Type | Required | Description | Example |
| --- | --- | --- | --- | --- | --- |
| `page` | query | integer | - | Page number, starting at 1 (offset pagination). |  |
| `per_page` | query | integer | - | Results per page (maximum 500). |  |
| `view` | query | enum | - | simple (default for lists) or full (includes source metadata). |  |
| `status` | query | enum | - | Filter by approval status. | `approved` |
| `source` | query | string | - | Filter by source. Exact match, or use % for wildcard matching (minimum 3 characters). | `Google` |
| `verified` | query | integer | - | Filter by verified flag (0 or 1). |  |
| `cursor` | query | string | - | Keyset pagination cursor from a previous response's meta.pagination.next_cursor. When supplied, page/total are not returned. |  |
| `fields` | query | string | - | Comma-separated dot-paths to return only those fields, e.g. id,data.stock.price_channel. |  |

**Responses**

| Status | Description |
| --- | --- |
| `200` OK | Paginated reviews |

Failures use the standard [error responses](https://motordesk.com/api-docs/v2/errors/) (4xx/5xx) with the shared error envelope.

```json
{
    "success": true,
    "data": [
        {
            "id": 8821,
            "rating": 4.5,
            "name": "John Smith",
            "review": "Excellent service, would buy again.",
            "source": "Google",
            "verified": true,
            "status": "approved",
            "date": "2026-05-20",
            "data": {}
        }
    ],
    "meta": {
        "pagination": {
            "page": 0,
            "per_page": 0,
            "total": 0,
            "total_pages": 0,
            "next_cursor": ""
        }
    }
}
```

### POST Create Review

`POST /2.0/reviews` · scope `reviews:write`

Create a customer review. Reviews are approved (live) by default; set status to pending to hold for moderation.

**Request body**

| Attribute | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `rating` | number | - | Star rating out of 5 (0-5, in 0.5 increments). | `4.5` |
| `name` | string | - | Reviewer / customer name. | `John Smith` |
| `review` | string | - | Review text. | `Excellent service, would buy again.` |
| `source` | string | - | Where the review came from (max 32 chars). | `Google` |
| `verified` | boolean | - | Mark the review as verified. | `true` |
| `status` | enum | - | Approval status. New reviews are approved by default; set to pending to hold for moderation. Only approved reviews show on the public website. | `approved` |
| `date` | string (date) | - | Review date (YYYY-MM-DD). Defaults to today on create. | `2026-05-20` |

```json
{
    "rating": 4.5,
    "name": "John Smith",
    "review": "Excellent service, would buy again.",
    "source": "Google",
    "verified": true,
    "status": "approved",
    "date": "2026-05-20"
}
```

**Responses**

| Status | Description |
| --- | --- |
| `201` Created | Review created |

Failures use the standard [error responses](https://motordesk.com/api-docs/v2/errors/) (4xx/5xx) with the shared error envelope.

```json
{
    "success": true,
    "data": {
        "id": 8821,
        "rating": 4.5,
        "name": "John Smith",
        "review": "Excellent service, would buy again.",
        "source": "Google",
        "verified": true,
        "status": "approved",
        "date": "2026-05-20",
        "data": {}
    }
}
```

### GET Get Review

`GET /2.0/reviews/{id}` · scope `reviews:read`

Retrieve a single review by id (includes pending reviews).

**Parameters (2)**

| Parameter | In | Type | Required | Description | Example |
| --- | --- | --- | --- | --- | --- |
| `id` | path | string | Yes | Resource identifier in the path. |  |
| `fields` | query | string | - | Comma-separated dot-paths to return only those fields, e.g. id,data.stock.price_channel. |  |

**Responses**

| Status | Description |
| --- | --- |
| `200` OK | Get Review |

Failures use the standard [error responses](https://motordesk.com/api-docs/v2/errors/) (4xx/5xx) with the shared error envelope.

```json
{
    "success": true,
    "data": {
        "id": 8821,
        "rating": 4.5,
        "name": "John Smith",
        "review": "Excellent service, would buy again.",
        "source": "Google",
        "verified": true,
        "status": "approved",
        "date": "2026-05-20",
        "data": {}
    }
}
```

### PATCH Update Review

`PATCH /2.0/reviews/{id}` · scope `reviews:write`

Update a review, including approving or un-approving it. Only the supplied fields are changed.

**Parameters (1)**

| Parameter | In | Type | Required | Description | Example |
| --- | --- | --- | --- | --- | --- |
| `id` | path | string | Yes | Resource identifier in the path. |  |

**Request body**

| Attribute | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `rating` | number | - | Star rating out of 5 (0-5, in 0.5 increments). | `4.5` |
| `name` | string | - | Reviewer / customer name. | `John Smith` |
| `review` | string | - | Review text. | `Excellent service, would buy again.` |
| `source` | string | - | Where the review came from (max 32 chars). | `Google` |
| `verified` | boolean | - | Mark the review as verified. | `true` |
| `status` | enum | - | Approval status. New reviews are approved by default; set to pending to hold for moderation. Only approved reviews show on the public website. | `approved` |
| `date` | string (date) | - | Review date (YYYY-MM-DD). Defaults to today on create. | `2026-05-20` |

```json
{
    "rating": 4.5,
    "name": "John Smith",
    "review": "Excellent service, would buy again.",
    "source": "Google",
    "verified": true,
    "status": "approved",
    "date": "2026-05-20"
}
```

**Responses**

| Status | Description |
| --- | --- |
| `200` OK | Update Review |

Failures use the standard [error responses](https://motordesk.com/api-docs/v2/errors/) (4xx/5xx) with the shared error envelope.

```json
{
    "success": true,
    "data": {
        "id": 8821,
        "rating": 4.5,
        "name": "John Smith",
        "review": "Excellent service, would buy again.",
        "source": "Google",
        "verified": true,
        "status": "approved",
        "date": "2026-05-20",
        "data": {}
    }
}
```

### DELETE Delete Review

`DELETE /2.0/reviews/{id}` · scope `reviews:delete`

Delete a review.

**Parameters (1)**

| Parameter | In | Type | Required | Description | Example |
| --- | --- | --- | --- | --- | --- |
| `id` | path | string | Yes | Resource identifier in the path. |  |

**Responses**

| Status | Description |
| --- | --- |
| `200` OK | Delete Review |

Failures use the standard [error responses](https://motordesk.com/api-docs/v2/errors/) (4xx/5xx) with the shared error envelope.

```json
{
    "success": true,
    "data": {
        "id": 0,
        "deleted": false
    }
}
```