API Reference

Errors

FriendlyScore uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that was caused by the information provided (e.g., a required parameter was omitted, endpoint has been called with improper method, etc.), and codes in the 5xx range indicate an error with FriendlyScore's servers.

How to read the reference

For each API endpoint the reference contains:

  • Required HTTP method (like POST)
  • Description
  • GET/POST parameters denoted in curly brackets like: {param}
  • Descriptions of abovementioned parameters
  • Examples

The examples may use the same parameters denoted in curly brackets like this: {param}. In such case you should substitute them with actual values to be able to run the example.

HTTP status code summary

HTTP status code Cause
200 (Success) Everything worked as expected.
202 (Accepted) System scheduled calculations – data will be available soon
204 (No Content) No data available (probably due to lack of data in user's social networks)
400 (Bad Request) The request was unacceptable due to omitting a required parameter, improper method, etc.
401 (Unauthorized) Invalid OAuth2 access token or OAuth2 access token not provided
403 (Access Denied) Insufficient permissions.
404 (Not Found) The requested resource doesn't exist.
500, 502, 503, 504 (Server Errors) Something went wrong on FriendlyScore's end.

token

POST

Obtain access token.

Parameters


{client_id}

Client ID for your OAuth2 application


{client_secret}

Client secret for your OAuth2 application


{grant_type}

Should be set to: "client_credentials" – other types of grants are currently not used

                            oauth/v2/token
                        

Obtain access token endpoint examples

Response if client_id and client_secret are invalid:

HTTP CODE: 400 (Bad Request)
{
  "error": "invalid_client",
  "error_description": "The client credentials are invalid"
}

Response if client_id and client_secret are valid:

HTTP CODE: 200 (Success)
{
  "access_token": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
  "expires_in": 3600,
  "token_type": "bearer",
  "scope": null
}

calculate-score

POST

Schedules user for score calculation.

Parameters


{id-type}

Type of identifier used to identify the user. There are 2 options:

  • 'id' which means internal FriendlyScore identifier; when you send the first scoring request you won't have it yet, so you can only use the other option
  • 'partner-id' which means identifier provided by the client's company (internal id from your database - this you can always use)


{id}

Identifier of the user. Depends on what is set as {id-type}:

  • when {id-type} is set to 'id': user's FriendlyScore id (returned by our endpoints - it will only be available after the first scoring call)
  • when {id-type} is set to 'partner-id': user id assigned by your database


{access_tokens}

Array with keys obtained from social networks: facebook, linkedin, twitter_user_id, google, paypal, instagram. Your application must allow the user to login into those services to obtain the keys/tokens and provide them to the API.

Required scopes:

    Google:
  • https://www.googleapis.com/auth/plus.login
  • https://www.googleapis.com/auth/userinfo.email
  • https://www.googleapis.com/auth/userinfo.email
  • https://www.googleapis.com/auth/userinfo.profile
  • https://www.googleapis.com/auth/calendar.readonly
  • https://www.googleapis.com/auth/drive.file
  • https://www.googleapis.com/auth/gmail.readonly
  • https://www.googleapis.com/auth/analytics.readonly
  • https://www.googleapis.com/auth/plus.me
    Facebook:
  • email
  • public_profile
  • user_friends


{webhook}

Webhook address to call when data is ready. This is parameter NOT mandatory. If you provide an address, a request will be sent to it when the scoring process ends.


{ip}

IP address of the user


{user_agent}

User agent object. It must follow certain structure – see examples

                            api/v2/users/{id-type}/{id}/calculate_score.json
                        

Scheduling score calculation endpoint examples

Example calculate score call:

Response if everything went fine:

HTTP CODE: 200 (Success)
{
    "result": "success",
    "message": "Queued for calculation.",
    "user_id": "USER-ID"
}

Response if request is not authorized (no authorization header):

HTTP CODE: 401 (Unauthorized)
{
  "code": 401,
  "message": "Unauthorized"
}

Response if IP Address is not provided:

HTTP CODE: 404 (Not Found)
{
  "error": "Client error: `POST http://yourdomain.com/api/v2/users/partner-id/test/calculate_score.json` resulted in a `404 Not Found` response:{\"result\":\"error\",\"message\":\"Bad parameters provided - IP Address is mandatory!\",\"user_id\":\"test\"}"
}

Response if access tokens from social networks are not provided:

HTTP CODE: 404 (Not Found)
{
  "result": "error",
  "message": "Bad parameters provided - access_tokens parameter is empty. It needs to contain at least one field: facebook, linkedin, google, paypal, twitter_user_id, twitter_screen_name, instagram.",
  "user_id": "123456789"
}

NOTE Webhook parameter is not mandatory. If your software doesn't need immediate information when data is ready, just do not provide webhook parameter. Instead of using webhook, your software can check after some time if score has been calculated – it should take less than 1 minute since scheduling (it depends on the amount of data that the user has got on his social networks).

show-user

GET

Returns user's main data details.

Parameters


{id-type}

Type of identifier used to identify the user. There are 2 options:

  • 'id' which means internal FriendlyScore identifier; when you send the first scoring request you won't have it yet, so you can only use the other option
  • 'partner-id' which means identifier provided by the client's company (internal id from your database - this you can always use)


{id}

Identifier of the user. Depends on what is set as {id-type}:

  • when {id-type} is set to 'id': user's FriendlyScore id (returned by our endpoints - it will only be available after the first scoring call)
  • when {id-type} is set to 'partner-id': user id assigned by your database

                            api/v2/users/{id-type}/{id}/show.json
                        

NOTE
Check key "notices" on the bottom of response for get valid data

HTTP CODE: 200 (Success)
{
  ...
  "notices": {
    "google_scopes_notice": "FriendlyScore uses more google api scopes than provided within access_token. Missing scopes: https://www.googleapis.com/auth/calendar.readonly, https://www.googleapis.com/auth/drive.file, https://www.googleapis.com/auth/analytics.readonly, https://www.googleapis.com/auth/plus.me. Lack of scopes can lead to underestimated scoring result.",
    "ip_address_notice": "Bad IPv4 address format or reserved IP address provided!" 
  }
}

show-user-social

GET

Returns user's social network data.

Parameters


{id-type}

Type of identifier used to identify the user. There are 2 options:

  • 'id' which means internal FriendlyScore identifier; when you send the first scoring request you won't have it yet, so you can only use the other option
  • 'partner-id' which means identifier provided by the client's company (internal id from your database - this you can always use)


{id}

Identifier of the user. Depends on what is set as {id-type}:

  • when {id-type} is set to 'id': user's FriendlyScore id (returned by our endpoints - it will only be available after the first scoring call)
  • when {id-type} is set to 'partner-id': user id assigned by your database

                            api/v2/users/{id-type}/{id}/show/social-network-data.json
                        

show-user-ip-addr

GET

Returns user data obtained from IP addresses.

Parameters


{id-type}

Type of identifier used to identify the user. There are 2 options:

  • 'id' which means internal FriendlyScore identifier; when you send the first scoring request you won't have it yet, so you can only use the other option
  • 'partner-id' which means identifier provided by the client's company (internal id from your database - this you can always use)


{id}

Identifier of the user. Depends on what is set as {id-type}:

  • when {id-type} is set to 'id': user's FriendlyScore id (returned by our endpoints - it will only be available after the first scoring call)
  • when {id-type} is set to 'partner-id': user id assigned by your database

                            api/v2/users/{id-type}/{id}/show/ip-address-data.json
                        

show-user-data-points

GET

Returns user data points.

Parameters


{id-type}

Type of identifier used to identify the user. There are 2 options:

  • 'id' which means internal FriendlyScore identifier; when you send the first scoring request you won't have it yet, so you can only use the other option
  • 'partner-id' which means identifier provided by the client's company (internal id from your database - this you can always use)


{id}

Identifier of the user. Depends on what is set as {id-type}:

  • when {id-type} is set to 'id': user's FriendlyScore id (returned by our endpoints - it will only be available after the first scoring call)
  • when {id-type} is set to 'partner-id': user id assigned by your database

                            api/v2/users/{id-type}/{id}/show/data-points.json
                        

show-user-heat-map

GET

Returns user heat map coordinates.

Parameters


{id-type}

Type of identifier used to identify the user. There are 2 options:

  • 'id' which means internal FriendlyScore identifier; when you send the first scoring request you won't have it yet, so you can only use the other option
  • 'partner-id' which means identifier provided by the client's company (internal id from your database - this you can always use)


{id}

Identifier of the user. Depends on what is set as {id-type}:

  • when {id-type} is set to 'id': user's FriendlyScore id (returned by our endpoints - it will only be available after the first scoring call)
  • when {id-type} is set to 'partner-id': user id assigned by your database

                            api/v2/users/{id-type}/{id}/show/heat-map-coordinates.json
                        

performance-data

POST

Sets user performance data.

Parameters


{id-type}

Type of identifier used to identify the user. There are 2 options:

  • 'id' which means internal FriendlyScore identifier; when you send the first scoring request you won't have it yet, so you can only use the other option
  • 'partner-id' which means identifier provided by the client's company (internal id from your database - this you can always use)


{id}

Identifier of the user. Depends on what is set as {id-type}:

  • when {id-type} is set to 'id': user's FriendlyScore id (returned by our endpoints - it will only be available after the first scoring call)
  • when {id-type} is set to 'partner-id': user id assigned by your database


{loan_application_customer_id}

Text field: application customer id


{loan_application_date}

Date field: format (YYYY-mm-dd H:i:s)


{loan_application_status}

Text field: loan application status. Options: accepted, declined, drop-off.


{loan_value}

Float field: loan value


{loan_paid_capital}

Float field: loan paid capital


{loan_currency}

Text field: loan currency


{loan_term}

Integer field: loan term days


{loan_status}

Text field: loan status. Options: active, arrears, paid.


{loan_arrears_days}

Integer field: loan arrears days


{loan_arrears_amount_overdue}

Float field: loan arrears amount overdue


{loan_is_installment}

Boolean field: 1 if is installment, 0 otherwise


{comments}

Array with keys: positive, negative, neutral. Should contain number of comments for each key.

                            api/v2/users/{id-type}/{id}/performance-data.json
                        

set-positive

PUT

Sets or unsets "positive" flag for a given user.

Parameters


{id-type}

Type of identifier used to identify the user. There are 2 options:

  • 'id' which means internal FriendlyScore identifier; when you send the first scoring request you won't have it yet, so you can only use the other option
  • 'partner-id' which means identifier provided by the client's company (internal id from your database - this you can always use)


{id}

Identifier of the user. Depends on what is set as {id-type}:

  • when {id-type} is set to 'id': user's FriendlyScore id (returned by our endpoints - it will only be available after the first scoring call)
  • when {id-type} is set to 'partner-id': user id assigned by your database


{positive-val}

Boolean field: 1 for positive, 0 for negative

                            api/v2/users/{id-type}/{id}/positive/{positive-val}.json
                        

set-status

POST

Sets user status and status description.

Parameters


{id-type}

Type of identifier used to identify the user. There are 2 options:

  • 'id' which means internal FriendlyScore identifier; when you send the first scoring request you won't have it yet, so you can only use the other option
  • 'partner-id' which means identifier provided by the client's company (internal id from your database - this you can always use)


{id}

Identifier of the user. Depends on what is set as {id-type}:

  • when {id-type} is set to 'id': user's FriendlyScore id (returned by our endpoints - it will only be available after the first scoring call)
  • when {id-type} is set to 'partner-id': user id assigned by your database


{status}

Text field: user status


{status_description}

Text field: user status description

                            api/v2/users/{id-type}/{id}/status.json
                        

min-fraud-data

GET

Returns user fraud data.

Parameters


{id-type}

Type of identifier used to identify the user. There are 2 options:

  • 'id' which means internal FriendlyScore identifier; when you send the first scoring request you won't have it yet, so you can only use the other option
  • 'partner-id' which means identifier provided by the client's company (internal id from your database - this you can always use)


{id}

Identifier of the user. Depends on what is set as {id-type}:

  • when {id-type} is set to 'id': user's FriendlyScore id (returned by our endpoints - it will only be available after the first scoring call)
  • when {id-type} is set to 'partner-id': user id assigned by your database

                            api/v2/users/{id-type}/{id}/show/min-fraud-data.json
                        

show-fraudalerts

GET

Gets user fraud alert list.

Parameters


{id-type}

Type of identifier used to identify the user. There are 2 options:

  • 'id' which means internal FriendlyScore identifier; when you send the first scoring request you won't have it yet, so you can only use the other option
  • 'partner-id' which means identifier provided by the client's company (internal id from your database - this you can always use)


{id}

Identifier of the user. Depends on what is set as {id-type}:

  • when {id-type} is set to 'id': user's FriendlyScore id (returned by our endpoints - it will only be available after the first scoring call)
  • when {id-type} is set to 'partner-id': user id assigned by your database

                            api/v2/fraudalerts/{id-type}/{id}/show.json
                        

show-gmail-places

GET

Gets user places extracted from gmail attachments CV parser.

Parameters


{id-type}

Type of identifier used to identify the user. There are 2 options:

  • 'id' which means internal FriendlyScore identifier; when you send the first scoring request you won't have it yet, so you can only use the other option
  • 'partner-id' which means identifier provided by the client's company (internal id from your database - this you can always use)


{id}

Identifier of the user. Depends on what is set as {id-type}:

  • when {id-type} is set to 'id': user's FriendlyScore id (returned by our endpoints - it will only be available after the first scoring call)
  • when {id-type} is set to 'partner-id': user id assigned by your database

                            api/v2/users/{id-type}/{id}/google/raw-file-data/places.json
                        

show-gmail-days-of-birth

GET

Gets user days of birth extracted from gmail attachments CV parser.

Parameters


{id-type}

Type of identifier used to identify the user. There are 2 options:

  • 'id' which means internal FriendlyScore identifier; when you send the first scoring request you won't have it yet, so you can only use the other option
  • 'partner-id' which means identifier provided by the client's company (internal id from your database - this you can always use)


{id}

Identifier of the user. Depends on what is set as {id-type}:

  • when {id-type} is set to 'id': user's FriendlyScore id (returned by our endpoints - it will only be available after the first scoring call)
  • when {id-type} is set to 'partner-id': user id assigned by your database

                            api/v2/users/{id-type}/{id}/google/raw-file-data/days-of-birth.json
                        

show-gmail-skills

GET

Gets user skills extracted from gmail attachments CV parser.

Parameters


{id-type}

Type of identifier used to identify the user. There are 2 options:

  • 'id' which means internal FriendlyScore identifier; when you send the first scoring request you won't have it yet, so you can only use the other option
  • 'partner-id' which means identifier provided by the client's company (internal id from your database - this you can always use)


{id}

Identifier of the user. Depends on what is set as {id-type}:

  • when {id-type} is set to 'id': user's FriendlyScore id (returned by our endpoints - it will only be available after the first scoring call)
  • when {id-type} is set to 'partner-id': user id assigned by your database

                            api/v2/users/{id-type}/{id}/google/raw-file-data/skills.json
                        

show-gmail-phones

GET

Gets user phone numbers extracted from gmail attachments CV parser.

Parameters


{id-type}

Type of identifier used to identify the user. There are 2 options:

  • 'id' which means internal FriendlyScore identifier; when you send the first scoring request you won't have it yet, so you can only use the other option
  • 'partner-id' which means identifier provided by the client's company (internal id from your database - this you can always use)


{id}

Identifier of the user. Depends on what is set as {id-type}:

  • when {id-type} is set to 'id': user's FriendlyScore id (returned by our endpoints - it will only be available after the first scoring call)
  • when {id-type} is set to 'partner-id': user id assigned by your database

                            api/v2/users/{id-type}/{id}/google/raw-file-data/phones.json
                        

show-gmail-work-periods

GET

Gets user work periods extracted from gmail attachments CV parser.

Parameters


{id-type}

Type of identifier used to identify the user. There are 2 options:

  • 'id' which means internal FriendlyScore identifier; when you send the first scoring request you won't have it yet, so you can only use the other option
  • 'partner-id' which means identifier provided by the client's company (internal id from your database - this you can always use)


{id}

Identifier of the user. Depends on what is set as {id-type}:

  • when {id-type} is set to 'id': user's FriendlyScore id (returned by our endpoints - it will only be available after the first scoring call)
  • when {id-type} is set to 'partner-id': user id assigned by your database

                            api/v2/users/{id-type}/{id}/google/raw-file-data/work-periods.json
                        

show-gmail-universities

GET

Gets user universities extracted from gmail attachments CV parser.

Parameters


{id-type}

Type of identifier used to identify the user. There are 2 options:

  • 'id' which means internal FriendlyScore identifier; when you send the first scoring request you won't have it yet, so you can only use the other option
  • 'partner-id' which means identifier provided by the client's company (internal id from your database - this you can always use)


{id}

Identifier of the user. Depends on what is set as {id-type}:

  • when {id-type} is set to 'id': user's FriendlyScore id (returned by our endpoints - it will only be available after the first scoring call)
  • when {id-type} is set to 'partner-id': user id assigned by your database

                            api/v2/users/{id-type}/{id}/google/raw-file-data/universities.json
                        

show-gmail-emails

GET

Gets user e-mails extracted from gmail attachments CV parser.

Parameters


{id-type}

Type of identifier used to identify the user. There are 2 options:

  • 'id' which means internal FriendlyScore identifier; when you send the first scoring request you won't have it yet, so you can only use the other option
  • 'partner-id' which means identifier provided by the client's company (internal id from your database - this you can always use)


{id}

Identifier of the user. Depends on what is set as {id-type}:

  • when {id-type} is set to 'id': user's FriendlyScore id (returned by our endpoints - it will only be available after the first scoring call)
  • when {id-type} is set to 'partner-id': user id assigned by your database

                            api/v2/users/{id-type}/{id}/google/raw-file-data/emails.json
                        

list-users

GET

Lists all users.

Parameters


{page}

Page number to be displayed. Default is 1.


{max_results}

How many results API should return per page. Default is 20 and maximum is 200.

                            api/v2/users.json
                        

NOTE
Check key "notices" on the bottom of response for get valid data

HTTP CODE: 200 (Success)
{
  ...
  "notices": {
    "google_scopes_notice": "FriendlyScore uses more google api scopes than provided within access_token. Missing scopes: https://www.googleapis.com/auth/calendar.readonly, https://www.googleapis.com/auth/drive.file, https://www.googleapis.com/auth/analytics.readonly, https://www.googleapis.com/auth/plus.me. Lack of scopes can lead to underestimated scoring result.",
    "ip_address_notice": "Bad IPv4 address format or reserved IP address provided!" 
  }
}