Reviews
Your published reviews, always in their original language, with replies and proof type.
In short
The reviews endpoints return your published reviews with their proof type, replies and dates, and let you post a reply from your business. Reviews always come in their original language. To be told about new reviews as they arrive, use webhook events instead of checking again and again.
- List your published reviews, filtered by proof type, stars or date.
- Read one review with its replies.
- Post a public reply from your business.
Query parameters
| Field | Type | Description |
|---|---|---|
| stars | 1–5 | Only this rating |
| proof | string | transaction, invited, identity, after_review, imported or unverified |
| since | datetime | Reviews published after this time |
| language | string | Original language, e.g. ms |
| business | string | One of your businesses (needed only to narrow the list) |
| limit | integer | Up to 100 (default 20) |
| cursor | string | next_cursor from the previous page |
Review object
| Field | Type | Description |
|---|---|---|
| id | string | Review id |
| stars | integer | 1–5 |
| title, text | string | Always in the original language |
| language | string | Language the review was written in |
| proof | string | Proof type shown on the review |
| reviewer.name | string | First name and initial only |
| replies | array | Public replies from your business and the reviewer |
| product | object | The product reviewed (sku and name), or null |
| experience_date | date | When it happened |
| resolved | boolean | The reviewer marked the problem as solved |
Replying
POST /reviews/{id}/replies with a text field (2 to 4,000 characters) publishes a reply from your business, shown with the review. It is recorded for the person who created the key. Send an Idempotency-Key to avoid posting twice.
curl "https://api.proofwell.io/v1/reviews?proof=transaction&limit=2" \
-H "Authorization: Bearer $PROOFWELL_KEY"{
"data": [
{
"id": "rev_1042",
"business_id": "biz_example-coffee",
"stars": 5,
"title": "Fresh beans, fast delivery",
"text": "Roast date was three days before delivery.",
"language": "en",
"proof": "transaction",
"reviewer": {
"name": "Aisha K."
},
"product": null,
"experience_date": "2026-09-20",
"resolved": false,
"replies": [
{
"id": "rpl_88",
"from": "business",
"text": "Thank you!",
"created_at": "2026-09-22T08:00:00.000Z"
}
],
"url": "https://example.com/biz/example-coffee#review-1042",
"created_at": "2026-09-21T10:12:00.000Z",
"updated_at": "2026-09-21T10:12:00.000Z"
}
],
"next_cursor": "YzoxMDQy"
}