Skip to content
Pathbound DOCS
Sign in Start free →

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

Section titled “Create a Company”
POST /v1/companies

Required scope: companies:write

Request Body

Section titled “Request Body”
FieldTypeRequiredDescription
domainstringyesCompany domain (must be unique).
propertiesobjectnoArbitrary key-value properties.

Response — 201 Created

Section titled “Response — 201 Created”
{
  "status": "success",
  "company": {
    "company_id": "co_abc",
    "_id": "co_abc",
    "properties": {
      "domain": "example.com",
      "name": "Example Corp"
    },
    "created_at": "2026-01-15T10:00:00.000Z",
    "updated_at": "2026-01-15T10:00:00.000Z"
  }
}

_id is a transitional alias for company_id and will be removed in a future release — prefer company_id in new integrations.

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

List Companies

Section titled “List Companies”
GET /v1/companies

Required scope: companies:read

Query Parameters

Section titled “Query Parameters”
ParameterTypeDefaultDescription
pagenumber1Page number.
limitnumber20Results per page (1–100).
searchstring—Free-text search by name, domain, industry.
industrystring—Filter by industry.
countrystring—Filter by country.
sort_bystring—Field to sort by.
sort_dirstringdescSort direction (asc or desc).
fieldsstring—summary for a compact projection (company_id, id, name, domain, industry, last_activity_at); omit for full.
includestring—Comma-separated list of optional fields to include. Currently supports provenance to add the per-field source/timestamp record (properties_provenance).

Response — 200 OK

Section titled “Response — 200 OK”
{
  "status": "success",
  "companies": [
    {
      "company_id": "co_abc",
      "_id": "co_abc",
      "properties": { "domain": "example.com", "name": "Example Corp", "industry": "Software" },
      "created_at": "2026-01-15T10:00:00.000Z",
      "updated_at": "2026-04-29T12:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total_pages": 3,
    "total_items": 25
  }
}

_id is a transitional alias for company_id and will be removed in a future release.

Get a Company

Section titled “Get a Company”
GET /v1/companies/:company_id

Required scope: companies:read

Returns the company along with its full deduplicated cross-source unified_profile and its associated contacts.

Query Parameters

Section titled “Query Parameters”
ParameterTypeDefaultDescription
include_contactsbooleantrueIf false, omit the contacts array from the response.
contacts_limitnumber10How many associated contacts to return (1–25).
includestring—Comma-separated list of optional fields to include. Supports provenance (per-field provenance on the base company record) and raw (adds unified_profile.raw_data — the un-deduplicated per-source field dumps; large, omitted by default).

Response — 200 OK

Section titled “Response — 200 OK”
{
  "status": "success",
  "company": {
    "company_id": "co_abc",
    "_id": "co_abc",
    "properties": {
      "domain": "example.com",
      "name": "Example Corp",
      "industry": "Software",
      "employee_count": 250,
      "lifecyclestage": "customer"
    },
    "created_at": "2026-01-15T10:00:00.000Z"
  },
  "unified_profile": {
    "_id": "co_abc",
    "source_count": 2,
    "sources": {
      "internal": { "id": "co_abc", "updated_at": "...", "first_seen_at": "..." },
      "hubspot": { "id": "98765", "synced_at": "...", "first_seen_at": "..." }
    },
    "profile": {
      "name": {
        "unique_values": [
          { "value": "Example Corp", "sources": [{ "source": "internal", "updated_at": "..." }, { "source": "hubspot", "updated_at": "..." }] }
        ],
        "all_sources": ["internal", "hubspot"],
        "has_conflict": false
      },
      "numberofemployees": {
        "unique_values": [
          { "value": 250, "sources": [{ "source": "internal", "updated_at": "..." }] },
          { "value": 300, "sources": [{ "source": "hubspot", "updated_at": "..." }] }
        ],
        "all_sources": ["internal", "hubspot"],
        "has_conflict": true
      }
    },
    "created_at": "...",
    "updated_at": "..."
  },
  "contacts": [
    {
      "id": "ct_abc",
      "email": "[email protected]",
      "firstname": "Ada",
      "lastname": "Lovelace",
      "job_title": "CTO",
      "lifecycle_stage": "customer"
    }
  ],
  "total_contacts": 12
}

unified_profile is the full deduplicated cross-source profile. Each profile field is a multi-source object: unique_values holds every distinct value found across sources (deduplicated), each annotated with the sources that supplied it; all_sources lists every source that had any value; and has_conflict is true when sources disagree. sources is a per-source map (presence, external IDs, sync/enrichment timestamps), and source_count is how many sources contributed. Pass ?include=raw for raw_data (the verbatim, un-deduplicated per-source dumps). Company firmographics are not PII and are never masked.

The embedded contacts array is a compact projection (intentionally uses id rather than the full contact serializer). For the full contact shape, fetch the contact directly via GET /v1/contacts/:contact_id.

Update a Company

Section titled “Update a Company”
PUT /v1/companies/:company_id

Required scope: companies:write

Request Body

Section titled “Request Body”
FieldTypeRequiredDescription
propertiesobjectnoProperties to update or add (merge).

Response — 200 OK

Section titled “Response — 200 OK”
{
  "status": "success",
  "company": {
    "company_id": "co_abc",
    "_id": "co_abc",
    "properties": { "domain": "example.com", "name": "Example Corp", "industry": "Software" },
    "updated_at": "2026-04-29T12:00:00.000Z"
  }
}

Delete a Company

Section titled “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

Section titled “Company Notes”

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

List Notes

Section titled “List Notes”
GET /v1/companies/:company_id/notes

Required scope: companies:read

Create a Note

Section titled “Create a Note”
POST /v1/companies/:company_id/notes

Required scope: companies:write

FieldTypeRequiredDescription
contentstringyesNote body (markdown).

Update a Note

Section titled “Update a Note”
PATCH /v1/companies/:company_id/notes/:note_id

Required scope: companies:write

Delete a Note

Section titled “Delete a Note”
DELETE /v1/companies/:company_id/notes/:note_id

Required scope: companies:write