--- title: "Create and update a review from a custom partner" method: POST path: "/reviews" tags: ["Reviews"] --- # Create and update a review from a custom partner `POST /reviews` ## Request - Base URL: `https://api.partoo.co/v2` - URL: `https://api.partoo.co/v2/reviews` - Auth: API key in header `x-APIKey` - TypeScript: (a function with typed inputs; its response is checked against the schema) This endpoint lets you push into Partoo the reviews you collect on your own platform, through a **custom review partner** enabled on your organization. A review is identified by the pair (`partner_slug`, `external_id`): - the first call with a given pair **creates** the review, - every later call with the same pair **updates** it in place. Sending the same payload twice is therefore safe: the second call is a no-op and still answers `200`. Pushing a review you previously deleted **restores** it. You can push for partners that are flagged as `is_custom` by [List review partners](/api-reference/reviews/list-review-partners). Reviews created this way behave like any other review: they are returned by [Search for reviews](/api-reference/reviews/search-for-reviews), they can be replied to, and they trigger the `review_created` / `review_updated` webhooks. You must use an API key with `ORG_ADMIN` rights and the `review_edit` permission, and the business must belong to the organization of the API key's. ## Request body - object: The review to create or update - `partner_slug` string, required: Slug of the custom partner the review comes from. It must be a partner enabled on your organization, returned with `is_custom: true` by [List review partners](/api-reference/reviews/list-review-partners). - `external_id` string, required: The review's unique id on the source platform. This is the key of the upsert: re-sending the same `external_id` for the same `partner_slug` updates the review instead of creating a new one. It is returned as `key` and `partner_id` on the review. An `external_id` already used by a review of **another** partner is rejected with a `409`. - `business_id` string, required: Business id - `rating` integer, required: Star rating given by the author. - `content` string, nullable: Body of the review. Omit it for a rating-only review. - `author` object, required: Author of the review, as displayed on the source platform. - `display_name` string, required: Name displayed for the author. Returned as `author_name` on the review. - `is_anonymous` boolean: Whether the author chose to stay anonymous on the source platform. **Note:** accepted for forward compatibility — it is not stored and not returned on the review today. Use a generic `display_name` for an anonymous author. - `profile_photo_url` string, uri, nullable: Public URL of the author's profile picture. **Note:** accepted for forward compatibility — it is not stored and not returned on the review today. - `date` string, date-time, required: When the review was posted on the source platform. The offset is required (for example `+02:00` or `Z`); Partoo stores the date in UTC and renders it in the business timezone. Two reviews of the same business cannot share the same `date` **and** `author.display_name`: such a push answers `409`. - `update_date` string, date-time: Last update of the review on the source platform. Defaults to `date`, and cannot be earlier than it. - `link` string, uri, nullable: Public URL of the review on the source platform. - `reply` object, nullable: The reply already published on the source platform, if any. It is created with the review, and updated on a later push carrying a different content or date. Replies written from Partoo are handled by [Post a reply to a review](/api-reference/reviews/post-a-reply-to-a-review) instead. - `content` string, required: Body of the reply. - `date` string, date-time, required: When the reply was posted on the source platform. The offset is required. ## Response `200` The review that was created or updated - Review: Business Review on partner - `key` string: Identifier of the review on the partner platform. For a review pushed through a custom partner, this is the `external_id` you sent. - `org_id` integer: Unique identifier of an organization in Partoo. - `id` integer: Review id - `business_id` string: Business id - `partner` string: Review partner slug - `partner_id` string: Review id on publisher - `author_name` string: The author name of the review. **Note:** Replies don't have an author. - `date` string, datetime: Review creation date - `update_date` string, datetime: Review update date - `delete_date` string, datetime: Review deletion date (only specified if the review has been deleted) - `rating` integer: Review rating (can be null) - `recommended` boolean: Review recommended (can be null) - `title` string: Review title - `content` string: Review body content - `state` 'treated' | 'not_treated' | 'deleted': Reply state - `link` string, uri: Link to review on publisher platform - `comments` Comment[]: Replies to the review - `id` integer: Comment id - `partner_id` string: Review id on publisher - `created` string, datetime: Creation date on Partoo - `author_name` string: The author name of the review. **Note:** Replies don't have an author. - `content` string: Reply content - `date` string, datetime: Comment date - `update_date` string, datetime: Comment update date. Only specified if the comment was updated - `can_edit` boolean: If the current user can or cannot edit a reply **Note:** This applies on Facebook replies only. A reply left by an external user on Facebook cannot be edited. - `review_id` integer: Review id - `parent_id` integer: id of the parent comment. Is only specified if the comment is a reply to another comment **Note:** This applies on Facebook replies only. - `user_id` string: User id of the comment author - `is_reply_suggestion` boolean: If AI reply suggestion was used to generate this comment - `replies` Comment[]: List of replies to this comment - `tags` Tag[]: Tags associated to the review - `id` integer: Tag id - `label` string: The label of the tag Must be <= 30 characters and cannot contain a comma (commas will be ignored) - `color` '#808080' | '#9B7CDB' | '#F47FBE' | '#4D4D4D' | '#9E6957' | '#2F8DE4' | '#37CED0' | '#53C944' | '#B1DA34' | '#F78234' | '#F4BD38' | '#992842': The color of the tag, in hexadecimal representation - `media_links` string[]: Array of Google photo URLs associated with the review. Populated when `with_media_links=true` query parameter is used. Empty array if no associated media found or if `with_media_links=false`. ## Other responses - `400`: Your request is incorrect - `401`: You are not authenticated - `403`: You are not allowed to perform this action. Either: - the API key's user is not an `ORG_ADMIN`, lacks the `review_edit` permission, or has no write access to the business (`errors.authorization`), - or your organization is not enabled for this custom partner (`errors.json`). - `404`: Unknown `partner_slug`, a slug that is not a custom partner, unknown `business_id`. - `409`: The review conflicts with an existing one. Either the business already has a review with the same `date` and `author.display_name`, or the `external_id` is already used by a review of another partner. - `500`: The review, or its reply, could not be saved. The push is safe to retry: it is keyed on (`partner_slug`, `external_id`), so a retry never duplicates the review. ## Changes - **2026-11-03** `dcb8190f5a29`: 1 info - endpoint added [Operation history](https://skmtc.dev/partoo/apis/partoo-rest-api/changes/reviews/post.md) --- [API](https://skmtc.dev/partoo/apis/partoo-rest-api.md) - [All operations](https://skmtc.dev/partoo/apis/partoo-rest-api/llms.txt) - [OpenAPI document](https://skmtc.dev/partoo/apis/partoo-rest-api/revisions/dcb8190f5a29?raw)