Workspaces

Workspaces are the top-level organizational units in Pipeback. Each workspace has its own contacts, conversations, deals, settings, and team members. Users can belong to multiple workspaces.

The Workspace Object

Name
id
Type
uuid
Description
Unique identifier for the workspace.
Name
name
Type
string
Description
Workspace name.
Name
domain
Type
string
Description
Workspace website domain URL.
Name
has_logo
Type
boolean
Description
Whether the workspace has a custom logo.
Name
logo_url
Type
string
Description
URL to the workspace logo (custom logo or auto-generated initial avatar).
Name
identity_verification_enabled
Type
boolean
Description
Whether identity verification is enabled for secure conversations.
Name
trial_ends_at
Type
date
Description
Trial end date in YYYY-MM-DD format.
Name
is_available
Type
boolean
Description
Whether the workspace has available team members online.
Name
response_delay
Type
integer
Description
Response delay in minutes for availability calculation.
Name
availability
Type
boolean
Description
Real-time availability status (cached for 5 minutes).
Name
plan_id
Type
uuid
Description
Subscription plan ID.
Name
users_count
Type
integer
Description
Total number of users in the workspace.
Name
timezone_id
Type
uuid
Description
Workspace timezone ID.
Name
timezone
Type
object
Description
Timezone object (when included in response).
Name
default_domain
Type
string
Description
Default email sending domain.
Name
billing_email
Type
string
Description
Billing contact email address.
Name
billing_cycle_start
Type
integer
Description
Day of the month when billing cycle starts (1-31).
Name
created_at
Type
datetime
Description
Timestamp when the workspace was created.
Name
updated_at
Type
datetime
Description
Timestamp when the workspace was last updated.

GET/app/workspaces

Create a Workspace

Create a new workspace. The authenticated user will be automatically added as the owner with a full seat. A 15-day trial is automatically applied.

Required Attributes

Name
name
Type
string
Required
*
Description
Workspace name (min 2 characters).
Name
domain
Type
string
Required
*
Description
Workspace website URL (must be valid URL, min 2 characters).

Creating a workspace performs several setup operations including: creating a Stripe customer, setting up default team, assigning role, and initializing onboarding tasks. This is a transaction-based operation.

Request

POST

/app/workspaces

curl -X POST https://api.pipeback.com/app/workspaces \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Tech Startup Inc",
    "domain": "https://techstartup.io"
  }'

Response

{
  "data": {
    "id": "9d5f3cf9-fa6f-498b-b5be-bd078b7d5340",
    "name": "Tech Startup Inc",
    "domain": "https://techstartup.io",
    "has_logo": false,
    "logo_url": "https://api.dicebear.com/9.x/initials/svg?backgroundColor=777777&clip=true&chars=1&scale=100&seed=Tech%20Startup%20Inc",
    "identity_verification_enabled": false,
    "trial_ends_at": "2025-11-10",
    "is_available": false,
    "response_delay": null,
    "availability": false,
    "plan_id": "9d5f3d04-8h25-0j7g-4g9k-7h8i9j0k1l2a",
    "users_count": 1,
    "timezone_id": "9d5f3d04-3c71-5e2b-9b4f-2c3d4e5f6g7e",
    "default_domain": null,
    "billing_email": "user@example.com",
    "billing_cycle_start": 26,
    "created_at": "2025-10-26 16:00:00",
    "updated_at": "2025-10-26 16:00:00"
  }
}

GET/app/workspaces/{id}

Retrieve a Workspace

Retrieve details about a specific workspace. The authenticated user must belong to the workspace.

Request

GET

/app/workspaces/{id}

curl https://api.pipeback.com/app/workspaces/9d5f3cf9-fa6f-498b-b5be-bd078b7d5339 \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response

{
  "data": {
    "id": "9d5f3cf9-fa6f-498b-b5be-bd078b7d5339",
    "name": "Acme Corp",
    "domain": "https://acmecorp.com",
    "has_logo": true,
    "logo_url": "https://example.com/logos/acme.png",
    "identity_verification_enabled": true,
    "trial_ends_at": "2025-11-10",
    "is_available": true,
    "response_delay": 5,
    "availability": true,
    "plan_id": "9d5f3d04-8h25-0j7g-4g9k-7h8i9j0k1l2a",
    "users_count": 12,
    "timezone_id": "9d5f3d04-3c71-5e2b-9b4f-2c3d4e5f6g7d",
    "timezone": {
      "id": "9d5f3d04-3c71-5e2b-9b4f-2c3d4e5f6g7d",
      "value": "America/New_York",
      "title": "Eastern Time (ET) - New York (UTC-05:00)"
    },
    "default_domain": "mail.acmecorp.com",
    "billing_email": "billing@acmecorp.com",
    "billing_cycle_start": 1,
    "created_at": "2025-01-15 10:00:00",
    "updated_at": "2025-10-26 16:00:00"
  }
}

PUT/app/workspaces/{id}

Update a Workspace

Update an existing workspace. The authenticated user must belong to the workspace.

Required Attributes

Name
name
Type
string
Required
*
Description
Workspace name.
Name
domain
Type
string
Required
*
Description
Workspace website URL.
Name
timezone_id
Type
uuid
Required
*
Description
Workspace timezone ID.

Request

PUT

/app/workspaces/{id}

curl -X PUT https://api.pipeback.com/app/workspaces/9d5f3cf9-fa6f-498b-b5be-bd078b7d5339 \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corporation",
    "domain": "https://acmecorporation.com",
    "timezone_id": "9d5f3d04-3c71-5e2b-9b4f-2c3d4e5f6g7f"
  }'

Response

{
  "data": {
    "id": "9d5f3cf9-fa6f-498b-b5be-bd078b7d5339",
    "name": "Acme Corporation",
    "domain": "https://acmecorporation.com",
    "has_logo": true,
    "logo_url": "https://example.com/logos/acme.png",
    "identity_verification_enabled": true,
    "trial_ends_at": "2025-11-10",
    "is_available": true,
    "response_delay": 5,
    "availability": true,
    "plan_id": "9d5f3d04-8h25-0j7g-4g9k-7h8i9j0k1l2a",
    "users_count": 12,
    "timezone_id": "9d5f3d04-3c71-5e2b-9b4f-2c3d4e5f6g7f",
    "default_domain": "mail.acmecorp.com",
    "billing_email": "billing@acmecorp.com",
    "billing_cycle_start": 1,
    "created_at": "2025-01-15 10:00:00",
    "updated_at": "2025-10-26 16:30:00"
  }
}

DELETE/app/workspaces/{id}/logo

Delete Workspace Logo

Delete the custom logo from a workspace. After deletion, the workspace will use an auto-generated avatar based on its initials.

This endpoint uses the workspace from the x-workspace-id header rather than the URL parameter. The workspace will automatically fall back to a Dicebear-generated initial avatar.

Request

DELETE

/app/workspaces/{id}/logo

curl -X DELETE https://api.pipeback.com/app/workspaces/9d5f3cf9-fa6f-498b-b5be-bd078b7d5339/logo \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "x-workspace-id: 9d5f3cf9-fa6f-498b-b5be-bd078b7d5339"

Response

{
  "data": {
    "id": "9d5f3cf9-fa6f-498b-b5be-bd078b7d5339",
    "name": "Acme Corporation",
    "domain": "https://acmecorporation.com",
    "has_logo": false,
    "logo_url": "https://api.dicebear.com/9.x/initials/svg?backgroundColor=777777&clip=true&chars=1&scale=100&seed=Acme%20Corporation",
    "identity_verification_enabled": true,
    "trial_ends_at": "2025-11-10",
    "is_available": true,
    "response_delay": 5,
    "availability": true,
    "plan_id": "9d5f3d04-8h25-0j7g-4g9k-7h8i9j0k1l2a",
    "users_count": 12,
    "timezone_id": "9d5f3d04-3c71-5e2b-9b4f-2c3d4e5f6g7f",
    "default_domain": "mail.acmecorp.com",
    "billing_email": "billing@acmecorp.com",
    "billing_cycle_start": 1,
    "created_at": "2025-01-15 10:00:00",
    "updated_at": "2025-10-26 16:30:00"
  }
}

Availability System

Workspaces track team availability to show customers when support is available:

Availability Calculation

The availability field is calculated based on team members who were active within the response_delay window (in minutes). This value is cached for 5 minutes to optimize performance.

Fields

is_available: Database-stored availability status (updated when calculated)
availability: Real-time calculated availability (cached)
response_delay: Time window in minutes to consider a user as available

For example, with response_delay: 5, users who were active in the last 5 minutes are considered available. If any team member is available, the workspace is marked as available.

Trial Period

New workspaces automatically receive a 15-day trial period:

Trial starts immediately upon workspace creation
trial_ends_at is set to 15 days from creation
Default plan is set to "pro-yearly"
No payment method required during trial

After the trial ends, workspaces require an active subscription to continue using paid features.