Create a review

POST 
https://api.freemius.com/v1/products/{product_id}/users/{user_id}/licenses/{license_id}/reviews.json

Auth:Bearer TokenSCOPE: PRODUCT

Product-scoped API tokens allow you to operate on the product itself. This token usually allows read-only access to the product configuration and write access to several operations on subscriptions, customers, payments, and more. For most SaaS or app integrations, this is the token you will need.

1. Go to the Freemius Developer Dashboard.
2. Open the Settings page of the relevant product.
3. Click the API & Keys tab.
4. Copy the API Bearer Authorization Token from the UI.

---

Create a review associated with a license. If you want to create/import reviews which are not associated with a license or from a different system, please use the Review endpoint under products/{product_id}/reviews.json.

Request

Path Parameters

product_id integer<int64>required
The ID of the product.
Possible values: >= 1
Example: 1234
user_id integer<int64>required
The ID of the User.
Possible values: >= 1
Example: 1234
license_id integer<int64>required
The ID of the License.
Possible values: >= 1
Example: 1234

Query Parameters

fields string
Comma separated list of fields to return in the response. If not specified, all fields are returned.
Example: id,name,slug

multipart/form-dataapplication/json

Bodyrequired

Data needed to create a review with an optional picture. When sending multipart/form-data the data property must be a JSON object with same structure as the JSON payload.

picturestring<binary>

Reviewer's profile picture. A maximum of 200KB in size and 300px width and 300px height is allowed.

datastring<json>
The JSON data of the endpoint, matching the same schema as the json request body. Must be a valid JSON object.
Example: {"name":"My Product"}

Responses

201

The created review.

application/json

Schema

idstring<int64>

The unique identifier of the entity.

Possible values: >= 1

Example: 123456

createdstring<date-time>

The date and time the entity was created, under UTC timezone.

Example: 2025-01-01 00:00:00

updatedstring<date-time>nullable

The date and time the entity was updated, under UTC timezone. If null then the entity was never updated since its creation.

Example: 2025-01-01 00:00:00

plugin_idstring<int64>

The ID of the product the entity belongs to.

Possible values: >= 1

Example: 123456

external_idstring

The external ID of the review (in case migrating from another system).

user_idstring<int64>nullable

The ID of the user the entity belongs to. If NULL then still not associated to any user.

Possible values: >= 1

Example: 123456

rateinteger

The score of the review.

Possible values: >= 0 and <= 100

Example: 80

titlestring

The title of the review.

Example: Great plugin! It works perfectly.

textstring

The content of the review.

Example: I love this plugin! It has all the features I need and more. The support team is also very responsive and helpful. Highly recommend!

namestring

The full name of the reviewer.

Example: John Doe

job_titlestring

The job title of the reviewer.

Example: Software Engineer

companystring

The company name of the reviewer.

Example: Example Software Inc.

company_urlstring

The URL of the entity.

Example: https://www.example.com

picturestring<binary>

The icon of the entity, must be a valid JPG, PNG or GIF image, with dimension not exceeding 300px by 300px. Max allowed size is 200KB

profile_urlstring

The URL of the reviewer's profile.

Example: https://example.com/profile

license_idstring<int64>

The ID of the license associated with the entity.

Possible values: >= 1

Example: 123456

is_verifiedboolean

Default value: true

Whether this is a genuine review generated by a real user.

is_featuredboolean

Default value: false

Whether the review should be included in marketing material (e.g. pricing page).

400

Bad request. The request could not be understood by the server due to malformed syntax or arguments.

application/json

Schema

pathstring

The API request path.

Example: :/products/product_id/users.json

error object

This object contains the error details.

typestring

The type of the error encountered by the server.

Example: UnauthorizedAccess

messagestring

The descriptive error message.

Example: Some error has occured.

codestring

The error code.

Example: unauthorized_access

httpinteger

The HTTP status code returned by the server.

Example: 401

timestampstring

Current timestamp.

Example: Thu, 11 May 2023 11:45:30 +0000

request object

This object sends back the request payload as received by the server (both from path and from body or query).

property name*any

This object sends back the request payload as received by the server (both from path and from body or query).

Example: {"beautify":true,"format":"json"}

401

Unauthorized access error. The request requires authentication but was not provided or the provided authentication does not satisfy the required permissions.

application/json

Schema

pathstring

The API request path.

Example: :/products/product_id/users.json

error object

This object contains the error details.

typestring

The type of the error encountered by the server.

Example: UnauthorizedAccess

messagestring

The descriptive error message.

Example: Some error has occured.

codestring

The error code.

Example: unauthorized_access

httpinteger

The HTTP status code returned by the server.

Example: 401

timestampstring

Current timestamp.

Example: Thu, 11 May 2023 11:45:30 +0000

request object

This object sends back the request payload as received by the server (both from path and from body or query).

property name*any

This object sends back the request payload as received by the server (both from path and from body or query).

Example: {"beautify":true,"format":"json"}

402

The request is missing the specified argument.

application/json

Schema

pathstring

The API request path.

Example: :/products/product_id/users.json

error object

This object contains the error details.

typestring

The type of the error encountered by the server.

Example: UnauthorizedAccess

messagestring

The descriptive error message.

Example: Some error has occured.

codestring

The error code.

Example: unauthorized_access

httpinteger

The HTTP status code returned by the server.

Example: 401

timestampstring

Current timestamp.

Example: Thu, 11 May 2023 11:45:30 +0000

request object

This object sends back the request payload as received by the server (both from path and from body or query).

property name*any

This object sends back the request payload as received by the server (both from path and from body or query).

Example: {"beautify":true,"format":"json"}

404

The requested resource was not found.

application/json

Schema

pathstring

The API request path.

Example: :/products/product_id/users.json

error object

This object contains the error details.

typestring

The type of the error encountered by the server.

Example: UnauthorizedAccess

messagestring

The descriptive error message.

Example: Some error has occured.

codestring

The error code.

Example: unauthorized_access

httpinteger

The HTTP status code returned by the server.

Example: 401

timestampstring

Current timestamp.

Example: Thu, 11 May 2023 11:45:30 +0000

request object

This object sends back the request payload as received by the server (both from path and from body or query).

property name*any

This object sends back the request payload as received by the server (both from path and from body or query).

Example: {"beautify":true,"format":"json"}