Platform Overview #
This document introduces the Review Platform, providing interfaces for collecting, storing, moderating, and distributing user-generated product reviews and ratings. The subsequent pages will delve into the intricacies of these functionalities, empowering partners to effectively utilize and leverage the available content through the specified interfaces.
NOTE: The examples shown in this document use example data. The correct API-keys and SFTP access data will be provided to you by your person of contact.
Review Display #
The Review Display offers four options: the Display Frontend is a ready-made interface with limited customization, while the Display API allows for fully customizable review displays but requires development. The Fetch API is ideal for bulk data retrieval without display logic, and the SFTP Feed supports secure, batch data transfers for large-scale operations.
Display Frontend
The Display Reviews HTML API provides an iFrame solution for seamlessly displaying and collecting product reviews on a webpage. It offers various customization options to tailor the review display according to specific market and product needs.
Capabilities:
- iFrame Review Display: Provides a standard iFrame solution to display reviews directly on a webpage.
- Customization Options:
- Company Name: Allows filtering reviews by specifying the company’s name.
- Market-Specific Display: Uses a
displayCodeto represent the company, language, and country, enabling market-specific review displays. - Header Inclusion: Option to include or exclude the header in the displayed content.
- HTML Body Control: Allows including or excluding the HTML body in the review display.
- Submit Review Button: Option to include a submit review button in the iFrame.
- Star Rating Only: Displays only the star ratings if desired.
- Product-Specific Reviews: Fetches reviews for specific products using the
productId. - API Versioning: Supports different API versions, with the latest being
5.4.
Limitations:
- Authentication Requirement: Requires a valid
passKeyto authenticate requests, which must be provided by the consuming market/client. - Static Content: As it is an iFrame solution, the content displayed might have limited interactivity or customization beyond the provided parameters.
The base URL differs for each environment:
<base_url>/content/display/displayReviews.html| Environment | URL |
| Test | https://test.one2five.digital |
| Production | https://app.one2five.digital |
Example : https://test.one2five.digital/content/display/displayReviews.html?productId=CX7-2-45AN&displayCode=aeg-de_de&passKey="YOUR_PASS_KEY"&version=5.4
iFrame C.1 Standard Display iFrame
| Title | Display Reviews |
| Overview | Consume this iFrame endpoint to display the standard iFrame solution for review display. |
| URL | /content/display/displayReviews.html |
| Host | <base_url> |
| Content-Type | text/html |
| Method | HTTP GET |
| Response-Type | html |
| Current Version | 5.4 |
| Base Version | 5.4 |
Request Parameters:
| Parameter Name | Description | Additional Info | Example |
|---|---|---|---|
| apiversion | Latest API Version. | Mandatory | 5.4 |
| passKey | The API key provided by us to each consuming market/client. It is required to authenticate the request source. | Mandatory | |
| productId | The ID of the product for which the review is being requested.It’s Mandatory if productEAN is not provided | Conditional | |
| displayCode | A code which represents the market using company name, country name and language. In the given example (electrolux_fr_ch) – electrolux represents the company, fr represents the language(French) and ch represents the country (Switzerland). | Mandatory | electrolux_fr_ch |
| fromDate | The start date from which you need to extract the reviews. | Optional | YYYY-MM-DD |
| toDate | The end date till which you need to extract the reviews. | Optional | YYYY-MM-DD |
| productEAN | The ID of the product for which the review is being requested. It’s Mandatory if productId is not provided | Conditional |
Display API
The Display API is a versatile tool designed to programmatically retrieve and display reviews on your platform. It provides comprehensive access to product reviews, allowing for detailed customization and integration into various display formats.
Capabilities:
- Product Grouping: The API can display reviews grouped by product, including all necessary review details such as badges, attachments, and client comments. This ensures that each product’s reviews are presented in a cohesive and organized manner.
- Shared Market Reviews: It supports the display of shared market reviews, also including badges, attachments, and client comments. This feature is particularly useful for businesses operating across multiple markets or regions.
- Product-Specific Reviews: The API delivers reviews based on specific products, making it easy to showcase reviews directly related to a particular item, helping users make informed decisions.
- Review Metrics: The API provides detailed review metrics, including the total count of reviews for a particular product, average feedback rating, average quality rating, average design rating, average functionality rating, and the distribution of star ratings (one to five stars).
- Filtering Options: The API allows filtering of reviews within a specified date range and by dual EAN (European Article Number). This filtering capability enables precise control over which reviews are retrieved and displayed.
- Sorting Functionality: Reviews can be sorted by date and rating in either ascending or descending order, providing flexibility in how reviews are presented to end-users.
- API Rate Limiting: The API enforces rate limiting to prevent excessive requests and ensure consistent performance. When the request rate exceeds the allowed threshold, the API responds with a status indicating too many requests and includes a retry-after duration. This ensures fair usage and prevents system overload by requiring clients to wait before making further requests.
Limitations:
- Passkey Validation: The API requires a valid API passkey for access. Ensuring that the passkey is valid and properly managed is crucial for seamless API operation. Failure to provide a valid passkey will result in denied access to the API.
The base URL differs for each environment:
<base_url>/data/displayreviews.json| Environment | URL |
| Test | https://test.one2five.digital |
| Production | https://app.one2five.digital |
| Title | Display Reviews |
| Overview | Consume this API to fetch reviews for the display only those which has feedback rating, which takes display code, product id and data as input parameters. |
| URL | /data/displayreviews.json |
| Host | <base_url> |
| Content-Type | applications/json |
| Method | HTTP POST |
| Response-Type | json |
| Current Version | 5.4 |
| Base Version | 5.4 |
| Sample Call | This is the sample call. Please see the list below for all request parameters that can be submitted to the API. POST /data/displayreviews.json Host: <base_url> Content-Type: application/json { “passKey”: “aa60c6d8-148f-4ca0-93d6-0eee26f78942”, “apiversion”: “5.4”, “format”: “json”, “displayCode”: “5469-sv_se”, “productId”: 925053258 } |
| Success Response | { “totalReviews”: 70, “averageFeedbackRating”: 4.44, “averageQualityRating”: 4.47, “averageDesignRating”: 4.53, “averageFunctionalityRating”: 4.31, “oneStarRating”: 0, “twoStarRating”: 0, “threeStarRating”: 5, “fourStarRating”: 19, “fiveStarRating”: 44, “reviews”: [ { “reviewTitle”: “Akku – Staubsauger”, “reviewText”: “Super Gerät. \nMan kann sogar im Dunkeln “, “reviewerName”: “Wiersch”, “submissionDate”: “2018-10-31T15:12:36.087Z”, “feedbackRating”: 5, “designRating”: 5, “qualityRating”: 5, “functionalityRating”: 5, “isRecommended”: true, “badges”: [ “Verified Purchaser” ] } ], “hasErrors”: false, “errors”: [] } |
| Error Response | { “totalReviews”: null, “averageFeedbackRating”: 0, “averageQualityRating”: 0, “averageDesignRating”: 0, “averageFunctionalityRating”: 0, “reviews”: null, “hasErrors”: true, “errors”: [ { “Code”: “ERROR_PARAM_INVALID_API_KEY”, “Message”: “The passKey provided is invalid.” } ] } |
| Rate Limiting Error Response | {“totalReviews”:null, “averageFeedbackRating”:0.0, “averageQualityRating”:0.0, “averageDesignRating”:0.0, “averageFunctionalityRating”:0.0, “oneStarRating”:0.0, “twoStarRating”:0.0, “threeStarRating”:0.0, “fourStarRating”:0.0, “fiveStarRating”:0.0, “reviews”:null, “hasErrors”:true, “errors”:[ { “Code”:”429 TOO_MANY_REQUESTS”, “Message”:”X-Rate-Limit-Retry-After-Seconds 50″ } ] } |
Request Parameters
| Parameter Name | Description | Additional Info | Example |
| apiversion | Latest API Version. | Mandatory | 5.4 |
| format | Response format. | Mandatory | json |
| passKey | The API key provided by us to each consuming market/client. It is required to authenticate the request source. | Mandatory | |
| productId | The ID of the product for which the review is being requested. | Optional | |
| displayCode | It is a code which represents the market using company name, country name and language. In the given example (electrolux_fr_ch) – electrolux represents the company, fr represents the language(French) and ch represents the country (Switzerland). | Mandatory | electrolux_fr_ch |
| fromDate | It is the start date from which you need to extract the reviews. | Optional | YYYY-MM-DD |
| toDate | It is the end date till which you need to extract the reviews. | Optional | YYYY-MM-DD |
| productEan | The ID of the product for which the review is being requested. | Optional | |
| sortBy | To sort the reviews either by submission Date or Rating | Optional | Date/Rating |
| sortOrder | It’s parameters which will specify the order of sorting by default it’s DESC | Optional | DESC/ASC |
Response Parameter:
| Parameter Name | Description |
|---|---|
| HasErrors | ‘true’ if it is an ErrorResponse i.e. something is not correct in the submission request; other wise ‘false’ for a SuccessResponse. |
| Errors | Populated with the error code and message if present. |
| Reviews | Contains Reviews data. |
| TotalReviews | Count of all the reviews for the particular product. |
| AverageFeedbackRating | Average feedback rating for the particular product. |
| AverageQualityRating | Average quality rating for the particular product. |
| AverageDesignRating | Average design rating for the particular product. |
| AverageFunctionalityRating | Average functionality rating for the particular product. |
| ReviewTitle | Review title for the particular review. |
| ReviewText | Review text for the particular review. |
| ReviewerName | Reviewer name for the particular review. |
| SubmissionDate | Submission date of the particular review. |
| FeedbackRating | Feedback rating for the particular product in the given review. |
| DesignRating | Design rating for the particular product in the given review. |
| QualityRating | Quality rating for the particular product in the given review. |
| FunctionalityRating | Functionality rating for the particular product in the given review. |
| OneStarRating | Total count of reviews which has one start rating |
| TwoStarRating | Total count of reviews which has Two start rating |
| ThreeStarRating | Total count of reviews which has three start rating |
| FourStarRating | Total count of reviews which has four start rating |
| FiveStarRating | Total count of reviews which has Five start rating |
| IsRecommended | IsRecommend is a boolean field which describes whether user would recommend this product or not |
| Badges | Badges contains the array of badges which is associated with particular review |
| totalPages | Total no of pages the response is divided into. |
| pageNo | Current displayed page number. |
Fetch API #
The Fetch API is designed for efficient retrieval of large volumes of review data, making it ideal for backend systems that require comprehensive data analysis and processing.
Capabilities:
- Market-Wise Display: The API can fetch and display reviews segmented by market, allowing for tailored data retrieval based on geographical or market-specific needs.
- Shared Market Reviews: It supports fetching reviews that are shared across different markets, providing a unified view of review data across various regions.
- Date Range Filtering: The API allows for the retrieval of reviews within a specified date range, making it easy to access reviews from specific periods.
- Flexible Filtering: Reviews can be filtered based on criteria such as product status, review status, and dual EAN (European Article Number), enabling precise data extraction according to specific needs.
- Pagination: Pagination is supported by version v2 API.
- API Rate Limiting: The API enforces rate limiting to prevent excessive requests and ensure consistent performance. When the request rate exceeds the allowed threshold, the API responds with a status indicating too many requests and includes a retry-after duration. This ensures fair usage and prevents system overload by requiring clients to wait before making further requests.
Limitations:
- Passkey Validation: The API requires a valid API passkey for access. Ensuring that the passkey is valid and properly managed is crucial for seamless API operation. Failure to provide a valid passkey will result in denied access to the API.
- No Display Logic: The Fetch API focuses solely on data retrieval and does not include any built-in display or presentation logic.
version 1 api : <base_url>/data/fetch/reviews.json
version 2 api : <base_url>/data/v2/fetch/reviews.jsonAPI : V1 Fetch API
| Title | Display Reviews |
| Overview | Consume this API to fetch reviews for the display which takes display code data as input parameters. |
| URL | version v1 : /data/fetch/reviews.json |
| Host | <base_url> |
| Content-Type | applications/json |
| Method | HTTP POST |
| Response-Type | json |
| Current Version | 5.4 |
| Base Version | 5.4 |
| Success Response | { “totalReviews”: 2698, “reviews”: [ { “reviewId”: 765548, “productExtId”: “PA91-404DG”, “reviewText”: “Har haft denna nu i ett par månader och tycker att den fungerar utmärkt ingenting att klaga över. “, “reviewTitle”: “Hel nöjd kund”, “reviewerNickname”: “Jerry21a”, “displayCode”: “ELECTROLUX-SV_SE”, “submissionTime”: “2019-10-01T18:18:27.634Z”, “reviewStatus”: “Approved”, “productEan”: “7332543636570”, “productStatus”: “Active”, “sourceType”: “PIE”, “isRecommended”: true, “feedbackRating”: 5, “functionalityRating”: 5, “designRating”: 5, “qualityRating”: 4, “badges”: null, “helpfulness”: 0, “totalFeedbackCount”: 0 }, { “”reviewId”: 765548, “productExtId”: “PA91-404DG”, “reviewText”: “Har haft denna nu i ett par månader och tycker att den fungerar utmärkt ingenting att klaga över. “, “reviewTitle”: “Hel nöjd kund”, “reviewerNickname”: “Jerry21a”, “displayCode”: “ELECTROLUX-SV_SE”, “submissionTime”: “2019-10-01T18:18:27.634Z”, “reviewStatus”: “Approved”, “productEan”: “7332543636570”, “productStatus”: “Active”, “sourceType”: “PIE”, “isRecommended”: true, “feedbackRating”: 5, “functionalityRating”: 5, “designRating”: 5, “qualityRating”: 4, “badges”: null, “helpfulness”: 0, “totalFeedbackCount”: 0 } “HasErrors”: false, “Errors”: null, } |
| Error Response | { “totalAvailableReview”: 0, “reviews”: [] “hasErrors”: true, “errors”: [ { “Code”: “ERROR_PARAM_INVALID_API_KEY”, “Message”: “The passKey provided is invalid.” } ] } |
| Rate Limiting Error Response | { “reviews”: [], “HasErrors”: true, “Errors”: [ { “Code”: “429 TOO_MANY_REQUESTS”, “Message”: “X-Rate-Limit-Retry-After-Seconds 35” } ], “TypicalHoursToPost”: 0 } |
API : V2 FETCH API
| Title | Display Reviews |
| Overview | Consume this API to fetch reviews for the display which takes display code data as input parameters. |
| URL | version v2 : /data/v2/fetch/reviews.json |
| Host | <base_url> |
| Content-Type | applications/json |
| Method | HTTP POST |
| Response-Type | json |
| Current Version | 5.4 |
| Base Version | 5.4 |
| Success Response | { “totalReviews”: 2698, “totalPages”: 185, “pageNo”: 1, “reviews”: [ { “reviewId”: 23801, “productExtId”: “HKP87420FB”, “reviewText”: “Die Nudeln haben innerhalb von Sekunden gekocht! Wow so etwas habe ich noch nie erlebt!”, “reviewTitle”: “So schnell habe ich noch nie gekocht”, “reviewerNickname”: “RobertG86”, “displayCode”: “AEG-DE_DE”, “submissionTime”: “2017-08-12T07:05:45.000-05:00”, “badges”: [ “shared review” ], “reviewStatus”: “Approved”, “productEan”: “7332543293599”, “productStatus”: “Active”, “sourceType”: “Brand Site”, “isRecommended”: false, “feedback”: 5, “functionality”: 5, “design”: 5, “quality”: null, “helpfulness”: 0, “totalFeedbackCount”: 0 }, { “reviewId”: 23734, “productExtId”: “HK6542H1IB”, “reviewText”: “Keine Angabe wie die Uhrzeit des Gerätes einzustellen ist.!!”, “reviewTitle”: “Uhrzeit einstellen?”, “reviewerNickname”: “G.Kieselstein137”, “displayCode”: “AEG-DE_DE”, “submissionTime”: “2017-11-03T17:25:54.000-05:00”, “badges”: [], “feedbackRating”: 3, “functionalityRating”: 3, “designRating”: 5, “qualityRating”: 3, “reviewStatus”: “Approved”, “productEan”: “7332543293599”, “productStatus”: “Active”, “sourceType”: “Brand Site”, “isRecommended”: false, “helpfulness”: 0, “totalFeedbackCount”: 0 } “HasErrors”: false, “Errors”: null, } |
| Error Response | { “totalAvailableReview”: 0, “reviews”: [] “hasErrors”: true, “errors”: [ { “Code”: “ERROR_PARAM_INVALID_API_KEY”, “Message”: “The passKey provided is invalid.” } ] } |
Request Parameters:
| Parameter Name | Description | Additional Info | Example |
|---|---|---|---|
| apiversion | Latest API Version. | Mandatory | 5.4 |
| format | Response format. | Mandatory | json |
| passKey | The API key provided by us to each consuming market/client. It is required to authenticate the request source. | Mandatory | |
| displayCode | It is a code which represents the market using company name, country name and language. In the given example (electrolux_fr_ch) – electrolux represents the company, fr represents the language(French) and ch represents the country (Switzerland). | Conditional | electrolux_fr_ch |
| source | it shows all the reviews on the basis of brandSite,Pie,Event and so on. | Conditional | Pie |
| reviewStatus | it Shows the Review is Approved ,rejected or Pending | Conditional | Approved |
| productStatus | it Shows the Product is Active or Inactive | Conditional | Active |
| fromDate | The Start date till which you need to extract the reviews. | Conditional | YYYY-MM-DD |
| toDate | The End date till which you need to extract the reviews. | Conditional | YYYY-MM-DD |
| pageNo | page no value | (Mandatory) Only Supported by version 2 api | 2 |
| pageSize | no of records per page | (Optional default is 25) Only Supported by version 2 api | 25 |
Response Parameter:
| Parameter Name | Description |
|---|---|
| HasErrors | ‘true’ if it is an ErrorResponse i.e. something is not correct in the submission request; other wise ‘false’ for a SuccessResponse. |
| Errors | Populated with the error code and message if present. |
| Reviews | Contains Reviews data. |
| TotalReviews | Count of all the reviews for the particular product. |
| ReviewTitle | Review title for the particular review. |
| ReviewText | Review text for the particular review. |
| ReviewerName | Reviewer name for the particular review. |
| submissionTime | Submission date time of the particular review. |
| FeedbackRating | Feedback rating for the particular product in the given review. |
| DesignRating | Design rating for the particular product in the given review. |
| QualityRating | Quality rating for the particular product in the given review. |
| FunctionalityRating | Functionality rating for the particular product in the given review. |
| productExtId | Unique Product Id For particular market. |
| displayCode | Market Code . |
| reviewStatus | Status of review example Approved , Rejected. |
| productStatus | Status of Product example Active, Inactive |
| sourceType | Source from where the review originates. example brand site , personal interaction mail. |
| isRecommended | can a product be recommended example true, false. |
| badges | It determines what badge a review has, it contains data if review is shared , or is incentivized etc. |
SFTP Feed
The SFTP Feed provides a secure and efficient method for batch uploading and downloading review data, suitable for handling large-scale data transfers and integrating with legacy systems.
Capabilities:
- Daily XML Feed Generation: The system generates XML feeds on a daily basis for markets that require review feeds. This ensures that the most recent data is available for processing.
- Detailed Data Structure: The generated feed includes a comprehensive structure with review details, badges, attachments, comments (including those with attachments), and questions and answers associated with reviews.
- Market-Wise Feed Options: There are two types of feeds available:
- Data Lake Feed: Includes all reviews, including user email addresses, for comprehensive data analysis.
- Normal Feed: Includes only approved reviews, suitable for general use where sensitive information is not required.
- Shared Market Reviews: The feed can also include reviews shared across multiple markets, providing a unified dataset for broader analysis.
Limitations:
- Passkey Validation: The API requires a valid API passkey for access. Ensuring that the passkey is valid and properly managed is crucial for seamless API operation. Failure to provide a valid passkey will result in denied access to the API.
- Complex Setup: Configuring SFTP connections and ensuring proper file placement requires technical knowledge and careful setup.
Example Usage:
- Download Review-Feed:
- Download Path:
/feeds/ - The Review-Feed, generated once daily, can be downloaded from this directory. Regularly check this folder to retrieve the latest reviews.
- for additional details of review-feed click here.
- Download Path:
By leveraging the appropriate API or SFTP feed, you can efficiently manage and display review data based on your specific requirements and technical capabilities. Each method offers unique benefits and potential challenges, so the choice depends on your specific use case.
Submission #
Review Submission
The Review Submission API is used to submit review data from client websites via the API endpoint, which can be later processed as per requirement and used to display reviews on the client website.
<base_url>/data/submitreview.json
The base URL differs for each environment:
| Environment | URL |
| Test | https://test.one2five.digital |
| Production | https://app.one2five.digital |
| Title | Submit Review |
| Overview | This API lets you submit the review to the platform from a remote website. |
| URL | /data/submitreview.json |
| Host | <base_url> |
| Content-Type | applications/x-www-form-urlencoded |
| Method | Post |
| Response-Type | json |
| Current Version | 5.4 |
| Base Version | 5.4 |
| Sample Call | This is the sample call with all mandatory parameters. Please see the list below for all request parameters that can be submitted to the API. POST /data/submitreview.json Host: <base_url> Content-Type: application/x-www-form-urlencoded apiVersion: [latestApiVersion] productId: [ProductId] action: [Action] passKey: [PassKey] FP: [DeviceFingerPrint] userNickname[UserName] agreedToTermsAndConditions: [UserTermsAndConditionsResponse] title: [ReviewTitle]reviewText: [ReviewText] isRecommended: [userRecommendation] rating : [Rating] rating_Features: [RatingFeatures] rating_Desing: [RatingDesign] rating_Quality: [RatingQuality] displayCode: [DisplayCode] hostedAuthentication_AuthenticationEmail: [userEmail] hostedAuthentication_CallbackUrl: [AuthenticationUrl] isAuthenticationRequired: [AuthenticationRequired] format: [ResponseFormat] |
| Success Response | { “Data”:{}, “HasErrors”:false, “Form”:[], “FormErrors”:{}, “TypicalHoursToPost”:72, “SubmissionId”:”3bjfuudsrjt516vitpvwnqrli”, “Review”:{ “SendEmailAlertWhenPublished”:true, “SendEmailAlertWhenCommented”:null, “SubmissionTime”:”2017-12-15T01:51:01.196Z”, “Rating”:5, “IsRecommended”:true, “ReviewText”:”testtesttesttesttesttestesttest”, “TypicalHoursToPost”:null, “Id”:null, “SubmissionId”:null, “Title”:”This product is really nifty” , “CampaignId”:270 }, “Locale”:”en_us”, “Errors”:[] } |
| Error Response | 1. ERROR_DUPLICATE_SUBMISSION { “Locale”=“null”, “Errors”:[ { “Message”:”Duplicate Submission”, “Code”:”ERROR_DUPLICATE_SUBMISSION” } ], “Form”:[], “FormErrors”:{}, “SubmissionId”:null, “Data”:{}, “TypicalHoursToPost”:null, “AuthorSubmissionToken”:null, “HasErrors”:true } 2. ERROR_BAD_REQUEST { “Locale”=“null”, “Errors”:[ { “Message”:”400 – ERROR_PARAM_MISSING_SUBJECT_ID”, “Code”:” ERROR_BAD_REQUEST” } ], “Form”:[], “FormErrors”:{}, “SubmissionId”:null, “Data”:{}, “TypicalHoursToPost”:null, “AuthorSubmissionToken”:null, “HasErrors”:true } 3. ERROR_UNSUPPORTED { “Locale”=“null”, “Errors”:[ { “Message”:”Api version 0.1 is not supported for this pass key.”, “Code”:” ERROR_UNSUPPORTED” } ], “Form”:[], “FormErrors”:{}, “SubmissionId”:null, “Data”:{}, “TypicalHoursToPost”:null, “AuthorSubmissionToken”:null, “HasErrors”:true } |
Request Parameters:
| Parameter Name | Description | Additional Info | Example |
| apiversion | Latest API Version | Mandatory | 5.4 |
| format | Response format. | Mandatory | json |
| passkey | The API key provided by us to the clients. It is required to authenticate the request source. | Mandatory | xx1x-y2yy-3hg4 |
| displayCode | Represents the markt and locale of the Review submitted | Mandatory | 5469-sv_se |
| productId | The id of the product for which the review is being submitted. | Mandatory | 12345 |
| action | The submission action to take. either ‘Preview’ or ‘Submit’. | Mandatory | Preview/Submit |
| agreedToTermsAndConditions | boolean indicating whether or not the user agreed to the terms and conditions. Depends on the client’s settings. | Mandatory | true |
| FP | Device Fingerprint of the users device. The fingerprint should be unique and untouched. | Mandatory | |
| hostedAuthentication_AuthenticationEmail | Email address where the users will receive the verification email from our platform. This parameter is mandatory if you are using a Hosted Authentication Service. | Conditional | test@one2five.digital |
| hostedAuthentication_CallbackURL | This should point to a landing page where a web application exists to complete a user authentication process. | Conditional | https://www.google.com |
| isRecommended | Value in the request is either ‘true’ or ‘false’. The default value will be null. | Conditional | true |
| rating | Value is either positive integer between 1 and 5, and represents review overall rating. | Mandatory | 5 |
| rating_Features | Value is either positive integer between 1 and 5, and represents review overall rating. | Mandatory | 5 |
| rating_Design | Value is either positive integer between 1 and 5, and represents review overall rating. | Mandatory | 4 |
| rating_Quality | Value is either positive integer between 1 and 5, and represents review overall rating. | Mandatory | 3 |
| reviewText | Value is the review body text. The review with less than 50 characters will be considered as a Rating only review. | Mandatory | This is the Review Text. It is a text about the product and describes the users experience with the particular product in detail. |
| title | This is the review title. | Mandatory | Title of a Review |
| userNickname | The display name of the user | Mandatory | Nick98 |
| contextdatavalue_VerifiedPurchaser | ‘true’ or ‘false’ depending on the context of the submission. | Conditional | true |
| contextdatavalue_IncentivizedReview | ‘true’ or ‘false’ depending on the context of the submission. | Conditional | false |
| contextdatavalue_Translated | ‘true’ or ‘false’ depending on the context of the submission. | Conditional | false |
| contextdatavalue_Sweepstake | ‘true’ or ‘false’ depending on the context of the submission. | Conditional | false |
| contextDataValue_Competition | ‘true’ or ‘false’ depending on the context of the submission. | Conditional | false |
| contextdatavalue_Staff | ‘true’ or ‘false’ depending on the context of the submission. | Conditional | false |
| isAuthenticationRequired | ‘false’- To skip the email authentication. ‘true’- otherwise. | Conditional | Mandatory in case of PIE Review submissions to skip the email authentication as the email ids are already verified. |
| userId | This is the id extracted from the PIE feeds. This id should be unique amongst all users. | Conditional | Mandatory in case of PIE Review submissions. |
| campaignId | This is the campaign name form Microsite events. This name should be unique amongst all Microsite events. | Conditional | Mandatory in case of Microsite Review submissions. |
Response Parameter:
| Parameter Name | Description |
| Data | Section containing fields and groups. |
| HasErrors | ‘true’ if it is an ErrorResponse i.e. something is not correct in the submission request; other wise ‘false’ for a SuccessResponse. |
| Errors | Section is populated with the error code and message if present. |
| Form | Section containing an array of field and group references. |
| FormErrors | |
| TypicalHoursToPost | Usual Time it takes for the content to get posted. |
| SubmissionId | An Id for a successful submission returned by our platform. |
| Review | Section containing Review data. |
| SendEmailAlertWhenPublished | ‘true’ or ‘false’ depending on what user has submitted in the request. |
| SendEmailAlertWhenCommented | ‘true’ or ‘false’ depending on what user has submitted in the request. |
| SubmissionTime | The timestamp when the review is submitted to our platform. If you are using any middleware between client’s website and our platform, then please make sure that the middleware does not delay the review submission to our platform. |
| Rating | The rating submitted in the request |
| IsRecommended | ‘true’ or ‘false’ depending on what user has submitted in the request. |
| Author Submission Token | |
| Locale | Whatever was submitted by the user. Default is considered as en_US. |
| Review Text | The text submitted by user as it is. |
| Title | The title of the review as it is submitted by the user from the website. |
Comment Submission
The Submit Review Answer API manages the submission of external comments on reviews. This API allows external comments to be submitted on existing reviews via a secure API endpoint, enabling integration with client systems.
<base_url>/data/submit/reviewanswer
The base URL differs for each environment:
| Environment | URL |
| Test | https://test.one2five.digital |
| Production | https://app.one2five.digital |
| Title | Submit Review Answer |
| Overview | This API lets you submit the review to the platform from a remote website. |
| URL | /data/submit/reviewanswer |
| Host | <base_url> |
| Content-Type | applications/x-www-form-urlencoded |
| Method | Post |
| Response-Type | json |
| Current Version | 5.4 |
| Base Version | 5.4 |
| Sample Call | This is the sample call with all mandatory parameters. Please see the list below for all request parameters that can be submitted to the API. POST /data/submit/reviewanswer { “apiversion”: 0, “commentText”: “string”, “commentType”: “string”, “department”: “string”, “format”: “string”, “passKey”: “string”, “reviewId”: 0, “valid”: true } |
| Request parameters | See Table 1 |
| Success Response | { “Errors”: [ { “Code”: “string”, “Message”: “string” } ], “HasErrors”: true, “comment”: { “commentId”: 0, “commentText”: “string”, “commentType”: “string”, “department”: “string”, “submissionTime”: “string” }, “reviewId”: 0 } |
| Response Parameters | See Table 2 |
Request Parameters
| Parameter | Description | Example |
|---|---|---|
| apiversion | Specifies the version of the API being used. | 5.4 |
| commentText | The text of the external comment. | This is an external comment. |
| commentType | The type of comment being submitted (e.g., feedback, question). | feedback |
| department | The department responsible for the comment. | Customer Support |
| format | The response format (e.g., json). | json |
| passKey | Passkey for authentication. | xx1x-y2yy-3hg4 |
| reviewId | The ID of the review to which the comment is being added. | 1234 |
| valid | Indicates whether the comment is valid. | true |
Response Parameters
| Parameter | Description | Example |
|---|---|---|
| Errors | A list of error objects if any errors occurred during the submission process. Each error object contains a Code and Message. | See below example |
| HasErrors | Indicates whether there were any errors in the submission process. | true |
| comment | An object containing details about the submitted comment. | See below example |
| commentId | The unique ID of the submitted comment. | 5678 |
| commentText | The text content of the submitted comment. | This is an external comment. |
| commentType | The type of comment submitted (e.g., feedback, question). | feedback |
| department | The department responsible for the comment. | Customer Support |
| submissionTime | The timestamp when the comment was submitted. | 2024-09-02T12:34:56Z |
| reviewId | The ID of the review associated with the submitted comment. | 1234 |
File Submission
In the context of the Review or Q&A submission APIs, file attachments such as photos, videos, and documents can be submitted. Each review or Q&A submission allows for a maximum of five attachments in each category (photos, videos, and documents).
Endpoint
- Review Submission:
<base_url>/data/submit/review - Question Submission:
<base_url>/data/submit/question - Answer Submission:
<base_url>/data/submit/answer
Request Parameters for File Attachments
| Parameter | Type | Description | Example |
|---|---|---|---|
| photoCaption_1 to photoCaption_5 | string | Captions for the uploaded photos. | Product front view |
| photoUrl_1 to photoUrl_5 | string | URLs of the uploaded photos. | https://example.com/photo1.jpg |
| videoCaption_1 to videoCaption_5 | string | Captions for the uploaded videos. | Unboxing video |
| videoUrl_1 to videoUrl_5 | string | URLs of the uploaded videos. | https://example.com/video1.mp4 |
| documentCaption_1 to documentCaption_5 | string | Captions for the uploaded documents. | User manual |
| documentUrl_1 to documentUrl_5 | string | URLs of the uploaded documents. | https://example.com/document1.pdf |
Question Submission
The Submit Question API allows clients to submit questions directly from their websites. This API supports a wide range of parameters, enabling detailed question submissions and user authentication via hosted email services. The API is highly customizable to accommodate different client configurations and user authentication flows.
Endpoint:
<base_url>/data/submit/question
The base URL differs for each environment:
| Environment | URL |
| Test | https://test.one2five.digital |
| Production | https://app.one2five.digital |
| Title | Submit ReviewAnswer |
| Overview | The Question submission API is used to submit Question data from client websites via the API endpoint |
| URL | /data/submit/question |
| Host | <base_url> |
| Content-Type | applications/x-www-form-urlencoded |
| Method | Post |
| Response-Type | json |
| Current Version | 5.4 |
| Base Version | 5.4 |
| Sample Call | This is the sample call with all mandatory parameters. Please see the list below for all request parameters that can be submitted to the API. /data/submit/question { “format”: “string”, “apiversion”: 0, “passKey”: “string”, “agreedToTermsAndConditions”: true, “action”: “string”, “productId”: “string”, “questionDetails”: “string”, “questionSummary”: “string”, “displayCode”: “string”, “userNickname”: “string”, “isAuthenticationRequired”: true, “sendEmailAlertWhenPublished”: true, “sendEmailAlertWhenAnswered”: true, “token”: “string”, “photoCaption_1”: “string”, “hostedAuthentication_AuthenticationEmail”: “string”, “documentCaption_5”: “string”, “documentUrl_1”: “string”, “documentUrl_2”: “string”, “documentUrl_3”: “string”, “documentUrl_4”: “string”, “documentUrl_5”: “string”, “fp”: “string”, “videoCaption_3”: “string”, “videoCaption_4”: “string”, “videoCaption_5”: “string”, “videoUrl_1”: “string”, “videoUrl_2”: “string”, “videoUrl_3”: “string”, “videoUrl_4”: “string”, “videoUrl_5”: “string”, “documentCaption_1”: “string”, “documentCaption_2”: “string”, “documentCaption_3”: “string”, “documentCaption_4”: “string”, “hostedAuthentication_CallbackURL”: “string”, “photoCaption_2”: “string”, “photoCaption_3”: “string”, “photoCaption_4”: “string”, “photoCaption_5”: “string”, “photoUrl_1”: “string”, “photoUrl_2”: “string”, “photoUrl_3”: “string”, “photoUrl_4”: “string”, “photoUrl_5”: “string”, “videoCaption_1”: “string”, “videoCaption_2”: “string”, “valid”: true } |
| Success Response | { “Errors”: [ { “Code”: “string”, “Message”: “string” } ], “HasErrors”: true, “questionId”: 0, “questionSummery”: “string”, “questionDetails”: “string”, “userNickname”: “string”, “submissionTime”: “string”, “productExtId”: “string”, “market”: “string”, “sendEmailAlertWhenPublished”: true, “sendEmailAlertWhenAnswered”: true, “fp”: “string”, “hostedAuthenticationCallbackUrl”: “string”, “agreedToTermsAndConditions”: true } |
Request Parameter:
| Parameter Name | Description | Mandatory | Example |
|---|---|---|---|
| apiversion | Latest API Version. | Yes | 5.4 |
| authtoken | The token sent by the platform in the authentication link. | Yes | authtoken |
| format | Response format. | Yes | json |
| passKey | Passkey for authentication. | Yes | xx1x-y2yy-3hg4 |
| agreedToTermsAndConditions | Boolean indicating whether the user agreed to the terms and conditions. | Yes | true |
| FP | Device Fingerprint of the user’s device. | No | FP |
| HostedAuthentication_AuthenticationEmail | Email address where users receive the verification email from the platform. | Yes (if using Hosted Authentication) | user@gmail.com |
| HostedAuthentication_CallbackURL | URL of the link contained in the user authentication email. | Yes (if using Hosted Authentication) | http://www.google.com |
| action | The submission action to take (Preview or Submit). | Yes | Submit |
| productId | The ID of the product for which the question is being submitted. | Yes | 1234 |
| questionDetails | Details of the question. | Yes | Text of the question |
| questionSummary | Summary of the question. | Yes | Title of the question |
| displayCode | Represents the market and locale of the review submitted. | Yes | aeg-de_de |
| userNickname | The display name of the user. | Yes | Nick |
| isAuthenticationRequired | Boolean to skip the email authentication. (false to skip, true otherwise) | No | false |
| sendEmailAlertWhenPublished | Boolean to send an email alert when the question is published. | No | false |
| PhotoCaption_1 to PhotoCaption_5 | Caption for uploaded photos. | No | PhotoCaption_1 |
| PhotoUrl_1 to PhotoUrl_5 | URL for uploaded photos. | No | PhotoUrl_1 |
| VideoCaption_1 to VideoCaption_5 | Caption for uploaded videos. | No | VideoCaption_1 |
| VideoUrl_1 to VideoUrl_5 | URL for uploaded videos. | No | VideoUrl_1 |
| DocumentCaption_1 to DocumentCaption_5 | Caption for uploaded documents. | No | DocumentCaption_1 |
| DocumentUrl_1 to DocumentUrl_5 | URL for uploaded documents. | No | DocumentUrl_1 |
Response Parameter:
| Parameter Name | Description |
|---|---|
| Errors | Array containing error code and message, if any errors occurred. |
| HasErrors | Boolean indicating if there were errors in the submission. |
| questionId | ID of the submitted question. |
| questionSummary | Summary of the submitted question. |
| questionDetails | Details of the submitted question. |
| userNickname | Display name of the user who submitted the question. |
| submissionTime | Time when the question was submitted. |
| productExtId | External ID of the product associated with the question. |
| market | Market where the question was submitted. |
| sendEmailAlertWhenPublished | Boolean indicating if an email alert will be sent when the question is published. |
| sendEmailAlertWhenAnswered | Boolean indicating if an email alert will be sent when the question is answered. |
| fp | Device Fingerprint of the user’s device. |
| hostedAuthenticationCallbackUrl | Callback URL for hosted authentication. |
| agreedToTermsAndConditions | Boolean indicating if the user agreed to the terms and conditions. |
Answer Submission
The Submit Answer API facilitates the submission of answers to specific questions directly from client websites. This API allows users to post their answers, ensuring they are properly authenticated and associated with the relevant question on the platform. It supports various customization options, such as including media files, setting display preferences, and handling user authentication through hosted services.
Endpoint:
<base_url>/data/submit/answer
The base URL differs for each environment:
| Environment | URL |
| Test | https://test.one2five.digital |
| Production | https://app.one2five.digital |
| Title | Submit ReviewAnswer |
| Overview | The Answer submission API is used to submit Answer data from client websites via the API endpoint |
| URL | /data/submit/answer |
| Host | <base_url> |
| Content-Type | applications/x-www-form-urlencoded |
| Method | Post |
| Response-Type | json |
| Current Version | 5.4 |
| Base Version | 5.4 |
| Sample Call | This is the sample call with all mandatory parameters. Please see the list below for all request parameters that can be submitted to the API. /data/submit/answer { “format”: “string”, “apiversion”: 0, “passKey”: “string”, “agreedToTermsAndConditions”: true, “action”: “string”, “isAuthenticationRequired”: true, “sendEmailAlertWhenPublished”: true, “userNickname”: “string”, “displayCode”: “string”, “answerText”: “string”, “questionId”: 0, “photoCaption_1”: “string”, “documentCaption_5”: “string”, “documentUrl_1”: “string”, “documentUrl_2”: “string”, “documentUrl_3”: “string”, “documentUrl_4”: “string”, “documentUrl_5”: “string”, “videoCaption_3”: “string”, “videoCaption_4”: “string”, “videoCaption_5”: “string”, “videoUrl_1”: “string”, “videoUrl_2”: “string”, “videoUrl_3”: “string”, “videoUrl_4”: “string”, “videoUrl_5”: “string”, “documentCaption_1”: “string”, “documentCaption_2”: “string”, “documentCaption_3”: “string”, “documentCaption_4”: “string”, “photoCaption_2”: “string”, “photoCaption_3”: “string”, “photoCaption_4”: “string”, “photoCaption_5”: “string”, “photoUrl_1”: “string”, “photoUrl_2”: “string”, “photoUrl_3”: “string”, “photoUrl_4”: “string”, “photoUrl_5”: “string”, “videoCaption_1”: “string”, “videoCaption_2”: “string”, “hostedAuthentication_AuthenticationEmail”: “string”, “fp”: “string”, “hostedAuthentication_CallbackURL”: “string”, “valid”: true } |
| Success Response | { “Errors”: [ { “Code”: “string”, “Message”: “string” } ], “HasErrors”: true, “answerId”: 0, “questionId”: 0, “answerText”: “string”, “userNickname”: “string”, “submissionTime”: “string”, “productExtId”: “string”, “locale”: “string”, “sendEmailAlertWhenPublished”: true, “isAuthenticationRequired”: true, “hostedAuthenticationCallbackUrl”: “string” } |
Request Parameters:
| Name | Description | Required | Example Value |
|---|---|---|---|
| apiversion | Latest API Version. | Yes | 5.4 |
| authtoken | The token sent by our platform in the authentication link in the email sent to the specified user email-id. | Yes | authtoken |
| format | Response format. | Yes | json |
| passKey | Passkey for authentication. | Yes | xx1x-y2yy-3hg4 |
| agreedToTermsAndConditions | Boolean indicating whether or not the user agreed to the terms and conditions. Depends on the client’s settings. | Yes | true |
| FP | Device Fingerprint of the user’s device. The fingerprint should be unique and untouched. | Yes | `134567edjtcvb~!@#$%^&*(Z_+{:<>>:”} |
| HostedAuthentication_AuthenticationEmail | Email address where the users will receive the verification email from our platform. Required if using Hosted Authentication Service. | Yes | user@gmail.com |
| HostedAuthentication_CallbackURL | URL of the link contained in the user authentication email. Required if using Hosted Authentication Service. | Yes | http://www.google.com |
| action | The submission action to take. Either ‘Preview’ or ‘Submit’. ‘Preview’ will show a draft of the review being submitted. | Yes | submit |
| questionId | The ID of the Question for which the Answer is being submitted. | Yes | 1234 |
| answerText | Answer Text. | Yes | Text of the answer |
| displayCode | Represents the market and locale of the Review submitted. | No | aeg-de_de |
| userNickname | The display name of the user. | Yes | Nick |
| isAuthenticationRequired | false– To skip the email authentication. true– otherwise. | No | false |
| sendEmailAlertWhenPublished | Send email alert when published. | No | false |
| PhotoCaption_1 | Caption for the uploaded photo. You can include parameters for PhotoCaption_1 to PhotoCaption_5. | No | PhotoCaption_1 |
| PhotoUrl_1 | Photo URL. You can include parameters for PhotoUrl_1 to PhotoUrl_5. | No | PhotoUrl_1 |
| VideoCaption_1 | Caption for the uploaded video. You can include parameters for VideoCaption_1 to VideoCaption_5. | No | VideoCaption_1 |
| VideoUrl_1 | Video URL. You can include parameters for VideoUrl_1 to VideoUrl_5. | No | VideoUrl_1 |
| DocumentCaption_1 | Caption for the uploaded document. You can include parameters for DocumentCaption_1 to DocumentCaption_5. | No | DocumentCaption_1 |
| DocumentUrl_1 | Document URL. You can include parameters for DocumentUrl_1 to DocumentUrl_5. | No | DocumentUrl_1 |
Response Parameters:
| Name | Description |
|---|---|
| Errors | An array of error objects, each containing a code and message indicating the error details. |
| Errors.Code | The code of the specific error. |
| Errors.Message | The message describing the error. |
| HasErrors | Indicates whether there were any errors during the submission. true if errors occurred. |
| answerId | The unique ID of the submitted answer. |
| questionId | The unique ID of the question to which the answer was submitted. |
| answerText | The text of the submitted answer. |
| userNickname | The display name of the user who submitted the answer. |
| submissionTime | The timestamp when the answer was submitted. |
| productExtId | The external ID of the product associated with the answer. |
| locale | The locale of the submitted answer (e.g., en_US, de_DE). |
| sendEmailAlertWhenPublished | Indicates if an email alert will be sent when the answer is published. |
| isAuthenticationRequired | Indicates if email authentication was required for the submission. |
| hostedAuthenticationCallbackUrl | The callback URL used for hosted authentication if applicable. |
Feedback Submission
The Feedback Submission API enables the submission of feedback related to reviews directly from your website. By interacting with this API, you can provide feedback such as marking content as inappropriate or voting on its helpfulness. This API is crucial for maintaining the integrity and quality of user-generated content on your platform.
Endpoint:
<base_url>/data/submitfeedback.json
API A.4 Feedback Submission API
| Title | Submit Feedback |
| Overview | This API allows you to submit feedback for a review from your website. |
| URL | /data/submitfeedback.json |
| Host | <base_url> |
| Content-Type | applications/json |
| Method | HTTP POST |
| Response-Type | json |
| Current Version | 5.4 |
| Base Version | 5.4 |
| Sample Call | Below is the sample call without all parameters. Please see the list of request parameters that can be submitted to the API.This is the sample call. Please see the list below for all request parameters that can be submitted to the API.POST /data/submitfeedback.json Host: <base_url> Content-Type: application/json{ “passKey”: “aa60c6d8-148f-4ca0-93d6-0eee26f78942”, “apiversion”: “5.4”, “format”: “json”, “contentId”: 12345, “contentType”: “question”, “feedbackType”: “inappropriate” } |
| Success Response | { “Data”:{}, “HasErrors”:false, “Form”:[], "FormErrors":{}, "TypicalHoursToPost":72, "SubmissionId":"3bjfuudsrjt516vitpvwnqrli", "Feedback":{ "Helfulness":{ "Vote"Positive, "AuthorId":"" }, "Inappropriate":null }, "Locale":"en_us", "Errors":[] } |
| Error Response | 1. ERROR_DUPLICATE_SUBMISSION{ “Locale”=“null”, “Errors”:[ { “Message”:”Duplicate Submission”, “Code”:”ERROR_DUPLICATE_SUBMISSION” } ], “Form”:[], “FormErrors”:{}, “SubmissionId”:null, “Data”:{}, “TypicalHoursToPost”:null, “AuthorSubmissionToken”:null, “HasErrors”:true}2. ERROR_BAD_REQUEST { “Locale”=“null”, “Errors”:[ { “Message”:”400 - ERROR_PARAM_MISSING_SUBJECT_ID”, “Code”:” ERROR_BAD_REQUEST” } ], “Form”:[], “FormErrors”:{}, “SubmissionId”:null, “Data”:{}, “TypicalHoursToPost”:null, “AuthorSubmissionToken”:null, “HasErrors”:true}3. ERROR_UNSUPPORTED { “Locale”=“null”, “Errors”:[ { “Message”:”Api version 0.1 is not supported for this pass key.”, “Code”:” ERROR_UNSUPPORTED” } ], “Form”:[], “FormErrors”:{}, “SubmissionId”:null, “Data”:{}, “TypicalHoursToPost”:null, “AuthorSubmissionToken”:null, “HasErrors”:true} |
Request Parameter:
| Parameter Name | Description | Additional Info | Example |
|---|---|---|---|
| apiversion | API Version to be used. | Mandatory | 5.4 |
| format | Response format. | Mandatory | json |
| passKey | The API key provided by us to each consuming market/client. It is required to authenticate the request source. | Mandatory | |
| contentId | The id of the content for which the feedback is being submitted. | Mandatory | 2345 |
| contentType | Type of content with which the feedback is associated (review, question, answer or review_comment) | Mandatory | review, question, |
| feedbackType | Type of feedback (inappropriate, helpfulness) | Mandatory | helpfulness |
| vote | Helpfulness vote for this content. Valid votes are: Positive, Negative. This parameter is only required for FeedbackType=helpfulness. | Mandatory if feedbackType is “helpfulness” | |
| reasonText | This parameter will be set if feedbackType is inappropriate. | Conditional | |
| authorId | This is the id of content submitter | Optional |
Response Parameter:
| Parameter Name | Description | Additional Info |
|---|---|---|
| Data | Section containing fields and groups. | |
| HasErrors | ‘true’ if it is an ErrorResponse i.e. something is not correct in the submission request; other wise ‘false’ for a SuccessResponse. | |
| Errors | Section is populated with the error code and message if present. | |
| Form | Section containing an array of field and group references. | Not used currently |
| FormErrors | Not used currently | |
| TypicalHoursToPost | Usual Time it takes for the content to get posted. | |
| SubmissionId | An Id for a successful submission returned by our platform. | Not used currently |
| Locale | Whatever was submitted by the user. Default is considered as en_US. | de_de |
| Feedback | Section containing the feedback data |