Deals

Deals represent sales opportunities in your CRM pipeline. Each deal tracks amount, stage, status, associated contact/company, owner, and timeline information. Deals can be sorted within stages, archived, and duplicated.

The Deal Object

Name
id
Type
uuid
Description
Unique identifier for the deal.
Name
workspace_id
Type
uuid
Description
The workspace this deal belongs to.
Name
pipeline_id
Type
uuid
Description
Pipeline this deal belongs to.
Name
pipeline_stage_id
Type
uuid
Description
Current stage within the pipeline.
Name
contact_id
Type
uuid
Description
Associated contact ID (nullable).
Name
contact
Type
object
Description
Full contact object (when included in response).
Name
company_id
Type
uuid
Description
Associated company ID (nullable).
Name
company
Type
object
Description
Full company object (when included in response).
Name
owner_id
Type
uuid
Description
Deal owner (user) ID.
Name
owner
Type
object
Description
Owner object with id, name, and photo_url (when included).
Name
currency_id
Type
uuid
Description
Currency ID for the deal amount.
Name
sort
Type
integer
Description
Sort order within the pipeline stage.
Name
name
Type
string
Description
Deal name (max 255 characters).
Name
status
Type
string
Description
Deal status: open, won, or lost.
Name
status_changed_at
Type
datetime
Description
Timestamp when status was last changed.
Name
amount
Type
integer
Description
Deal amount in cents (e.g., 5000000 = $50,000.00).
Name
amount_formatted
Type
string
Description
Formatted amount with currency symbol (e.g., $50,000.00).
Name
expected_close_date
Type
date
Description
Expected close date in YYYY-MM-DD format (nullable).
Name
source_origin
Type
string
Description
Source origin: api or manually.
Name
source_channel_id
Type
uuid
Description
Deal source channel ID (nullable).
Name
source_reference_id
Type
string
Description
External reference ID for tracking source (max 255 characters, nullable).
Name
is_archived
Type
boolean
Description
Whether the deal is archived.
Name
total_tasks
Type
integer
Description
Total number of tasks associated with this deal.
Name
total_notes
Type
integer
Description
Total number of notes associated with this deal.
Name
next_due_task
Type
object
Description
Next incomplete task sorted by due date (nullable).
Name
next_interaction
Type
object
Description
Next scheduled interaction (task) (nullable).
Name
last_interaction
Type
object
Description
Most recent completed interaction (task) (nullable).
Name
created_at
Type
datetime
Description
Timestamp when the deal was created.
Name
updated_at
Type
datetime
Description
Timestamp when the deal was last updated.

GET/app/deals

List Deals

Retrieve all deals in your workspace with optional filtering. Results are paginated.

Query Parameters

Name
pipeline_id
Type
uuid
Description
Filter by pipeline ID.
Name
pipeline_stage_id
Type
uuid
Description
Filter by pipeline stage ID.
Name
status
Type
string
Description
Filter by status: open, won, or lost.
Name
is_archived
Type
boolean
Description
Filter by archived status.
Name
q
Type
string
Description
Search query to filter by deal name (max 255 characters).

Request

GET

/app/deals

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

Response

{
  "data": [
    {
      "id": "9d5f3d04-1a2b-3c4d-5e6f-7g8h9i0j1k2a",
      "workspace_id": "9d5f3cf9-fa6f-498b-b5be-bd078b7d5339",
      "pipeline_id": "9d5f3d04-8h25-0j7g-4g9k-7h8i9j0k1l2a",
      "pipeline_stage_id": "9d5f3d04-9i36-1k8h-5h0l-8i9j0k1l2m3a",
      "contact_id": "9d5f3d04-2c61-4d1a-8a3e-1b2c3d4e5f6a",
      "contact": {
        "id": "9d5f3d04-2c61-4d1a-8a3e-1b2c3d4e5f6a",
        "name": "John Smith"
      },
      "company_id": "9d5f3d04-3c71-5e2b-9b4f-2c3d4e5f6g7a",
      "company": {
        "id": "9d5f3d04-3c71-5e2b-9b4f-2c3d4e5f6g7a",
        "name": "Acme Corp"
      },
      "owner_id": "9d5f3d04-2c61-4d1a-8a3e-1b2c3d4e5f6b",
      "owner": {
        "id": "9d5f3d04-2c61-4d1a-8a3e-1b2c3d4e5f6b",
        "name": "Jane Doe",
        "photo_url": "https://example.com/photos/jane.jpg"
      },
      "currency_id": "9d5f3d04-3c71-5e2b-9b4f-2c3d4e5f6g7d",
      "sort": 1,
      "name": "Enterprise Plan - Acme Corp",
      "status": "open",
      "status_changed_at": "2025-10-20T10:00:00.000000Z",
      "amount": 5000000,
      "amount_formatted": "$50,000.00",
      "expected_close_date": "2025-11-30",
      "source_origin": "manually",
      "source_channel_id": null,
      "source_reference_id": null,
      "is_archived": false,
      "total_tasks": 3,
      "total_notes": 5,
      "next_due_task": null,
      "next_interaction": null,
      "last_interaction": null,
      "created_at": "2025-10-20 10:00:00",
      "updated_at": "2025-10-20 10:00:00"
    }
  ],
  "links": {
    "first": "https://api.pipeback.com/app/deals?page=1",
    "last": "https://api.pipeback.com/app/deals?page=1",
    "prev": null,
    "next": null
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "path": "https://api.pipeback.com/app/deals",
    "per_page": 15,
    "to": 1,
    "total": 1
  }
}

POST/app/deals

Create a Deal

Create a new deal in your workspace. You can optionally create or associate contacts and companies by providing their ID or name.

Required Attributes

Name
pipeline_id
Type
uuid
Required
*
Description
Pipeline ID for this deal.
Name
pipeline_stage_id
Type
uuid
Required
*
Description
Initial pipeline stage ID.
Name
name
Type
string
Required
*
Description
Deal name (max 255 characters).
Name
currency_id
Type
uuid
Required
*
Description
Currency ID for the deal amount.
Name
owner_id
Type
uuid
Required
*
Description
Deal owner (user) ID.

Optional Attributes

Name
contact
Type
object
Description
Contact object with id (to link existing) or name (to create new).
Name
company
Type
object
Description
Company object with id (to link existing) or name (to create new).
Name
amount
Type
number
Description
Deal amount as a number (will be stored in cents).
Name
expected_close_date
Type
date
Description
Expected close date in YYYY-MM-DD format.
Name
products
Type
array
Description
Array of product UUIDs to associate with the deal.
Name
source_origin
Type
string
Description
Source origin: api or manually.
Name
source_channel_id
Type
uuid
Description
Deal source channel ID.
Name
source_reference_id
Type
string
Description
External reference ID (max 255 characters).

Request

POST

/app/deals

curl -X POST https://api.pipeback.com/app/deals \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "x-workspace-id: YOUR_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "pipeline_id": "9d5f3d04-8h25-0j7g-4g9k-7h8i9j0k1l2a",
    "pipeline_stage_id": "9d5f3d04-9i36-1k8h-5h0l-8i9j0k1l2m3a",
    "name": "Professional Plan - Tech Startup",
    "amount": 2500000,
    "currency_id": "9d5f3d04-3c71-5e2b-9b4f-2c3d4e5f6g7d",
    "owner_id": "9d5f3d04-2c61-4d1a-8a3e-1b2c3d4e5f6b",
    "expected_close_date": "2025-12-15",
    "contact": {
      "name": "Sarah Johnson"
    },
    "company": {
      "name": "Tech Startup Inc"
    },
    "source_origin": "api"
  }'

Response

{
  "data": {
    "id": "9d5f3d04-1a2b-3c4d-5e6f-7g8h9i0j1k2b",
    "workspace_id": "9d5f3cf9-fa6f-498b-b5be-bd078b7d5339",
    "pipeline_id": "9d5f3d04-8h25-0j7g-4g9k-7h8i9j0k1l2a",
    "pipeline_stage_id": "9d5f3d04-9i36-1k8h-5h0l-8i9j0k1l2m3a",
    "contact_id": "9d5f3d04-2c61-4d1a-8a3e-1b2c3d4e5f6c",
    "contact": null,
    "company_id": "9d5f3d04-3c71-5e2b-9b4f-2c3d4e5f6g7b",
    "company": null,
    "owner_id": "9d5f3d04-2c61-4d1a-8a3e-1b2c3d4e5f6b",
    "owner": null,
    "currency_id": "9d5f3d04-3c71-5e2b-9b4f-2c3d4e5f6g7d",
    "sort": 1,
    "name": "Professional Plan - Tech Startup",
    "status": "open",
    "status_changed_at": "2025-10-26T16:00:00.000000Z",
    "amount": 2500000,
    "amount_formatted": "$25,000.00",
    "expected_close_date": "2025-12-15",
    "source_origin": "api",
    "source_channel_id": null,
    "source_reference_id": null,
    "is_archived": false,
    "total_tasks": 0,
    "total_notes": 0,
    "next_due_task": null,
    "next_interaction": null,
    "last_interaction": null,
    "created_at": "2025-10-26 16:00:00",
    "updated_at": "2025-10-26 16:00:00"
  }
}

GET/app/deals/{id}

Retrieve a Deal

Retrieve details about a specific deal, including relationships with contact, company, owner, and source channel.

Request

GET

/app/deals/{id}

curl https://api.pipeback.com/app/deals/9d5f3d04-1a2b-3c4d-5e6f-7g8h9i0j1k2a \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "x-workspace-id: YOUR_WORKSPACE_ID"

Response

{
  "data": {
    "id": "9d5f3d04-1a2b-3c4d-5e6f-7g8h9i0j1k2a",
    "workspace_id": "9d5f3cf9-fa6f-498b-b5be-bd078b7d5339",
    "pipeline_id": "9d5f3d04-8h25-0j7g-4g9k-7h8i9j0k1l2a",
    "pipeline_stage_id": "9d5f3d04-9i36-1k8h-5h0l-8i9j0k1l2m3a",
    "contact_id": "9d5f3d04-2c61-4d1a-8a3e-1b2c3d4e5f6a",
    "contact": {
      "id": "9d5f3d04-2c61-4d1a-8a3e-1b2c3d4e5f6a",
      "name": "John Smith",
      "email": "john@example.com"
    },
    "company_id": "9d5f3d04-3c71-5e2b-9b4f-2c3d4e5f6g7a",
    "company": {
      "id": "9d5f3d04-3c71-5e2b-9b4f-2c3d4e5f6g7a",
      "name": "Acme Corp"
    },
    "owner_id": "9d5f3d04-2c61-4d1a-8a3e-1b2c3d4e5f6b",
    "owner": {
      "id": "9d5f3d04-2c61-4d1a-8a3e-1b2c3d4e5f6b",
      "name": "Jane Doe",
      "photo_url": "https://example.com/photos/jane.jpg"
    },
    "currency_id": "9d5f3d04-3c71-5e2b-9b4f-2c3d4e5f6g7d",
    "sort": 1,
    "name": "Enterprise Plan - Acme Corp",
    "status": "open",
    "status_changed_at": "2025-10-20T10:00:00.000000Z",
    "amount": 5000000,
    "amount_formatted": "$50,000.00",
    "expected_close_date": "2025-11-30",
    "source_origin": "manually",
    "source_channel_id": null,
    "source_reference_id": null,
    "is_archived": false,
    "total_tasks": 3,
    "total_notes": 5,
    "next_due_task": null,
    "next_interaction": null,
    "last_interaction": null,
    "created_at": "2025-10-20 10:00:00",
    "updated_at": "2025-10-20 10:00:00"
  }
}

PUT/app/deals/{id}

Update a Deal

Update an existing deal's information. When the status is changed, status_changed_at is automatically updated.

Required Attributes

Name
pipeline_id
Type
uuid
Required
*
Description
Pipeline ID.
Name
pipeline_stage_id
Type
uuid
Required
*
Description
Pipeline stage ID.
Name
name
Type
string
Required
*
Description
Deal name (max 255 characters).
Name
currency_id
Type
uuid
Required
*
Description
Currency ID.
Name
owner_id
Type
uuid
Required
*
Description
Deal owner (user) ID.

Optional Attributes

Name
contact
Type
object
Description
Contact object with id or name.
Name
company
Type
object
Description
Company object with id or name.
Name
amount
Type
number
Description
Deal amount.
Name
expected_close_date
Type
date
Description
Expected close date in YYYY-MM-DD format.
Name
status
Type
string
Description
Deal status: open, won, or lost.
Name
products
Type
array
Description
Array of product UUIDs.
Name
source_origin
Type
string
Description
Source origin: api or manually.
Name
source_channel_id
Type
uuid
Description
Deal source channel ID.
Name
source_reference_id
Type
string
Description
External reference ID (max 255 characters).
Name
is_archived
Type
boolean
Description
Whether the deal is archived.

Request

PUT

/app/deals/{id}

curl -X PUT https://api.pipeback.com/app/deals/9d5f3d04-1a2b-3c4d-5e6f-7g8h9i0j1k2a \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "x-workspace-id: YOUR_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "pipeline_id": "9d5f3d04-8h25-0j7g-4g9k-7h8i9j0k1l2a",
    "pipeline_stage_id": "9d5f3d04-9i36-1k8h-5h0l-8i9j0k1l2m3b",
    "name": "Enterprise Plan - Acme Corp (Updated)",
    "amount": 7500000,
    "currency_id": "9d5f3d04-3c71-5e2b-9b4f-2c3d4e5f6g7d",
    "owner_id": "9d5f3d04-2c61-4d1a-8a3e-1b2c3d4e5f6b",
    "status": "won",
    "expected_close_date": "2025-11-15"
  }'

Response

{
  "data": {
    "id": "9d5f3d04-1a2b-3c4d-5e6f-7g8h9i0j1k2a",
    "workspace_id": "9d5f3cf9-fa6f-498b-b5be-bd078b7d5339",
    "pipeline_id": "9d5f3d04-8h25-0j7g-4g9k-7h8i9j0k1l2a",
    "pipeline_stage_id": "9d5f3d04-9i36-1k8h-5h0l-8i9j0k1l2m3b",
    "contact_id": "9d5f3d04-2c61-4d1a-8a3e-1b2c3d4e5f6a",
    "contact": null,
    "company_id": "9d5f3d04-3c71-5e2b-9b4f-2c3d4e5f6g7a",
    "company": null,
    "owner_id": "9d5f3d04-2c61-4d1a-8a3e-1b2c3d4e5f6b",
    "owner": null,
    "currency_id": "9d5f3d04-3c71-5e2b-9b4f-2c3d4e5f6g7d",
    "sort": 1,
    "name": "Enterprise Plan - Acme Corp (Updated)",
    "status": "won",
    "status_changed_at": "2025-10-26T16:30:00.000000Z",
    "amount": 7500000,
    "amount_formatted": "$75,000.00",
    "expected_close_date": "2025-11-15",
    "source_origin": "manually",
    "source_channel_id": null,
    "source_reference_id": null,
    "is_archived": false,
    "total_tasks": 3,
    "total_notes": 5,
    "next_due_task": null,
    "next_interaction": null,
    "last_interaction": null,
    "created_at": "2025-10-20 10:00:00",
    "updated_at": "2025-10-26 16:30:00"
  }
}

DELETE/app/deals/{id}

Delete a Deal

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

Soft deleted deals can still be retrieved through the API if needed, but will not appear in standard deal lists. Associated notes, tasks, and relationships are preserved.

Request

DELETE

/app/deals/{id}

curl -X DELETE https://api.pipeback.com/app/deals/9d5f3d04-1a2b-3c4d-5e6f-7g8h9i0j1k2a \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "x-workspace-id: YOUR_WORKSPACE_ID"

Response

{
}

POST/app/deals/{id}/duplicate

Duplicate a Deal

Create a copy of an existing deal. The duplicated deal will have " (Copy)" appended to its name and will copy all tags and products from the original deal.

Request

POST

/app/deals/{id}/duplicate

curl -X POST https://api.pipeback.com/app/deals/9d5f3d04-1a2b-3c4d-5e6f-7g8h9i0j1k2a/duplicate \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "x-workspace-id: YOUR_WORKSPACE_ID"

Response

{
  "data": {
    "id": "9d5f3d04-1a2b-3c4d-5e6f-7g8h9i0j1k2c",
    "workspace_id": "9d5f3cf9-fa6f-498b-b5be-bd078b7d5339",
    "pipeline_id": "9d5f3d04-8h25-0j7g-4g9k-7h8i9j0k1l2a",
    "pipeline_stage_id": "9d5f3d04-9i36-1k8h-5h0l-8i9j0k1l2m3a",
    "contact_id": "9d5f3d04-2c61-4d1a-8a3e-1b2c3d4e5f6a",
    "contact": null,
    "company_id": "9d5f3d04-3c71-5e2b-9b4f-2c3d4e5f6g7a",
    "company": null,
    "owner_id": "9d5f3d04-2c61-4d1a-8a3e-1b2c3d4e5f6b",
    "owner": null,
    "currency_id": "9d5f3d04-3c71-5e2b-9b4f-2c3d4e5f6g7d",
    "sort": 2,
    "name": "Enterprise Plan - Acme Corp (Copy)",
    "status": "open",
    "status_changed_at": "2025-10-26T16:45:00.000000Z",
    "amount": 5000000,
    "amount_formatted": "$50,000.00",
    "expected_close_date": "2025-11-30",
    "source_origin": "manually",
    "source_channel_id": null,
    "source_reference_id": null,
    "is_archived": false,
    "total_tasks": 0,
    "total_notes": 0,
    "next_due_task": null,
    "next_interaction": null,
    "last_interaction": null,
    "created_at": "2025-10-26 16:45:00",
    "updated_at": "2025-10-26 16:45:00"
  }
}

POST/app/deals/{id}/toggle-archive

Toggle Archive

Toggle the archived status of a deal. If the deal is archived, it will be unarchived, and vice versa.

Request

POST

/app/deals/{id}/toggle-archive

curl -X POST https://api.pipeback.com/app/deals/9d5f3d04-1a2b-3c4d-5e6f-7g8h9i0j1k2a/toggle-archive \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "x-workspace-id: YOUR_WORKSPACE_ID"

Response

{
  "data": {
    "id": "9d5f3d04-1a2b-3c4d-5e6f-7g8h9i0j1k2a",
    "workspace_id": "9d5f3cf9-fa6f-498b-b5be-bd078b7d5339",
    "pipeline_id": "9d5f3d04-8h25-0j7g-4g9k-7h8i9j0k1l2a",
    "pipeline_stage_id": "9d5f3d04-9i36-1k8h-5h0l-8i9j0k1l2m3a",
    "contact_id": "9d5f3d04-2c61-4d1a-8a3e-1b2c3d4e5f6a",
    "contact": null,
    "company_id": "9d5f3d04-3c71-5e2b-9b4f-2c3d4e5f6g7a",
    "company": null,
    "owner_id": "9d5f3d04-2c61-4d1a-8a3e-1b2c3d4e5f6b",
    "owner": null,
    "currency_id": "9d5f3d04-3c71-5e2b-9b4f-2c3d4e5f6g7d",
    "sort": 1,
    "name": "Enterprise Plan - Acme Corp",
    "status": "open",
    "status_changed_at": "2025-10-20T10:00:00.000000Z",
    "amount": 5000000,
    "amount_formatted": "$50,000.00",
    "expected_close_date": "2025-11-30",
    "source_origin": "manually",
    "source_channel_id": null,
    "source_reference_id": null,
    "is_archived": true,
    "total_tasks": 3,
    "total_notes": 5,
    "next_due_task": null,
    "next_interaction": null,
    "last_interaction": null,
    "created_at": "2025-10-20 10:00:00",
    "updated_at": "2025-10-26 17:00:00"
  }
}

Deal Statuses

Deals can have one of three statuses:

Name
open
Description
Deal is active and in progress.
Name
won
Description
Deal was closed successfully.
Name
lost
Description
Deal was lost or abandoned.

When the status changes, the status_changed_at field is automatically updated to track when the deal moved to its current state.

Source Origins

Deals can be created from different sources:

Name
api
Description
Deal was created via API.
Name
manually
Description
Deal was created manually in the platform.

Amount Format

Deal amounts are stored in cents (smallest currency unit):

USD: 5000000 = $50,000.00
EUR: 4500000 = €45,000.00
BRL: 25000000 = R$250,000.00
GBP: 3999000 = £39,990.00

The amount_formatted field provides a human-readable version with the appropriate currency symbol and decimal places based on the deal's currency.

Contact and Company Creation

When creating or updating a deal, you can:

Link existing contact/company: Provide id in the contact/company object
Create new contact/company: Provide name without an id
Leave unassigned: Omit the contact/company object or provide an empty object

If you provide a name without an id, the system will use firstOrCreate to either find an existing record with that name or create a new one.