Companies

Manage companies in your graph8 workspace — your first-party CRM data.

Companies arrive in your workspace automatically when contacts are saved, enriched, or imported — you don’t need to create them manually. Each contact is linked to a company, and company records are created or updated as contacts flow in. These endpoints give you full read/write access at no credit cost.

List Companies

GET /companies

Returns a paginated list of companies.

Query Parameters

Parameter	Type	Default	Description
`page`	integer	`1`	Page number (1-indexed)
`limit`	integer	`50`	Items per page (1-200)
`domain`	string	—	Filter by domain (exact match)
`industry`	string	—	Filter by industry (partial match, case-insensitive)
`name`	string	—	Filter by company name (partial match, case-insensitive)
`employee_count_min`	integer	—	Minimum employee count
`employee_count_max`	integer	—	Maximum employee count
`country`	string	—	Filter by country (exact match)
`state`	string	—	Filter by state (exact match)
`city`	string	—	Filter by city (partial match, case-insensitive)
`description`	string	—	Filter by company description (partial match, case-insensitive)
`revenue_min`	integer	—	Minimum annual revenue
`revenue_max`	integer	—	Maximum annual revenue
`founded_year_min`	integer	—	Minimum founding year
`founded_year_max`	integer	—	Maximum founding year
`linkedin_followers_min`	integer	—	Minimum LinkedIn followers
`linkedin_followers_max`	integer	—	Maximum LinkedIn followers

All filters are optional and can be combined. When multiple filters are provided, results must match all of them (AND logic).

Example

# Filter by industry
curl "https://be.graph8.com/api/v1/companies?industry=Technology&limit=10" \
  -H "Authorization: Bearer $API_KEY"

# Search by company name with employee count range
curl "https://be.graph8.com/api/v1/companies?name=acme&employee_count_min=100&employee_count_max=1000" \
  -H "Authorization: Bearer $API_KEY"

# Search by company description (useful for ICP identification)
curl "https://be.graph8.com/api/v1/companies?description=enterprise%20software" \
  -H "Authorization: Bearer $API_KEY"

# Filter by revenue range and founding year
curl "https://be.graph8.com/api/v1/companies?revenue_min=1000000&revenue_max=50000000&founded_year_min=2015" \
  -H "Authorization: Bearer $API_KEY"

# Filter by LinkedIn followers (social presence)
curl "https://be.graph8.com/api/v1/companies?linkedin_followers_min=1000&industry=SaaS" \
  -H "Authorization: Bearer $API_KEY"

# Filter by industry
response = requests.get(
    f"{BASE_URL}/companies",
    headers=HEADERS,
    params={"industry": "Technology", "limit": 10}
)
companies = response.json()

# Search by name with employee count range
response = requests.get(
    f"{BASE_URL}/companies",
    headers=HEADERS,
    params={"name": "acme", "employee_count_min": 100, "employee_count_max": 1000}
)

# Filter by revenue range and founding year
response = requests.get(
    f"{BASE_URL}/companies",
    headers=HEADERS,
    params={"revenue_min": 1000000, "revenue_max": 50000000, "founded_year_min": 2015}
)

// Filter by industry
const response = await fetch(
  `${BASE_URL}/companies?industry=Technology&limit=10`,
  { headers: { Authorization: `Bearer ${API_KEY}` } }
);
const companies = await response.json();

// Search by name with employee count range
const filtered = await fetch(
  `${BASE_URL}/companies?name=acme&employee_count_min=100&employee_count_max=1000`,
  { headers: { Authorization: `Bearer ${API_KEY}` } }
);

// Filter by revenue range and founding year
const revenueFiltered = await fetch(
  `${BASE_URL}/companies?revenue_min=1000000&revenue_max=50000000&founded_year_min=2015`,
  { headers: { Authorization: `Bearer ${API_KEY}` } }
);

Response

{
  "data": [
    {
      "id": 42,
      "name": "Acme Inc",
      "description": "Enterprise software company specializing in cloud solutions",
      "domain": "acme.com",
      "website": "https://acme.com",
      "industry": "Technology",
      "employee_count": "500",
      "revenue": "25000000",
      "founded_year": 2015,
      "city": "San Francisco",
      "state": "CA",
      "country": "US",
      "linkedin_url": "https://linkedin.com/company/acme",
      "linkedin_followers": "12500",
      "logo_url": "https://logo.clearbit.com/acme.com"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 87,
    "has_next": true
  }
}

Get Company

GET /companies/{company_id}

Returns detailed information about a single company.

Path Parameters

Parameter	Type	Description
`company_id`	integer	Company ID

Example

curl "https://be.graph8.com/api/v1/companies/42" \
  -H "Authorization: Bearer $API_KEY"

response = requests.get(f"{BASE_URL}/companies/42", headers=HEADERS)
company = response.json()["data"]

const response = await fetch(`${BASE_URL}/companies/42`, {
  headers: { Authorization: `Bearer ${API_KEY}` }
});
const { data: company } = await response.json();

Response

{
  "data": {
    "id": 42,
    "name": "Acme Inc",
    "description": "Enterprise software company",
    "domain": "acme.com",
    "website": "https://acme.com",
    "logo_url": "https://logo.clearbit.com/acme.com",
    "phone": "+1-555-0200",
    "address": "123 Market St",
    "city": "San Francisco",
    "state": "CA",
    "country": "US",
    "zip": "94105",
    "founded_year": 2015,
    "employee_count": "500",
    "revenue": "25000000",
    "industry": "Technology",
    "industry_group": "Software",
    "linkedin_url": "https://linkedin.com/company/acme",
    "linkedin_followers": "12500",
    "facebook_url": null,
    "twitter_url": "https://twitter.com/acme",
    "crunchbase_url": null,
    "meta_data": null,
    "contact_count": 15,
    "created_at": "2026-01-10T08:00:00Z",
    "updated_at": "2026-02-20T16:45:00Z"
  }
}

Errors

Status	Meaning
`404`	Company not found

Get Company Contacts

GET /companies/{company_id}/contacts

Returns contacts associated with a company.

Path Parameters

Parameter	Type	Description
`company_id`	integer	Company ID

Query Parameters

Parameter	Type	Default	Description
`limit`	integer	`100`	Items per page (1-200)
`offset`	integer	`0`	Offset for pagination

Example

curl "https://be.graph8.com/api/v1/companies/42/contacts?limit=50" \
  -H "Authorization: Bearer $API_KEY"

response = requests.get(
    f"{BASE_URL}/companies/42/contacts",
    headers=HEADERS,
    params={"limit": 50}
)
contacts = response.json()["data"]

const response = await fetch(`${BASE_URL}/companies/42/contacts?limit=50`, {
  headers: { Authorization: `Bearer ${API_KEY}` }
});
const { data: contacts } = await response.json();

Response

{
  "data": [
    {
      "id": 1,
      "first_name": "Jane",
      "last_name": "Smith",
      "full_name": "Jane Smith",
      "work_email": "jane@acme.com",
      "job_title": "VP of Engineering",
      "seniority_level": "VP",
      "direct_phone": "+1-555-0100",
      "linkedin_url": "https://linkedin.com/in/janesmith",
      "city": "San Francisco",
      "state": "CA",
      "country": "US"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 15,
    "has_next": false
  }
}

Update Company

PATCH /companies/{company_id}

Update one or more fields on a company. Only include the fields you want to change.

Path Parameters

Parameter	Type	Description
`company_id`	integer	Company ID

Request Body

All fields are optional. Include only the fields to update.

Field	Type	Description
`name`	string	Company name
`domain`	string	Primary domain
`website`	string	Website URL
`phone`	string	Phone number
`address`	string	Street address
`city`	string	City
`state`	string	State or province
`country`	string	Country
`zip`	string	ZIP or postal code
`industry`	string	Industry
`employee_count`	integer	Number of employees
`linkedin_url`	string	LinkedIn company page URL

Example

curl -X PATCH "https://be.graph8.com/api/v1/companies/42" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"industry": "Enterprise Software", "employee_count": 550}'

response = requests.patch(
    f"{BASE_URL}/companies/42",
    headers=HEADERS,
    json={"industry": "Enterprise Software", "employee_count": 550}
)

const response = await fetch(`${BASE_URL}/companies/42`, {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ industry: "Enterprise Software", employee_count: 550 })
});

Response

{
  "data": {
    "updated": 1
  }
}

Errors

Status	Meaning
`400`	No fields provided to update
`404`	Company not found

Delete Company

DELETE /companies/{company_id}

Soft-delete a company. The company is marked as deleted but not permanently removed.

Path Parameters

Parameter	Type	Description
`company_id`	integer	Company ID

Example

curl -X DELETE "https://be.graph8.com/api/v1/companies/42" \
  -H "Authorization: Bearer $API_KEY"

response = requests.delete(f"{BASE_URL}/companies/42", headers=HEADERS)

const response = await fetch(`${BASE_URL}/companies/42`, {
  method: "DELETE",
  headers: { Authorization: `Bearer ${API_KEY}` }
});

Response

{
  "data": {
    "deleted": true
  }
}

Errors

Status	Meaning
`404`	Company not found