Companies

Manage companies in your graph8 workspace. Companies are automatically created when contacts are enriched or imported.

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)

Example

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

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

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

Response

{
  "data": [
    {
      "id": 42,
      "name": "Acme Inc",
      "domain": "acme.com",
      "website": "https://acme.com",
      "industry": "Technology",
      "employee_count": 500,
      "city": "San Francisco",
      "state": "CA",
      "country": "US",
      "linkedin_url": "https://linkedin.com/company/acme",
      "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