PowerReviews Write API

[CommunityJedi22]

Welcome

The Write Services B2B Write-a-Review endpoints are intended to provide external integration endpoints to PowerReviews Write-a-Review for server-to-server implementations by external customers. These endpoints include:

• GetReviewTemplate - Retrieve the set of review questions (also known in PowerReviews terminology as a “review template”) for a specific page id, locale and client, and (optionally) a user ID. This response is fully augmented by local specific content where applicable.
• SubmitReview - Submits a user’s review data for a product.

Before you get started

The API key used with the Write API is different than the API key used for the reviews or display API. Before beginning, please make sure the API key being used is for the Write API.

First Steps

You will need to first retrieve the review template using the GetReviewTemplate endpoint. This must be done to retrieve the necessary values and identifiers.

Example: http://writeservices.powerreviews.com/api/b2b/writereview/review_template?apikey=<write_api_key>&merchant_id=<merchant_id>&page_id=<page_id>

The template identifiers vary based on the account and product. Different products can have different review forms if they have been configured in the PowerReviews backend. Only after you have the identifiers from the template can you use the SubmitReview call.

GetReviewTemplate will also give you information about each form field including but not limited to the field_type, required, input_type, answer_type, max_length

Submitting the Review

Once you have collected the review from the end-user, you will need to construct a POST API call using the “Submit a review” endpoint.

The header should be set as Content-Type: application/json

Construct the URL using the parameters specific to your account and the page_id for the particular product the review is for. Example: http://writeservices.powerreviews.com/api/b2b/writereview/submit_review?apikey=<write_api_key>&page_id=<page_id>&merchant_id=<merchant_id>&locale=en_US

The body of the POST, should include the full review as well as other fields. You will need to use the template identifiers that you retrieved from the Get Review Template endpoint as part of the body of this call. The structure of the body should match that of the example in the documentation.

Field Types

Simple

• answer_type: “text” - A field_type of simple with answer_type of text will correspond to a field where the user can write a string of text (e.g. Review Headline, Comments, Nickname, Location). Keep in mind that some of these fields have a max character limit.
• answer_type: “numeric” - A field_type of simple with answer_type of numeric will correspond to either the overall star rating field or a subrating field. This field expects an integer value in the set [1 - 5].

Collection

• answer_type: “single” - A field_type of collection with answer_type of single will correspond to a radio button or dropdown type field. That is, the user must select from a list of predefined options. Even though only a maximum of one answer option is permitted, this field must still be structured using an array. For example,
• "values":"[{"id": "78175", "value": "Yes, I would recommend this to a friend"}]"
• answer_type: “multiple” - A field_type of collection with answer_type of multiple will correspond to a checkbox type field. That is, the user may select multiple options. Answer options may be selected from a predefined list and/or answer options may be defined by the user. All answer options must be structured using an array. For example,
• "values":"[{"value":"Attractive Design", "id":"85099"}, {"value":"Durable", "id":"25997"}]"
• composite - This field type corresponds to an image or video upload.

Additional Fields Outside of the Review Form

• iovation_black_box - This field is required for authenticity/fraud detection purposes as well as review syndication. More information on how to get the iovation_black_box value can be found here: https://developers.powerreviews.com/Content/Write%20API/iOvation.htm
• ip_address - This field should be populated with the user’s IP address. This field is required as part of authenticity/fraud as well as review syndication.
• order_id - If the review is being solicited from a Post Purchase Follow Up Email, the order_id from the customer’s order may be submitted with the review for reporting purposes.
• source - This field should be set to web if the review is coming from a reviewer who is organically searching the site. This field should be set to email if the reviewer was directed to the form from a Post Purchase Follow Up Email. Setting this field to email will badge the review with the Verified Buyer badge.
• disclosure_code - This field may be set to sampling if the review was solicited as part of a sampling campaign. This field may be set to sweepstakes if the review was solicited as part of a sweepstakes campaign. If this field is used for either sampling or sweepstakes, then a disclosure text will be included as part of the review claiming that the review was written as part of sampling or sweepstakes.

Response

If a request fails to pass validation, a response similar to the GetReviewTemplate quest will be returned; however, only fields that failed validation will be returned and will have an error_message attribute will be populated.

Status codes

• 200 OK - Successful request
• 400 CouldNotReadRequest - Invalid JSON body or otherwise unreadable request body
• 400 Missing Merchant - Missing parameter combination to identify merchant account.
• 400 MissingParameter - General error message if a required parameter is missing. Message will identify the missing parameter.
• 400 Invalid Parameter - General error message if a parameter fails validation. Message will identify the missing parameter.
• 400 CouldNotSaveImage
• 400 ImageUploadNotEnabled
• 400 UnrecognizedField - Field provided has a key that is not part of the expected review template
• 400 ValidationFailure - One of the fields submitted failed validations
• 400 ReviewAlreadySubmitted - Returned if a review is identified as having already been submitted
• 401 MerchantNotEnabled
• 401 MerchantNotEnabledForSSL
• 401 Missing API
• 403 Invalid API Key
• 405 Method Not Allowed - Returned if your request is not HTTPS
• 413 ReviewTooLong - Returned if the review content was too large for the internal system to handle
• 415 Unsupported Media Type - Returned if the body of your POST request is not JSON
• 504 InternalError - Returned if an unexpected error was encountered in the server

400 Error Details When a field has failed validation, a 400 status_code is returned with the message "Please update the highlighted fields below to continue with your submission." When that occurs, a JSON response is provided with a separate error_code object within each individual field object.

Example:

{
"id": "ag1_o44240",
"field_type": "simple",
"key": "headline",
"label": "Review Title",
"required": true,
"helper_text": "Include a short, descriptive title to publish with your review",
"error_message": {
"error_code": "RequiredField",
"message": "Required Field"
},
"input_type": "TextBox",
"answer_type": "text",
"max_length": 60
}

Possible error codes for individual fields are:

• RequiredField - RequiredField
• RestrictedWord - One or more words were flagged by our profanity/restricted word filter.

TTL

The time-to-live value for the PowerReviews Write API is 6 hours.