API Endpoints

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 or instagram. You must have registered apps in each social network and their credentials set in hour WhiteLabel configuration file parameters.yml for them to work.

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.


{user_ip}

IP address of the user


{user_agent}

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

DEPRECATED Parameters


{partner_user_id}

Used by the deprecated api/v2/calculate_score.json URL. User ID from your database

api/v2/users/{id-type}/{id}/calculate_score.json
		DEPRECATED: api/v2/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).

get-score

GET

Returns user score

Parameters


{partner_user_id}

User ID from your database

api/v2/get_score.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!" 
  }
}

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-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
						

min-fraud-data

GET

Return 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
						

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
						

performance-data

POST

Sets user performance date

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
						

facebook-data

GET

Returns facebook 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}/facebook-data.json
						

linkedin-data

GET

Returns linkedin 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}/linkedin-data.json
						

twitter-data

GET

Returns twitter 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}/twitter-data.json
						

google-data

GET

Returns google 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}/google-data.json
						

paypal-data

GET

Returns paypal 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}/paypal-data.json
						

instagram-data

GET

Returns instagram 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}/instagram-data.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
						

show-gmail-places

GET

Get 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

Get 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

Get 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

Get 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

Get 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

Get 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

Get 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