Deal Notes

Deal notes allow you to add context and track important information about your deals. Each note can have an optional title and belongs to a specific deal and user.

The Deal Note Object

Name
id
Type
uuid
Description
Unique identifier for the note.
Name
deal_id
Type
uuid
Description
The deal this note belongs to.
Name
user_id
Type
uuid
Description
ID of the user who created the note.
Name
title
Type
string
Description
Optional note title (max 255 characters).
Name
note
Type
string
Description
Note content/body.
Name
user
Type
object
Description
User object with id, name, and photo_url (when included in response).
Name
created_at
Type
datetime
Description
Timestamp when the note was created.
Name
updated_at
Type
datetime
Description
Timestamp when the note was last updated.

GET/app/deals/{id}/notes

List Deal Notes

Retrieve all notes for a specific deal, ordered by creation date (most recent first). Results are paginated.

Request

GET

/app/deals/{id}/notes

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

Response

{
  "data": [
    {
      "id": "9d5f3d04-3c4d-5e6f-7g8h-9i0j1k2l3m4a",
      "deal_id": "9d5f3d04-1a2b-3c4d-5e6f-7g8h9i0j1k2a",
      "user_id": "9d5f3d04-2c61-4d1a-8a3e-1b2c3d4e5f6a",
      "title": "Initial Call",
      "note": "Had a great conversation with the client. They are interested in our Enterprise plan and want to schedule a demo next week.",
      "user": {
        "id": "9d5f3d04-2c61-4d1a-8a3e-1b2c3d4e5f6a",
        "name": "John Doe",
        "photo_url": "https://example.com/photos/john.jpg"
      },
      "created_at": "2025-10-26T10:00:00.000000Z",
      "updated_at": "2025-10-26T10:00:00.000000Z"
    },
    {
      "id": "9d5f3d04-3c4d-5e6f-7g8h-9i0j1k2l3m4b",
      "deal_id": "9d5f3d04-1a2b-3c4d-5e6f-7g8h9i0j1k2a",
      "user_id": "9d5f3d04-2c61-4d1a-8a3e-1b2c3d4e5f6a",
      "title": "Follow-up Meeting",
      "note": "Client requested custom pricing for their team of 50 users. Sent proposal to CFO.",
      "user": {
        "id": "9d5f3d04-2c61-4d1a-8a3e-1b2c3d4e5f6a",
        "name": "John Doe",
        "photo_url": "https://example.com/photos/john.jpg"
      },
      "created_at": "2025-10-25T14:30:00.000000Z",
      "updated_at": "2025-10-25T14:30:00.000000Z"
    }
  ],
  "links": {
    "first": "https://api.pipeback.com/app/deals/9d5f3d04-1a2b-3c4d-5e6f-7g8h9i0j1k2a/notes?page=1",
    "last": "https://api.pipeback.com/app/deals/9d5f3d04-1a2b-3c4d-5e6f-7g8h9i0j1k2a/notes?page=1",
    "prev": null,
    "next": null
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "path": "https://api.pipeback.com/app/deals/9d5f3d04-1a2b-3c4d-5e6f-7g8h9i0j1k2a/notes",
    "per_page": 15,
    "to": 2,
    "total": 2
  }
}

POST/app/deals/{id}/notes

Create a Deal Note

Create a new note for a specific deal. The note will be associated with the authenticated user.

Required Attributes

Name
note
Type
string
Required
*
Description
Note content/body.

Optional Attributes

Name
title
Type
string
Description
Note title (max 255 characters).

Request

POST

/app/deals/{id}/notes

curl -X POST https://api.pipeback.com/app/deals/9d5f3d04-1a2b-3c4d-5e6f-7g8h9i0j1k2a/notes \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "x-workspace-id: YOUR_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Demo Scheduled",
    "note": "Scheduled product demo for next Tuesday at 2pm EST. Make sure to include the custom integration examples they requested."
  }'

Response

{
  "data": {
    "id": "9d5f3d04-3c4d-5e6f-7g8h-9i0j1k2l3m4c",
    "deal_id": "9d5f3d04-1a2b-3c4d-5e6f-7g8h9i0j1k2a",
    "user_id": "9d5f3d04-2c61-4d1a-8a3e-1b2c3d4e5f6a",
    "title": "Demo Scheduled",
    "note": "Scheduled product demo for next Tuesday at 2pm EST. Make sure to include the custom integration examples they requested.",
    "user": null,
    "created_at": "2025-10-26T16:00:00.000000Z",
    "updated_at": "2025-10-26T16:00:00.000000Z"
  }
}

PUT/app/deals/{id}/notes/{noteId}

Update a Deal Note

Update an existing deal note. Users can only update their own notes.

Required Attributes

Name
note
Type
string
Required
*
Description
Note content/body.

Optional Attributes

Name
title
Type
string
Description
Note title (max 255 characters).

Users can only update notes they created. Attempting to update another user's note will result in a 404 error.

Request

PUT

/app/deals/{id}/notes/{noteId}

curl -X PUT https://api.pipeback.com/app/deals/9d5f3d04-1a2b-3c4d-5e6f-7g8h9i0j1k2a/notes/9d5f3d04-3c4d-5e6f-7g8h-9i0j1k2l3m4c \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "x-workspace-id: YOUR_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Demo Completed",
    "note": "Product demo went well. Client was very impressed with the automation features. Next step: send final proposal by Friday."
  }'

Response

{
  "data": {
    "id": "9d5f3d04-3c4d-5e6f-7g8h-9i0j1k2l3m4c",
    "deal_id": "9d5f3d04-1a2b-3c4d-5e6f-7g8h9i0j1k2a",
    "user_id": "9d5f3d04-2c61-4d1a-8a3e-1b2c3d4e5f6a",
    "title": "Demo Completed",
    "note": "Product demo went well. Client was very impressed with the automation features. Next step: send final proposal by Friday.",
    "user": null,
    "created_at": "2025-10-26T16:00:00.000000Z",
    "updated_at": "2025-10-26T16:30:00.000000Z"
  }
}

DELETE/app/deals/{id}/notes/{noteId}

Delete a Deal Note

Delete a deal note. Users can only delete their own notes. This performs a soft delete, preserving the note data but marking it as deleted.

Users can only delete notes they created. Attempting to delete another user's note will result in a 404 error.

Request

DELETE

/app/deals/{id}/notes/{noteId}

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

Response

{
}

User Permissions

Deal notes have user-level permissions:

Create: Any authenticated user can create notes on deals within their workspace
Read: All workspace users can read all notes on deals they have access to
Update: Users can only update notes they created (enforced by user_id check)
Delete: Users can only delete notes they created (enforced by user_id check)

This ensures that while notes are visible to the team, users maintain ownership of their own notes and cannot modify or delete notes created by other team members.