Workforce Management

Role management and workforce analytics

All endpoints require authentication. Include your access token in the Authorization header: Authorization: Bearer your_access_token

InternalGET/v1/ja/roles

Get all roles

Retrieve all roles within a company with filtering and pagination options

Path Parameters

Query Parameters

Name
departmentId
Type
string
Description
Filter roles by department ID
Name
teamId
Type
string
Description
Filter roles by team ID
Name
seniorityLevel
Type
string
Description
Filter roles by seniority level (e.g., "Junior", "Senior", "Executive")
Name
limit
Type
integer
Description
Number of roles to return (default: 50, max: 100)
Name
offset
Type
integer
Description
Number of roles to skip for pagination

Response

Name
success
Type
boolean
Description
Indicates if the request was successful
Name
data
Type
array<object>
Description
Array of role objects, each containing:
- id (string): Unique identifier for the role
- title (string): Role title
- description (string): Role description
- seniorityLevel (string): Seniority level
- team (object): Team information with id and name
- department (object): Department information with id and name
- headcount (integer): Number of people in this role
Name
pagination
Type
object
Description
Pagination information containing:
- total (integer): Total number of roles
- limit (integer): Number of items per page
- offset (integer): Starting position
- hasMore (boolean): Whether more results are available

Request

GET

/v1/ja/roles

curl https://frontier.beamery.com/v1/ja/roles \
  -H "Authorization: Bearer your_access_token"

Response

{
  "success": true,
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-123456789012",
      "title": "Personal Banking Advisor",
      "description": "Responsible for providing personalized banking services to clients, assisting with account management, and offering financial advice. This role requires strong interpersonal skills and knowledge of banking products and services.",
      "seniorityLevel": "Junior",
      "team": {
        "id": "t1a2b3c4-d5e6-7890-fghi-123456789012",
        "name": "Personal Banking Services"
      },
      "department": {
        "id": "d1e2f3g4-h5i6-7890-jklm-123456789012",
        "name": "Retail Banking Operations"
      },
      "headcount": 6,
      "location": {
        "id": "l1a2b3c4-d5e6-7890-fghi-123456789012",
        "address": "London, UK",
        "city": "London",
        "country": "United Kingdom",
        "countryCode": "GB",
        "geometry": {
          "type": "Point",
          "coordinates": [-0.12, 51.5]
        }
      },
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-20T14:22:00Z"
    },
    {
      "id": "b2c3d4e5-f6g7-8901-bcde-234567890123",
      "title": "Senior Data Analyst",
      "description": "Lead data analysis initiatives to drive business insights and support strategic decision-making. This role involves working with large datasets, creating visualizations, and presenting findings to stakeholders.",
      "seniorityLevel": "Senior",
      "team": {
        "id": "t2b3c4d5-e6f7-8901-ghij-234567890123",
        "name": "Data Analytics Team"
      },
      "department": {
        "id": "d2f3g4h5-i6j7-8901-klmn-234567890123",
        "name": "Data Analytics"
      },
      "headcount": 3,
      "location": {
        "id": "l2b3c4d5-e6f7-8901-ghij-234567890123",
        "address": "Remote Work",
        "city": "Remote",
        "country": "Global",
        "countryCode": "WW",
        "geometry": {
          "type": "Point",
          "coordinates": [0, 0]
        }
      },
      "createdAt": "2024-01-10T09:15:00Z",
      "updatedAt": "2024-01-25T11:45:00Z"
    },
    {
      "id": "c3d4e5f6-g7h8-9012-cdef-345678901234",
      "title": "Software Engineer",
      "description": "Develop and maintain software applications, write clean and efficient code, and collaborate with cross-functional teams to deliver high-quality software solutions.",
      "seniorityLevel": "Mid-Level",
      "team": {
        "id": "t3c4d5e6-f7g8-9012-hijk-345678901234",
        "name": "Backend Development"
      },
      "department": {
        "id": "d3g4h5i6-j7k8-9012-lmno-345678901234",
        "name": "Engineering"
      },
      "headcount": 12,
      "location": {
        "id": "l3c4d5e6-f7g8-9012-hijk-345678901234",
        "address": "San Francisco, CA, USA",
        "city": "San Francisco",
        "country": "United States",
        "countryCode": "US",
        "geometry": {
          "type": "Point",
          "coordinates": [-122.4194, 37.7749]
        }
      },
      "createdAt": "2024-01-05T08:00:00Z",
      "updatedAt": "2024-01-30T16:30:00Z"
    }
  ],
  "pagination": {
    "total": 156,
    "limit": 50,
    "offset": 0,
    "hasMore": true
  }
}

InternalGET/v1/ja/roles/{roleId}

Get role

Retrieve detailed role information with skills, tasks, and context

Path Parameters

Name
roleId
Type
string
Description
Unique identifier for the role

Response

Name
success
Type
boolean
Description
Indicates if the request was successful
Name
data
Type
object
Description
Detailed role information containing:
- id (string): Unique identifier for the role
- title (string): Role title
- description (string): Detailed role description
- seniorityLevel (string): Seniority level
- team (object): Team information with id and name
- department (object): Department information with id and name
- headcount (integer): Number of people in this role
- skills (array): Required skills with IDs and names
- tasks (array): Associated tasks with IDs and descriptions
- location (object): Location information
- createdAt (string): Creation timestamp
- updatedAt (string): Last update timestamp

Request

GET

/v1/ja/roles/{roleId}

curl https://frontier.beamery.com/v1/ja/roles/a1b2c3d4-e5f6-7890-abcd-123456789012 \
  -H "Authorization: Bearer your_access_token"

Response

{
  "success": true,
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-123456789012",
    "title": "Personal Banking Advisor",
    "description": "Responsible for providing personalized banking services to clients, assisting with account management, and offering financial advice. This role involves building relationships with customers, understanding their financial needs, and recommending appropriate banking products and services. The advisor must stay current with banking regulations and compliance requirements.",
    "seniorityLevel": "Junior",
    "team": {
      "id": "t1a2b3c4-d5e6-7890-fghi-123456789012",
      "name": "Personal Banking Services"
    },
    "department": {
      "id": "d1e2f3g4-h5i6-7890-jklm-123456789012",
      "name": "Retail Banking Operations"
    },
    "headcount": 6,
    "skills": [
      { 
        "id": "s1a2b3c4-d5e6-7890-fghi-123456789012", 
        "name": "Customer Service",
        "level": "intermediate",
        "category": "Soft Skills"
      },
      { 
        "id": "s2b3c4d5-e6f7-8901-ghij-234567890123", 
        "name": "Financial Analysis",
        "level": "beginner",
        "category": "Technical"
      },
      { 
        "id": "s3c4d5e6-f7g8-9012-hijk-345678901234", 
        "name": "Banking Regulations",
        "level": "intermediate",
        "category": "Compliance"
      },
      { 
        "id": "s4d5e6f7-g8h9-0123-ijkl-456789012345", 
        "name": "Communication",
        "level": "advanced",
        "category": "Soft Skills"
      },
      { 
        "id": "s5e6f7g8-h9i0-1234-jklm-567890123456", 
        "name": "Sales Techniques",
        "level": "intermediate",
        "category": "Sales"
      }
    ],
    "tasks": [
      { 
        "id": "t1f2g3h4-i5j6-7890-klmn-123456789012", 
        "name": "Assist clients with opening and managing accounts",
        "description": "Guide customers through account setup processes and provide ongoing account management support"
      },
      { 
        "id": "t2g3h4i5-j6k7-8901-lmno-234567890123", 
        "name": "Provide information on banking products and services",
        "description": "Educate clients about available banking products, their features, and benefits"
      },
      { 
        "id": "t3h4i5j6-k7l8-9012-mnop-345678901234", 
        "name": "Resolve customer inquiries and complaints",
        "description": "Address customer concerns professionally and find appropriate solutions"
      },
      { 
        "id": "t4i5j6k7-l8m9-0123-nopq-456789012345", 
        "name": "Conduct financial needs assessments",
        "description": "Analyze customer financial situations to recommend suitable products and services"
      },
      { 
        "id": "t5j6k7l8-m9n0-1234-opqr-567890123456", 
        "name": "Promote and sell banking products",
        "description": "Identify opportunities to cross-sell and upsell banking products to existing customers"
      }
    ],
    "location": {
      "id": "l1a2b3c4-d5e6-7890-fghi-123456789012",
      "address": "London, UK",
      "city": "London",
      "country": "United Kingdom",
      "countryCode": "GB",
      "geometry": {
        "type": "Point",
        "coordinates": [-0.12, 51.5]
      }
    },
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-20T14:22:00Z"
  }
}

InternalPOST/v1/ja/roles

Create role

Create a new role with validation

Path Parameters

Request Body

Name
name
Type
string
Description
Role name
Name
description
Type
string
Description
Role description
Name
seniorityLevel
Type
string
Description
Seniority level
Name
departmentId
Type
string
Description
Department ID this role belongs to
Name
requiredSkills
Type
array<string>
Description
Required skill IDs
Name
tasks
Type
array<string>
Description
Task IDs associated with this role

Response

Name
success
Type
boolean
Description
No description
Name
data
Type
RoleDetails
Description
No description

Request

POST

/v1/ja/roles

curl https://frontier.beamery.com/v1/ja/roles \
  -X POST \
  -H "Authorization: Bearer your_access_token" \
  -H "Content-Type: application/json" \
  -d '{
        "name": "Senior Software Engineer",
        "description": "Lead technical initiatives and mentor junior developers",
        "seniorityLevel": "senior",
        "departmentId": "d1e2f3g4-h5i6-7890-jklm-123456789012",
        "requiredSkills": ["2e813466-3525-46e7-817c-6400f65d6717", "1bdce777-8888-99aa-bbcc-123456789012"],
        "tasks": ["t1f2g3h4-i5j6-7890-klmn-123456789012", "t2g3h4i5-j6k7-8901-lmno-234567890123"]
    }'

Response

{
  "success": true,
  "data": {
    "id": "role-456",
    "name": "Senior Software Engineer",
    "description": "Lead technical initiatives and mentor junior developers",
    "seniorityLevel": "senior",
    "departmentId": "d1e2f3g4-h5i6-7890-jklm-123456789012",
    "requiredSkills": ["2e813466-3525-46e7-817c-6400f65d6717", "1bdce777-8888-99aa-bbcc-123456789012"],
    "tasks": ["t1f2g3h4-i5j6-7890-klmn-123456789012", "t2g3h4i5-j6k7-8901-lmno-234567890123"],
    "createdAt": "2024-01-15T10:30:00Z"
  }
}

InternalPATCH/v1/ja/roles/{roleId}

Update role

Update existing role with partial data

Path Parameters

Name
roleId
Type
string
Description
Unique identifier for the role

Request Body

Name
name
Type
string
Description
Updated role name
Name
description
Type
string
Description
Updated role description
Name
level
Type
string
Description
Updated seniority level
Name
departmentId
Type
string
Description
Updated department ID
Name
requiredSkills
Type
array<string>
Description
Updated required skill IDs
Name
tasks
Type
array<string>
Description
Updated task IDs

Response

Name
success
Type
boolean
Description
No description
Name
data
Type
RoleDetails
Description
No description

Request

PATCH

/v1/ja/roles/{roleId}

curl https://frontier.beamery.com/v1/ja/roles/{roleId} \
  -X PATCH \
  -H "Authorization: Bearer your_access_token" \
  -H "Content-Type: application/json" \
  -d '{
        "description": "Lead technical initiatives, architect solutions, and mentor team members",
        "requiredSkills": ["2e813466-3525-46e7-817c-6400f65d6717", "1bdce777-8888-99aa-bbcc-123456789012", "3f924577-9999-aaaa-dddd-234567890123"]
    }'

Response

{
  "success": true,
  "data": {
    "id": "role-456",
    "name": "Senior Software Engineer",
    "description": "Lead technical initiatives, architect solutions, and mentor team members",
    "seniorityLevel": "senior",
    "departmentId": "d1e2f3g4-h5i6-7890-jklm-123456789012",
    "requiredSkills": ["2e813466-3525-46e7-817c-6400f65d6717", "1bdce777-8888-99aa-bbcc-123456789012", "3f924577-9999-aaaa-dddd-234567890123"],
    "tasks": ["t1f2g3h4-i5j6-7890-klmn-123456789012", "t2g3h4i5-j6k7-8901-lmno-234567890123"],
    "updatedAt": "2024-01-15T14:45:00Z"
  }
}

InternalDELETE/v1/ja/roles/{roleId}

Delete role

Remove a specific role permanently

Path Parameters

Name
roleId
Type
string
Description
Unique identifier for the role

Response

Name
success
Type
boolean
Description
No description
Name
data
Type
object
Description
Response data containing:
- message (string): Success message

Request

DELETE

/v1/ja/roles/{roleId}

curl https://frontier.beamery.com/v1/ja/roles/{roleId} \
  -X DELETE \
  -H "Authorization: Bearer your_access_token"

Response

{
  "success": true,
  "data": {
    "message": "Role successfully deleted"
  }
}

InternalGET/v1/ja/roles/{roleId}/compensation

Role compensation analysis

Retrieve compensation analysis for a specific role including market benchmarks

Path Parameters

Name
roleId
Type
string
Description
Unique identifier for the role

Query Parameters

Name
analysis
Type
string
Description
Specific analysis section to retrieve. Available options:
- geographicVariations - Geographic salary variations
- experienceBreakdown - Compensation by seniority level
- jobFamilyGroupComparison - Job family group comparison
- benefitsAnalysis - Benefits and perks analysis
- trendsAndProjections - Salary trends and projections
- recommendations - Compensation recommendations
If not specified, returns all analysis sections

Response

Name
success
Type
boolean
Description
Indicates if the request was successful
Name
data
Type
object
Description
Comprehensive compensation analysis containing:
- roleId (string): The role identifier
- analysisDate (string): When the analysis was generated
- salaryBenchmark (object): Market salary benchmarks
- analysis (object): Analysis sections (Alpha feature) containing:
  - geographicVariations (array): Salary variations by location
  - experienceBreakdown (array): Compensation by seniority level
  - jobFamilyGroupComparison (object): Job family group-specific compensation data
  - benefitsAnalysis (object): Benefits and perks analysis
  - trendsAndProjections (object): Salary trend analysis
  - recommendations (array): Actionable compensation recommendations

Request

GET

/v1/ja/roles/{roleId}/compensation

curl https://frontier.beamery.com/v1/ja/roles/{roleId}/compensation \
  -H "Authorization: Bearer your_access_token"

Response

{
  "success": true,
  "data": {
    "roleId": "a1b2c3d4-e5f6-7890-abcd-123456789012",
    "analysisDate": "2024-01-15T10:30:00Z",
    "salaryBenchmark": {
      "median": 75000,
      "p25": 65000,
      "p75": 85000,
      "p90": 95000,
      "currency": "USD"
    },
    "analysis": {
      "geographicVariations": [
        {
          "location": {
            "city": "New York",
            "country": "United States",
            "countryCode": "US"
          },
          "salaryAdjustment": 1.25,
          "medianSalary": 93750,
          "costOfLiving": 1.32
        },
        {
          "location": {
            "city": "Austin",
            "country": "United States",
            "countryCode": "US"
          },
          "salaryAdjustment": 1.05,
          "medianSalary": 78750,
          "costOfLiving": 1.08
        },
        {
          "location": {
            "city": "Remote",
            "country": "Global",
            "countryCode": "GL"
          },
          "salaryAdjustment": 0.95,
          "medianSalary": 71250,
          "costOfLiving": 1.00
        }
      ],
      "experienceBreakdown": [
        {
          "seniorityLevel": "seniority:junior",
          "medianSalary": 58000,
          "range": {
            "min": 50000,
            "max": 68000
          }
        },
        {
          "seniorityLevel": "seniority:mid-level",
          "medianSalary": 75000,
          "range": {
            "min": 65000,
            "max": 85000
          }
        },
        {
          "seniorityLevel": "seniority:senior",
          "medianSalary": 95000,
          "range": {
            "min": 85000,
            "max": 110000
          }
        }
      ],
      "jobFamilyGroupComparison": {
        "currentJobFamilyGroup": "jobfamilygroup:financial-services",
        "medianSalary": 75000,
        "otherJobFamilyGroups": [
          {
            "jobFamilyGroup": "jobfamilygroup:technology",
            "medianSalary": 85000,
            "difference": 13.3
          },
          {
            "jobFamilyGroup": "jobfamilygroup:healthcare",
            "medianSalary": 68000,
            "difference": -9.3
          },
          {
            "jobFamilyGroup": "jobfamilygroup:manufacturing",
            "medianSalary": 70000,
            "difference": -6.7
          }
        ]
      },
      "benefitsAnalysis": {
        "healthInsurance": {
          "coverage": "Full coverage",
          "employerContribution": 85,
          "marketValue": 8500
        },
        "retirement": {
          "type": "401(k)",
          "matching": "6% match",
          "marketValue": 4500
        },
        "paidTimeOff": {
          "vacationDays": 20,
          "sickDays": 10,
          "marketValue": 3800
        },
        "totalBenefitsValue": 16800
      },
      "trendsAndProjections": {
        "yearOverYear": {
          "growthRate": 4.2,
          "trend": "increasing"
        },
        "nextYear": {
          "projectedGrowth": 3.8,
          "confidence": "moderate"
        },
        "factors": [
          "Increasing demand for financial advisory skills",
          "Remote work flexibility impact",
          "Regulatory changes in financial services"
        ]
      },
      "recommendations": [
        {
          "type": "salary_adjustment",
          "priority": "high",
          "description": "Consider 8% salary increase to match market median",
          "impact": "retention_improvement"
        },
        {
          "type": "geographic_expansion",
          "priority": "medium",
          "description": "Expand remote work options to access wider talent pool",
          "impact": "cost_optimization"
        },
        {
          "type": "benefits_enhancement",
          "priority": "low",
          "description": "Review retirement matching to stay competitive",
          "impact": "attraction_improvement"
        }
      ]
    }
  }
}

InternalGET/v1/ja/roles/{roleId}/demand

Role demand analysis

Retrieve demand analysis for a specific role including market trends

Path Parameters

Name
roleId
Type
string
Description
Unique identifier for the role

Query Parameters

Name
analysis
Type
string
Description
Specific analysis section to retrieve. Available options:
- geographicDemand - Geographic demand variations
- jobFamilyGroupDemand - Job family group demand comparison
- skillsDemand - Skills demand analysis
- timeTrends - Time-based demand trends
- demandDrivers - Demand driver analysis
- recommendations - Demand recommendations If not specified, returns all analysis sections

Response

Name
success
Type
boolean
Description
Indicates if the request was successful
Name
data
Type
object
Description
Comprehensive demand analysis containing:
- roleId (string): The role identifier
- analysisDate (string): When the analysis was generated
- demandLevel (string): Overall demand level (low, medium, high)
- demandScore (number): Numerical demand score
- demandTrend (string): Demand trend direction
- marketDemand (object): Market-level demand information
- analysis (object): Analysis sections (Alpha feature) containing:
  - geographicDemand (array): Demand variations by location
  - jobFamilyGroupDemand (object): Job family group demand comparison
  - skillsDemand (array): Skills demand analysis
  - timeTrends (object): Time-based demand trends
  - demandDrivers (array): Demand driver analysis
  - recommendations (array): Actionable demand recommendations

Request

GET

/v1/ja/roles/{roleId}/demand

curl https://frontier.beamery.com/v1/ja/roles/{roleId}/demand \
  -H "Authorization: Bearer your_access_token"

Response

{
  "success": true,
  "data": {
    "roleId": "a1b2c3d4-e5f6-7890-abcd-123456789012",
    "analysisDate": "2024-01-15T10:30:00Z",
    "demandLevel": "high",
    "demandScore": 8.2,
    "demandTrend": "increasing",
    "marketDemand": {
      "currentOpenings": 2847,
      "previousPeriod": 2345,
      "growthRate": 21.4,
      "competitionLevel": "high"
    },
    "analysis": {
      "geographicDemand": [
        {
          "location": {
            "city": "New York",
            "country": "United States",
            "countryCode": "US"
          },
          "openings": 456,
          "demandScore": 9.1,
          "competitionLevel": "very_high"
        },
        {
          "location": {
            "city": "San Francisco",
            "country": "United States",
            "countryCode": "US"
          },
          "openings": 398,
          "demandScore": 8.9,
          "competitionLevel": "high"
        },
        {
          "location": {
            "city": "Austin",
            "country": "United States",
            "countryCode": "US"
          },
          "openings": 234,
          "demandScore": 7.8,
          "competitionLevel": "medium"
        },
        {
          "location": {
            "city": "Remote",
            "country": "Global",
            "countryCode": "GL"
          },
          "openings": 645,
          "demandScore": 8.5,
          "competitionLevel": "high"
        }
      ],
      "jobFamilyGroupDemand": {
        "currentJobFamilyGroup": "jobfamilygroup:financial-services",
        "demandScore": 8.2,
        "otherJobFamilyGroups": [
          {
            "jobFamilyGroup": "jobfamilygroup:technology",
            "demandScore": 9.3,
            "openings": 1234
          },
          {
            "jobFamilyGroup": "jobfamilygroup:healthcare",
            "demandScore": 6.8,
            "openings": 567
          },
          {
            "jobFamilyGroup": "jobfamilygroup:consulting",
            "demandScore": 7.9,
            "openings": 456
          }
        ]
      },
      "skillsDemand": [
      {
        "skill": "Customer Service",
        "demandScore": 9.1,
        "importance": "critical",
        "marketGrowth": 15.2
      },
      {
        "skill": "Financial Analysis",
        "demandScore": 8.7,
        "importance": "high",
        "marketGrowth": 22.3
      },
      {
        "skill": "Digital Banking",
        "demandScore": 9.4,
        "importance": "critical",
        "marketGrowth": 35.7
      },
      {
        "skill": "Risk Assessment",
        "demandScore": 8.2,
        "importance": "high",
        "marketGrowth": 18.9
      }
    ],
      "timeTrends": {
        "lastQuarter": {
          "demandScore": 7.8,
          "change": "+5.1%"
        },
        "lastYear": {
          "demandScore": 7.2,
          "change": "+13.9%"
        },
        "projection": {
          "nextQuarter": {
            "demandScore": 8.6,
            "confidence": "high"
          },
          "nextYear": {
            "demandScore": 9.1,
            "confidence": "moderate"
          }
        }
      },
      "demandDrivers": [
        {
          "factor": "Digital transformation in banking",
          "impact": "high",
          "description": "Increasing need for advisors with digital banking skills"
        },
        {
          "factor": "Regulatory compliance requirements",
          "impact": "medium",
          "description": "Growing complexity of financial regulations"
        },
        {
          "factor": "Customer experience focus",
          "impact": "high",
          "description": "Banks prioritizing personalized customer service"
        }
      ],
      "recommendations": [
        {
          "type": "skill_development",
          "priority": "high",
          "description": "Focus on digital banking and fintech skills training",
          "impact": "demand_alignment"
        },
        {
          "type": "geographic_expansion",
          "priority": "medium",
          "description": "Consider expanding to high-demand markets like NYC and SF",
          "impact": "opportunity_access"
        },
        {
          "type": "compensation_adjustment",
          "priority": "medium",
          "description": "Increase compensation to compete in high-demand market",
          "impact": "talent_attraction"
        }
      ]
    }
  }
}

InternalGET/v1/ja/roles/{roleId}/supply

Role supply analysis

Analyze role supply and availability in the market

Path Parameters

Name
roleId
Type
string
Description
Unique identifier for the role

Query Parameters

Name
analysis
Type
string
Description
Specific analysis section to retrieve. Available options:
- geographicSupply - Geographic supply variations
- candidateProfile - Candidate profile analysis
- skillsAvailability - Skills availability analysis
- competitionAnalysis - Competition analysis
- hiringMetrics - Hiring metrics and projections
- recommendations - Supply recommendations If not specified, returns all analysis sections

Response

Name
success
Type
boolean
Description
Indicates if the request was successful
Name
data
Type
object
Description
Comprehensive supply analysis containing:
- roleId (string): The role identifier
- analysisDate (string): When the analysis was generated
- supplyLevel (string): Overall supply level (low, medium, high)
- supplyScore (number): Numerical supply score
- supplyTrend (string): Supply trend direction
- marketSupply (object): Market-level supply information
- analysis (object): Analysis sections (Alpha feature) containing:
  - geographicSupply (array): Supply variations by location
  - candidateProfile (object): Candidate profile analysis
  - skillsAvailability (array): Skills availability analysis
  - competitionAnalysis (object): Competition analysis
  - hiringMetrics (object): Hiring metrics and projections
  - recommendations (array): Actionable supply recommendations

Request

GET

/v1/ja/roles/{roleId}/supply

curl https://frontier.beamery.com/v1/ja/roles/{roleId}/supply \
  -H "Authorization: Bearer your_access_token"

Response

  "success": true,
  "data": {
    "roleId": "a1b2c3d4-e5f6-7890-abcd-123456789012",
    "analysisDate": "2024-01-15T10:30:00Z",
    "supplyLevel": "medium",
    "supplyScore": 6.8,
    "supplyTrend": "stable",
    "marketSupply": {
      "availableCandidates": 18453,
      "qualifiedCandidates": 7321,
      "activeJobSeekers": 4892,
      "passiveCandidates": 11561,
      "competitionIndex": 0.75
    },
    "analysis": {
      "geographicSupply": [
        {
          "location": {
            "city": "New York",
            "country": "United States",
            "countryCode": "US"
          },
          "availableCandidates": 3247,
          "qualifiedCandidates": 1456,
          "supplyScore": 7.8,
          "costToHire": 12500
        },
        {
          "location": {
            "city": "San Francisco",
            "country": "United States",
            "countryCode": "US"
          },
          "availableCandidates": 2198,
          "qualifiedCandidates": 1034,
          "supplyScore": 6.9,
          "costToHire": 15200
        },
        {
          "location": {
            "city": "Austin",
            "country": "United States",
            "countryCode": "US"
          },
          "availableCandidates": 1876,
          "qualifiedCandidates": 923,
          "supplyScore": 7.2,
          "costToHire": 8900
        },
        {
          "location": {
            "city": "Remote",
            "country": "Global",
            "countryCode": "GL"
          },
          "availableCandidates": 5234,
          "qualifiedCandidates": 2187,
          "supplyScore": 8.1,
          "costToHire": 7800
        }
      ],
      "candidateProfile": {
        "averageExperience": 4.2,
        "educationLevel": {
          "bachelors": 0.65,
          "masters": 0.28,
          "phd": 0.03,
          "other": 0.04
        },
        "topSources": [
          {
            "source": "LinkedIn",
            "percentage": 45.3,
            "quality": "high"
          },
          {
            "source": "Indeed",
            "percentage": 23.1,
            "quality": "medium"
          },
          {
            "source": "Company Website",
            "percentage": 18.7,
            "quality": "high"
          },
          {
            "source": "Referrals",
            "percentage": 12.9,
            "quality": "very_high"
          }
        ]
      },
      "skillsAvailability": [
      {
        "skill": "Customer Service",
        "availableCandidates": 6789,
        "skillLevel": "intermediate",
        "supplyScore": 8.2
      },
      {
        "skill": "Financial Analysis",
        "availableCandidates": 4321,
        "skillLevel": "beginner",
        "supplyScore": 6.8
      },
      {
        "skill": "Digital Banking",
        "availableCandidates": 2156,
        "skillLevel": "intermediate",
        "supplyScore": 5.1
      },
      {
        "skill": "Risk Assessment",
        "availableCandidates": 3876,
        "skillLevel": "intermediate",
        "supplyScore": 7.3
      },
      {
        "skill": "Regulatory Compliance",
        "availableCandidates": 5234,
        "skillLevel": "intermediate",
        "supplyScore": 7.9
      }
    ],
      "competitionAnalysis": {
      "directCompetitors": [
        {
          "company": "JPMorgan Chase",
          "activeRequisitions": 234,
          "averageTimeToFill": 45,
          "competitionLevel": "high"
        },
        {
          "company": "Bank of America",
          "activeRequisitions": 189,
          "averageTimeToFill": 38,
          "competitionLevel": "high"
        },
        {
          "company": "Wells Fargo",
          "activeRequisitions": 156,
          "averageTimeToFill": 42,
          "competitionLevel": "medium"
        }
      ],
      "industryBenchmarks": {
        "averageTimeToFill": 41,
        "averageCostPerHire": 9800,
        "offerAcceptanceRate": 0.73
      }
    },
      "hiringMetrics": {
      "expectedTimeToFill": 38,
      "estimatedCostPerHire": 9200,
      "probabilityOfFill": 0.78,
      "recommendedSalaryRange": {
        "min": 65000,
        "max": 85000,
        "competitive": 75000
      }
    },
      "recommendations": [
      {
        "type": "sourcing_strategy",
        "priority": "high",
        "description": "Focus on remote candidates to access larger talent pool",
        "impact": "supply_increase"
      },
      {
        "type": "skill_requirements",
        "priority": "medium",
        "description": "Consider candidates with transferable skills for Digital Banking",
        "impact": "qualification_flexibility"
      },
      {
        "type": "compensation_adjustment",
        "priority": "medium",
        "description": "Offer competitive salary in 70-80k range to attract quality candidates",
        "impact": "candidate_attraction"
      }
      ]
    }
  }
}

InternalGET/v1/ja/roles/{roleId}/trends

Role trend analysis

Analyze historical and projected trends for a specific role

Path Parameters

Name
roleId
Type
string
Description
Unique identifier for the role

Query Parameters

Name
analysis
Type
string
Description
Specific analysis section to retrieve. Available options:
- timeframeAnalysis - Timeframe-based trend analysis
- demandTrends - Demand trend analysis
- salaryTrends - Salary trend analysis
- skillTrends - Skill trend analysis
- industryDrivers - Industry driver analysis
- forecasting - Forecasting projections
- recommendations - Trend recommendations If not specified, returns all analysis sections

Response

Name
success
Type
boolean
Description
Indicates if the request was successful
Name
data
Type
object
Description
Comprehensive trend analysis containing:
- roleId (string): The role identifier
- analysisDate (string): When the analysis was generated
- overallTrend (string): Overall trend direction
- trendScore (number): Numerical trend score
- analysis (object): Analysis sections (Alpha feature) containing:
  - timeframeAnalysis (object): Timeframe-based trend analysis
  - demandTrends (object): Demand trend analysis
  - salaryTrends (object): Salary trend analysis
  - skillTrends (object): Skill trend analysis
  - industryDrivers (array): Industry driver analysis
  - forecasting (object): Forecasting projections
  - recommendations (array): Actionable trend recommendations

Request

GET

/v1/ja/roles/{roleId}/trends

curl https://frontier.beamery.com/v1/ja/roles/{roleId}/trends \
  -H "Authorization: Bearer your_access_token"

Response

{
  "success": true,
  "data": {
    "roleId": "a1b2c3d4-e5f6-7890-abcd-123456789012",
    "analysisDate": "2024-01-15T10:30:00Z",
    "overallTrend": "growing",
    "trendScore": 7.6,
    "analysis": {
      "timeframeAnalysis": {
        "shortTerm": {
          "period": "Last 3 months",
          "trendDirection": "increasing",
          "changeRate": 12.3,
          "confidence": "high"
        },
        "mediumTerm": {
          "period": "Last 12 months",
          "trendDirection": "stable",
          "changeRate": 5.8,
          "confidence": "high"
        },
        "longTerm": {
          "period": "Last 3 years",
          "trendDirection": "growing",
          "changeRate": 18.7,
          "confidence": "moderate"
        }
      },
      "demandTrends": {
      "historicalDemand": [
        {
          "period": "Q1 2023",
          "demand": 1850,
          "growth": 8.2
        },
        {
          "period": "Q2 2023",
          "demand": 1923,
          "growth": 3.9
        },
        {
          "period": "Q3 2023",
          "demand": 2156,
          "growth": 12.1
        },
        {
          "period": "Q4 2023",
          "demand": 2387,
          "growth": 10.7
        }
      ],
      "projectedDemand": [
        {
          "period": "Q1 2024",
          "demand": 2584,
          "growth": 8.3,
          "confidence": "high"
        },
        {
          "period": "Q2 2024",
          "demand": 2798,
          "growth": 8.3,
          "confidence": "moderate"
        },
        {
          "period": "Q3 2024",
          "demand": 3021,
          "growth": 8.0,
          "confidence": "moderate"
        }
      ]
    },
      "salaryTrends": {
      "historicalSalary": [
        {
          "period": "2021",
          "medianSalary": 68000,
          "growth": 3.2
        },
        {
          "period": "2022",
          "medianSalary": 71000,
          "growth": 4.4
        },
        {
          "period": "2023",
          "medianSalary": 75000,
          "growth": 5.6
        }
      ],
      "projectedSalary": [
        {
          "period": "2024",
          "medianSalary": 78000,
          "growth": 4.0,
          "confidence": "high"
        },
        {
          "period": "2025",
          "medianSalary": 81000,
          "growth": 3.8,
          "confidence": "moderate"
        }
      ]
    },
      "skillTrends": {
      "emergingSkills": [
        {
          "skill": "Digital Banking",
          "growth": 45.2,
          "importance": "critical",
          "timeToMaturity": "6-12 months"
        },
        {
          "skill": "AI Customer Insights",
          "growth": 38.7,
          "importance": "high",
          "timeToMaturity": "12-18 months"
        },
        {
          "skill": "Cryptocurrency Advisory",
          "growth": 29.4,
          "importance": "medium",
          "timeToMaturity": "18-24 months"
        }
      ],
      "decliningSkills": [
        {
          "skill": "Manual Transaction Processing",
          "decline": -23.1,
          "replacement": "Automated Systems"
        },
        {
          "skill": "Paper-based Documentation",
          "decline": -15.8,
          "replacement": "Digital Documentation"
        }
      ]
    },
      "industryDrivers": [
      {
        "driver": "Digital Transformation",
        "impact": "high",
        "timeframe": "ongoing",
        "description": "Banks accelerating digital transformation initiatives"
      },
      {
        "driver": "Regulatory Changes",
        "impact": "medium",
        "timeframe": "12-18 months",
        "description": "New compliance requirements coming into effect"
      },
      {
        "driver": "Customer Expectations",
        "impact": "high",
        "timeframe": "ongoing",
        "description": "Increasing demand for personalized digital experiences"
      }
    ],
      "forecasting": {
      "nextQuarter": {
        "demandProjection": 2584,
        "confidenceLevel": "high",
        "keyFactors": [
          "Seasonal banking patterns",
          "Digital initiative rollouts"
        ]
      },
      "nextYear": {
        "demandProjection": 11200,
        "confidenceLevel": "moderate",
        "keyFactors": [
          "Economic recovery patterns",
          "Technology adoption rates",
          "Regulatory compliance deadlines"
        ]
      }
    },
    "recommendations": [
      {
        "type": "skill_investment",
        "priority": "high",
        "description": "Invest heavily in Digital Banking training programs",
        "impact": "future_readiness"
      },
      {
        "type": "workforce_planning",
        "priority": "medium",
        "description": "Plan for 8-10% workforce expansion over next 12 months",
        "impact": "capacity_planning"
      },
      {
        "type": "compensation_strategy",
        "priority": "medium",
        "description": "Adjust salary bands to reflect 4-5% annual growth",
        "impact": "talent_retention"
      }
      ]
    }
  }
}

InternalGET/v1/ja/roles/requisitions

Role requisitions analysis

Analyze hiring requisitions and workforce planning needs for roles

Path Parameters

Query Parameters

Name
period
Type
string
Description
Analysis period (current, quarterly, yearly)
Name
roleId
Type
string
Description
Filter by specific role
Name
departmentId
Type
string
Description
Filter by department
Name
analysis
Type
string
Description
Specific analysis section to retrieve. Available options:
- roleBreakdown - Role-specific breakdown
- departmentBreakdown - Department-specific breakdown
- hiringTrends - Hiring trend analysis
- challengesAndBottlenecks - Challenges and bottlenecks analysis
- forecastAndPlanning - Forecast and planning analysis
- recommendations - Requisitions recommendations If not specified, returns all analysis sections

Response

Name
success
Type
boolean
Description
Indicates if the request was successful
Name
data
Type
object
Description
Comprehensive requisitions analysis containing:
- analysisDate (string): When the analysis was generated
- analysisPeriod (string): Analysis period
- totalRequisitions (number): Total requisitions count
- activeRequisitions (number): Active requisitions count
- completedRequisitions (number): Completed requisitions count
- summary (object): Summary statistics
- analysis (object): Analysis sections (Alpha feature) containing:
  - roleBreakdown (array): Role-specific breakdown
  - departmentBreakdown (array): Department-specific breakdown
  - hiringTrends (object): Hiring trend analysis
  - challengesAndBottlenecks (array): Challenges and bottlenecks analysis
  - forecastAndPlanning (object): Forecast and planning analysis
  - recommendations (array): Actionable requisitions recommendations

Request

GET

/v1/ja/roles/requisitions

curl https://frontier.beamery.com/v1/ja/roles/requisitions \
  -H "Authorization: Bearer your_access_token"

Response

{
  "success": true,
  "data": {
    "analysisDate": "2024-01-15T10:30:00Z",
    "analysisPeriod": "quarterly",
    "totalRequisitions": 847,
    "activeRequisitions": 234,
    "completedRequisitions": 613,
    "summary": {
      "averageTimeToFill": 42,
      "averageCostPerHire": 8950,
      "fillRate": 0.72,
      "offerAcceptanceRate": 0.78,
      "totalHiringCost": 5486750
    },
    "analysis": {
      "roleBreakdown": [
      {
        "roleId": "a1b2c3d4-e5f6-7890-abcd-123456789012",
        "roleTitle": "Personal Banking Advisor",
        "totalRequisitions": 45,
        "activeRequisitions": 12,
        "completedRequisitions": 33,
        "averageTimeToFill": 38,
        "averageCostPerHire": 7800,
        "fillRate": 0.73,
        "priorityLevel": "high",
        "urgency": "medium"
      },
      {
        "roleId": "b2c3d4e5-f6g7-8901-bcde-234567890123",
        "roleTitle": "Senior Data Analyst",
        "totalRequisitions": 18,
        "activeRequisitions": 8,
        "completedRequisitions": 10,
        "averageTimeToFill": 52,
        "averageCostPerHire": 12500,
        "fillRate": 0.56,
        "priorityLevel": "critical",
        "urgency": "high"
      },
      {
        "roleId": "c3d4e5f6-g7h8-9012-cdef-345678901234",
        "roleTitle": "Software Engineer",
        "totalRequisitions": 67,
        "activeRequisitions": 23,
        "completedRequisitions": 44,
        "averageTimeToFill": 47,
        "averageCostPerHire": 11200,
        "fillRate": 0.66,
        "priorityLevel": "high",
        "urgency": "medium"
      }
    ],
      "departmentBreakdown": [
      {
        "departmentId": "d1e2f3g4-h5i6-7890-jklm-123456789012",
        "departmentName": "Retail Banking Operations",
        "totalRequisitions": 156,
        "activeRequisitions": 42,
        "completedRequisitions": 114,
        "averageTimeToFill": 39,
        "averageCostPerHire": 8200,
        "fillRate": 0.73,
        "headcountGrowth": 12.3
      },
      {
        "departmentId": "d2f3g4h5-i6j7-8901-klmn-234567890123",
        "departmentName": "Data Analytics",
        "totalRequisitions": 89,
        "activeRequisitions": 34,
        "completedRequisitions": 55,
        "averageTimeToFill": 51,
        "averageCostPerHire": 13800,
        "fillRate": 0.62,
        "headcountGrowth": 28.7
      },
      {
        "departmentId": "d3g4h5i6-j7k8-9012-lmno-345678901234",
        "departmentName": "Engineering",
        "totalRequisitions": 234,
        "activeRequisitions": 67,
        "completedRequisitions": 167,
        "averageTimeToFill": 48,
        "averageCostPerHire": 12100,
        "fillRate": 0.71,
        "headcountGrowth": 15.9
      }
    ],
      "hiringTrends": {
      "quarterlyComparison": {
        "currentQuarter": {
          "period": "Q4 2023",
          "requisitions": 234,
          "completed": 167,
          "fillRate": 0.71
        },
        "previousQuarter": {
          "period": "Q3 2023",
          "requisitions": 198,
          "completed": 142,
          "fillRate": 0.72
        },
        "growthRate": 18.2
      },
      "yearlyComparison": {
        "currentYear": {
          "period": "2023",
          "requisitions": 847,
          "completed": 613,
          "fillRate": 0.72
        },
        "previousYear": {
          "period": "2022",
          "requisitions": 723,
          "completed": 528,
          "fillRate": 0.73
        },
        "growthRate": 17.1
      }
    },
      "challengesAndBottlenecks": [
      {
        "issue": "Specialized skill shortage",
        "affectedRoles": ["Senior Data Analyst", "ML Engineer"],
        "impact": "high",
        "averageDelayDays": 15,
        "mitigation": "Partner with specialized recruitment agencies"
      },
      {
        "issue": "Competitive market conditions",
        "affectedRoles": ["Software Engineer", "Product Manager"],
        "impact": "medium",
        "averageDelayDays": 8,
        "mitigation": "Increase compensation packages and benefits"
      },
      {
        "issue": "Location constraints",
        "affectedRoles": ["Personal Banking Advisor"],
        "impact": "low",
        "averageDelayDays": 3,
        "mitigation": "Expand remote work options"
      }
    ],
      "forecastAndPlanning": {
      "nextQuarter": {
        "projectedRequisitions": 278,
        "projectedCost": 2487000,
        "recommendedBudget": 2750000,
        "riskFactors": [
          "Seasonal hiring patterns",
          "Economic uncertainty"
        ]
      },
      "nextYear": {
        "projectedRequisitions": 1024,
        "projectedCost": 9152000,
        "recommendedBudget": 10000000,
        "riskFactors": [
          "Talent market competition",
          "Technology skill gaps",
          "Regulatory changes"
        ]
      }
    },
    "recommendations": [
      {
        "type": "process_optimization",
        "priority": "high",
        "description": "Implement automated screening tools to reduce time-to-fill by 20%",
        "impact": "efficiency_improvement",
        "estimatedSavings": 185000
      },
      {
        "type": "talent_pipeline",
        "priority": "high",
        "description": "Build talent pipeline for critical roles to reduce lead time",
        "impact": "supply_readiness",
        "estimatedSavings": 245000
      },
      {
        "type": "budget_reallocation",
        "priority": "medium",
        "description": "Reallocate 15% of budget to high-priority technical roles",
        "impact": "strategic_alignment",
        "estimatedSavings": 0
      },
      {
        "type": "partnership_expansion",
        "priority": "medium",
        "description": "Establish partnerships with technical bootcamps and universities",
        "impact": "candidate_sourcing",
        "estimatedSavings": 95000
      }
      ]
    }
  }
}