BeameryBeamery

Vacancies

Vacancies represent job openings within your organization. Beamery's vacancy management system allows you to create, track, and match talent to open positions using AI-powered capabilities.

The vacancy model

The vacancy model in Beamery stores comprehensive information about job openings as MongoDB documents, including requirements, team structure, workflow stages, and candidate targeting.

Core Properties

  • Name
    id
    Type
    string
    Description

    Unique identifier for the vacancy.

  • Name
    companyId
    Type
    string
    Description

    Company identifier for multi-tenant architecture.

  • Name
    title
    Type
    string
    Description

    Job title for the position.

  • Name
    departmentId
    Type
    string
    Description

    Department identifier the role belongs to.

  • Name
    teamId
    Type
    string
    Description

    Team identifier this vacancy belongs to.

  • Name
    location
    Type
    object
    Description

    Job location object, containing:

    • id (string): Unique identifier for the location entry
    • address (string): Full address string (e.g., "London, UK")
    • city (string): City name
    • country (string): Full country name
    • countryCode (string): Two-letter ISO 3166-1 alpha-2 country code (e.g., "GB", "US")
    • geometry (object): GeoJSON geometry object with coordinates
      • type (string): Always "Point" for vacancy locations
      • coordinates (array): Array of [longitude, latitude] coordinates
  • Name
    remote
    Type
    boolean
    Description

    Boolean indicating if remote work is allowed

  • Name
    description
    Type
    string
    Description

    Full job description with HTML content.

  • Name
    salary
    Type
    string
    Description

    Salary information as a string.

  • Name
    type
    Type
    string
    Description

    Employment type (full_time, part_time, contract, etc.).

  • Name
    priority
    Type
    string
    Description

    Priority level (High, Medium, Low).

  • Name
    published
    Type
    boolean
    Description

    Whether the vacancy is published.

  • Name
    jobUrl
    Type
    string
    Description

    External job posting URL.

  • Name
    createdAt
    Type
    timestamp
    Description

    When the vacancy was created.

  • Name
    updatedAt
    Type
    timestamp
    Description

    Last update timestamp.

  • Name
    createdBy
    Type
    string
    Description

    User ID who created the vacancy.

  • Name
    updatedBy
    Type
    string
    Description

    User ID who last updated the vacancy.

Workflow and Management

  • Name
    status
    Type
    string
    Description

    Current vacancy status (open, closed, on-hold).

  • Name
    stages
    Type
    array
    Description

    Array of workflow stage objects, where each stage contains:

    • id Unique identifier for the stage
    • value Stage value identifier
    • name Human-readable stage name
    • order Stage order in the workflow
    • locked Whether the stage is locked
    • group Stage group (open, close, etc.)
  • Name
    openAt
    Type
    timestamp
    Description

    When the position was opened.

  • Name
    dueDate
    Type
    string
    Description

    Due date for filling the position.

  • Name
    contactCount
    Type
    integer
    Description

    Number of contacts/applications.

Example Structure

{
  "status": "open",
  "stages": [
    {
      "id": "ZXpYnvF2",
      "value": "Qualified",
      "name": "Qualified",
      "order": 1,
      "locked": false,
      "group": "open"
    },
    {
      "id": "NRoMDnG8H",
      "value": "Company rejected",
      "name": "Company rejected",
      "order": 8,
      "locked": false,
      "group": "close"
    }
  ],
  "openAt": "2020-04-14T15:11:14.047Z",
  "dueDate": "2020-06-01T00:00:00+01:00",
  "contactCount": 0
}

Targeting and Metadata

  • Name
    globalTags
    Type
    array
    Description

    Array of global tag objects, each containing:

    • id Tag identifier
  • Name
    targetCompanies
    Type
    array
    Description

    Array of target company objects, each containing:

    • id Beamery knowledge graph company identifier
    • name Company name
    • domain Company domain

Example Structure

{
  "globalTags": [
    {
      "id": "5b380baa-fd91-4806-9cf4-657b233381a7"
    },
    {
      "id": "78032dcb-12c7-4e87-9d79-ea898f3da3c8"
    }
  ],
  "targetCompanies": [
    {
      "id": "company:beamery",
      "name": "Beamery",
      "domain": "beamery.com"
    }
  ]
}

Requirements and Skills

  • Name
    requirements
    Type
    array
    Description

    Array of requirement objects, each containing:

    • id Requirement identifier
    • name Requirement name
    • required Whether this requirement is mandatory
    • description Detailed requirement description
    • type Requirement type (skill, experience, certification, etc.)
    • level Required proficiency level
    • priority Priority level (high, medium, low)
    • category Requirement category
    • companyId Company identifier
    • createdAt Creation timestamp
    • updatedAt Last update timestamp
  • Name
    skills
    Type
    array
    Description

    Array of skill objects, each containing:

    • id Skill identifier from the company job architecture graph
    • value Skill name or label
    • proficiency Required skill proficiency level (beginner, intermediate, advanced, expert)
    • priority Skill priority (high, medium, low)
    • group Skill group category
    • required Whether this skill is mandatory
  • Name
    qualifications
    Type
    array
    Description

    Array of qualification objects, each containing:

    • id Qualification identifier
    • name Qualification name
    • level Required qualification level
    • required Whether this qualification is mandatory
    • type Qualification type (degree, certification, etc.)
    • field Field of study or specialization

Example Structure

{
  "requirements": [
    {
      "id": "req_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Bachelor's Degree in Computer Science",
      "required": true,
      "description": "4-year degree in computer science or related field",
      "type": "education",
      "level": "bachelor",
      "priority": "high",
      "category": "education",
      "companyId": "c031f2ce5bbe920dfb55",
      "createdAt": "2020-04-14T15:11:14.047Z",
      "updatedAt": "2020-04-14T15:11:14.047Z"
    }
  ],
  "skills": [
    {
      "id": "skill:python",
      "value": "Python",
      "proficiency": "advanced",
      "priority": "high",
      "group": "programming",
      "required": true
    },
    {
      "id": "skill:kubernetes",
      "value": "Kubernetes",
      "proficiency": "intermediate",
      "priority": "medium",
      "group": "devops",
      "required": false
    }
  ],
  "qualifications": [
    {
      "id": "qual_b2c3d4e5-f6g7-8901-bcde-f23456789012",
      "name": "AWS Certified Solutions Architect",
      "level": "professional",
      "required": false,
      "type": "certification",
      "field": "cloud-computing"
    }
  ]
}

Compensation and Benefits

  • Name
    salary
    Type
    string
    Description

    Salary information as a string (e.g., "$120,000 - $160,000").

  • Name
    salaryRange
    Type
    object
    Description

    Structured salary range object, containing:

    • min Minimum salary amount
    • max Maximum salary amount
    • currency Currency code (e.g., "USD", "EUR", "GBP")
    • period Payment period ("annual", "monthly", "hourly")
    • type Salary type ("base", "total", "hourly")
  • Name
    benefits
    Type
    array
    Description

    Array of benefit objects, each containing:

    • id Benefit identifier
    • name Benefit name
    • description Benefit description
    • type Benefit type (health, retirement, vacation, etc.)
    • value Benefit value or amount
    • currency Currency for monetary benefits
  • Name
    workArrangement
    Type
    object
    Description

    Work arrangement details, containing:

    • type Work type ("remote", "hybrid", "onsite")
    • flexibility Flexibility level ("high", "medium", "low")
    • remotePolicy Remote work policy details
    • officeRequirement Office attendance requirements

Example Structure

{
  "salary": "$120,000 - $160,000",
  "salaryRange": {
    "min": 120000,
    "max": 160000,
    "currency": "USD",
    "period": "annual",
    "type": "base"
  },
  "benefits": [
    {
      "id": "ben_c3d4e5f6-g7h8-9012-cdef-g34567890123",
      "name": "Health Insurance",
      "description": "Comprehensive health, dental, and vision coverage",
      "type": "health",
      "value": "100% premium coverage",
      "currency": null
    },
    {
      "id": "ben_d4e5f6g7-h8i9-0123-defg-h45678901234",
      "name": "401(k) Matching",
      "description": "Company matches up to 6% of salary",
      "type": "retirement",
      "value": "6%",
      "currency": "USD"
    }
  ],
  "workArrangement": {
    "type": "hybrid",
    "flexibility": "high",
    "remotePolicy": "3 days remote, 2 days in office",
    "officeRequirement": "2 days per week"
  }
}
GET/v1/vacancies

List vacancies

Retrieve a list of vacancies with optional filtering and pagination.

Query parameters

  • Name
    limit
    Type
    integer
    Description

    Number of vacancies to return (default: 20, max: 100).

  • Name
    offset
    Type
    integer
    Description

    Number of vacancies to skip for pagination.

  • Name
    status
    Type
    string
    Description

    Filter by status (draft, open, on-hold, closed).

  • Name
    department
    Type
    string
    Description

    Filter by department.

  • Name
    location
    Type
    string
    Description

    Filter by location.

  • Name
    skills
    Type
    array
    Description

    Filter by required skills.

Request

GET
/v1/vacancies
curl https://frontier.beamery.com/v1/vacancies \
  -H "Authorization: Bearer your_access_token" \
  -G \
  -d status=open \
  -d limit=10

Response

{
  "data": [
    {
      "id": "65f9a2b8-3c4d-4e5f-9a0b-1c2d3e4f5a6b",
      "companyId": "c031f2ce5bbe920dfb55",
      "hashId": "vac_507f1f77bcf86cd799439011",
      "shortPublicId": "ENG-2024-001",
      "title": "Senior Software Engineer",
      "department": "Engineering",
      "teamId": "team_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "location": "San Francisco, CA",
      "type": "full_time",
      "priority": "High",
      "visibility": "public",
      "published": true,
      "status": "open",
      "salary": "$150,000 - $200,000",
      "openAt": "2024-01-15T00:00:00Z",
      "dueDate": "2024-03-15T00:00:00Z",
      "contactCount": 45,
      "manager": "user_b2c3d4e5-f6g7-8901-bcde-f23456789012",
      "owner": "user_c3d4e5f6-g7h8-9012-cdef-g34567890123",
      "createdAt": "2024-01-10T14:00:00Z",
      "updatedAt": "2024-01-18T10:30:00Z",
      "createdBy": "user_d4e5f6g7-h8i9-0123-defg-h45678901234",
      "updatedBy": "user_e5f6g7h8-i9j0-1234-efgh-i56789012345"
    }
  ],
  "pagination": {
    "total": 23,
    "limit": 10,
    "offset": 0,
    "hasMore": true
  }
}
GET/v1/vacancies/{id}

Get a vacancy

Retrieve detailed information about a specific vacancy.

Path parameters

  • Name
    id
    Type
    string
    Description

    The vacancy's unique identifier.

Request

GET
/v1/vacancies/vac_507f1f77bcf86cd799439011
curl https://frontier.beamery.com/v1/vacancies/vac_507f1f77bcf86cd799439011 \
  -H "Authorization: Bearer your_access_token"

Response

{
  "id": "65f9a2b8-3c4d-4e5f-9a0b-1c2d3e4f5a6b",
  "companyId": "c031f2ce5bbe920dfb55",
  "hashId": "vac_507f1f77bcf86cd799439011",
  "shortPublicId": "ENG-2024-001",
  "title": "Senior Software Engineer",
  "department": "Engineering",
  "teamId": "team_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "location": "San Francisco, CA",
  "description": "<p>We are looking for a Senior Software Engineer to join our growing engineering team...</p>",
  "salary": "$150,000 - $200,000",
  "type": "full_time",
  "priority": "High",
  "visibility": "public",
  "published": true,
  "jobUrl": "https://beamery.com/jobs/senior-software-engineer",
  "status": "open",
  "openAt": "2024-01-15T00:00:00Z",
  "dueDate": "2024-03-15T00:00:00Z",
  "contactCount": 45,
  "manager": "user_b2c3d4e5-f6g7-8901-bcde-f23456789012",
  "owner": "user_c3d4e5f6-g7h8-9012-cdef-g34567890123",
  "stages": [
    {
      "id": "ZXpYnvF2",
      "value": "Qualified",
      "name": "Qualified",
      "order": 1,
      "locked": false,
      "group": "open"
    }
  ],
  "globalTags": [
    {
      "id": "tag_g7h8i9j0-k1l2-3456-ghij-k78901234567"
    }
  ],
  "targetCompanies": [
    {
      "id": "company:beamery",
      "name": "Beamery",
      "domain": "beamery.com"
    }
  ],
  "skills": [
    {
      "id": "skill:python",
      "value": "Python",
      "proficiency": "advanced",
      "priority": "high",
      "group": "programming",
      "required": true
    }
  ],
  "createdAt": "2024-01-10T14:00:00Z",
  "updatedAt": "2024-01-18T10:30:00Z",
  "createdBy": "user_h8i9j0k1-l2m3-4567-hijk-l89012345678",
  "updatedBy": "user_i9j0k1l2-m3n4-5678-ijkl-m90123456789",
}
POST/v1/vacancies

Create a vacancy

Create a new vacancy in the system. The vacancy will be created in draft status by default.

Request body

  • Name
    title
    Type
    string
    Description

    Job title for the position.

  • Name
    department
    Type
    string
    Description

    Department or team.

  • Name
    location
    Type
    object
    Description

    Job location details.

  • Name
    employmentType
    Type
    string
    Description

    Employment type (full-time, part-time, contract).

  • Name
    experienceLevel
    Type
    string
    Description

    Required experience level.

  • Name
    description
    Type
    string
    Description

    Full job description.

  • Name
    requirements
    Type
    array
    Description

    List of job requirements.

  • Name
    skills
    Type
    array
    Description

    Required skills.

  • Name
    salaryRange
    Type
    object
    Description

    Compensation range.

  • Name
    hiringManager
    Type
    string
    Description

    Hiring manager ID.

  • Name
    targetFillDate
    Type
    timestamp
    Description

    Target fill date.

Request

POST
/v1/vacancies
curl https://frontier.beamery.com/v1/vacancies \
  -X POST \
  -H "Authorization: Bearer your_access_token" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Data Engineer",
    "department": "Data Platform",
    "location": {
      "id": "l4d5e6f7-g8h9-0123-ijkl-456789012345",
      "address": "New York, NY, USA",
      "city": "New York",
      "country": "United States",
      "countryCode": "US",
      "geometry": {
        "type": "Point",
        "coordinates": [-74.0060, 40.7128]
      }
    },
    "remote": false,
    "employmentType": "full-time",
    "experienceLevel": "mid",
    "description": "Join our data platform team to build scalable data pipelines...",
    "requirements": [
      "3+ years of data engineering experience",
      "Experience with Apache Spark and Airflow",
      "Strong SQL and Python skills"
    ],
    "skills": ["Python", "Apache Spark", "Airflow", "SQL", "AWS"],
    "salaryRange": {
      "min": 120000,
      "max": 160000,
      "currency": "USD",
      "period": "annual"
    },
    "targetFillDate": "2024-04-01T00:00:00Z"
  }'

Response

{
  "id": "j0k1l2m3-n4o5-6789-jklm-n01234567890",
  "companyId": "c031f2ce5bbe920dfb55",
  "hashId": "vac_507f1f77bcf86cd799439012",
  "shortPublicId": "DATA-2024-001",
  "title": "Data Engineer",
  "department": "Data Platform",
  "teamId": "team_k1l2m3n4-o5p6-7890-klmn-o12345678901",
  "location": "New York, NY",
  "description": "<p>Join our data platform team to build scalable data pipelines...</p>",
  "salary": "$120,000 - $160,000",
  "type": "full_time",
  "priority": "Medium",
  "published": false,
  "status": "draft",
  "dueDate": "2024-04-01T00:00:00Z",
  "contactCount": 0,
  "manager": "user_l2m3n4o5-p6q7-8901-lmno-p23456789012",
  "owner": "user_m3n4o5p6-q7r8-9012-mnop-q34567890123",
  "skills": [
    {
      "id": "skill:python",
      "value": "Python",
      "proficiency": "advanced",
      "priority": "high",
      "group": "programming",
      "required": true
    },
    {
      "id": "skill:apache-spark",
      "value": "Apache Spark",
      "proficiency": "intermediate",
      "priority": "high",
      "group": "data-processing",
      "required": true
    }
  ],
  "createdAt": "2024-01-20T15:30:00Z",
  "updatedAt": "2024-01-20T15:30:00Z",
  "createdBy": "user_n4o5p6q7-r8s9-0123-nopq-r45678901234",
  "updatedBy": "user_o5p6q7r8-s9t0-1234-opqr-s56789012345"
}
PATCH/v1/vacancies/{id}/status

Update vacancy status

Update the status of a vacancy (e.g., from draft to open, or open to closed).

Path parameters

  • Name
    id
    Type
    string
    Description

    The vacancy's unique identifier.

Request body

  • Name
    status
    Type
    string
    Description

    New status (draft, open, on-hold, closed).

  • Name
    reason
    Type
    string
    Description

    Reason for status change (required when closing).

Request

PATCH
/v1/vacancies/vac_507f1f77bcf86cd799439011/status
curl https://frontier.beamery.com/v1/vacancies/vac_507f1f77bcf86cd799439011/status \
  -X PATCH \
  -H "Authorization: Bearer your_access_token" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "open"
  }'

Response

{
  "id": "65f9a2b8-3c4d-4e5f-9a0b-1c2d3e4f5a6b",
  "status": "open",
  "openAt": "2024-01-20T16:00:00Z",
  "updatedAt": "2024-01-20T16:00:00Z",
  "updatedBy": "user_p6q7r8s9-t0u1-2345-pqrs-t67890123456"
}
POST/v1/vacancies/{id}/match

Match candidates to vacancy

Find the best matching candidates for a vacancy using AI-powered matching.

Path parameters

  • Name
    id
    Type
    string
    Description

    The vacancy's unique identifier.

Request body

  • Name
    limit
    Type
    integer
    Description

    Maximum number of matches to return (default: 20).

  • Name
    minScore
    Type
    number
    Description

    Minimum match score (0-1, default: 0.7).

  • Name
    pools
    Type
    array
    Description

    Limit search to specific talent pools.

  • Name
    includeExternal
    Type
    boolean
    Description

    Include external candidates (default: true).

Request

POST
/v1/vacancies/vac_507f1f77bcf86cd799439011/match
curl https://frontier.beamery.com/v1/vacancies/vac_507f1f77bcf86cd799439011/match \
  -X POST \
  -H "Authorization: Bearer your_access_token" \
  -H "Content-Type: application/json" \
  -d '{
    "limit": 10,
    "minScore": 0.8
  }'

Response

{
  "matches": [
    {
      "contactId": "q7r8s9t0-u1v2-3456-qrst-u78901234567",
      "score": 0.92,
      "name": "Sarah Chen",
      "currentRole": "Lead Python Developer",
      "matchReasons": [
        "Strong Python experience",
        "AWS expertise",
        "Kubernetes experience",
        "Leadership skills match"
      ],
      "skills": ["Python", "AWS", "Kubernetes", "PostgreSQL", "Team Leadership"]
    },
    {
      "contactId": "r8s9t0u1-v2w3-4567-rstu-v89012345678",
      "score": 0.87,
      "name": "Michael Rodriguez",
      "currentRole": "Senior Backend Engineer",
      "matchReasons": [
        "Python expertise",
        "Cloud experience",
        "PostgreSQL skills"
      ],
      "skills": ["Python", "AWS", "Docker", "PostgreSQL"]
    }
  ],
  "totalMatches": 2
}