curl --request POST \
--url https://apiv2.gomarketbox.com/v1/projects/{projectId}/reviews \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"supplierId": "<string>",
"ratingStars": 3,
"reviewText": "<string>",
"reviewerId": "<string>",
"bookingId": "bk_01kv60qge5eh59ap0gw0pqrrys"
}
'import requests
url = "https://apiv2.gomarketbox.com/v1/projects/{projectId}/reviews"
payload = {
"supplierId": "<string>",
"ratingStars": 3,
"reviewText": "<string>",
"reviewerId": "<string>",
"bookingId": "bk_01kv60qge5eh59ap0gw0pqrrys"
}
headers = {
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
supplierId: '<string>',
ratingStars: 3,
reviewText: '<string>',
reviewerId: '<string>',
bookingId: 'bk_01kv60qge5eh59ap0gw0pqrrys'
})
};
fetch('https://apiv2.gomarketbox.com/v1/projects/{projectId}/reviews', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://apiv2.gomarketbox.com/v1/projects/{projectId}/reviews",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'supplierId' => '<string>',
'ratingStars' => 3,
'reviewText' => '<string>',
'reviewerId' => '<string>',
'bookingId' => 'bk_01kv60qge5eh59ap0gw0pqrrys'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-api-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://apiv2.gomarketbox.com/v1/projects/{projectId}/reviews"
payload := strings.NewReader("{\n \"supplierId\": \"<string>\",\n \"ratingStars\": 3,\n \"reviewText\": \"<string>\",\n \"reviewerId\": \"<string>\",\n \"bookingId\": \"bk_01kv60qge5eh59ap0gw0pqrrys\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-api-key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://apiv2.gomarketbox.com/v1/projects/{projectId}/reviews")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"supplierId\": \"<string>\",\n \"ratingStars\": 3,\n \"reviewText\": \"<string>\",\n \"reviewerId\": \"<string>\",\n \"bookingId\": \"bk_01kv60qge5eh59ap0gw0pqrrys\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://apiv2.gomarketbox.com/v1/projects/{projectId}/reviews")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"supplierId\": \"<string>\",\n \"ratingStars\": 3,\n \"reviewText\": \"<string>\",\n \"reviewerId\": \"<string>\",\n \"bookingId\": \"bk_01kv60qge5eh59ap0gw0pqrrys\"\n}"
response = http.request(request)
puts response.read_body{
"data": {
"reviewId": "<string>",
"supplierId": "<string>",
"projectId": "<string>",
"ratingStars": 123,
"direction": "CLIENT_TO_SUPPLIER",
"subjectType": "SUPPLIER",
"subjectId": "<string>",
"createdAt": "<string>",
"clientId": "<string>",
"reviewText": "<string>",
"reviewerId": "<string>",
"bookingId": "<string>",
"supplierName": "<string>",
"clientName": "<string>"
}
}{
"code": "NOT_FOUND",
"message": "Booking not found",
"statusCode": 404,
"requestId": "a3f1c2de-9b64-4a2f-8f0e-5c9d1b7a2e10"
}{
"code": "NOT_FOUND",
"message": "Booking not found",
"statusCode": 404,
"requestId": "a3f1c2de-9b64-4a2f-8f0e-5c9d1b7a2e10"
}{
"code": "NOT_FOUND",
"message": "Booking not found",
"statusCode": 404,
"requestId": "a3f1c2de-9b64-4a2f-8f0e-5c9d1b7a2e10"
}{
"code": "NOT_FOUND",
"message": "Booking not found",
"statusCode": 404,
"requestId": "a3f1c2de-9b64-4a2f-8f0e-5c9d1b7a2e10"
}Create a supplier review (1–5 star rating with optional comment)
Records a rating against a supplier and folds it into that supplier’s running average in the same atomic write, so the aggregate never disagrees with the rows behind it.
Treat this as permanent. There is no update or delete route, so a review posted by mistake moves the supplier’s average for good — validate on your side before calling. Nothing is deduplicated and no booking is required: the same reviewer can post repeatedly, and each submission counts again, so enforce “one review per completed booking” yourself if that is your intent. reviewerId is optional and stored as given; it is not authenticated or checked against the client who was served.
bookingId is optional and links the review to a booking. Supplying it stops MarketBox’s rating follow-up emails for that booking — omit it and the client keeps being nudged to rate a booking they have already reviewed. It is stored as given and is not validated: an id that does not exist, or belongs to another project or another client, is accepted and simply links to nothing. It does not deduplicate either — two reviews carrying the same bookingId both count.
ratingStars must be a whole number from 1 to 5, and reviewText is optional and capped at 5000 characters. The supplier must exist in this project, or 404.
curl --request POST \
--url https://apiv2.gomarketbox.com/v1/projects/{projectId}/reviews \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"supplierId": "<string>",
"ratingStars": 3,
"reviewText": "<string>",
"reviewerId": "<string>",
"bookingId": "bk_01kv60qge5eh59ap0gw0pqrrys"
}
'import requests
url = "https://apiv2.gomarketbox.com/v1/projects/{projectId}/reviews"
payload = {
"supplierId": "<string>",
"ratingStars": 3,
"reviewText": "<string>",
"reviewerId": "<string>",
"bookingId": "bk_01kv60qge5eh59ap0gw0pqrrys"
}
headers = {
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
supplierId: '<string>',
ratingStars: 3,
reviewText: '<string>',
reviewerId: '<string>',
bookingId: 'bk_01kv60qge5eh59ap0gw0pqrrys'
})
};
fetch('https://apiv2.gomarketbox.com/v1/projects/{projectId}/reviews', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://apiv2.gomarketbox.com/v1/projects/{projectId}/reviews",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'supplierId' => '<string>',
'ratingStars' => 3,
'reviewText' => '<string>',
'reviewerId' => '<string>',
'bookingId' => 'bk_01kv60qge5eh59ap0gw0pqrrys'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-api-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://apiv2.gomarketbox.com/v1/projects/{projectId}/reviews"
payload := strings.NewReader("{\n \"supplierId\": \"<string>\",\n \"ratingStars\": 3,\n \"reviewText\": \"<string>\",\n \"reviewerId\": \"<string>\",\n \"bookingId\": \"bk_01kv60qge5eh59ap0gw0pqrrys\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-api-key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://apiv2.gomarketbox.com/v1/projects/{projectId}/reviews")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"supplierId\": \"<string>\",\n \"ratingStars\": 3,\n \"reviewText\": \"<string>\",\n \"reviewerId\": \"<string>\",\n \"bookingId\": \"bk_01kv60qge5eh59ap0gw0pqrrys\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://apiv2.gomarketbox.com/v1/projects/{projectId}/reviews")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"supplierId\": \"<string>\",\n \"ratingStars\": 3,\n \"reviewText\": \"<string>\",\n \"reviewerId\": \"<string>\",\n \"bookingId\": \"bk_01kv60qge5eh59ap0gw0pqrrys\"\n}"
response = http.request(request)
puts response.read_body{
"data": {
"reviewId": "<string>",
"supplierId": "<string>",
"projectId": "<string>",
"ratingStars": 123,
"direction": "CLIENT_TO_SUPPLIER",
"subjectType": "SUPPLIER",
"subjectId": "<string>",
"createdAt": "<string>",
"clientId": "<string>",
"reviewText": "<string>",
"reviewerId": "<string>",
"bookingId": "<string>",
"supplierName": "<string>",
"clientName": "<string>"
}
}{
"code": "NOT_FOUND",
"message": "Booking not found",
"statusCode": 404,
"requestId": "a3f1c2de-9b64-4a2f-8f0e-5c9d1b7a2e10"
}{
"code": "NOT_FOUND",
"message": "Booking not found",
"statusCode": 404,
"requestId": "a3f1c2de-9b64-4a2f-8f0e-5c9d1b7a2e10"
}{
"code": "NOT_FOUND",
"message": "Booking not found",
"statusCode": 404,
"requestId": "a3f1c2de-9b64-4a2f-8f0e-5c9d1b7a2e10"
}{
"code": "NOT_FOUND",
"message": "Booking not found",
"statusCode": 404,
"requestId": "a3f1c2de-9b64-4a2f-8f0e-5c9d1b7a2e10"
}Authorizations
API key minted in the MarketBox dashboard. Scope is restricted to the projects you select at creation time. Every route needs the key's standard API access (*) except POST /v1/projects/{projectId}/events, which needs events:write; a key without * is refused with 403 CAPABILITY_NOT_GRANTED.
Path Parameters
Body
Review data