Companies API

Companies represent organizations in your Pathbound CRM, identified by their domain. Contacts roll up to companies for account-level intelligence.

Create a Company

POST /v1/companies

Required scope: companies:write

Request Body

Field	Type	Required	Description
domain	string	yes	Company domain (must be unique).
properties	object	no	Arbitrary key-value properties.

Response — 201 Created

{
  "status": "success",
  "company": { /* company object */ }
}

Returns 409 Conflict if a company with the same domain already exists.

---

List Companies

GET /v1/companies

Required scope: companies:read

Query Parameters

Parameter	Type	Default	Description
page	number	1	Page number.
limit	number	20	Results per page (1–100).
search	string	—	Free-text search by name, domain, industry.
industry	string	—	Filter by industry.
sort_by	string	—	Field to sort by.
sort_dir	string	desc	Sort direction (asc or desc).

Response — 200 OK

{
  "status": "success",
  "companies": [ /* company objects */ ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total_pages": 3,
    "total_items": 25
  }
}

---

Get a Company

GET /v1/companies/:company_id

Required scope: companies:read

Returns the company along with its associated contacts (up to 25).

Response — 200 OK

{
  "status": "success",
  "company": {
    "_id": "co_abc",
    "tenant_id": "tenant_xyz",
    "properties": {
      "domain": "example.com",
      "name": "Example Corp",
      "industry": "Software",
      "employee_count": 250,
      "lifecyclestage": "customer"
    },
    "created_at": "2026-01-15T10:00:00.000Z"
  },
  "contacts": [ /* up to 25 associated contacts */ ]
}

---

Update a Company

PUT /v1/companies/:company_id

Required scope: companies:write

Request Body

Field	Type	Required	Description
properties	object	no	Properties to update or add (merge).

Response — 200 OK

{
  "status": "success",
  "company": { /* updated company object */ }
}

---

Delete a Company

DELETE /v1/companies/:company_id

Required scope: companies:write

Permanently removes the company. Associated contacts are not deleted but lose their company association.

---

Company Notes

Each company can have free-form notes attached, just like contacts.

List Notes

GET /v1/companies/:company_id/notes

Required scope: companies:read

Create a Note

POST /v1/companies/:company_id/notes

Required scope: companies:write

Field	Type	Required	Description
content	string	yes	Note body (markdown).

Update a Note

PATCH /v1/companies/:company_id/notes/:note_id

Required scope: companies:write

Delete a Note

DELETE /v1/companies/:company_id/notes/:note_id

Required scope: companies:write