Report Charges

The usage endpoint is available at public-api-usage.service.payscale.com <https://public-api-usage.service.payscale.com>. There are two endpoints:

  • /usage - This endpoint returns a csv containing every logged request to the service, including information about whether that request was successful, the given inputs, and the given outputs.

  • /usagestats - This endpoint returns a json object with the following fields:

Viewing Usage

To view fine-grained usage, download the CSV from the /usage endpoint. The purpose of this endpoint is to allow users to explore their requests and responses, along with whether or not those responses were considered successful and are billable.

The output usage.csv from this minimal application is ready to explore with Excel or any text editor, and has the following columns:

  • CLIENTID - the clientId associated with this request.

  • REPORTID -

  • REPORT_DATE - A timestamp indicating when the request was recorded in UTC.

  • REPORT_TYPE - The type of report present in the request.

  • REPORTRATING - The report rating, where 0 indicates a low-confidence report and 1 indicates a high-confidence report.

  • REQUEST - A json object containing the received request.

  • SUBMITTED_ANSWERS - A list of json objects mapping the received QuestionId to the selected Value, along with the Type of that QuestionId. These are submitted in the Answers entry of the request object.

  • RESPONSE - A json object containing the content of the report associated with this request. If a single request contained two RequestedReports, they will be on separate lines in this csv.

  • SUCCESSFUL - A boolean representing whether the report was successful (True) or not (False). Reports are only billable if this value is True.

  • MONTH - The calendar month associated with this report, as report usage is billed monthly.

  • YEAR - The year associated with this report.

  • JOBTITLERATING - If applicable, the JobTitleRating associated with a the report. This is only present if AutoResolveJobTitle was set to True in the request.

A minimal python application to collect these results looks like the following:

import requests
import time


auth_url = 'https://accounts.payscale.com'
get_token_url = f'{auth_url}/connect/token'
client_id = '<client_id>'
client_secret = '<client_secret>'

# get oauth token using given clientId and clientSecret
payload = {
    'grant_type': 'client_credentials',
    'scope': 'jobalyzer',
    'client_id': client_id,
    'client_secret': client_secret
}
token_response = requests.post(get_token_url, data=payload)
token = None
if token_response.status_code == 200:
    token = token_response.json()['access_token']
else:
    print(f'failed to get token: {token_response.text}')

usage_root_url = 'https://public-api-usage.service.payscale.com'
usage_url = f'{usage_root_url}/usage'
usage_stats_url = f'{usage_root_url}/usagestats'

request_data = {
    'user': '<your-username>',
    'month': 'May', # casing does not matter here, but it must be the full name of the month.
    'year': 2021
}

# get the usage data and save to a csv
headers = {'Authorization': f'Bearer {token}', 'accept': 'csv/text'}
usage_response = requests.get(usage_url, headers=headers, params=request_data)

if usage_response.status_code == 200:
    with(open('usage.csv', 'w')) as file:
        file.write(usage_response.text)

Viewing Usage Summary

In addition to the endpoint which returns the entirety of the requests and responses for this billable month, there is also a summary endpoint which returns a summary of the usage. This endpoint is available at /usagestats.

{
    "usage": {
        "totalReports": <int>, // The total number of reports made in this time period
        "totalBillableReports": <int>, // The total number of billable (successful) reports made in this time period
        "clientId": <str>, // the clientId associated with these requests
        "successfulReports": {
            "skills": <int>, // The number of successful Skills reports
            "pay": <int>, // The number of successful Pay reports
            "yoe": <int> // The number of successful Years of Experience reports
        },
        "unsuccessfulReports": {
            "skills": <int>, // The number of unsuccessful Skills reports
            "pay": <int>, // The number of unsuccessful Pay reports
            "yoe": <int> // The number of unsuccessful Years of Experience reports
        }
    }
}

A minimal python application to collect these results looks like the following:

import requests
import time


auth_url = 'https://accounts.payscale.com'
get_token_url = f'{auth_url}/connect/token'
client_id = '<client_id>'
client_secret = '<client_secret>'

# get oauth token using given clientId and clientSecret
payload = {
    'grant_type': 'client_credentials',
    'scope': 'jobalyzer',
    'client_id': client_id,
    'client_secret': client_secret
}
token_response = requests.post(get_token_url, data=payload)
token = None
if token_response.status_code == 200:
    token = token_response.json()['access_token']
else:
    print(f'failed to get token: {token_response.text}')

usage_root_url = 'https://public-api-usage.service.payscale.com'
usage_url = f'{usage_root_url}/usage'
usage_stats_url = f'{usage_root_url}/usagestats'

request_data = {
    'user': '<your-username>',
    'month': 'May', # casing does not matter here, but it must be the full name of the month.
    'year': 2021
}

# get the usage summary statistics and save to a json file
headers = {'Authorization': f'Bearer {token}'}
usage_stats_response = requests.get(usage_stats_url, headers=headers, params=request_data)

if usage_stats_response.status_code == 200:
    with(open('usage_stats.json', 'w')) as file:
        file.write(usage_stats_response.text)

How Payscale Charges for Reports

Report Charges

Payscale charges per report. Each report incurs a report credit. Clients purchase report credits which are consumed.

Some endpoints are able to generate multiple reports with a single request. For example:

"requestedReports": ["yoe", "pay"]

This counts as 2 reports because we're requesting both the YoE and Pay reports.

Other endpoints only generate one report at a time, for example, the impacts reports.

Invalid Reports

In some cases a report may not have enough data to be valid. In this case the "report rating" will be returned as zero and the user will not be charged for this report.

In other cases the "auto resolve job title" flag may be set. If a suitable job title cannot be found, the "job title rating" will be returned as zero and the user will not be charged for this report.

Please see https://developers.payscale.com/jobalyzer/ratings.html for more information.

Avoiding Excess Charges

Please see https://developers.payscale.com/jobalyzer/quickstart.html#integration for advice on initial report integration.