AI Gateway Overview
The Beamery AI Gateway is a specialized microservice that provides AI and machine learning capabilities for talent intelligence. It complements the core Beamery API by offering advanced features like profile matching, skills inference, and job architecture extraction.
Introduction
While the main Beamery API handles CRUD operations for contacts, vacancies, and campaigns, the AI Gateway serves as the intelligence layer that powers smart talent decisions. Built on the Beamery Knowledge Graph with over 20 billion triples, it provides context-aware AI capabilities across the talent lifecycle.
Key Features
- Profile Matching - AI-powered similarity scoring between candidates and jobs
- Skills Inference - Extract skills from resumes and job descriptions
- Concept Management - Access to Beamery's skills and roles taxonomy
- Job Architecture - Extract structured role information from unstructured data
- Smart Recommendations - Suggest related skills, roles, and career paths
Use Cases
- Find best-matching candidates for open positions
- Identify internal mobility opportunities
- Standardize job titles and skill requirements
- Build skills-based talent strategies
- Support workforce planning initiatives
Core Capabilities
The AI Gateway provides comprehensive AI operations for talent intelligence:
Concept Operations
Work with knowledge graph concepts including skills, roles, industries, and more:
- List concepts - Browse available concepts in any taxonomy
- Lookup concepts - Find concepts by ID or label with fuzzy matching
- Autocomplete - Build smart typeahead interfaces
- Reconcile - Map custom terms to canonical concepts
- Recommend - Get AI-powered related concept suggestions
Profile Intelligence
AI-powered operations on talent profiles:
- Match profiles - Score similarity between candidates and jobs
- Search profiles - Find profiles with relevance ranking
- Extract architecture - Parse unstructured data into structured roles
- Infer skills - Identify skills from text descriptions
Taxonomy Support
Work with both global and customer-specific taxonomies:
Canonical Taxonomy
- Beamery's global taxonomy
- Continuously updated from market data
- Covers 32,000+ skills in multiple languages
- Industry-standard mappings (O*NET, ESCO)
Customer Taxonomy
- Organization-specific concepts
- Custom job architectures
- Internal role definitions
- Proprietary skill frameworks
API Structure
The AI Gateway follows RESTful principles with a consistent structure:
https://ai-gateway.beamery.com/api/v1/{resource}/{operation}
Available Resources
- Name
/concept/{concept_scheme}- Type
- resource
- Description
Operations on knowledge graph concepts
- Name
/profile/{profile_type}- Type
- resource
- Description
AI operations on talent profiles
Concept Schemes
The API supports these concept schemes:
enum ConceptScheme {
role = "role", // Job titles and roles
skill = "skill", // Technical and soft skills
industry = "industry", // Industry classifications
organisation = "organisation", // Companies
organisation_size = "organisation_size", // Company sizes
seniority = "seniority" // Experience levels
}
Profile Types
enum ProfileType {
internal_contact = "internal_contact", // Employees
external_contact = "external_contact", // Candidates
vacancy = "vacancy" // Job postings
}
Authentication
The AI Gateway uses the same authentication as the main Beamery API. You'll need to include your access token in all requests.
The beamery_company_id is required for all requests to ensure data isolation and access customer-specific taxonomies.
Getting Started
To start using the AI Gateway:
1. Set Up Authentication
First, obtain an access token using the main Beamery API authentication flow.
2. Explore Available Concepts
Once authenticated, you can start exploring the available skills and concepts in the taxonomy.
3. Leverage Advanced Features
Once familiar with basic operations, explore:
- Concept management for taxonomy operations
- Profile matching for AI-powered talent matching
- Job architecture extraction for role analysis
Best Practices
Request Handling
- Always include
beamery_company_id - Use pagination for large result sets
- Handle rate limits appropriately
- Cache taxonomy data when possible
Error Handling
- Check for business fault codes
- Implement exponential backoff
- Log correlation IDs for support
- Validate inputs before requests