Pipelines

Pipelines represent sales workflows in your CRM. Each pipeline contains stages that deals move through, from initial contact to closed-won or closed-lost. Pipelines can be sorted and one can be set as the default for new deals.

The Pipeline Object

Name
id
Type
uuid
Description
Unique identifier for the pipeline.
Name
workspace_id
Type
uuid
Description
The workspace this pipeline belongs to.
Name
sort
Type
integer
Description
Sort order for displaying pipelines (starts at 1).
Name
name
Type
string
Description
Pipeline name (max 255 characters).
Name
is_default
Type
boolean
Description
Whether this is the default pipeline for new deals. Only one pipeline per workspace can be default.
Name
stages
Type
array
Description
Array of pipeline stages. See Pipeline Stages endpoint for details.
Name
total_deals
Type
integer
Description
Total number of deals in this pipeline.
Name
total_deals_amount
Type
integer
Description
Sum of all deal amounts in this pipeline (in cents).
Name
total_deals_amount_formatted
Type
string
Description
Formatted total deal amount with currency symbol (e.g., $50,000.00).
Name
created_at
Type
datetime
Description
Timestamp when the pipeline was created.
Name
updated_at
Type
datetime
Description
Timestamp when the pipeline was last updated.

GET/app/pipelines

List Pipelines

Retrieve all pipelines in your workspace, including their stages.

Request

GET

/app/pipelines

curl https://api.pipeback.com/app/pipelines \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "x-workspace-id: YOUR_WORKSPACE_ID"

Response

{
  "data": [
    {
      "id": "9d5f3d04-8h25-0j7g-4g9k-7h8i9j0k1l2a",
      "workspace_id": "9d5f3cf9-fa6f-498b-b5be-bd078b7d5339",
      "sort": 1,
      "name": "Sales Pipeline",
      "is_default": true,
      "stages": [
        {
          "id": "9d5f3d04-9i36-1k8h-5h0l-8i9j0k1l2m3a",
          "pipeline_id": "9d5f3d04-8h25-0j7g-4g9k-7h8i9j0k1l2a",
          "sort": 1,
          "name": "Qualified",
          "created_at": "2025-01-15 10:00:00",
          "updated_at": "2025-01-15 10:00:00"
        },
        {
          "id": "9d5f3d04-9i36-1k8h-5h0l-8i9j0k1l2m3b",
          "pipeline_id": "9d5f3d04-8h25-0j7g-4g9k-7h8i9j0k1l2a",
          "sort": 2,
          "name": "Proposal Sent",
          "created_at": "2025-01-15 10:00:00",
          "updated_at": "2025-01-15 10:00:00"
        }
      ],
      "total_deals": 12,
      "total_deals_amount": 15000000,
      "total_deals_amount_formatted": "$150,000.00",
      "created_at": "2025-01-15 10:00:00",
      "updated_at": "2025-01-15 10:00:00"
    },
    {
      "id": "9d5f3d04-8h25-0j7g-4g9k-7h8i9j0k1l2b",
      "workspace_id": "9d5f3cf9-fa6f-498b-b5be-bd078b7d5339",
      "sort": 2,
      "name": "Partner Pipeline",
      "is_default": false,
      "stages": [
        {
          "id": "9d5f3d04-9i36-1k8h-5h0l-8i9j0k1l2m3c",
          "pipeline_id": "9d5f3d04-8h25-0j7g-4g9k-7h8i9j0k1l2b",
          "sort": 1,
          "name": "Initial Contact",
          "created_at": "2025-01-20 10:00:00",
          "updated_at": "2025-01-20 10:00:00"
        }
      ],
      "total_deals": 5,
      "total_deals_amount": 5000000,
      "total_deals_amount_formatted": "$50,000.00",
      "created_at": "2025-01-20 10:00:00",
      "updated_at": "2025-01-20 10:00:00"
    }
  ]
}

POST/app/pipelines

Create a Pipeline

Create a new pipeline in your workspace. The pipeline will be automatically sorted at the end of the current pipeline list and will not be set as default.

Required Attributes

Name
name
Type
string
Required
*
Description
Pipeline name (max 255 characters).

Request

POST

/app/pipelines

curl -X POST https://api.pipeback.com/app/pipelines \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "x-workspace-id: YOUR_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Enterprise Pipeline"
  }'

Response

{
  "data": {
    "id": "9d5f3d04-8h25-0j7g-4g9k-7h8i9j0k1l2c",
    "workspace_id": "9d5f3cf9-fa6f-498b-b5be-bd078b7d5339",
    "sort": 3,
    "name": "Enterprise Pipeline",
    "is_default": false,
    "stages": [],
    "total_deals": 0,
    "total_deals_amount": 0,
    "total_deals_amount_formatted": "$0.00",
    "created_at": "2025-10-26 16:00:00",
    "updated_at": "2025-10-26 16:00:00"
  }
}

GET/app/pipelines/{id}

Retrieve a Pipeline

Retrieve details about a specific pipeline.

Request

GET

/app/pipelines/{id}

curl https://api.pipeback.com/app/pipelines/9d5f3d04-8h25-0j7g-4g9k-7h8i9j0k1l2a \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "x-workspace-id: YOUR_WORKSPACE_ID"

Response

{
  "data": {
    "id": "9d5f3d04-8h25-0j7g-4g9k-7h8i9j0k1l2a",
    "workspace_id": "9d5f3cf9-fa6f-498b-b5be-bd078b7d5339",
    "sort": 1,
    "name": "Sales Pipeline",
    "is_default": true,
    "stages": [
      {
        "id": "9d5f3d04-9i36-1k8h-5h0l-8i9j0k1l2m3a",
        "pipeline_id": "9d5f3d04-8h25-0j7g-4g9k-7h8i9j0k1l2a",
        "sort": 1,
        "name": "Qualified",
        "created_at": "2025-01-15 10:00:00",
        "updated_at": "2025-01-15 10:00:00"
      },
      {
        "id": "9d5f3d04-9i36-1k8h-5h0l-8i9j0k1l2m3b",
        "pipeline_id": "9d5f3d04-8h25-0j7g-4g9k-7h8i9j0k1l2a",
        "sort": 2,
        "name": "Proposal Sent",
        "created_at": "2025-01-15 10:00:00",
        "updated_at": "2025-01-15 10:00:00"
      }
    ],
    "total_deals": 12,
    "total_deals_amount": 15000000,
    "total_deals_amount_formatted": "$150,000.00",
    "created_at": "2025-01-15 10:00:00",
    "updated_at": "2025-01-15 10:00:00"
  }
}

PUT/app/pipelines/{id}

Update a Pipeline

Update an existing pipeline's information. When setting a pipeline as default, all other pipelines in the workspace will automatically have their is_default flag set to false.

Required Attributes

Name
name
Type
string
Required
*
Description
Pipeline name (max 255 characters).
Name
is_default
Type
boolean
Required
*
Description
Whether this should be the default pipeline for new deals.

When you set is_default to true, the system automatically updates all other pipelines in your workspace to is_default: false. Only one pipeline can be default at a time.

Request

PUT

/app/pipelines/{id}

curl -X PUT https://api.pipeback.com/app/pipelines/9d5f3d04-8h25-0j7g-4g9k-7h8i9j0k1l2a \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "x-workspace-id: YOUR_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Main Sales Pipeline",
    "is_default": true
  }'

Response

{
  "data": {
    "id": "9d5f3d04-8h25-0j7g-4g9k-7h8i9j0k1l2a",
    "workspace_id": "9d5f3cf9-fa6f-498b-b5be-bd078b7d5339",
    "sort": 1,
    "name": "Main Sales Pipeline",
    "is_default": true,
    "stages": [
      {
        "id": "9d5f3d04-9i36-1k8h-5h0l-8i9j0k1l2m3a",
        "pipeline_id": "9d5f3d04-8h25-0j7g-4g9k-7h8i9j0k1l2a",
        "sort": 1,
        "name": "Qualified",
        "created_at": "2025-01-15 10:00:00",
        "updated_at": "2025-01-15 10:00:00"
      }
    ],
    "total_deals": 12,
    "total_deals_amount": 15000000,
    "total_deals_amount_formatted": "$150,000.00",
    "created_at": "2025-01-15 10:00:00",
    "updated_at": "2025-10-26 16:15:00"
  }
}

DELETE/app/pipelines/{id}

Delete a Pipeline

Delete a pipeline from your workspace. This performs a soft delete, preserving the pipeline data but marking it as deleted.

Soft deleted pipelines can still be retrieved through the API if needed, but will not appear in standard pipeline lists. Associated deals will remain in the database.

Request

DELETE

/app/pipelines/{id}

curl -X DELETE https://api.pipeback.com/app/pipelines/9d5f3d04-8h25-0j7g-4g9k-7h8i9j0k1l2a \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "x-workspace-id: YOUR_WORKSPACE_ID"

Response

{
}

Default Pipeline Behavior

Only one pipeline per workspace can be set as the default:

When creating a new pipeline, is_default is automatically set to false
When updating a pipeline to is_default: true, all other pipelines in the workspace are automatically set to is_default: false
The default pipeline is used when creating new deals without specifying a pipeline
If no pipelines are marked as default, the first pipeline (by sort order) is typically used

Deal Metrics

Each pipeline includes aggregated deal metrics:

total_deals: Count of all deals currently in the pipeline
total_deals_amount: Sum of deal amounts in cents (e.g., 15000000 = $150,000.00)
total_deals_amount_formatted: Human-readable formatted amount with currency symbol

These metrics are calculated in real-time when retrieving pipeline data and reflect the current state of deals in the pipeline.