Job Insights

Returns AI-generated insights for a parsed job description, including role classification, seniority level, required/preferred skills, employment details, and bias detection.

Request Details

path Parameters

Field	Type	Required	Description
id	string	Yes	The unique identifier of the job.

query Parameters

Field	Type	Required	Description
include	string	No	comma-separated sections to include: 'bias,keywords,benefits'
locale	string	No	e.g., 'en-US' for salary/location normalization

Sample Request & Response

GET

/v1/jobs/{id}/analysis

Sample Request

Headers:

{
  "Authorization": "Bearer <YOUR_API_KEY>"
}

Path Parameters:

{
  "id": "string (required) - The unique identifier of the job."
}

Query Parameters:

{
  "include": "string (optional) - comma-separated sections to include: 'bias,keywords,benefits'",
  "locale": "string (optional) - e.g., 'en-US' for salary/location normalization"
}

Sample Response (200)

{
  "jobId": "job_67890",
  "analysis": {
    "role": "Senior Backend Engineer",
    "level": "Senior",
    "classification": "Software Engineering",
    "requiredSkills": [
      "Node.js",
      "PostgreSQL",
      "System Design"
    ],
    "preferredSkills": [
      "AWS",
      "Docker"
    ],
    "coreTechnologies": [
      "Node.js",
      "PostgreSQL"
    ],
    "yearsExperienceRequired": 5,
    "educationRequired": "Bachelor's or equivalent experience",
    "employmentType": "Full-time",
    "locationType": "Hybrid",
    "location": "Toronto, ON, Canada",
    "visaSponsorship": "Not specified",
    "securityClearance": "Not required",
    "salaryRange": {
      "currency": "USD",
      "min": 150000,
      "max": 180000,
      "period": "year"
    },
    "benefits": [
      "Health insurance",
      "401(k)",
      "Flexible PTO"
    ],
    "responsibilities": [
      "Design and scale backend services",
      "Own database performance and observability"
    ],
    "keywords": [
      "microservices",
      "observability",
      "scalability"
    ],
    "redFlags": [
      "Vague outcomes (e.g., 'work under pressure' without context)"
    ],
    "readability": {
      "gradeLevel": 11,
      "lengthTokens": 820,
      "qualityScore": 0.82
    }
  },
  "biasDetection": {
    "overallRisk": "moderate",
    "summary": "2 potential bias issues detected.",
    "biasedPhrases": [
      {
        "text": "rockstar engineer",
        "category": "gender",
        "suggestion": "Use neutral terms like 'skilled' or 'experienced engineer'."
      },
      {
        "text": "digital native",
        "category": "age",
        "suggestion": "Avoid age-coded phrasing; describe tools or competencies needed."
      }
    ],
    "id": "jobbias_1a2b3c",
    "jobId": "job_67890",
    "createdAt": 1692351200000,
    "updatedAt": 1692351300000
  },
  "metadata": {
    "id": "jobinsights_9f8e7d",
    "createdAt": 1692351200000,
    "updatedAt": 1692351300000
  }
}