Tasks

Tasks represent activities and to-dos in your CRM. Each task can be assigned to a user, associated with deals/contacts/companies, categorized by type, and tracked with due dates and completion status.

The Task Object

  • Name
    id
    Type
    uuid
    Description

    Unique identifier for the task.

  • Name
    workspace_id
    Type
    uuid
    Description

    The workspace this task belongs to.

  • Name
    user_id
    Type
    uuid
    Description

    ID of the user assigned to this task.

  • Name
    task_type_id
    Type
    uuid
    Description

    Task type/category ID.

  • Name
    deal_id
    Type
    uuid
    Description

    Associated deal ID (nullable).

  • Name
    company_id
    Type
    uuid
    Description

    Associated company ID (nullable).

  • Name
    contact_id
    Type
    uuid
    Description

    Associated contact ID (nullable).

  • Name
    name
    Type
    string
    Description

    Task name (max 255 characters).

  • Name
    description
    Type
    string
    Description

    Task description (nullable).

  • Name
    due_at
    Type
    datetime
    Description

    Task due date and time.

  • Name
    completed_at
    Type
    datetime
    Description

    Timestamp when the task was completed (nullable).

  • Name
    user
    Type
    object
    Description

    User object with id and name (when included in response).

  • Name
    taskType
    Type
    object
    Description

    Task type object with id, name, and icon (when included in response).

  • Name
    deal
    Type
    object
    Description

    Deal object with id and name (when included in response).

  • Name
    company
    Type
    object
    Description

    Company object with id and name (when included in response).

  • Name
    contact
    Type
    object
    Description

    Contact object with id and name (when included in response).

  • Name
    created_at
    Type
    datetime
    Description

    Timestamp when the task was created.

  • Name
    updated_at
    Type
    datetime
    Description

    Timestamp when the task was last updated.

GET/app/tasks

List Tasks

Retrieve all tasks in your workspace with optional filtering. Results are paginated and ordered by due date (descending).

Query Parameters

  • Name
    deal_id
    Type
    uuid
    Description

    Filter by deal ID.

  • Name
    contact_id
    Type
    uuid
    Description

    Filter by contact ID.

  • Name
    company_id
    Type
    uuid
    Description

    Filter by company ID.

  • Name
    user_id
    Type
    uuid
    Description

    Filter by assigned user ID.

  • Name
    task_type_id
    Type
    uuid
    Description

    Filter by task type ID.

  • Name
    completed_at
    Type
    date
    Description

    Filter by completion date.

  • Name
    due_at_from
    Type
    date
    Description

    Filter tasks due on or after this date.

  • Name
    due_at_to
    Type
    date
    Description

    Filter tasks due on or before this date.

  • Name
    q
    Type
    string
    Description

    Search query to filter by name or description (max 255 characters).

Request

GET
/app/tasks
curl "https://api.pipeback.com/app/tasks?deal_id=9d5f3d04-1a2b-3c4d-5e6f-7g8h9i0j1k2a&completed_at=null" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "x-workspace-id: YOUR_WORKSPACE_ID"

Response

{
  "data": [
    {
      "id": "9d5f3d04-5e6f-7g8h-9i0j-1k2l3m4n5o6a",
      "workspace_id": "9d5f3cf9-fa6f-498b-b5be-bd078b7d5339",
      "user_id": "9d5f3d04-2c61-4d1a-8a3e-1b2c3d4e5f6a",
      "task_type_id": "9d5f3d04-6f7g-8h9i-0j1k-2l3m4n5o6p7a",
      "deal_id": "9d5f3d04-1a2b-3c4d-5e6f-7g8h9i0j1k2a",
      "company_id": "9d5f3d04-3c71-5e2b-9b4f-2c3d4e5f6g7a",
      "contact_id": "9d5f3d04-2c61-4d1a-8a3e-1b2c3d4e5f6b",
      "name": "Follow-up call with Acme Corp",
      "description": "Discuss proposal and answer any questions about pricing",
      "due_at": "2025-10-28T14:00:00.000000Z",
      "completed_at": null,
      "user": {
        "id": "9d5f3d04-2c61-4d1a-8a3e-1b2c3d4e5f6a",
        "name": "John Doe"
      },
      "taskType": {
        "id": "9d5f3d04-6f7g-8h9i-0j1k-2l3m4n5o6p7a",
        "name": "Call",
        "icon": "phone"
      },
      "deal": {
        "id": "9d5f3d04-1a2b-3c4d-5e6f-7g8h9i0j1k2a",
        "name": "Enterprise Plan - Acme Corp"
      },
      "company": {
        "id": "9d5f3d04-3c71-5e2b-9b4f-2c3d4e5f6g7a",
        "name": "Acme Corp"
      },
      "contact": {
        "id": "9d5f3d04-2c61-4d1a-8a3e-1b2c3d4e5f6b",
        "name": "Jane Smith"
      },
      "created_at": "2025-10-26T10:00:00.000000Z",
      "updated_at": "2025-10-26T10:00:00.000000Z",
      "deleted_at": null
    }
  ],
  "links": {
    "first": "https://api.pipeback.com/app/tasks?page=1",
    "last": "https://api.pipeback.com/app/tasks?page=1",
    "prev": null,
    "next": null
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "path": "https://api.pipeback.com/app/tasks",
    "per_page": 15,
    "to": 1,
    "total": 1
  }
}
POST/app/tasks

Create a Task

Create a new task in your workspace.

Required Attributes

  • Name
    task_type_id
    Type
    uuid
    Required
    *
    Description

    Task type/category ID.

  • Name
    user_id
    Type
    uuid
    Required
    *
    Description

    ID of the user to assign this task to.

  • Name
    name
    Type
    string
    Required
    *
    Description

    Task name (max 255 characters).

  • Name
    due_at
    Type
    date
    Required
    *
    Description

    Task due date and time. Must be today or in the future.

Optional Attributes

  • Name
    deal_id
    Type
    uuid
    Description

    Associate task with a deal.

  • Name
    company_id
    Type
    uuid
    Description

    Associate task with a company.

  • Name
    contact_id
    Type
    uuid
    Description

    Associate task with a contact.

  • Name
    description
    Type
    string
    Description

    Task description.

  • Name
    completed_at
    Type
    date
    Description

    Completion timestamp (if creating an already completed task).

Request

POST
/app/tasks
curl -X POST https://api.pipeback.com/app/tasks \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "x-workspace-id: YOUR_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "task_type_id": "9d5f3d04-6f7g-8h9i-0j1k-2l3m4n5o6p7a",
    "user_id": "9d5f3d04-2c61-4d1a-8a3e-1b2c3d4e5f6a",
    "deal_id": "9d5f3d04-1a2b-3c4d-5e6f-7g8h9i0j1k2a",
    "contact_id": "9d5f3d04-2c61-4d1a-8a3e-1b2c3d4e5f6b",
    "name": "Send contract for review",
    "description": "Send the final contract to the legal team for review before sending to client",
    "due_at": "2025-10-30 15:00:00"
  }'

Response

{
  "id": "9d5f3d04-5e6f-7g8h-9i0j-1k2l3m4n5o6b",
  "workspace_id": "9d5f3cf9-fa6f-498b-b5be-bd078b7d5339",
  "user_id": "9d5f3d04-2c61-4d1a-8a3e-1b2c3d4e5f6a",
  "task_type_id": "9d5f3d04-6f7g-8h9i-0j1k-2l3m4n5o6p7a",
  "deal_id": "9d5f3d04-1a2b-3c4d-5e6f-7g8h9i0j1k2a",
  "company_id": null,
  "contact_id": "9d5f3d04-2c61-4d1a-8a3e-1b2c3d4e5f6b",
  "name": "Send contract for review",
  "description": "Send the final contract to the legal team for review before sending to client",
  "due_at": "2025-10-30T15:00:00.000000Z",
  "completed_at": null,
  "user": {
    "id": "9d5f3d04-2c61-4d1a-8a3e-1b2c3d4e5f6a",
    "name": "John Doe"
  },
  "taskType": {
    "id": "9d5f3d04-6f7g-8h9i-0j1k-2l3m4n5o6p7a",
    "name": "Call",
    "icon": "phone"
  },
  "deal": {
    "id": "9d5f3d04-1a2b-3c4d-5e6f-7g8h9i0j1k2a",
    "name": "Enterprise Plan - Acme Corp"
  },
  "company": null,
  "contact": {
    "id": "9d5f3d04-2c61-4d1a-8a3e-1b2c3d4e5f6b",
    "name": "Jane Smith"
  },
  "created_at": "2025-10-26T16:00:00.000000Z",
  "updated_at": "2025-10-26T16:00:00.000000Z",
  "deleted_at": null
}
GET/app/tasks/{id}

Retrieve a Task

Retrieve details about a specific task, including all relationships.

Request

GET
/app/tasks/{id}
curl https://api.pipeback.com/app/tasks/9d5f3d04-5e6f-7g8h-9i0j-1k2l3m4n5o6a \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "x-workspace-id: YOUR_WORKSPACE_ID"

Response

{
  "id": "9d5f3d04-5e6f-7g8h-9i0j-1k2l3m4n5o6a",
  "workspace_id": "9d5f3cf9-fa6f-498b-b5be-bd078b7d5339",
  "user_id": "9d5f3d04-2c61-4d1a-8a3e-1b2c3d4e5f6a",
  "task_type_id": "9d5f3d04-6f7g-8h9i-0j1k-2l3m4n5o6p7a",
  "deal_id": "9d5f3d04-1a2b-3c4d-5e6f-7g8h9i0j1k2a",
  "company_id": "9d5f3d04-3c71-5e2b-9b4f-2c3d4e5f6g7a",
  "contact_id": "9d5f3d04-2c61-4d1a-8a3e-1b2c3d4e5f6b",
  "name": "Follow-up call with Acme Corp",
  "description": "Discuss proposal and answer any questions about pricing",
  "due_at": "2025-10-28T14:00:00.000000Z",
  "completed_at": null,
  "user": {
    "id": "9d5f3d04-2c61-4d1a-8a3e-1b2c3d4e5f6a",
    "name": "John Doe"
  },
  "taskType": {
    "id": "9d5f3d04-6f7g-8h9i-0j1k-2l3m4n5o6p7a",
    "name": "Call",
    "icon": "phone"
  },
  "deal": {
    "id": "9d5f3d04-1a2b-3c4d-5e6f-7g8h9i0j1k2a",
    "name": "Enterprise Plan - Acme Corp"
  },
  "company": {
    "id": "9d5f3d04-3c71-5e2b-9b4f-2c3d4e5f6g7a",
    "name": "Acme Corp"
  },
  "contact": {
    "id": "9d5f3d04-2c61-4d1a-8a3e-1b2c3d4e5f6b",
    "name": "Jane Smith"
  },
  "created_at": "2025-10-26T10:00:00.000000Z",
  "updated_at": "2025-10-26T10:00:00.000000Z",
  "deleted_at": null
}
PUT/app/tasks/{id}

Update a Task

Update an existing task. All fields are optional - only provide the fields you want to update.

Optional Attributes

  • Name
    task_type_id
    Type
    uuid
    Description

    Task type/category ID.

  • Name
    user_id
    Type
    uuid
    Description

    Reassign task to a different user.

  • Name
    deal_id
    Type
    uuid
    Description

    Associate with a different deal (or null to remove).

  • Name
    company_id
    Type
    uuid
    Description

    Associate with a different company (or null to remove).

  • Name
    contact_id
    Type
    uuid
    Description

    Associate with a different contact (or null to remove).

  • Name
    name
    Type
    string
    Description

    Task name (max 255 characters).

  • Name
    description
    Type
    string
    Description

    Task description.

  • Name
    due_at
    Type
    date
    Description

    Task due date and time.

  • Name
    completed_at
    Type
    datetime
    Description

    Completion timestamp (set to mark as complete, null to mark as incomplete).

Request

PUT
/app/tasks/{id}
curl -X PUT https://api.pipeback.com/app/tasks/9d5f3d04-5e6f-7g8h-9i0j-1k2l3m4n5o6a \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "x-workspace-id: YOUR_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "completed_at": "2025-10-26 16:30:00",
    "description": "Call completed. Client confirmed they will review and get back to us by Friday."
  }'

Response

{
  "id": "9d5f3d04-5e6f-7g8h-9i0j-1k2l3m4n5o6a",
  "workspace_id": "9d5f3cf9-fa6f-498b-b5be-bd078b7d5339",
  "user_id": "9d5f3d04-2c61-4d1a-8a3e-1b2c3d4e5f6a",
  "task_type_id": "9d5f3d04-6f7g-8h9i-0j1k-2l3m4n5o6p7a",
  "deal_id": "9d5f3d04-1a2b-3c4d-5e6f-7g8h9i0j1k2a",
  "company_id": "9d5f3d04-3c71-5e2b-9b4f-2c3d4e5f6g7a",
  "contact_id": "9d5f3d04-2c61-4d1a-8a3e-1b2c3d4e5f6b",
  "name": "Follow-up call with Acme Corp",
  "description": "Call completed. Client confirmed they will review and get back to us by Friday.",
  "due_at": "2025-10-28T14:00:00.000000Z",
  "completed_at": "2025-10-26T16:30:00.000000Z",
  "user": {
    "id": "9d5f3d04-2c61-4d1a-8a3e-1b2c3d4e5f6a",
    "name": "John Doe"
  },
  "taskType": {
    "id": "9d5f3d04-6f7g-8h9i-0j1k-2l3m4n5o6p7a",
    "name": "Call",
    "icon": "phone"
  },
  "deal": {
    "id": "9d5f3d04-1a2b-3c4d-5e6f-7g8h9i0j1k2a",
    "name": "Enterprise Plan - Acme Corp"
  },
  "company": {
    "id": "9d5f3d04-3c71-5e2b-9b4f-2c3d4e5f6g7a",
    "name": "Acme Corp"
  },
  "contact": {
    "id": "9d5f3d04-2c61-4d1a-8a3e-1b2c3d4e5f6b",
    "name": "Jane Smith"
  },
  "created_at": "2025-10-26T10:00:00.000000Z",
  "updated_at": "2025-10-26T16:30:00.000000Z",
  "deleted_at": null
}
DELETE/app/tasks/{id}

Delete a Task

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

Request

DELETE
/app/tasks/{id}
curl -X DELETE https://api.pipeback.com/app/tasks/9d5f3d04-5e6f-7g8h-9i0j-1k2l3m4n5o6a \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "x-workspace-id: YOUR_WORKSPACE_ID"

Response

{
}

Task Completion

Tasks can be marked as complete or incomplete by setting the completed_at field:

  • Mark as complete: Set completed_at to a timestamp (typically the current time)
  • Mark as incomplete: Set completed_at to null

The completed_at field is used to track when a task was finished and to filter completed vs pending tasks.

Date Range Filtering

The list endpoint supports filtering by due date range using two parameters:

  • due_at_from: Returns tasks due on or after this date
  • due_at_to: Returns tasks due on or before this date

These can be used together to find tasks within a specific timeframe, or separately to find tasks due after/before a certain date.

Search Functionality

The q parameter searches across both task name and description fields using case-insensitive matching. This allows you to find tasks by keywords in either field.

Something wrong with this page?