Companies

Companies represent organizations in your workspace. They can be associated with multiple contacts and contain business information, activity history, and relationships to deals and conversations.

The Company Object

Name
id
Type
uuid
Description
Unique identifier for the company.
Name
workspace_id
Type
uuid
Description
The workspace this company belongs to.
Name
owner_id
Type
uuid
Description
User ID of the company owner.
Name
company_id
Type
string
Description
External company identifier from your system.
Name
name
Type
string
Description
Company name.
Name
email
Type
string
Description
Company email address.
Name
website
Type
string
Description
Company website URL.
Name
industry
Type
string
Description
Industry or sector the company operates in.
Name
size
Type
string
Description
Company size (e.g., number of employees).
Name
plan
Type
string
Description
Current plan or subscription level.
Name
monthly_spend
Type
number
Description
Monthly spending or revenue amount.
Name
notes
Type
string
Description
Internal notes about the company.
Name
attributes
Type
object
Description
Custom attributes stored as key-value pairs.
Name
last_seen
Type
datetime
Description
Last time the company was active.
Name
company_created_at
Type
datetime
Description
When the company was created in the external system.
Name
web_sessions
Type
integer
Description
Number of web sessions recorded.
Name
photo_url
Type
string
Description
Auto-generated avatar URL based on company name.
Name
contacts_count
Type
integer
Description
Number of contacts associated with this company.
Name
created_at
Type
datetime
Description
Timestamp when the company was created.
Name
updated_at
Type
datetime
Description
Timestamp when the company was last updated.

GET/app/companies

List Companies

Retrieve a paginated list of companies in your workspace. Results can be filtered by segment and searched by name.

Query Parameters

Name
segment
Type
uuid
Required
*
Description
Segment ID to filter companies. Must be a valid segment of type company.
Name
q
Type
string
Description
Search query to filter companies by name (uses full-text search).
Name
page
Type
integer
Description
Page number for pagination (default: 1).

Request

GET

/app/companies

curl "https://api.pipeback.com/app/companies?segment=9d5f3d04-2c61-4d1a-8a3e-1b2c3d4e5f6a" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "x-workspace-id: YOUR_WORKSPACE_ID"

Response

{
  "data": [
    {
      "id": "9d5f3d04-3c71-5e2b-9b4f-2c3d4e5f6g7a",
      "workspace_id": "9d5f3cf9-fa6f-498b-b5be-bd078b7d5339",
      "owner_id": "9d5f3d04-2c61-4d1a-8a3e-1b2c3d4e5f6a",
      "company_id": "comp_1234567890",
      "name": "Acme Corporation",
      "email": "contact@acme.com",
      "website": "https://acme.com",
      "industry": "Technology",
      "size": "50-200",
      "plan": "Enterprise",
      "monthly_spend": 5000,
      "notes": "Important client",
      "attributes": {
        "tier": "platinum",
        "contract_end": "2026-12-31"
      },
      "last_seen": "2025-10-26T15:30:00.000000Z",
      "company_created_at": "2023-05-10T10:00:00.000000Z",
      "web_sessions": 120,
      "photo_url": "https://ui-avatars.com/api/?name=Acme+Corporation&color=1D2674&background=EAF0FB&length=1",
      "contacts_count": 15,
      "created_at": "2023-05-10T10:00:00.000000Z",
      "updated_at": "2025-10-26T15:30:00.000000Z"
    }
  ],
  "links": {
    "first": "https://api.pipeback.com/app/companies?page=1",
    "last": "https://api.pipeback.com/app/companies?page=5",
    "prev": null,
    "next": "https://api.pipeback.com/app/companies?page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 5,
    "per_page": 25,
    "to": 25,
    "total": 125
  }
}

POST/app/companies

Create a Company

Create a new company in your workspace.

Required Attributes

Name
name
Type
string
Required
*
Description
Company name.
Name
email
Type
string
Required
*
Description
Company email address. Must be a valid email format.

Request

POST

/app/companies

curl -X POST https://api.pipeback.com/app/companies \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "x-workspace-id: YOUR_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Tech Startup Inc",
    "email": "hello@techstartup.com"
  }'

Response

{
  "id": "9d5f3d04-3c71-5e2b-9b4f-2c3d4e5f6g7b",
  "workspace_id": "9d5f3cf9-fa6f-498b-b5be-bd078b7d5339",
  "owner_id": null,
  "company_id": null,
  "name": "Tech Startup Inc",
  "email": "hello@techstartup.com",
  "website": null,
  "industry": null,
  "size": null,
  "plan": null,
  "monthly_spend": null,
  "notes": null,
  "attributes": null,
  "last_seen": null,
  "company_created_at": null,
  "web_sessions": null,
  "photo_url": "https://ui-avatars.com/api/?name=Tech+Startup+Inc&color=1D2674&background=EAF0FB&length=1",
  "created_at": "2025-10-26T16:00:00.000000Z",
  "updated_at": "2025-10-26T16:00:00.000000Z"
}

GET/app/companies/{id}

Retrieve a Company

Retrieve detailed information about a specific company, including associated contacts, conversations, and tags.

The response includes three main sections:

company: Full company details with tags
contacts: Array of contacts associated with this company
conversations: Array of conversations related to this company's contacts

Request

GET

/app/companies/{id}

curl https://api.pipeback.com/app/companies/9d5f3d04-3c71-5e2b-9b4f-2c3d4e5f6g7a \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "x-workspace-id: YOUR_WORKSPACE_ID"

Response

{
  "company": {
    "id": "9d5f3d04-3c71-5e2b-9b4f-2c3d4e5f6g7a",
    "workspace_id": "9d5f3cf9-fa6f-498b-b5be-bd078b7d5339",
    "owner_id": "9d5f3d04-2c61-4d1a-8a3e-1b2c3d4e5f6a",
    "company_id": "comp_1234567890",
    "name": "Acme Corporation",
    "email": "contact@acme.com",
    "website": "https://acme.com",
    "industry": "Technology",
    "size": "50-200",
    "plan": "Enterprise",
    "monthly_spend": 5000,
    "notes": "Important client",
    "attributes": {
      "tier": "platinum",
      "contract_end": "2026-12-31"
    },
    "last_seen": "2025-10-26T15:30:00.000000Z",
    "company_created_at": "2023-05-10T10:00:00.000000Z",
    "web_sessions": 120,
    "photo_url": "https://ui-avatars.com/api/?name=Acme+Corporation&color=1D2674&background=EAF0FB&length=1",
    "created_at": "2023-05-10T10:00:00.000000Z",
    "updated_at": "2025-10-26T15:30:00.000000Z",
    "tags": [
      {
        "id": "9d5f3d04-4d81-6f3c-0c5g-3d4e5f6g7h8a",
        "name": "Enterprise",
        "color": "blue"
      }
    ]
  },
  "contacts": [
    {
      "id": "9d5f3d04-2c61-4d1a-8a3e-1b2c3d4e5f6a",
      "name": "John Doe",
      "email": "john@acme.com",
      "type": "user",
      "last_seen": "2025-10-26T15:30:00.000000Z"
    }
  ],
  "conversations": []
}

PUT/app/companies/{id}

Update a Company

Update an existing company's information.

Attributes

Name
notes
Type
string
Description
Internal notes about the company.
Name
tags
Type
array
Description
Array of tag IDs to associate with the company. This will replace existing tags.

Request

PUT

/app/companies/{id}

curl -X PUT https://api.pipeback.com/app/companies/9d5f3d04-3c71-5e2b-9b4f-2c3d4e5f6g7a \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "x-workspace-id: YOUR_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "notes": "Updated enterprise client notes",
    "tags": ["9d5f3d04-4d81-6f3c-0c5g-3d4e5f6g7h8a"]
  }'

Response

{
  "id": "9d5f3d04-3c71-5e2b-9b4f-2c3d4e5f6g7a",
  "workspace_id": "9d5f3cf9-fa6f-498b-b5be-bd078b7d5339",
  "owner_id": "9d5f3d04-2c61-4d1a-8a3e-1b2c3d4e5f6a",
  "company_id": "comp_1234567890",
  "name": "Acme Corporation",
  "email": "contact@acme.com",
  "website": "https://acme.com",
  "industry": "Technology",
  "size": "50-200",
  "plan": "Enterprise",
  "monthly_spend": 5000,
  "notes": "Updated enterprise client notes",
  "attributes": {
    "tier": "platinum",
    "contract_end": "2026-12-31"
  },
  "last_seen": "2025-10-26T15:30:00.000000Z",
  "company_created_at": "2023-05-10T10:00:00.000000Z",
  "web_sessions": 120,
  "photo_url": "https://ui-avatars.com/api/?name=Acme+Corporation&color=1D2674&background=EAF0FB&length=1",
  "created_at": "2023-05-10T10:00:00.000000Z",
  "updated_at": "2025-10-26T16:15:00.000000Z"
}

DELETE/app/companies/{id}

Delete a Company

Delete a company from your workspace. This action cannot be undone.

Deleting a company does not delete associated contacts. The contacts will remain in the workspace but will no longer be associated with this company.

Request

DELETE

/app/companies/{id}

curl -X DELETE https://api.pipeback.com/app/companies/9d5f3d04-3c71-5e2b-9b4f-2c3d4e5f6g7a \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "x-workspace-id: YOUR_WORKSPACE_ID"

Response

{
}