> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tailoredd.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Submit review with media
> Submit a customer review and attach images or videos in a single multipart request, with media processed asynchronously.
`POST {BASE_URL}/reviews/with-media`
The API validates the form and file signatures, creates the review, and waits for each media upload to be
accepted before responding. Final Cloudinary webhook processing remains asynchronous, so a successful response
normally starts with `mediaStatus: "processing"`. A later media failure does **not** roll back the review; the
terminal status is `partial` or `failed`.
## Body parameters
This endpoint uses `multipart/form-data` encoding. Send all fields as form values, not JSON.
Product ID.
1–5.
Customer display name.
Customer email.
JPEG, PNG, WebP, GIF, MP4, WebM, or QuickTime media. Repeat the key for up to three files, max 50 MB each.
File signatures are validated; a declared type that does not match the bytes returns `400 INVALID_FILE_TYPE`
before the review is created. Generic `application/octet-stream` uploads are accepted only when the bytes identify
one of these supported formats.
Review headline.
Review body.
Order ID for verified purchase.
Incentive claim ID.
`"true"` to confirm FTC disclosure.
`"true"` or `"false"`.
Free-text pros.
Free-text cons.
Custom attributes as a JSON-stringified string, e.g., `'{"fit":"true_to_size"}'`.
## Example
```bash theme={null}
curl -X POST "${RF_BASE_URL}/reviews/with-media" \
-H "X-Merchant-Id: YOUR_MERCHANT_ID" \
-H "X-API-Key: YOUR_API_KEY" \
-F "productId=SKU-001" -F "rating=5" \
-F "authorName=Jane Doe" -F "authorEmail=jane@example.com" \
-F "file=@/path/to/photo.jpg"
```
## OpenAPI
````yaml openapi.yaml POST /reviews/with-media
openapi: 3.0.0
info:
title: ReviewFlow API
description: >-
ReviewFlow is a fully managed ratings, reviews, and UGC platform by
Tailoredd. This API covers batch reviews, product reviews, Q&A, media
management, webhooks, tokens, analytics, incentives, and CSV export
endpoints.
version: 2.3.0
servers:
- url: https://cdn.tailoredd.com/apiV2
description: Production Gen 2 API front door
security: []
tags:
- name: Batch Reviews
description: Fetch rating summaries for multiple products in a single request.
- name: Webhooks
description: Receive post-purchase order events to trigger review request flows.
- name: Tokens
description: Validate and revoke review request tokens sent to customers.
- name: CSV Export
description: Asynchronous export of reviews or questions as CSV files.
- name: Health
description: Service availability and version check.
- name: Cloudinary Media
description: Upload, retrieve, and delete media assets attached to reviews.
- name: Reviews & Ratings
description: Create, read, moderate, and interact with product reviews.
- name: Featured Reviews
description: Feature or unfeature reviews for prominent display.
- name: Questions & Answers
description: Product Q&A with moderation and merchant answers.
- name: Admin Dashboard
description: Admin analytics and dashboard aggregation endpoints.
- name: Custom Attributes (Growth+/Enterprise)
description: Manage custom review form attributes like fit, quality, etc.
- name: Incentive Claims
description: Track and fulfill review incentive coupon claims.
- name: Sentiment Analysis
description: Filter reviews by NLP-derived sentiment labels.
- name: Google Shopping Feed
description: Generate and check eligibility for Google product reviews XML feed.
paths:
/reviews/with-media:
post:
tags:
- Reviews & Ratings
summary: Submit Review With Media (Merchant, one-call)
description: |-
Single-call review creation with media upload. The endpoint validates
file signatures, creates the review, and waits for upload initiation
before responding; final webhook reconciliation remains asynchronous.
Supported formats are JPEG, PNG, WebP, GIF, MP4, WebM, and QuickTime.
A declared type that does not match the bytes returns
`INVALID_FILE_TYPE` before review creation. Generic
`application/octet-stream` is accepted only when the bytes identify a
supported format. Merchant-scoped endpoint using API key and merchant
ID headers.
operationId: submitReviewWithMedia
parameters:
- name: X-Merchant-Id
in: header
schema:
type: string
example: your-merchant-id
- name: X-API-Key
in: header
schema:
type: string
example: tr_your-api-key
requestBody:
required: true
content:
multipart/form-data:
schema:
type: object
required:
- productId
- rating
- title
- text
- authorName
- authorEmail
properties:
productId:
type: string
rating:
type: string
enum:
- '1'
- '2'
- '3'
- '4'
- '5'
title:
type: string
text:
type: string
authorName:
type: string
authorEmail:
type: string
format: email
orderId:
type: string
wouldRecommend:
type: string
enum:
- 'true'
- 'false'
pros:
type: string
cons:
type: string
attributes:
type: string
description: JSON-stringified custom attributes.
file:
type: array
maxItems: 3
items:
type: string
format: binary
description: Repeat the field for each file. Maximum 50 MB per file.
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
'400':
description: Bad Request / Validation Error, including INVALID_FILE_TYPE
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
invalidFileType:
summary: Unsupported or mismatched media bytes
value:
success: false
error:
code: INVALID_FILE_TYPE
message: >-
Supported media types are JPEG, PNG, WebP, GIF, MP4,
WebM, and QuickTime
components:
schemas:
SuccessResponse:
type: object
properties:
success:
type: boolean
example: true
data:
type: object
required:
- success
ErrorResponse:
type: object
properties:
success:
type: boolean
example: false
error:
type: object
properties:
code:
type: string
example: VALIDATION_ERROR
message:
type: string
example: Rating must be between 1 and 5
required:
- success
- error
````