NAV
cURL Ruby Python JavaScript

Introduction

Trendence exposes parts of its architecture for integrational use, intended to fuel your custom applications and systems with data and proper exports. This system is what we call our Talent Intelligence API. These documentation pages are intended to help you getting started.

Base URL: https://api.trendence.com/v1/

API Version: 1.0.0

Authentication

To authorize, use this code:

# With Bearer Token (recommended)
curl "https://api.trendence.com/v1/talents" \
  -H "Authorization: Bearer YOUR_API_KEY"

require 'net/http'
require 'uri'

uri = URI.parse("https://api.trendence.com/v1/talents")
request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer YOUR_API_KEY"
request["Content-Type"] = "application/json"

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
}

response = requests.post(
    'https://api.trendence.com/v1/talents',
    headers=headers
)

const fetch = require('node-fetch');

fetch('https://api.trendence.com/v1/talents', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
});

Make sure to replace YOUR_API_KEY with your actual API key.

The Trendence API uses API keys for authentication. Every request must include a valid API key.

Authentication Methods

You can provide your API key in two ways:

Send the API key in the Authorization header as a Bearer token:

Authorization: Bearer YOUR_API_KEY

X-API-Key Header

Alternatively, you can use the X-API-Key header:

X-API-Key: YOUR_API_KEY

Content-Type Required

Otherwise, you will receive a 415 Unsupported Media Type error.

Security Recommendations

  1. Keep your API key secret: Never share your API key publicly or in version control systems.
  2. Use environment variables: Store API keys in environment variables instead of source code.
  3. Use HTTPS: All API requests are required to be made over HTTPS.
  4. Rotate keys regularly: Request a new API key when needed.

Understanding the Endpoints

The API offers two endpoints — Talents and Professions — that serve different use cases and are optimized for different types of input.

Talents Professions
Designed for CV / resume-style text Job posting / role description text
Input field talent_text.description profession_text.title + profession_text.description (or profession_taxonomy)
Perspective Candidate-centric (what someone has done) Role-centric (what a position requires)

Both endpoints return the same categories of data (salary, scarcity, vacancies, skills, etc.), but the underlying analysis pipelines are tailored to the semantics of their respective input types. This means that sending the same text to both endpoints may produce slightly different results — this is expected and by design.

Recruitment Complexity Index

Both endpoints return a Recruitment Complexity Index (also known as the scarcity index) as part of their labour market analytics. This section explains what the index measures, what the individual dimensions mean, and how to interpret them.

What the Index Measures

Example scarcity response:

{
  "scarcity": {
    "scarcity_index": 7.8,
    "job_adds_people_available_ratio": "high",
    "campaigns_repeated": "moderate",
    "avg_postings_per_campaign": "low",
    "vacancy_duration": "high",
    "foreign_employee_share_change": "very high",
    "median_earnings_change": "very high",
    "job_change_reluctance": "very low"
  }
}

The Recruitment Complexity Index answers a single question: How difficult is it to recruit for a given profession in a given location right now?

It produces a composite score from 0 to 10, where:

Score Category Meaning
0–2 very low Easy to recruit — large candidate pool, low competition
2–4 low Below-average hiring difficulty
4–6 moderate Average hiring difficulty
6–8 high Challenging to recruit — consider competitive offers
8–10 very high Extremely difficult — expect long hiring timelines and premium compensation

The index is not a single metric. It is computed from seven dimensions, each capturing a different signal of labour market tension. This gives you a detailed breakdown of why a profession is easy or hard to recruit.

The Seven Dimensions

The scarcity index is built from three categories of data: job market behaviour (derived from job postings data), official government statistics, and workforce survey data.

Job Market Behaviour

These dimensions are derived from real-world job posting patterns and carry the most weight in the index. They reflect what employers actually do in the market.

job_adds_people_available_ratio — Supply-demand balance

Are there more open positions than available candidates? This is the single most influential dimension. A high value means there are significantly more vacancies than jobseekers for this profession — a clear signal of scarcity.

campaigns_repeated — Reposting frequency

Do employers keep re-posting the same vacancy? When the same position is re-advertised shortly after a previous attempt expired, it indicates that the employer struggled to fill it. A high value is a strong signal of recruitment difficulty.

avg_postings_per_campaign — Recruitment effort

How many individual ads does it take to fill one position? When employers need to publish the same vacancy on many platforms simultaneously, it signals that finding the right candidate requires significant effort.

Official Government Statistics

These dimensions come from the German Federal Employment Agency (Bundesagentur für Arbeit) and provide structural context.

vacancy_duration — Time to fill

How long do vacancies for this profession stay open on average? Longer vacancy durations confirm that positions are harder to fill. This is based on official Engpass data matched by occupation code.

foreign_employee_share_change — International recruitment trend

Is the share of foreign employees in this profession increasing? A rising share often indicates that the domestic talent pool is insufficient, driving employers to recruit internationally.

median_earnings_change — Salary pressure

Are salaries for this profession rising above average? When demand for a profession exceeds supply, market pressure pushes wages up. Rising earnings are a classic economic indicator of scarcity.

Workforce Survey Data

job_change_reluctance — Worker mobility

Are workers in this profession willing to change jobs? This dimension is based on Trendence's proprietary survey data. When workers are reluctant to change positions, the effective talent pool for recruiters shrinks — even if the total number of professionals is large.

How to Interpret the Results

A practical example — Software Developer in Germany:

{
  "scarcity_index": 7.8,
  "job_adds_people_available_ratio": "high",
  "campaigns_repeated": "moderate",
  "vacancy_duration": "high",
  "median_earnings_change": "very high",
  "foreign_employee_share_change": "very high",
  "avg_postings_per_campaign": "low",
  "job_change_reluctance": "very low"
}

Reading this: The overall score of 7.8 ("high") is primarily driven by a high vacancy-to-candidate ratio and long vacancy durations. Salaries are rising fast and international recruitment is increasing — both confirming market pressure. However, workers are very willing to change jobs ("very low" reluctance), which partially offsets the scarcity.

The composite scarcity_index gives you the headline, but the individual dimensions tell the story. Here's how to use them:

For workforce planning: Focus on job_adds_people_available_ratio and vacancy_duration. Together they show whether the talent pool is sufficient and how long filling a position will take.

For compensation strategy: Look at median_earnings_change alongside the overall index. Rising earnings in a scarce market mean you may need to offer above-average compensation to attract talent.

For recruitment strategy: campaigns_repeated and avg_postings_per_campaign reveal how much effort other employers invest. High values suggest you should differentiate your job posting strategy or consider alternative sourcing channels.

For long-term trends: foreign_employee_share_change indicates structural shifts. A consistently increasing share signals that domestic supply alone may not meet demand in the medium term.

Talents Endpoint

Create Talent Analysis

curl --request POST \
  --url "https://api.trendence.com/v1/talents" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "talent_text": {
      "description": "Experienced Full-Stack Developer with 5 years of professional experience. Expertise in React, Node.js, and Python."
    },
    "location": {
      "country": "DE"
    }
  }'

require 'net/http'
require 'uri'
require 'json'

uri = URI.parse("https://api.trendence.com/v1/talents")
request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer YOUR_API_KEY"
request["Content-Type"] = "application/json"
request.body = JSON.dump({
  "talent_text" => {
    "description" => "Experienced Full-Stack Developer with 5 years..."
  },
  "location" => {
    "country" => "DE"
  }
})

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

import requests
import json

url = "https://api.trendence.com/v1/talents"
headers = {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
}
data = {
    'talent_text': {
        'description': 'Experienced Full-Stack Developer with 5 years...'
    },
    'location': {
        'country': 'DE'
    }
}

response = requests.post(url, headers=headers, json=data)

const fetch = require('node-fetch');

const url = 'https://api.trendence.com/v1/talents';
const data = {
  talent_text: {
    description: 'Experienced Full-Stack Developer with 5 years...'
  },
  location: {
    country: 'DE'
  }
};

fetch(url, {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(data)
})
.then(response => response.json())
.then(data => console.log(data));

The above command returns JSON structured like this:

{
  "meta": {
    "tie": {
      "version": "1.0.0"
    }
  },
  "status": "pending",
  "hints": "The data is being prepared, please check talent_url for an update.",
  "talent_uuid": "550e8400-e29b-41d4-a716-446655440000",
  "talent_url": "https://api.trendence.com/v1/talents/550e8400-e29b-41d4-a716-446655440000"
}

This endpoint creates a new asynchronous talent analysis.

HTTP Request

POST https://api.trendence.com/v1/talents

Request Body Parameters

Parameter Type Required Description
talent_text.description String Yes Description of the talent in natural language (minimum 50 characters)
language String No Language code for the analysis (e.g., "de", "en")
location.country String Yes ISO 3166-1 alpha-2 country code (e.g., "DE", "AT", "CH")
location.region String No Region name (see valid values below)
location.coordinates.lat String No Latitude coordinate
location.coordinates.lng String No Longitude coordinate

Valid Region Values:

Query Parameters

Parameter Type Default Description
force_sync Boolean false When true, processes synchronously (max. 29 seconds)

Response

The API processes requests asynchronously by default. Upon successful acceptance, you will receive a 202 Accepted response.

Get Talent Analysis

curl --request GET \
  --url "https://api.trendence.com/v1/talents/550e8400-e29b-41d4-a716-446655440000" \
  --header "Authorization: Bearer YOUR_API_KEY"

require 'net/http'
require 'uri'

uuid = "550e8400-e29b-41d4-a716-446655440000"
uri = URI.parse("https://api.trendence.com/v1/talents/#{uuid}")
request = Net::HTTP::Get.new(uri)
request["Authorization"] = "Bearer YOUR_API_KEY"

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

import requests

uuid = "550e8400-e29b-41d4-a716-446655440000"
url = f"https://api.trendence.com/v1/talents/{uuid}"
headers = {'Authorization': 'Bearer YOUR_API_KEY'}

response = requests.get(url, headers=headers)

const uuid = '550e8400-e29b-41d4-a716-446655440000';
const url = `https://api.trendence.com/v1/talents/${uuid}`;

fetch(url, {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
})
.then(response => response.json())
.then(data => console.log(data));

When processing is complete (200 OK):

{
  "meta": {
    "tie": {
      "version": "1.0.0"
    }
  },
  "status": "completed",
  "talent_uuid": "550e8400-e29b-41d4-a716-446655440000",
  "request": {
    "talent_text": {
      "description": "Experienced Full-Stack Developer with 5 years..."
    },
    "language": "en",
    "location": {
      "country": "DE",
      "region": "Brandenburg / Berlin"
    }
  },
  "results": [{
    "skillset_id": "12345",
    "skillset_label": "Software Development",
    "vacancies": {
      "current": [
        {
          "location": "Berlin",
          "similarity": 0.9466,
          "vacancy_url": "https://jobportal24.example/view/abc123",
          "vacancy_title": "Senior Full Stack Developer (m/f/d)",
          "organization_name": "TechCorp GmbH",
          "vacancy_publish_date": "2025-06-08"
        },
        {
          "location": "Munich",
          "similarity": 0.9234,
          "vacancy_url": "https://careersite.example/jobs/def456",
          "vacancy_title": "Full Stack Engineer",
          "organization_name": "InnovateLabs AG",
          "vacancy_publish_date": "2025-06-15"
        }
      ],
      "sources_last_12_months": [
        {"count": 45821, "share": 0.312, "source": "jobportal24.example"},
        {"count": 28934, "share": 0.197, "source": "careersite.example"},
        {"count": 19283, "share": 0.131, "source": "hiringboard.example"}
      ],
      "employers_last_12_months": [
        {"count": 342, "share": 0.089, "employer": "TechCorp GmbH"},
        {"count": 287, "share": 0.075, "employer": "InnovateLabs AG"},
        {"count": 215, "share": 0.056, "employer": "Digital Solutions GmbH"}
      ]
    },
    "labour_market": {
      "salary": {
        "q10": 52000, "q20": 58000, "q30": 63000, "q40": 68000,
        "q50": 72000, "q60": 76000, "q70": 81000, "q80": 87000, "q90": 95000
      },
      "scarcity": {
        "scarcity_index": 7.8,
        "vacancy_duration": "high",
        "campaigns_repeated": "very high",
        "job_change_reluctance": "low",
        "median_earnings_change": "high"
      },
      "vacancies_count": [
        {"date": "2025-04-01", "vacancies": 156},
        {"date": "2025-05-01", "vacancies": 178}
      ],
      "kldb_vacancies_jobseekers_ratio": [
        {"date": "2025-04-01", "vacancies": 1245, "jobseekers": 3890,
         "vacancies_jobseekers_ratio": 0.32}
      ]
    },
    "matched_profession_profile": {
      "tools": ["React", "Node.js", "Docker", "Git"],
      "hard_skills": ["JavaScript", "TypeScript", "REST APIs", "SQL"],
      "soft_skills": ["Communication", "Problem Solving"],
      "responsibilities": ["Develop web applications", "Code reviews", "Team collaboration"],
      "similar_titles": ["Full Stack Developer", "Software Engineer", "Web Developer"]
    }
  }]
}

This endpoint retrieves the status or result of a talent analysis.

The results array contains matching vacancy data including job postings, similarity scores, labour market analytics (salary, scarcity index), and statistics about vacancy sources and employers. See Understanding Talent Responses for detailed field descriptions.

HTTP Request

GET https://api.trendence.com/v1/talents/:uuid

URL Parameters

Parameter Description
uuid The UUID of the talent analysis to retrieve

Response Status Codes

Status Meaning
202 Accepted Analysis is still processing
200 OK Analysis is complete, result available
502 Bad Gateway Processing error occurred

Understanding Talent Responses

When you submit a talent description, the API performs intelligent job matching and returns four key types of information:

  1. Matching Job Vacancies - A ranked list of relevant job opportunities with similarity scores, enabling you to present the best-fitting positions to job seekers.

  2. Labour Market Analytics - Salary quantiles (q10-q90) and recruitment complexity metrics including the Recruitment Complexity Index (scarcity_index), helping candidates understand compensation expectations and their market value.

  3. Market Intelligence - Insights into where these jobs are posted (sources) and which employers are hiring, helping you understand the job market landscape.

  4. Talent Profile - Extracted skills, tools, responsibilities, and matching job titles from the talent description.

Response Structure

Field Type Description
results Array Analysis results (typically one element)
results[].vacancies Object Vacancy-related data
results[].labour_market Object Salary and recruitment complexity metrics
results[].matched_profession_profile Object Extracted skills and profile data
results[].skillset_id String Internal skillset classification ID
results[].skillset_label String Human-readable skillset label

Vacancy Fields

Field Description Usage Notes
location Geographic location Filter by candidate's preferred location
similarity Match quality (0-1) Higher values indicate better match between talent and vacancy
vacancy_url Direct link to posting Provide to candidates for easy application
vacancy_title Job position title Display prominently in your UI
organization_name Hiring organization Useful for company preference filtering
vacancy_publish_date Publication date (YYYY-MM-DD) Prioritize recent postings

Labour Market Data

Field Description Usage Notes
salary.q10 - salary.q90 Salary quantiles Annual salary in local currency; q50 is median
scarcity.scarcity_index Recruitment Complexity Index (0-10) Higher = harder to find candidates = better market value
scarcity.vacancy_duration Time to fill Values: low, high, very high
scarcity.campaigns_repeated Reposting frequency very high = candidate scarcity = strong negotiating position
scarcity.median_earnings_change Salary growth when switching jobs very high = potential for salary increases
vacancies_count[] Historical vacancy volume Monthly time series showing demand trends
kldb_vacancies_jobseekers_ratio[] Supply-demand ratio Higher ratio = tighter labor market = better prospects

Profession Profile

Field Description
tools Technical tools and platforms identified (e.g., "React", ".NET Core")
hard_skills Technical competencies detected (e.g., "Typescript", "Angular")
soft_skills Non-technical competencies
responsibilities Experience areas and capabilities
similar_titles Job titles matching the talent's profile

Polling Strategy

For asynchronous requests, we recommend using exponential backoff when polling for results.

Professions Endpoint

Create Profession Analysis

curl --request POST \
  --url "https://api.trendence.com/v1/professions" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "profession_text": {
      "title": "Full Stack Developer",
      "description": "Full Stack Developer with over 10 years of experience..."
    },
    "language": "de",
    "location": {
      "country": "DE"
    }
  }'

require 'net/http'
require 'uri'
require 'json'

uri = URI.parse("https://api.trendence.com/v1/professions")
request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer YOUR_API_KEY"
request["Content-Type"] = "application/json"
request.body = JSON.dump({
  "profession_text" => {
    "title" => "Full Stack Developer",
    "description" => "Full Stack Developer with over 10 years..."
  },
  "language" => "de",
  "location" => {
    "country" => "DE"
  }
})

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

import requests

url = "https://api.trendence.com/v1/professions"
headers = {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
}
data = {
    'profession_text': {
        'title': 'Full Stack Developer',
        'description': 'Full Stack Developer with over 10 years...'
    },
    'language': 'de',
    'location': {
        'country': 'DE'
    }
}

response = requests.post(url, headers=headers, json=data)

const fetch = require('node-fetch');

const url = 'https://api.trendence.com/v1/professions';
const data = {
  profession_text: {
    title: 'Full Stack Developer',
    description: 'Full Stack Developer with over 10 years...'
  },
  language: 'de',
  location: {
    country: 'DE'
  }
};

fetch(url, {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(data)
})
.then(response => response.json())
.then(data => console.log(data));

The above command returns JSON structured like this:

{
  "meta": {
    "tie": {
      "version": "1.0.0"
    }
  },
  "status": "pending",
  "hints": "The data is being prepared, please check professions_url for an update.",
  "professions_uuid": "660e8400-e29b-41d4-a716-446655440001",
  "professions_url": "https://api.trendence.com/v1/professions/660e8400-e29b-41d4-a716-446655440001"
}

This endpoint creates a new asynchronous profession analysis.

The API supports two input methods:

HTTP Request

POST https://api.trendence.com/v1/professions

Request Body Parameters

Text-Based Request Parameters

Parameter Type Required Description
profession_text.title String Yes* Job title
profession_text.description String Yes* Description of the profession in natural language (minimum 50 characters)

*Required when using text-based approach

Taxonomy-Based Request Parameters

Parameter Type Required Description
profession_taxonomy.taxonomy String Yes* Taxonomy system identifier: "kldb" or "berufenet"
profession_taxonomy.id String Yes* Occupation code within the taxonomy (e.g., "43413" for Software Developers in KLDB)

*Required when using taxonomy-based approach

Supported Taxonomy Systems: - KLDB (Klassifikation der Berufe) - German occupation classification - BERUFENET (Berufenet) - Federal Employment Agency occupation database

Common Parameters (Both Approaches)

Parameter Type Required Description
language String No Language code for the analysis (e.g., "de", "en")
location.country String Yes ISO 3166-1 alpha-2 country code (e.g., "DE", "AT", "CH")
location.region String No Region name (see valid values in Talents section)
location.coordinates.lat String No Latitude coordinate
location.coordinates.lng String No Longitude coordinate

Valid Region Values: See the Talents section above for the complete list of valid region values.

Query Parameters

Parameter Type Default Description
force_sync Boolean false When true, processes synchronously (max. 29 seconds)

Taxonomy Code based input

Instead of providing a text description, you can use standardized occupation classification codes. This is useful when you already have classified occupation data or want to ensure consistent classification.

# Using KLDB occupation code instead of text description
curl --request POST \
  --url "https://api.trendence.com/v1/professions" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "profession_taxonomy": {
      "taxonomy": "kldb",
      "id": "43413"
    },
    "language": "de",
    "location": {
      "country": "DE",
      "region": "Brandenburg / Berlin"
    }
  }'

# Using BERUFENET occupation ID
curl --request POST \
  --url "https://api.trendence.com/v1/professions" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "profession_taxonomy": {
      "taxonomy": "berufenet",
      "id": "58965"
    },
    "language": "de",
    "location": {
      "country": "DE"
    }
  }'

require 'net/http'
require 'uri'
require 'json'

uri = URI.parse("https://api.trendence.com/v1/professions")
request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer YOUR_API_KEY"
request["Content-Type"] = "application/json"

# Example with KLDB
request.body = JSON.dump({
  "profession_taxonomy" => {
    "taxonomy" => "kldb",
    "id" => "43413"
  },
  "language" => "de",
  "location" => {
    "country" => "DE"
  }
})

# Or with BERUFENET
# request.body = JSON.dump({
#   "profession_taxonomy" => {
#     "taxonomy" => "berufenet",
#     "id" => "58965"
#   },
#   "language" => "de",
#   "location" => {
#     "country" => "DE"
#   }
# })

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

import requests

url = "https://api.trendence.com/v1/professions"
headers = {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
}

# Example with KLDB
data = {
    'profession_taxonomy': {
        'taxonomy': 'kldb',
        'id': '43413'
    },
    'language': 'de',
    'location': {
        'country': 'DE'
    }
}

# Or with BERUFENET
# data = {
#     'profession_taxonomy': {
#         'taxonomy': 'berufenet',
#         'id': '58965'
#     },
#     'language': 'de',
#     'location': {
#         'country': 'DE'
#     }
# }

response = requests.post(url, headers=headers, json=data)

const fetch = require('node-fetch');

const url = 'https://api.trendence.com/v1/professions';

// Example with KLDB
const data = {
  profession_taxonomy: {
    taxonomy: 'kldb',
    id: '43413'
  },
  language: 'de',
  location: {
    country: 'DE'
  }
};

// Or with BERUFENET
// const data = {
//   profession_taxonomy: {
//     taxonomy: 'berufenet',
//     id: '58965'
//   },
//   language: 'de',
//   location: {
//     country: 'DE'
//   }
// };

fetch(url, {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(data)
})
.then(response => response.json())
.then(data => console.log(data));

Returns the same response format as text-based requests.

Common Taxonomy Reference

Example KLDB Codes

KLDB Code Occupation (German) Occupation (English)
43413 Softwareentwickler/in Software Developers
51302 Krankenpfleger/in Nurses
62193 Verkäufer/in Sales Personnel

Example BERUFENET IDs

BERUFENET ID Occupation (German) Occupation (English)
58965 Fachinformatiker/in - Anwendungsentwicklung IT Specialist - Application Development
9162 Krankenschwester/Krankenpfleger Nurse
120735 Vertriebsassistent/in Sales Assistant

Get Profession Analysis

curl --request GET \
  --url "https://api.trendence.com/v1/professions/660e8400-e29b-41d4-a716-446655440001" \
  --header "Authorization: Bearer YOUR_API_KEY"

require 'net/http'
require 'uri'

uuid = "660e8400-e29b-41d4-a716-446655440001"
uri = URI.parse("https://api.trendence.com/v1/professions/#{uuid}")
request = Net::HTTP::Get.new(uri)
request["Authorization"] = "Bearer YOUR_API_KEY"

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

import requests

uuid = "660e8400-e29b-41d4-a716-446655440001"
url = f"https://api.trendence.com/v1/professions/{uuid}"
headers = {'Authorization': 'Bearer YOUR_API_KEY'}

response = requests.get(url, headers=headers)

const uuid = '660e8400-e29b-41d4-a716-446655440001';
const url = `https://api.trendence.com/v1/professions/${uuid}`;

fetch(url, {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
})
.then(response => response.json())
.then(data => console.log(data));

When processing is complete (200 OK):

{
  "meta": {
    "tie": {
      "version": "1.0.0"
    }
  },
  "status": "completed",
  "professions_uuid": "660e8400-e29b-41d4-a716-446655440001",
  "request": {
    "profession_text": {
      "title": "Senior Full Stack Developer",
      "description": "Full Stack Developer with over 10 years of experience in Java, JavaScript, React, Python..."
    },
    "language": "de",
    "location": {
      "country": "DE"
    }
  },
  "results": [{
    "vacancies": {
      "current": [
        {
          "location": "München",
          "similarity": 0.9430,
          "vacancy_url": "https://talentboard.example/jobs/xyz789",
          "vacancy_title": "Senior Fullstack Developer (w/m/d)",
          "organization_name": "SoftwareHouse GmbH",
          "vacancy_publish_date": "2025-06-19"
        },
        {
          "location": "Hamburg",
          "similarity": 0.9201,
          "vacancy_url": "https://careerplatform.example/positions/ghi012",
          "vacancy_title": "Full Stack Engineer",
          "organization_name": "CloudTech AG",
          "vacancy_publish_date": "2025-06-22"
        }
      ],
      "sources_last_12_months": [
        {"count": 82341, "share": 0.245, "source": "talentboard.example"},
        {"count": 61829, "share": 0.184, "source": "careerplatform.example"},
        {"count": 43567, "share": 0.130, "source": "jobfinder.example"}
      ],
      "employers_last_12_months": [
        {"count": 428, "share": 0.112, "employer": "SoftwareHouse GmbH"},
        {"count": 356, "share": 0.093, "employer": "CloudTech AG"},
        {"count": 289, "share": 0.076, "employer": "DevOps Solutions GmbH"}
      ]
    },
    "labour_market": {
      "salary": {
        "q10": 63300, "q20": 68900, "q30": 72800, "q40": 76300,
        "q50": 79700, "q60": 83000, "q70": 86700, "q80": 91400, "q90": 100700
      },
      "scarcity": {
        "scarcity_index": 8.1,
        "vacancy_duration": "high",
        "campaigns_repeated": "very high",
        "job_change_reluctance": "very low",
        "median_earnings_change": "very high",
        "avg_postings_per_campaign": "very low",
        "foreign_employee_share_change": "very high",
        "job_adds_people_available_ratio": "high"
      },
      "vacancies_count": [
        {"date": "2025-04-01", "vacancies": 21},
        {"date": "2025-05-01", "vacancies": 20},
        {"date": "2025-06-01", "vacancies": 32}
      ],
      "kldb_vacancies_jobseekers_ratio": [
        {"date": "2025-04-01", "vacancies": 892, "jobseekers": 11821,
         "vacancies_jobseekers_ratio": 0.075, "vacancies_jobseekers_ratio_log": 0.023}
      ]
    },
    "matched_profession_profile": {
      "tools": ["React", ".NET Core", "OpenAPI", "Docker"],
      "hard_skills": ["Typescript", "Angular", "Java", "Python"],
      "soft_skills": ["Kritisches Denken", "Teamarbeit"],
      "responsibilities": ["Software entwickeln", "Benutzeroberflächen optimieren", "Code Reviews durchführen"],
      "similar_titles": ["Entwickler Fullstack", "Developer", "Software Engineer"]
    }
  }],
  "metadata": {
    "taxonomy": [{
      "kldb": {
        "id": "43413",
        "label": "Softwareentwicklung - Spezialist/in"
      },
      "berufenet": {
        "id": "58965",
        "label": "Fachinformatiker/in - Anwendungsentwicklung"
      },
      "similarity_score": 0.9245
    }],
    "extracted_attributes": {
      "tools": ["React", ".NET Core", "OpenAPI"],
      "industry": "information and communication",
      "sub_industry": "computer programming activities",
      "education": [],
      "experience": ["10 years"],
      "hard_skills": ["Java", "JavaScript", "React", "Python"],
      "soft_skills": ["teamwork", "problem solving"],
      "responsibilities": ["develop software", "maintain applications", "code review"]
    }
  }
}

This endpoint retrieves the status or result of a profession analysis.

The results array contains matching vacancy data including job postings, similarity scores, labour market analytics (salary, scarcity index), and statistics about vacancy sources and employers. See Understanding Profession Responses for detailed field descriptions.

HTTP Request

GET https://api.trendence.com/v1/professions/:uuid

URL Parameters

Parameter Description
uuid The UUID of the profession analysis to retrieve

Understanding Profession Responses

When you submit a profession description, the API analyzes the job requirements and returns four key types of information:

  1. Matching Job Vacancies - A ranked list of similar job opportunities with similarity scores, enabling you to show employers comparable positions in the market.

  2. Labour Market Analytics - Salary quantiles (q10-q90) and recruitment complexity metrics including the Recruitment Complexity Index (scarcity_index), providing insights into compensation benchmarks and hiring difficulty.

  3. Market Intelligence - Insights into where these jobs are posted (sources) and which employers are hiring for similar roles, helping you understand competitive hiring landscapes.

  4. Profession Profile - Extracted skills, tools, responsibilities, and similar job titles from the profession description.

Response Structure

Field Type Description
results Array Analysis results (typically one element)
results[].vacancies Object Vacancy-related data
results[].labour_market Object Salary and recruitment complexity metrics
results[].matched_profession_profile Object Extracted skills and profile data

Vacancy Fields

Field Description Usage Notes
location Geographic location Analyze regional hiring patterns
similarity Match quality (0-1) Higher values indicate better match between talent and vacancy
vacancy_url Direct link to posting For detailed job analysis or referrals
vacancy_title Job position title Shows market positioning of similar roles
organization_name Hiring organization Identify competitors or benchmarking
vacancy_publish_date Publication date (YYYY-MM-DD) Analyze hiring trends over time

Labour Market Data

Field Description Usage Notes
salary.q10 - salary.q90 Salary quantiles Annual salary in local currency; q50 is median. Use for compensation benchmarking
scarcity.scarcity_index Recruitment Complexity Index (0-10) Higher = greater difficulty finding candidates. Use for workforce planning
scarcity.vacancy_duration Time to fill positions Values: low, high, very high. Indicates typical hiring timeline
scarcity.campaigns_repeated Reposting frequency very high = candidate scarcity
scarcity.median_earnings_change Salary growth when changing jobs Indicates competitive pressure on compensation
scarcity.foreign_employee_share_change International recruitment trend very high = reliance on foreign talent
scarcity.job_adds_people_available_ratio Supply-demand balance Higher = more competition for talent
vacancies_count[] Historical vacancy volume Monthly time series data
kldb_vacancies_jobseekers_ratio[] Supply-demand ratio over time Based on official occupation classification (KLDB)

Profession Profile

Field Description
tools Technologies mentioned or inferred (e.g., "React", ".NET Core", "OpenAPI")
hard_skills Technical competencies required (e.g., "Typescript", "Angular")
soft_skills Non-technical competencies (e.g., "Kritisches Denken")
responsibilities Job duties and tasks (e.g., "Software entwickeln")
similar_titles Alternative titles for this profession (e.g., "Developer Full Stack")

Market Intelligence

The response includes vacancy source and employer statistics:

Vacancy Sources - Shows which job boards have the most postings for this profession type. Use to optimize job posting strategy and understand platform reach.

Vacancy Employers - Lists top hiring employers with their market share. High vacancy counts indicate strong hiring demand, useful for talent scarcity assessment.

Rate Limiting

The API is limited to 100 requests per minute for POST, PUT, and PATCH requests.

When the rate limit is exceeded, you will receive a 429 Too Many Requests status:

{
  "error": "Rate limit exceeded. Please try again later."
}

Changelog

[1.0.0] - 2026-03-16

Changed

[0.2.2] - 2026-01-20

Added

[0.2.1] - 2026-01-06

Changed

[0.2.0] - 2025-12-16

Added

Changed

[0.1.0] - 2025-12-01

Versioning Policy

Every request includes the API version shipped in the response metadata:

{
  "meta": {
    "tie": {
      "version": "1.0.0"
    }
  }
}

Version Numbering

Deprecation Policy

When endpoints or features are deprecated:

  1. Deprecated features will be announced at least 6 months before removal
  2. Deprecation notices will appear in this changelog and API responses
  3. Migration guides will be provided for breaking changes

Errors

The Trendence API uses conventional HTTP response codes to indicate the success or failure of an API request.

HTTP Status Codes

Error Code Meaning
200 OK -- Analysis completed successfully (synchronous requests).
202 Accepted -- Request accepted and processing asynchronously.
400 Bad Request -- Your request is malformed or invalid.
401 Unauthorized -- Your API key is invalid or missing.
404 Not Found -- The requested resource could not be found.
415 Unsupported Media Type -- Content-Type header must be application/json.
422 Unprocessable Entity -- Validation failed (see error details).
429 Too Many Requests -- Rate limit exceeded. Slow down!
500 Internal Server Error -- We had a problem with our server. Try again later.
502 Bad Gateway -- The backend service is temporarily unavailable.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.

Validation Errors

When validation fails (422 status), the API returns a detailed error response:

{
  "error": "Validation failed",
  "missing_fields": [
    "profession_text or profession_taxonomy is required"
  ],
  "example": {
    "profession_text": {
      "title": "Full Stack Developer",
      "description": "Full Stack Developer with experience in Java, JavaScript, and modern web frameworks."
    },
    "profession_taxonomy": {
      "taxonomy": "kldb",
      "id": "12193"
    },
    "location": {
      "country": "DE"
    }
  },
  "meta": {
    "tie": {
      "version": "1.0.0"
    }
  }
}

Common Validation Errors

Error Message Cause Solution
profession_text or profession_taxonomy is required Neither text nor taxonomy provided Provide either profession_text with title/description OR profession_taxonomy with taxonomy/id
profession_taxonomy.id is required Taxonomy object missing id field Include both taxonomy and id fields in profession_taxonomy
location.country is required Missing country code Provide ISO 3166-1 alpha-2 country code (e.g., "DE", "AT", "CH")
talent_text.description is required Missing talent description Provide description in talent_text object

Taxonomy Not Found (404)

When using taxonomy-based requests, you may receive a 404 error if the specified occupation code is not found or unavailable:

{
  "error": "Upstream request failed",
  "detail": "Profession not found or embedding unavailable: 'berufenet:11510 not found'",
  "meta": {
    "tie": {
      "version": "1.0.0"
    }
  }
}

Common Causes

Solution

Verify that your taxonomy code is valid: - For KLDB: Check the official KLDB classification - For BERUFENET: Check the BERUFENET database

Rate Limiting

{
  "error": "Rate limit exceeded. Please try again later."
}

When you exceed the rate limit (100 requests per minute for POST/PUT/PATCH), you'll receive a 429 status code. Implement exponential backoff in your client to handle rate limiting gracefully.

cURL Ruby Python JavaScript