Pools

Pools are collections of contacts that help you organize and manage talent segments within your Beamery platform. They allow you to group contacts based on various criteria, track their progress through different stages, and manage talent pipelines effectively.

The pool model

The pool model in Beamery stores comprehensive information about talent pools as MongoDB documents, including their configuration, permissions, contact associations, and pipeline stages.

Core Properties

Name
id
Type
string
Description
Unique identifier for the pool.
Name
companyId
Type
string
Description
Company identifier for multi-tenant architecture.
Name
name
Type
string
Description
The logical name of the pool.
Name
description
Type
string
Description
Detailed description of the pool's purpose and criteria.
Name
type
Type
string
Description
Pool type classification (e.g., "talent", "candidate", "employee").
Name
pipeline
Type
string
Description
The type of pipeline associated with this pool (e.g., "frontend", "backend", "qa", "devops").
Name
visibility
Type
string
Description
The visibility level of the pool (private, standard, public).
Name
createdAt
Type
timestamp
Description
When the pool was created.
Name
updatedAt
Type
timestamp
Description
When the pool was last updated.
Name
createdBy
Type
string
Description
User ID who created the pool.
Name
updatedBy
Type
string
Description
User ID who last updated the pool.

Tags and Metadata

Name
globalTags
Type
array
Description
Array of global tag objects, each containing:
- id Tag identifier for consistent tagging across candidates, pools, and vacancies
Name
contactCount
Type
integer
Description
Total number of contacts associated with this pool.
Name
links
Type
object
Description
Pool link configuration object, containing:
- step Current step configuration within the pool
- metadata Additional link metadata

Example Structure

{
  "globalTags": [
    {
      "id": "tag_f6g7h8i9-j0k1-2345-fghi-j67890123456"
    },
    {
      "id": "tag_g7h8i9j0-k1l2-3456-ghij-k78901234567"
    }
  ],
  "contactCount": 247,
  "links": {
    "step": {
      "id": "step_h8i9j0k1-l2m3-4567-hijk-l89012345678",
      "name": "Qualified",
      "order": 1
    },
    "metadata": {
      "lastUpdated": "2024-01-15T10:30:00Z",
      "source": "manual"
    }
  }
}

Pool Steps and Stages

Name
steps
Type
array
Description
Array of pool step objects, each containing:
- id Step identifier
- name Human-readable step name
- order Step order in the pool workflow
- description Step description
- type Step type (screening, interview, assessment, etc.)
- required Whether this step is mandatory
- automated Whether this step is automated
Name
defaultStep
Type
string
Description
ID of the default step for new contacts added to the pool.
Name
configuration
Type
object
Description
Pool configuration settings, containing:
- autoAdvance Whether contacts auto-advance through steps
- notifications Notification settings
- scoring Scoring configuration
- filters Pool filtering criteria

Example Structure

{
  "steps": [
    {
      "id": "step_i9j0k1l2-m3n4-5678-ijkl-m90123456789",
      "name": "Initial Screening",
      "order": 1,
      "description": "Initial candidate screening and qualification",
      "type": "screening",
      "required": true,
      "automated": false
    },
    {
      "id": "step_j0k1l2m3-n4o5-6789-jklm-n01234567890",
      "name": "Technical Interview",
      "order": 2,
      "description": "Technical assessment and coding interview",
      "type": "interview",
      "required": true,
      "automated": false
    }
  ],
  "defaultStep": "step_i9j0k1l2-m3n4-5678-ijkl-m90123456789",
  "configuration": {
    "autoAdvance": false,
    "notifications": {
      "enabled": true,
      "recipients": ["manager", "owner"]
    },
    "scoring": {
      "enabled": true,
      "maxScore": 100
    },
    "filters": {
      "skills": ["skill:python", "skill:react"],
      "locations": ["US", "UK"],
      "experience": "3+"
    }
  }
}

GET/v1/pools

List pools

Retrieve a list of talent pools with optional filtering and pagination.

Query parameters

Name
limit
Type
integer
Description
Number of pools to return (default: 20, max: 100).
Name
offset
Type
integer
Description
Number of pools to skip for pagination.
Name
type
Type
string
Description
Filter by pool type (talent, candidate, employee).
Name
pipeline
Type
string
Description
Filter by pipeline type.
Name
visibility
Type
string
Description
Filter by visibility level (private, standard, public).
Name
owner
Type
string
Description
Filter by owner user ID.
Name
tags
Type
array
Description
Filter by global tag IDs.

Request

GET

/v1/pools

curl https://frontier.beamery.com/v1/pools \
  -H "Authorization: Bearer your_access_token" \
  -G \
  -d type=dynamic \
  -d limit=10

Response

{
  "data": [
    {
      "id": "pool_k1l2m3n4-o5p6-7890-klmn-o12345678901",
      "companyId": "c031f2ce5bbe920dfb55",
      "name": "Frontend Engineering Talent",
      "description": "Senior frontend developers with React and TypeScript expertise",
      "type": "talent",
      "pipeline": "frontend",
      "visibility": "standard",
      "owner": "user_l2m3n4o5-p6q7-8901-lmno-p23456789012",
      "manager": "user_m3n4o5p6-q7r8-9012-mnop-q34567890123",
      "contactCount": 127,
      "globalTags": [
        {
          "id": "tag_n4o5p6q7-r8s9-0123-nopq-r45678901234"
        }
      ],
      "createdAt": "2024-01-10T14:00:00Z",
      "updatedAt": "2024-01-18T10:30:00Z",
      "createdBy": "user_o5p6q7r8-s9t0-1234-opqr-s56789012345",
      "updatedBy": "user_p6q7r8s9-t0u1-2345-pqrs-t67890123456"
    }
  ],
  "pagination": {
    "total": 45,
    "limit": 10,
    "offset": 0,
    "hasMore": true
  }
}

GET/v1/pools/{id}

Get a pool

Retrieve detailed information about a specific talent pool.

Path parameters

Name
id
Type
string
Description
The pool's unique identifier.

Request

GET

/v1/pools/pool_507f1f77bcf86cd799439011

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

Response

{
  "id": "pool_k1l2m3n4-o5p6-7890-klmn-o12345678901",
  "companyId": "c031f2ce5bbe920dfb55",
  "name": "Frontend Engineering Talent",
  "description": "Senior frontend developers with React and TypeScript expertise for our engineering team",
  "type": "talent",
  "pipeline": "frontend",
  "visibility": "standard",
  "owner": "user_l2m3n4o5-p6q7-8901-lmno-p23456789012",
  "manager": "user_m3n4o5p6-q7r8-9012-mnop-q34567890123",
  "sharedUsers": [
    {
      "id": "user_q7r8s9t0-u1v2-3456-qrst-u78901234567"
    }
  ],
  "sharedTeams": [
    {
      "id": "team_r8s9t0u1-v2w3-4567-rstu-v89012345678"
    }
  ],
  "globalTags": [
    {
      "id": "tag_s9t0u1v2-w3x4-5678-stuv-w90123456789"
    }
  ],
  "contactCount": 127,
  "steps": [
    {
      "id": "step_t0u1v2w3-x4y5-6789-tuvw-x01234567890",
      "name": "Initial Screening",
      "order": 1,
      "description": "Initial candidate screening and qualification",
      "type": "screening",
      "required": true,
      "automated": false
    },
    {
      "id": "step_u1v2w3x4-y5z6-7890-uvwx-y12345678901",
      "name": "Technical Interview",
      "order": 2,
      "description": "Technical assessment and coding interview",
      "type": "interview",
      "required": true,
      "automated": false
    }
  ],
  "defaultStep": "step_t0u1v2w3-x4y5-6789-tuvw-x01234567890",
  "configuration": {
    "autoAdvance": false,
    "notifications": {
      "enabled": true,
      "recipients": ["manager", "owner"]
    },
    "scoring": {
      "enabled": true,
      "maxScore": 100
    },
    "filters": {
      "skills": ["skill:react", "skill:typescript"],
      "locations": ["US", "UK"],
      "experience": "3+"
    }
  },
  "links": {
    "step": {
      "id": "step_t0u1v2w3-x4y5-6789-tuvw-x01234567890",
      "name": "Initial Screening",
      "order": 1
    },
    "metadata": {
      "lastUpdated": "2024-01-15T10:30:00Z",
      "source": "manual"
    }
  },
  "createdAt": "2024-01-10T14:00:00Z",
  "updatedAt": "2024-01-18T10:30:00Z",
  "createdBy": "user_v2w3x4y5-z6a7-8901-vwxy-z23456789012",
  "updatedBy": "user_w3x4y5z6-a7b8-9012-wxyz-a34567890123"
}

POST/v1/pools

Create a pool

Create a new talent pool. For dynamic pools, contacts matching the criteria will be automatically added.

Request body

Name
name
Type
string
Description
Name of the talent pool.
Name
description
Type
string
Description
Description of the pool's purpose.
Name
type
Type
string
Description
Pool type (static or dynamic).
Name
criteria
Type
object
Description
Criteria for dynamic pools (required if type is dynamic).
Name
tags
Type
array
Description
Tags for categorization.
Name
collaborators
Type
array
Description
User IDs who can access the pool.
Name
engagementEnabled
Type
boolean
Description
Enable engagement campaigns (default: false).

Request

POST

/v1/pools

curl https://frontier.beamery.com/v1/pools \
  -X POST \
  -H "Authorization: Bearer your_access_token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Data Scientists - Active",
    "description": "Active data science candidates with recent engagement",
    "type": "dynamic",
    "criteria": {
      "skills": ["Python", "Machine Learning", "Data Science"],
      "experienceYears": { "min": 3, "max": 10 },
      "lastActivityDays": 90,
      "locations": ["USA", "Remote"]
    },
    "tags": ["data-science", "active", "q1-2024"],
    "engagementEnabled": true
  }'

Response

{
  "id": "pool_507f1f77bcf86cd799439012",
  "name": "Data Scientists - Active",
  "description": "Active data science candidates with recent engagement",
  "type": "dynamic",
  "criteria": {
    "skills": ["Python", "Machine Learning", "Data Science"],
    "experienceYears": { "min": 3, "max": 10 },
    "lastActivityDays": 90,
    "locations": ["USA", "Remote"]
  },
  "tags": ["data-science", "active", "q1-2024"],
  "owner": "usr_507f191e810c19729de860ea",
  "contactCount": 0,
  "engagementEnabled": true,
  "createdAt": "2024-01-20T16:00:00Z",
  "processingStatus": "building",
  "estimatedContacts": 85
}

POST/v1/pools/{id}/contacts

Add contacts to pool

Manually add contacts to a pool. This works for both static and dynamic pools.

Path parameters

Name
id
Type
string
Description
The pool's unique identifier.

Request body

Name
contactIds
Type
array
Description
Array of contact IDs to add to the pool.

Request

POST

/v1/pools/pool_507f1f77bcf86cd799439011/contacts

curl https://frontier.beamery.com/v1/pools/pool_507f1f77bcf86cd799439011/contacts \
  -X POST \
  -H "Authorization: Bearer your_access_token" \
  -H "Content-Type: application/json" \
  -d '{
    "contactIds": [
      "507f1f77bcf86cd799439013",
      "507f1f77bcf86cd799439014",
      "507f1f77bcf86cd799439015"
    ]
  }'

Response

{
  "message": "Successfully added 3 contacts to pool",
  "poolId": "pool_507f1f77bcf86cd799439011",
  "addedContacts": [
    {
      "contactId": "contact_f2g3h4i5-j6k7-8901-fghi-j23456789012",
      "step": "step_t0u1v2w3-x4y5-6789-tuvw-x01234567890",
      "addedAt": "2024-01-20T17:00:00Z"
    },
    {
      "contactId": "contact_g3h4i5j6-k7l8-9012-ghij-k34567890123",
      "step": "step_t0u1v2w3-x4y5-6789-tuvw-x01234567890",
      "addedAt": "2024-01-20T17:00:00Z"
    },
    {
      "contactId": "contact_h4i5j6k7-l8m9-0123-hijk-l45678901234",
      "step": "step_t0u1v2w3-x4y5-6789-tuvw-x01234567890",
      "addedAt": "2024-01-20T17:00:00Z"
    }
  ],
  "contactCount": 145
}

GET/v1/pools/{id}/contacts

Get pool contacts

Retrieve contacts from a specific pool with pagination.

Path parameters

Name
id
Type
string
Description
The pool's unique identifier.

Query parameters

Name
limit
Type
integer
Description
Number of contacts to return (default: 20, max: 100).
Name
offset
Type
integer
Description
Number of contacts to skip for pagination.
Name
sort
Type
string
Description
Sort field (lastActivity, createdAt, name).
Name
order
Type
string
Description
Sort order (asc or desc).

Request

GET

/v1/pools/pool_507f1f77bcf86cd799439011/contacts

curl https://frontier.beamery.com/v1/pools/pool_507f1f77bcf86cd799439011/contacts \
  -H "Authorization: Bearer your_access_token" \
  -G \
  -d limit=20 \
  -d sort=lastActivity \
  -d order=desc

Response

{
  "data": [
    {
      "id": "contact_i5j6k7l8-m9n0-1234-ijkl-m56789012345",
      "email": "sarah.chen@example.com",
      "firstName": "Sarah",
      "lastName": "Chen",
      "currentRole": "Lead Python Developer",
      "skills": ["Python", "Django", "AWS", "PostgreSQL", "Team Leadership"],
      "lastActivity": "2024-01-19T14:30:00Z",
      "addedToPool": "2023-11-20T10:00:00Z",
      "currentStep": {
        "id": "step_t0u1v2w3-x4y5-6789-tuvw-x01234567890",
        "name": "Initial Screening",
        "order": 1
      }
    }
  ],
  "pagination": {
    "total": 142,
    "limit": 20,
    "offset": 0,
    "hasMore": true
  }
}

PUT/v1/pools/{id}

Update a pool

Update an existing talent pool with new information.

Path parameters

Name
id
Type
string
Description
The pool's unique identifier.

Request body

Name
name
Type
string
Description
Updated pool name.
Name
description
Type
string
Description
Updated pool description.
Name
type
Type
string
Description
Updated pool type.
Name
pipeline
Type
string
Description
Updated pipeline association.
Name
visibility
Type
string
Description
Updated visibility level.
Name
manager
Type
string
Description
Updated manager user ID.
Name
sharedUsers
Type
array
Description
Updated shared user access.
Name
sharedTeams
Type
array
Description
Updated shared team access.
Name
globalTags
Type
array
Description
Updated global tags.
Name
steps
Type
array
Description
Updated pool steps.
Name
configuration
Type
object
Description
Updated pool configuration.

Request

PUT

/v1/pools/pool_k1l2m3n4-o5p6-7890-klmn-o12345678901

curl https://frontier.beamery.com/v1/pools/pool_k1l2m3n4-o5p6-7890-klmn-o12345678901 \
  -X PUT \
  -H "Authorization: Bearer your_access_token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Senior Frontend Engineering Talent",
    "description": "Senior frontend developers with React, TypeScript, and leadership experience",
    "visibility": "public",
    "configuration": {
      "autoAdvance": true,
      "notifications": {
        "enabled": true,
        "recipients": ["manager", "owner", "team"]
      },
      "scoring": {
        "enabled": true,
        "maxScore": 100
      }
    }
  }'

Response

{
  "id": "pool_k1l2m3n4-o5p6-7890-klmn-o12345678901",
  "companyId": "c031f2ce5bbe920dfb55",
  "name": "Senior Frontend Engineering Talent",
  "description": "Senior frontend developers with React, TypeScript, and leadership experience",
  "type": "talent",
  "pipeline": "frontend",
  "visibility": "public",
  "owner": "user_l2m3n4o5-p6q7-8901-lmno-p23456789012",
  "manager": "user_m3n4o5p6-q7r8-9012-mnop-q34567890123",
  "contactCount": 127,
  "configuration": {
    "autoAdvance": true,
    "notifications": {
      "enabled": true,
      "recipients": ["manager", "owner", "team"]
    },
    "scoring": {
      "enabled": true,
      "maxScore": 100
    },
    "filters": {
      "skills": ["skill:react", "skill:typescript"],
      "locations": ["US", "UK"],
      "experience": "3+"
    }
  },
  "updatedAt": "2024-01-20T16:00:00Z",
  "updatedBy": "user_e1f2g3h4-i5j6-7890-efgh-i12345678901"
}

DELETE/v1/pools/{id}

Delete a pool

Delete a talent pool. This will not delete the contacts, only the pool itself.

Path parameters

Name
id
Type
string
Description
The pool's unique identifier.

Deleting a pool will also delete all associated engagement campaigns and analytics data.

Request

DELETE

/v1/pools/pool_507f1f77bcf86cd799439011

curl https://frontier.beamery.com/v1/pools/pool_507f1f77bcf86cd799439011 \
  -X DELETE \
  -H "Authorization: Bearer your_access_token"

Response

{
  "message": "Pool 'Frontend Engineering Talent' successfully deleted",
  "id": "pool_507f1f77bcf86cd799439011",
  "deletedAt": "2024-01-20T16:30:00Z"
}