Skip to main content
Pipelines define the hiring workflow with multiple stages that applicants move through. Each organization can have multiple pipelines for different types of positions.

​
Create pipeline

Create a new hiring pipeline with custom stages.

​
Parameters

​
name
string
required
Pipeline name (e.g., “Engineering Hiring”, “Sales Pipeline”)
​
organizationId
string
required
The organization ID this pipeline belongs to
​
stages
string[]
Array of stage names. If not provided, defaults to: [“Screening”, “Phone Interview”, “Technical Test”, “Onsite Interview”, “Offer”]

​
Response

Returns the created pipeline object with all stages.
​
id
string
Unique pipeline identifier
​
name
string
Pipeline name
​
organizationId
string
Parent organization ID
​
stages
array
Array of stage objects
​
createdAt
datetime
Pipeline creation timestamp
​
updatedAt
datetime
Last update timestamp

​
Error handling

Throws “Unauthorized” error if user is not authenticated.

​
List pipelines

Get all pipelines for an organization.

​
Parameters

​
organizationId
string
required
The organization ID

​
Response

Returns an array of pipeline objects, each including their stages ordered by stage order.
​
[]
array
Array of pipeline objects

​
Update pipeline

Update a pipeline’s name and/or stages.

​
Parameters

​
id
string
required
The pipeline ID to update
​
name
string
Updated pipeline name
​
stages
array
Updated stages array. Note: This replaces all existing stages.

​
Response

Returns the updated pipeline object with all stages.

​
Important notes

When updating stages, the current implementation deletes all existing stages and recreates them. This means:
  • Any applicants assigned to deleted stages will have their currentStageId set to null
  • Stage IDs will change
  • Historical stage references in activity logs remain intact but point to deleted stages

​
Delete pipeline

Delete a pipeline if it’s not in use.

​
Parameters

​
id
string
required
The pipeline ID to delete

​
Response

Returns the deleted pipeline object on success.

​
Error handling

Throws an error with message “Cannot delete pipeline that is being used by jobs” if any jobs are currently using this pipeline.

​
Pipeline structure

​
Default pipeline

When creating an organization, a default “General Hiring Pipeline” is automatically created with these stages:
  1. Screening (order: 1)
  2. Interview (order: 2)
  3. Technical Task (order: 3)
  4. Final Interview (order: 4)
  5. Offer (order: 5)

​
Stage ordering

Stages are ordered using a zero-based index in the order field. When displaying or moving applicants through stages:
  • Stages are sorted by order ascending
  • Lower order numbers appear first
  • The first stage (order: 0) is typically where new applicants start

​
Linking to jobs

Jobs can be assigned to a pipeline using the pipelineId field:
  • Set pipelineId when creating or updating a job
  • Set to null to remove pipeline assignment
  • When a job uses a pipeline, applicants for that job move through the pipeline’s stages

​
Common pipeline examples

​
Technical hiring pipeline

{
  "name": "Engineering Hiring",
  "stages": [
    "Application Review",
    "Phone Screen",
    "Technical Assessment",
    "System Design Interview",
    "Team Interview",
    "Offer"
  ]
}

​
Sales hiring pipeline

{
  "name": "Sales Pipeline",
  "stages": [
    "Resume Review",
    "Recruiter Call",
    "Hiring Manager Interview",
    "Role Play",
    "Final Interview",
    "Offer"
  ]
}

​
Internship pipeline

{
  "name": "Internship Pipeline",
  "stages": [
    "Application Review",
    "Video Interview",
    "Offer"
  ]
}

Build docs developers (and LLMs) love

Get started for freeTalk to us