B2B TOOL

API Documentation

Access UK salary data and career projections programmatically. 12 RESTful endpoints backed by official ONS ASHE and HMRC LEO data, covering 520 occupations, 50 career paths, and 12 UK regions.

Quick Start

Get an API key

API access is available on Agency, Enterprise, and University plans. Create a key from your organisation dashboard under the API Keys tab. Assign the permissions you need.

Make your first request

curl -H "X-API-Key: cm_live_your_key_here" \
  https://careermetrics.co.uk/api/v1/careers

Integrate

All responses are JSON. CORS is enabled for all origins. Cache headers are set to 5 minutes.

Authentication

All API requests require authentication via the X-API-Key header.

GET /api/v1/careers HTTP/1.1
Host: careermetrics.co.uk
X-API-Key: cm_live_a1b2c3d4e5f6...

API keys are generated from your organisation dashboard. Keys start with cm_live_ and are shown once at creation — store them securely.

Plan requirements: API access requires an Agency, Enterprise, or University plan. Recruiter plans do not include API access.

Permissions

Each API key has granular permissions that control which endpoints it can access. Assign only the permissions you need.

Permission	Endpoints	Description
careers	/careers, /salary, /compare, /benchmark	Career path and salary data
regions	/regions	Regional data and multipliers
projections	/projections/*	Salary forecasting, lifetime earnings, progression, percentile analysis, qualification premiums
export	/export/*	Bulk data export

Base URL

https://careermetrics.co.uk/api/v1

Career Data Endpoints

Access career paths, salary data, regional breakdowns, and benchmarks. Requires the careers permission.

GET /api/v1/careers

List all 50 career paths with summary information.

Example response

{
  "careers": [
    {
      "id": "software-engineering",
      "name": "Software Engineering",
      "industry": "Technology",
      "stages": 5,
      "entryLevel": "Junior Developer",
      "seniorLevel": "Engineering Director"
    }
  ],
  "count": 50
}

GET /api/v1/careers/:id

Get detailed salary data for a specific career path with all progression stages.

Parameter	Type	Required	Description
id	path	Yes	Career path ID (e.g. software-engineering)
region	query	No	Region ID for salary adjustment (e.g. london)

Example response

{
  "id": "software-engineering",
  "name": "Software Engineering",
  "industry": "Technology",
  "region": "london",
  "multiplier": 1.25,
  "stages": [
    {
      "title": "Junior Developer",
      "yearsExp": "0-2",
      "salaries": { "p25": 31250, "p50": 37500, "p75": 46250 }
    }
  ]
}

GET /api/v1/regions

List all 12 UK regions with salary multipliers and cost of living data. Requires regions permission.

Example response

{
  "regions": [
    {
      "id": "london",
      "name": "London",
      "costOfLivingIndex": 1.35,
      "salaryMultiplier": 1.25
    }
  ],
  "count": 12
}

GET /api/v1/salary

Get salary data for a career path, optionally adjusted for a region.

Parameter	Type	Required	Description
career	query	Yes	Career path ID
region	query	No	Region ID for salary adjustment

GET /api/v1/compare

Compare salary data across 2-5 career paths side by side.

Parameter	Type	Required	Description
careers	query	Yes	Comma-separated career IDs (2-5)
region	query	No	Region ID for salary adjustment

GET /api/v1/benchmark

Get percentile benchmarks for a career across all 12 UK regions.

Parameter	Type	Required	Description
career	query	Yes	Career path ID

Projections Endpoints

Salary forecasting, lifetime earnings, career progression, and qualification analysis powered by the CareerMetrics Projection Engine. Requires the projections permission.

Response format: All projections endpoints return { success, data, meta }. The meta object includes data source, methodology description, and a disclaimer.

GET /api/v1/projections/forecast

Project future salary growth for an occupation using compound annual growth rate (CAGR) extrapolation from 11 years of historical ONS data.

Parameter	Type	Default	Description
soc	string	required	SOC occupation code (1-4 digits)
years	integer	10	Years to forecast (max 30)
percentile	string	median	p25 \| median \| p75 \| p90
inflation	boolean	false	Adjust for CPI inflation

Example response

{
  "success": true,
  "data": {
    "soc": "2136",
    "occupation": "Programmers and software development professionals",
    "cagr": { "nominal": 0.032, "real": 0.008, "years": 10 },
    "forecast": [
      { "year": "2026", "nominal": 43860, "real": 42500, "low": 41667, "high": 46053 },
      { "year": "2027", "nominal": 45264, "real": 43340, "low": 42267, "high": 48261 }
    ]
  },
  "meta": {
    "source": "ONS ASHE",
    "methodology": "CAGR extrapolation from 11 years of historical data",
    "disclaimer": "Projections are estimates and should not be considered financial advice."
  }
}

GET /api/v1/projections/lifetime-earnings

Calculate total lifetime earnings with net present value (NPV), peak earnings age, and yearly breakdown.

Parameter	Type	Default	Description
soc	string	required	SOC occupation code
startAge	integer	22	Career start age (16-40)
retireAge	integer	67	Retirement age (50-75)
percentile	string	median	p25 \| median \| p75
discountRate	float	0.035	NPV discount rate (0-0.1)

Example response

{
  "success": true,
  "data": {
    "soc": "2136",
    "occupation": "Programmers and software development professionals",
    "total": 2150000,
    "npv": 1280000,
    "annualAverage": 47778,
    "peakEarnings": 68000,
    "peakAge": 55,
    "breakdown": [
      { "age": 22, "earnings": 28000 },
      { "age": 23, "earnings": 30500 }
    ]
  }
}

GET /api/v1/projections/progression

Get estimated career progression stages (Entry, Mid, Senior, Leadership) with salary at each level, derived from percentile distribution.

Parameter	Type	Description
soc	required	SOC occupation code

Example response

{
  "success": true,
  "data": {
    "soc": "2136",
    "occupation": "Programmers and software development professionals",
    "stages": [
      { "level": "Entry Level", "salary": 28000, "yearsExperience": "0-2 years", "percentile": "P10" },
      { "level": "Mid Level", "salary": 35000, "yearsExperience": "3-7 years", "percentile": "P25" },
      { "level": "Senior", "salary": 55000, "yearsExperience": "8-15 years", "percentile": "P75" },
      { "level": "Leadership", "salary": 72000, "yearsExperience": "15+ years", "percentile": "P90" }
    ]
  }
}

GET /api/v1/projections/percentile

Find where a given salary sits in the distribution for an occupation.

Parameter	Type	Description
soc	required	SOC occupation code
salary	required	Annual salary in GBP (0-1,000,000)

Example response

{
  "success": true,
  "data": {
    "soc": "2136",
    "salary": 45000,
    "percentile": 62,
    "aboveMedian": true,
    "aboveByAmount": 2500,
    "aboveByPercent": 5.9,
    "distribution": { "p10": 22000, "p25": 30000, "median": 42500, "p75": 55000, "p90": 72000 }
  }
}

GET /api/v1/projections/compare

Compare multiple occupations on lifetime earnings, CAGR, median salary, and career progression.

Parameter	Type	Description
soc	required	Comma-separated SOC codes (max 10)

GET /api/v1/projections/qualification-premium

Compare earnings by qualification level for a degree subject. Shows salary premium and estimated ROI for Masters and Doctoral degrees.

Parameter	Type	Default	Description
subject	string	required	Subject name (e.g. Computer science)
yag	integer	5	Years after graduation (1, 3, or 5)

Example response

{
  "success": true,
  "data": {
    "subject": "Computer science",
    "yag": 5,
    "firstDegree": 35000,
    "masters": 40000,
    "doctoral": 42000,
    "mastersPremium": 5000,
    "doctoralPremium": 7000,
    "mastersROI": { "cost": 47000, "paybackYears": 10 },
    "doctoralROI": { "cost": 138600, "paybackYears": 20 }
  }
}

Rate Limits

Plan	Rate Limit	Includes
Agency	1,000 req/day	Career data + projections
Enterprise	10,000 req/day	All endpoints + widgets
University	10,000 req/day	All endpoints + widgets + LTI 1.3

Rate limits reset daily at midnight UTC. Need higher limits? Contact us.

Error Handling

All errors return a JSON object with success: false and an error object:

{ "success": false, "error": { "code": "INVALID_SOC", "message": "Unknown SOC code: 9999" } }

400 Bad request — missing or invalid parameters

401 Unauthorised — missing or invalid API key

403 Forbidden — API key lacks required permission

404 Not found — unknown SOC code or resource

429 Rate limit exceeded — retry after midnight UTC

Data Sources

ONS ASHE

Annual Survey of Hours and Earnings. 520 occupations at 4-digit SOC level, 11 years (2015-2025), 6 percentiles (p10/p25/median/p75/p90/mean), gender breakdowns, full-time vs all employees.

DfE LEO

Longitudinal Education Outcomes linked to HMRC tax records. Graduate + postgraduate earnings by subject at 1, 3, 5, and 10 years after graduation. 28 undergraduate subjects, 25 postgraduate subjects.

Crown Copyright. Licensed under the Open Government Licence v3.0. Data updated when new ONS/DfE releases are published (typically annually).