RepStamp API Documentation

Introduction

The RepStamp API is at the heart of the RepStamp Vision.

It is what powers both e-commerce marketplaces by providing them with a trusted reputation system, and their users by enabling them to leverage their existing online reputation.

The RepStamp API enables marketplaces to:
1. Read reputation information about e-commerce buyers and sellers (based on their previous transactions in other marketplaces).
2. Supply reputation about their own users, thus empowering their users and their own brand.

Getting Started

To use the RepStamp API you must obtain a secret key generated by the RepStamp team.
You may do so by contacting us at info@repstamp.com.

The RepStamp API documentation is divided into two main sections:

   Integrating the RepStamp Widget (Used in most integrations) - Mostly client side code(Javascript) that the integrating marketplace/seller will add to his page.

   Using the RepStamp Server API - supplies all functionality the RepStamp widget provides with additional great features such as: Updating a user's reputation, Querying whether the seller and buyer are related on their social networks and more... legend>

The Repstamp Widget

Adding the RepStamp widgets and badges to your website are crucial when integrating with RepStamp. This allows all buyers to view the full user’s identity of the sellers through a well-designed widget and the sellers to present their full e-commerce identity, thus increasing sales and removing barriers to entry to your marketplace.

Our full widget displays a summary of the User’s Repstamp Reputation. In addition to showing the User’s Repstamp Badge/Stamp, when hovering the badge the following information will be displayed:
  • The User’s Image.
  • Full Name.
  • Current Position.
  • 3 Reputation Scores: Products, Rentals and Services.
  • Connected platforms – Social + Marketplaces. (Not Clickable).
  • A link to the user Repstamp Profile/Dashboard Page.

Display The Repstamp Widget

Displaying the Repstamp Plugin/widget is done by 2 simple steps:

1. Add the javascript SDK to the head tag in your html Page:

Under the window.Repstamp section in javascript:
key - Change the key value with the secret key that was generated to you by the Repstamp Team.
purchase_id (Optional) - change the purchase_id value with the purchase button's id located in the page where the repstamp widget (not badge) is integrated.

2. Widget Placement
Repstamp Full widget: To present the full widget, you need to place an html line in your seller pages. This html line varies according to the type of seller page you place it in:

Public Seller Page (All users can see this page, for example: when clicking on one this seller's products) - This badge will not be shown if the seller did not sign up to repstamp yet.
Newbie

Private Seller Page(can only be accessed by seller) - This badge will be shown as a locked RepStamp badge if seller does not have an account yet.
Unlocked

Repstamp Badge: In order to show the user’s Repstamp Badge, integrate the following code wherever you want the badge to appear in your page (recommended for search results page integration):
Newbie

Retrieving the RepStamp widget or badge is done via the user’s email address (hashed using Sha1). For example, for email "example@example.com" you should use: "914fec35ce8bfa1a067581032f26b053591ee38a". The SHA1 result should be placed in one of the div tags above.

This is all you need to do. It is as simple as that! Enjoy the power of the Repstamp Widget!

RepStamp's Server API

The RepStamp API is divided into 3 categories:
1. Creation of RepStamp Accounts
2. Retrieving RepStamp information
3. Updating RepStamp Information

The key should be supplied as a request parameter to each and every request. For example:
https://www.repstamp.com/api/v1/user?key=1234567890abab

Most of the API methods use the JSON format as input and output. Great tools to initially validate the JSON format: Json Formatter and Json Validator .

Creation of RepStamp Accounts

RepStamp accounts are to be created by the marketplace when the user initially creates an account in the platform.

Though, as you, the integrating marketplace might have an initial user base that was enrolled prior to the RepStamp integration, You will have to create an initial script to enroll your users in our system.

All Data provided to this method must be provided in valid JSON format.

User Creation

POST

https://www.repstamp.com/api/v1/user

Method Description:

This method creates users in the RepStamp platform. If the user already exists(was created by another marketplaces or through the RepStamp platform), request returns a Json descriptor of the user.

Sample Method Call:

HTTP Post: http://www.repstamp.com/api/v1/user?key=e444240718e648817b09&data={"identification":"{"facebook":"1342142141,"twitter":"1232421512,"email":""sample@sample.com"},"profile_link":""www.sample.com/sampleuser","nickname":""sample.user","first_name":""sample","last_name":""user"}

or using Curl:

curl -d "data={\"identification\":{\"facebook\":1342142141,\"twitter\":1232421512,\"email\":\"sample@sample.com\"},\"profile_link\":\"www.sample.com/sampleuser\",\"nickname\":\"sample.user\",\"first_name\":\"sample\",\"last_name\":\"user\"}" www.repstamp.com/api/v1/user?key=e444240718e648817b09
Mandatory Parameters

identification

This field is a hash of key value pairs.
It contains all unique identifiers the marketplace knows about the user.
It is composed of pairs of Identification Type and Unique Identifier related to the Identification Type.

Possible Identification Types: "email", "facebook", "linkedin"
Possible Unique Identifications(accordingly): "example@example.com", "12345"(facebook uid)", "67890"(linkedin uid)

It is extremely important to provide as many identification details as possible in order to prevent multiple identities of the same user in RepStamp
(after all... This is what were trying to solve...)
Email identification for new user is mandatory.

profile_link

Link to the user's profile within the marketplace.
For example: www.marketplace.com/users/john.smith

first_name

New user's first name

last_name

New user's last name

nickname

nickname of user within the marketplace

Method Output

JSON Output

upon successful user creation, the method will return a JSON representation of the user. The Json output might look like:
{"user":{"nickname":"dan.benjamin","first_name":"Dan","last_name":"Benjamin","profile_image_link":"https://graph.facebook.com/670160849/picture?width=142&height=142","badge":"Newbie","products_score":100,"rentals_score":80,"services_score":90,"profile_link":"https://www.Repstamp.com/users/dan.benjamin","facebook_profile_link":"http://www.facebook.com/benjamin.dan","linkedin_profile_link":null}}

Querying the RepStamp API

This section is the bread and butter of the RepStamp API.
It is what allows marketplaces to retrieve reputation information about their existing users, based on their past transactions online in other marketplaces.

The RepStamp API currently exposes 2 types of information about its users:
1. Reputation - General Reputation Score and a proprietary score per segment(Products, Rentals and Services)
2. Connections - As RepStamp users connect both their Facebook and Linkedin accounts, the RepStamp API will allow you to query whether a specific user has any shared connections with our seller.


Reputation Query

GET

https://www.repstamp.com/api/v1/user/:id

Method Description:

This method returns all information about a specific user in our system based on the sha1 digest of his email address

Sample Method Call:

http://www.repstamp.com/api/v1/user/bc42d7d61c52a609c6b93ee2388f16088bd9a39e?key=e444240718e648817b09&type=locked
Mandatory Parameters

User Identification

Sha1 of queried user's email address that is to be given in the url request

Request Type

This field is internal. You may fill whatever string you wish here

Method Output

JSON Output

upon successful user query, the method will return a JSON representation of the user. The Json output might look like:
{"user":{"nickname":"dan.benjamin","first_name":"Dan","last_name":"Benjamin","profile_image_link":"https://graph.facebook.com/670160849/picture?width=142&height=142","badge":"Newbie","products_score":100,"rentals_score":80,"services_score":90,"profile_link":"https://www.Repstamp.com/users/dan.benjamin","facebook_profile_link":"http://www.facebook.com/benjamin.dan","linkedin_profile_link":null}}

Mutual Connections Query

GET

https://www.repstamp.com/api/v1/user/:id/common

Method Description:

This method will check whether the user being queried has any mutual connections with input arguments (facebook/linkedin identifier of a user)

For example: A logged in(using linkedin) shopper is currently browsing John Smith's profile. John Smith has associated his linkedin account in RepStamp.


Using this method call, the caller might identify whether the shopper and seller share mutual friends or are already friends(facebook/linkedin)

Sample Method Call:

http://www.repstamp.com/api/v1/user/6b33bfcb6db8091ba96d129327c6b7780129ee1e/common?key=e444240718e648817b09&data={"buyer_facebook":593248192,"buyer_linkedin":12345}
Optional Parameters (one or both of these must be supplied)

buyer_facebook

facebook unique identifier of the buyer(one we are trying to find a mutual connection the RepStamp user

buyer_linkedin

linkedin unique identifier of the buyer(one we are trying to find a mutual connection the RepStamp user

Method Output

"0 - Buyer and Seller are friends!"

Buyers and Sellers are friends (either on facebook or linkedin)

"1 - Buyer and Seller are Same User"

Buyer ID and Seller ID provided represent the same user

"2 - Buyer and Seller have X mutual friends!"

Buyers and Sellers are not friends but have mutual friends.

"3 - No facebook information about seller"

RepStamp does not contain any facebook information about this specific seller

"4 - Buyer facebook identity does not exist"

RepStamp could not match the facebook identity of buyer given to a real facebook user

Updating User Reputation

This section discusses how connected marketplaces can update their user's reputation.
By updating their user's reputation they may increase buyers' and sellers' reputation scores within the RepStamp platform.
Updating one's reputation information is generally tied to a transaction made in the customer marketplace.


Reputation/Review Update

POST

https://www.repstamp.com/api/v1/user/:id

Method Description:

This method receives either reviews or reputation updates about a specific repstamp user (both may be supplied in one method call)

Upon receiving these, a new reputation score will be calculated for a given user based on new information received

Sample Method Call:

HTTP POST: www.repstamp.com/api/v1/user/6b33bfcb6db8091ba96d129327c6b7780129ee1e/update?key=e444240718e648817b09&data={"normalized_positive_reputation":97,"reviews_to_add":[{"review_content":"Dan is an excellent seller. Got the product as described","reviewer_nickname":"dbenajmin57","review_link":"www.sample.com/review_id=123"},{"review_content":"Product was not as described!","reviewer_nickname":"dbenajmin56","review_link":"www.sample.com/review_id=111"}],"number_of_feedbacks":20}

or using Curl:

curl -d "data={\"normalized_positive_reputation\":97,\"reviews_to_add\":[{\"review_content\":\"Dan is an excellent seller. Got product as described\",\"reviewer_nickname\":\"dbenajmin57\",\"review_link\":\"www.sample.com/review_id=123\"},{\"review_content\":\"Product was not as described\",\"reviewer_nickname\":\"dbenajmin56\",\"review_link\":\"www.sample.com/review_id=111\"}],\"number_of_feedbacks\":20}" www.repstamp.com/api/v1/user/6b33bfcb6db8091ba96d129327c6b7780129ee1e/update?key=e444240718e648817b09
Optional Parameters(Reputation Update)

normalized_positive_reputation

A normalized (to a scale of 0-100) reputation score for the user as calculated in the marketplace

Must be supplied with the parameter: number_of_feedbacks

number_of_feedbacks

This is the number of feedbacks the user has received in the marketplace (usually ties to the number of feedbacks that the user's reputation is based upon)

Must be supplied with the parameter: normalized_positive_reputation

Optional Parameters(Reviews Update) [Supplied as an array of reviews] [per-review parameters]

review_content

Content of the review as given in the marketplace

reviewer_nickname

nickname of the person who wrote the review

review_link

link to the review in the marketplace

Method Output

null

nothing updated

"Updated user reputation"

updated the user reputation data in marketplace.

"Updated user reviews"

updated the user reviews in marketplace in the RepStamp database.

"Updated user reputation, Updated user reviews"

updated both user reviews and user's reputation in the RepStamp database

Troubleshooting

This section covers common errors when initially starting to interact with the RepStamp API.
Most errors happen due to mis-use of the exposed methods and should be resolved using this troubleshooting guide and refering to the method samples supplied above.
If one believes there is a bug with any of these, please contact us at info@repstamp.com

Error Codes & Possible Solutions

"Error 1 - Could not find customer key in database. Please check your key and try again"

The supplied customer key given as a request parameter was not found in the database. Please check that the key supplied is the correct one. If this key is supposed to be valid, please contact us at info@repstamp.com

"Error 2 - Invalid JSON. Error details: ______"

The supplied JSON provided in the data variable is invalid. Please validate its syntax and try again. You may use tools such as: Json Validator to troubleshoot your supplied JSON

"Error 101 - User identification array must not be empty!"

User Creation Error - When initially creating a RepStamp user, you must supply an array of user identifications that we will use to create the user. This array must contain at least the user's email, but should also contain any additional identification you (as the marketplace) have, such as: Facebook UID and Linkedin UID

"Error 102 - User must have at least an identification of type email"

User Creation Error - When initially creating a RepStamp user, you must supply an array of user identifications that we will use to create the user. The array you have provided was not empty, though it did not contain the mandatory email address of the user we require to initial set his account.

"Error 103 - User identification email is invalid!"

User Creation Error - supplied email for user is an invalid email (does match email standards)

"Error 105 - User must have a nickname!"

User Creation Error - Every user we create in the system must have a nickname. We prefer taking the nickname he already chose in your system. This nickname will be used in the URL to the user profile in our system.

"Error 106 - User must have a first name!"

User Creation Error - All users created must have a first and last name

"Error 107 - User must have a last name!"

User Creation Error - All users created must have a first and last name

"Error 108 - User facebook identification is invalid (must be a number)"

User Creation Error - the supplied facebook identification for the user (the Facebook UID you provided in the identification array) is invalid. It must a parseable integer

"Error 201 - User does not exist!"

User Reputation Query Error - the supplied sha1 of the user's email does not exist in our database. Please verify that the user's email does exist in the database

"Error 301 - User does not exist!"

User Mutual Connections Error - the supplied sha1 of the user's email does not exist in our database. Please verify that the user's email does exist in the database

"Error 302 - Must supply either facebook or linkedin information about buyer"

User Mutual Connections Error - When querying to verify whether a RepStamp user has mutual connections with a profile viewer (usually the buyers), you must supplier one source of identification for the buyer. This identification can be either facebook UID or Linkedin UID

"Error 401 - Must supply number of feedbacks the reputation is based upon"

User Reputation Update Error - When updating a user's reputation in our database, you must supply the number of feedbacks this reputation score is based upon. These elements are entwined in our algorithm and we cannot accept any updates that do not include this information

"Error 402 - user reputation score must be a number"

User Reputation Update Error - The user reputation score must be a number (normalized to a range of 0-100)

"Error 403 - user reputation must be normalized to a scale between 0 to a 100"

User Reputation Update Error - The user reputation score must be a number (normalized to a range of 0-100)

"Error 404 - number of reviews must be a number"

User Reputation Update Error - When updating a user's reputation in our database, you must supply a valid integer representing the number of feedbacks this score is based upon (this number must be >= 0)

"Error 405 - number of user reviews must be a positive number"

User Reputation Update Error - When updating a user's reputation in our database, you must supply a valid integer representing the number of feedbacks this score is based upon (this number must be >= 0)

"Error 406 - User does not exist!"

User Reputation Update Error - Could not find the user (based on provided sha1 of his email address) in our database. Please verify accessed url
Widget