Job Pipelines - Taptalent Partner API

The Job Pipelines API allows you to create, update, and retrieve job pipelines for your company. Pipelines define the stages through which candidates progress in your hiring process.

Get All Pipelines

Retrieve all pipelines for your company.

`GET /pipelines`

Authentication

Requires API key authentication via Authorization: Bearer YOUR_API_KEY header.

Example Request

curl -X GET "https://partner-api.taptalent.io/v1/partner/pipelines" \
  -H "Authorization: Bearer sk_live_AbCdEfGhIjKlMnOpQrStUv"

Example Response

{
  "status": "success",
  "data": [
    {
      "id": 123,
      "name": "Engineering Pipeline",
      "createdAt": "2024-01-15T10:00:00.000Z",
      "updatedAt": "2024-01-15T10:00:00.000Z",
      "stages": [
        {
          "id": 789,
          "name": "Sourced",
          "type": "SOURCED",
          "createdAt": "2024-01-15T10:00:00.000Z",
          "updatedAt": "2024-01-15T10:00:00.000Z"
        },
        {
          "id": 790,
          "name": "Applied",
          "type": "APPLIED",
          "createdAt": "2024-01-15T10:00:00.000Z",
          "updatedAt": "2024-01-15T10:00:00.000Z"
        },
        {
          "id": 791,
          "name": "Phone Screen",
          "type": "SCREEN",
          "createdAt": "2024-01-15T10:00:00.000Z",
          "updatedAt": "2024-01-15T10:00:00.000Z"
        }
      ]
    },
    {
      "id": 124,
      "name": "Sales Pipeline",
      "createdAt": "2024-01-16T10:00:00.000Z",
      "updatedAt": "2024-01-16T10:00:00.000Z",
      "stages": [
        {
          "id": 792,
          "name": "Sourced",
          "type": "SOURCED",
          "createdAt": "2024-01-16T10:00:00.000Z",
          "updatedAt": "2024-01-16T10:00:00.000Z"
        }
      ]
    }
  ]
}

Get Pipeline Details

Retrieve a specific pipeline with all its stages.

`GET /pipelines/:pipelineId`

Authentication

Requires API key authentication via Authorization: Bearer YOUR_API_KEY header.

Path Parameters

Parameter	Type	Description
`pipelineId`	integer	The unique identifier of the pipeline

Example Request

curl -X GET "https://partner-api.taptalent.io/v1/partner/pipelines/123" \
  -H "Authorization: Bearer sk_live_AbCdEfGhIjKlMnOpQrStUv"

Example Response

{
  "status": "success",
  "data": {
        "id": 123,
        "name": "Engineering Pipeline",
        "createdAt": "2024-01-15T10:00:00.000Z",
        "updatedAt": "2024-01-15T10:00:00.000Z",
        "stages": [
          {
            "id": 789,
            "name": "Sourced",
            "type": "SOURCED",
            "createdAt": "2024-01-15T10:00:00.000Z",
            "updatedAt": "2024-01-15T10:00:00.000Z"
          },
          {
            "id": 790,
            "name": "Applied",
            "type": "APPLIED",
            "createdAt": "2024-01-15T10:00:00.000Z",
            "updatedAt": "2024-01-15T10:00:00.000Z"
          },
          {
            "id": 791,
            "name": "Phone Screen",
            "type": "SCREEN",
            "createdAt": "2024-01-15T10:00:00.000Z",
            "updatedAt": "2024-01-15T10:00:00.000Z"
          }
        ]
  }
}

Error Responses

Pipeline not found:

{
  "error": {
    "code": "PIPELINE_NOT_FOUND",
    "type": "resource_error",
    "message": "Pipeline not found"
  }
}

Unauthorized access:

{
  "error": {
    "code": "PERMISSION_DENIED",
    "type": "authorization_error",
    "message": "You are not authorized to access this pipeline"
  }
}

Create Pipeline

Create a new job pipeline for your company. A new pipeline will automatically include default stages: SOURCED, APPLIED, ASSESSMENT, SCREEN, SHORTLISTED, and HIRED. See Valid Stage Types for details.

`POST /pipelines`

Authentication

Requires API key authentication via Authorization: Bearer YOUR_API_KEY header.

Request Body

Field	Type	Required	Description
`name`	string	Yes	Pipeline name (must be non-empty after trimming)

Request Body Example

{
  "name": "Engineering Pipeline"
}

Example Request

curl -X POST "https://partner-api.taptalent.io/v1/partner/pipelines" \
  -H "Authorization: Bearer sk_live_AbCdEfGhIjKlMnOpQrStUv" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Engineering Pipeline"
  }'

Example Response

{
  "status": "success",
  "data": {
    "id": 123,
    "name": "Engineering Pipeline"
  }
}

Error Responses

Missing pipeline name:

{
  "error": {
    "code": "INVALID_REQUEST",
    "type": "validation_error",
    "message": "Pipeline name is required"
  }
}

Update Pipeline

Update the name of an existing pipeline.

`PUT /pipelines/:pipelineId`

Authentication

Requires API key authentication via Authorization: Bearer YOUR_API_KEY header.

Path Parameters

Parameter	Type	Description
`pipelineId`	integer	The unique identifier of the pipeline to update

Request Body

Field	Type	Required	Description
`name`	string	Yes	New pipeline name (must be non-empty after trimming)

Request Body Example

{
  "name": "Updated Engineering Pipeline"
}

Example Request

curl -X PUT "https://partner-api.taptalent.io/v1/partner/pipelines/123" \
  -H "Authorization: Bearer sk_live_AbCdEfGhIjKlMnOpQrStUv" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Engineering Pipeline"
  }'

Example Response

{
  "status": "success",
  "data": {
    "id": 123,
    "name": "Updated Engineering Pipeline"
  }
}

Error Responses

Pipeline not found:

{
  "error": {
    "code": "PIPELINE_NOT_FOUND",
    "type": "resource_error",
    "message": "Pipeline not found"
  }
}

Unauthorized access:

{
  "error": {
    "code": "PERMISSION_DENIED",
    "type": "authorization_error",
    "message": "You are not authorized to update this pipeline"
  }
}

Missing pipeline name:

{
  "error": {
    "code": "INVALID_REQUEST",
    "type": "validation_error",
    "message": "Pipeline name is required"
  }
}

Create or Update Pipeline Stage

Create a new stage or update an existing stage in a pipeline. When updating, you can optionally change the stage’s order, which will automatically adjust the order of other stages.

`POST /pipelines/stages`

Authentication

Requires API key authentication via Authorization: Bearer YOUR_API_KEY header.

Request Body

Field	Type	Required	Description
`pipelineId`	integer	Yes	The unique identifier of the pipeline
`name`	string	Yes	Stage name (required for new stages, optional for updates)
`type`	string	Yes	Stage type (required for new stages, optional for updates). Valid types: `ASSESSMENT`, `SCREEN`, `SHORTLISTED`, `OFFER`, `ONBOARDING`
`stageId`	integer	No	Stage ID (if provided, updates existing stage; if omitted, creates new stage)
`order`	integer	No	Desired order position (1-based). If not provided, new stages are placed before HIRED stage. When updating, adjusts other stages’ orders automatically.

Request Body Examples

Create a new stage:

{
  "pipelineId": 123,
  "name": "Technical Interview",
  "type": "SCREEN",
  "order": 3
}

Update an existing stage:

{
  "pipelineId": 123,
  "stageId": 791,
  "name": "Updated Stage Name",
  "type": "ASSESSMENT",
  "order": 2
}

Update only the name of a non-editable stage (SOURCED, APPLIED, HIRED):

{
  "pipelineId": 123,
  "stageId": 789,
  "name": "Updated Sourced Stage Name"
}

Example Request

curl -X POST "https://partner-api.taptalent.io/v1/partner/pipelines/stages" \
  -H "Authorization: Bearer sk_live_AbCdEfGhIjKlMnOpQrStUv" \
  -H "Content-Type: application/json" \
  -d '{
    "pipelineId": 123,
    "name": "Technical Interview",
    "type": "SCREEN",
    "order": 3
  }'

Example Response

Create response (201):

{
  "status": "success",
  "data": {
    "id": 791,
    "name": "Technical Interview",
    "type": "SCREEN",
    "createdAt": "2024-01-15T10:00:00.000Z",
    "updatedAt": "2024-01-15T10:00:00.000Z"
  }
}

Update response (200):

{
  "status": "success",
  "data": {
    "id": 791,
    "name": "Updated Stage Name",
    "type": "ASSESSMENT",
    "createdAt": "2024-01-15T10:00:00.000Z",
    "updatedAt": "2024-01-15T11:00:00.000Z"
  }
}

Error Responses

Invalid stage type:

{
  "error": {
    "code": "INVALID_REQUEST",
    "type": "validation_error",
    "message": "Stage type is not valid"
  }
}

Invalid order range:

{
  "error": {
    "code": "INVALID_REQUEST",
    "type": "validation_error",
    "message": "Order must be between 1 and 5"
  }
}

Invalid stage ID:

{
  "error": {
    "code": "INVALID_REQUEST",
    "type": "validation_error",
    "message": "Stage ID is not valid"
  }
}

Delete Pipeline Stage

Delete a stage from a pipeline. All candidates in the deleted stage will be moved to the specified new stage. The remaining stages will be automatically reordered.

`DELETE /pipelines/stages/:stageId`

Authentication

Requires API key authentication via Authorization: Bearer YOUR_API_KEY header.

Path Parameters

Parameter	Type	Description
`stageId`	integer	The unique identifier of the stage to delete

Request Body

Field	Type	Required	Description
`pipelineId`	integer	Yes	The unique identifier of the pipeline
`newStageId`	integer	Yes	The stage ID where candidates from the deleted stage should be moved

Request Body Example

{
  "pipelineId": 123,
  "newStageId": 790
}

Example Request

curl -X DELETE "https://partner-api.taptalent.io/v1/partner/pipelines/stages/791" \
  -H "Authorization: Bearer sk_live_AbCdEfGhIjKlMnOpQrStUv" \
  -H "Content-Type: application/json" \
  -d '{
    "pipelineId": 123,
    "newStageId": 790
  }'

Example Response

{
  "status": "success",
  "message": "Stage deleted successfully"
}

Error Responses

Cannot delete system stages:

{
  "error": {
    "code": "INVALID_REQUEST",
    "type": "validation_error",
    "message": "Cannot delete SOURCED, APPLIED, or HIRED stages"
  }
}

Invalid stage ID:

{
  "error": {
    "code": "INVALID_REQUEST",
    "type": "validation_error",
    "message": "Stage ID is invalid"
  }
}

Valid Stage Types

When creating or updating pipeline stages, you must use one of the following valid stage types:

Stage Type	Description	Default	Editable	Deletable
`SOURCED`	Candidates who have been sourced but haven’t applied	Yes	No (name only)	No
`APPLIED`	Candidates who have applied to the job	Yes	No (name only)	No
`ASSESSMENT`	Candidates in assessment/interview stage	Yes	Yes	Yes
`SCREEN`	Candidates in screening stage	Yes	Yes	Yes
`SHORTLISTED`	Candidates who have been shortlisted	Yes	Yes	Yes
`OFFER`	Candidates who have received an offer	No	Yes	Yes
`ONBOARDING`	Candidates in onboarding process	No	Yes	Yes
`HIRED`	Candidates who have been hired	Yes	No (name only)	No

Important Notes:

Default Stages: When you create a new pipeline, it automatically includes these default stages: SOURCED, APPLIED, ASSESSMENT, SCREEN, SHORTLISTED, and HIRED.
System Stages (SOURCED, APPLIED, HIRED): These stages cannot be deleted or have their type changed. Only the name can be updated.
Custom Stages (ASSESSMENT, SCREEN, SHORTLISTED, OFFER, ONBOARDING): These stages can be created, updated (including type), and deleted.
Stage Type Validation: When creating a new stage, the type field must be one of the valid types listed above. Invalid types will result in a validation error.

Notes

Pipeline Ownership: All pipelines belong to a company. You can only access and modify pipelines that belong to your company.
Stage Ordering:
- Stages have an order (1-based) that determines their position in the pipeline
- When creating a new stage, you can specify an order to place it at a specific position. If not specified, it will be placed before the HIRED stage
- When updating a stage’s order, other stages will automatically be adjusted to maintain sequential ordering
- The SOURCED stage order is locked and cannot be changed
Stage Deletion:
- When deleting a stage, all candidates in that stage must be moved to another stage (specified by newStageId)
- System stages (SOURCED, APPLIED, HIRED) cannot be deleted
- After deletion, remaining stages are automatically reordered sequentially

​Get All Pipelines

​GET /pipelines

​Authentication

​Example Request

​Example Response

​Get Pipeline Details

​GET /pipelines/:pipelineId

​Authentication

​Path Parameters

​Example Request

​Example Response

​Error Responses

​Create Pipeline

​POST /pipelines

​Authentication

​Request Body

​Request Body Example

​Example Request

​Example Response

​Error Responses

​Update Pipeline

​PUT /pipelines/:pipelineId

​Authentication

​Path Parameters

​Request Body

​Request Body Example

​Example Request

​Example Response

​Error Responses

​Create or Update Pipeline Stage

​POST /pipelines/stages

​Authentication

​Request Body

​Request Body Examples

​Example Request

​Example Response

​Error Responses

​Delete Pipeline Stage

​DELETE /pipelines/stages/:stageId

​Authentication

​Path Parameters

​Request Body

​Request Body Example

​Example Request

​Example Response

​Error Responses

​Valid Stage Types

​Notes

Get All Pipelines

`GET /pipelines`

Authentication

Example Request

Example Response

Get Pipeline Details

`GET /pipelines/:pipelineId`

Authentication

Path Parameters

Example Request

Example Response

Error Responses

Create Pipeline

`POST /pipelines`

Authentication

Request Body

Request Body Example

Example Request

Example Response

Error Responses

Update Pipeline

`PUT /pipelines/:pipelineId`

Authentication

Path Parameters

Request Body

Request Body Example

Example Request

Example Response

Error Responses

Create or Update Pipeline Stage

`POST /pipelines/stages`

Authentication

Request Body

Request Body Examples

Example Request

Example Response

Error Responses

Delete Pipeline Stage

`DELETE /pipelines/stages/:stageId`

Authentication

Path Parameters

Request Body

Request Body Example

Example Request

Example Response

Error Responses

Valid Stage Types

Notes