Api Reference

Obtaining Oauth2 access token

Before scoring user in FriendlyScore White Label API, scoring application needs to be authorized by requesting an access token. This can be made requesting address:

https://YOUR-WHITELABEL-DOMAIN.com/oauth/v2/token?client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&grant_type=client_credentials

where YOUR-WHITELABEL-DOMAIN.com is address where FriendlyScore White Label has been installed. Parameters YOUR_CLIENT_ID and YOUR_CLIENT_SECRET are respectively your OAuth2 client identifier and your OAuth2 client secret. Those can be passed by URL parameters (example above) or via JSON, for example using cURL:

curl -H 'Content-Type: application/json' -X POST \
     -d '{
            "grant_type": "client_credentials",
            "client_id": "YOUR_CLIENT_ID",
            "client_secret": "YOUR_CLIENT_SECRET"
        }' \
      'http://YOUR-WHITELABEL-DOMAIN.com/oauth/v2/token'

Example response is shown below.

{
    "access_token":"MzA0MzE4MmQ0YWVkZDQzYzVlM2JkMDY1ZGZlYzgzNzVjMDdhYWNlYTM1MDQ3NTEwNmE0NDhiMWUxNGNmYjlmZQ",
    "expires_in":3600,
    "token_type":"bearer",
    "scope":null
}

The key access_token needs to be stored somwhere for feature use.

Scoring user in FriendlyScore using White Label API

Scoring user in FriendlyScore using White Label API is divided into two steps. First we need to provide user access_tokens, which will result scheduling user for score calculation. Second step is to obtain calculated score from API – we can ask FriendlyScore White Label API whether data is ready or be informed by webhook provided during score calculation request.

Scheduling score calculation

Having valid access_token user scoring can be performed by sending request to http://YOUR-WHITELABEL-DOMAIN.com/api/v2/calculate_score.json. Access token can be send both via parameter or via authorization header. Other mandatory parameter is access_tokens with scrutcture shown below (example in JSON format):

{
    "facebook"       => "USER_FACEBOOK_ACCESS_TOKEN",
    "linkedin"       => "USER_LINKEDIN_ACCESS_TOKEN",
    "twitter"        => "USER_TWITER_ACCESS_TOKEN",
    "twitter_secret" => "USER_TWITTER_ACCESS_TOKEN_SECRET",
    "google"         => "USER_GOOGLE_ACCESS_TOKEN"
}

All access tokens should be valid. Currently only facebook access token is mandatory. Next parameter is partner_user_id. It is used to identify user by identifier from scoring application and it is also mandatory. Last optional parameter is webhook. If we want to be informed when our data is ready, we can provide webhook to scoring application e.g. https://YOUR-SCORING-APPLICATION.com/scoring-finished?user_id=THE-ID

If everything went fine, response code from calculate_score endpoint is 202 (Accepted) and content looks like below:

{
    "result": "success",
    "message": "Queued for calculation.",
    "user_id": "USER-ID"
}

Fetching calculated score

To fetch data from FriendlyScore White Label API, we need to call http://YOUR-WHITELABEL-DOMAIN.com/api/v2/get_score.json endpoint with parameter partner_user_id.

Responses

Sample responses from get_score endpoint are shown below.

Data found

If everything went fine and our data is ready we get HTTP status code: 200 Success with content:

{
    "result":"success",
    "message":"",
    "user_id":"example.user@example.com",
    "facebook_score":"0%",
    "linkedin_score":"25%",
    "twitter_score":"0%",
    "google_score":"60%",
    "score":"24%",
    "social_id_mismatches":null
}
Data not ready

If our data is not yet ready, the HTTP Status code will be 202 Accepted with response:

{
    "result": "error",
    "message": "Data not ready. Try again later"
}
Data not scheduled for calculation

If user identified with partner_user_id has not been scheduled for score calculation API will return HTTP Status code: 424 Failed Dependency, with content:

{
    "result": "error",
    "message": "Score for provided partner_user_id not scheduled for calculation. Call calculate_score endpoint first."
}
Partner user ID not provided

If the parameter partner_user_id has not been provided, API will return HTTP Status code: 404 Not Found, with content:

{
    "result": "error",
    "message": "Parameter partner_user_id not provided."
}


Examples

Performing requests with cURL

Below are examples how API can be queried using cURL command line tool.

Fetching an access token

curl -H "Content-Type: application/json"\
     -X POST\
     -d JSON_DATA\
     'http://YOUR-WHITELABEL-DOMAIN.com/oauth/v2/token'

where JSON_DATA is JSON with following fields:

{
    "client_id":     "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "grant_type":    "client_credentials"
}

Scheduling calculation

curl -H "Authorization: Bearer ACCESS_TOKEN"\
     -H "Content-Type: application/json"\
     -X POST\
     -d JSON_DATA\
     'http://YOUR-WHITELABEL-DOMAIN.com/api/v2/calculate_score.json'

Where ACCESS_TOKEN is the access_token obtained via /oauth/v2/token action and JSON_DATA is JSON with following fields:

{
    "partner_user_id": "SAMPLE_USER_ID",
    "access_tokens": {
        "facebook":       "USER_FACEBOOK_ACCESS_TOKEN",
        "linkedin":       "USER_LINKEDIN_ACCESS_TOKEN",
        "twitter":        "USER_TWITTER_ACCESS_TOKEN",
        "twitter_secret": "USER_TWITTER_ACCESS_TOKEN_SECRET",
        "google":         "USER_GOOGLE_ACCESS_TOKEN"
    },
    "webhook": "http://example.com/api/my-webhook?user=SAMPLE_USER_ID&is_ok=1"
}

facebook token is mendatory.

Getting ready data

curl -H "Authorization: Bearer ACCESS_TOKEN"
     -H "Content-Type: application/json"
     -X GET
     'http://YOUR-WHITELABEL-DOMAIN.com/api/v2/get_score.json?partner_user_id=USER_ID_FROM_YOUR_SCORING_APP'

or

curl -H "Authorization: Bearer ACCESS_TOKEN"
     -H "Content-Type: application/json"
     -X POST
     -d JSON_DATA
     'http://YOUR-WHITELABEL-DOMAIN.com/api/v2/get_score.json'

Where ACCESS_TOKEN is the access_token obtained via /oauth/v2/token action and JSON_DATA is JSON with following field:

{
    "partner_user_id": "USER_ID_FROM_YOUR_SCORING_APP"
}