curl --request GET \
--url https://api.wellapp.ai/v1/companies \
--header 'Authorization: <authorization>'import requests
url = "https://api.wellapp.ai/v1/companies"
headers = {"Authorization": "<authorization>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: '<authorization>'}};
fetch('https://api.wellapp.ai/v1/companies', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.wellapp.ai/v1/companies",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: <authorization>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.wellapp.ai/v1/companies"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "<authorization>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.wellapp.ai/v1/companies")
.header("Authorization", "<authorization>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.wellapp.ai/v1/companies")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = '<authorization>'
response = http.request(request)
puts response.read_body{
"data": [
{
"type": "company",
"id": "550e8400-e29b-41d4-a716-446655440000",
"attributes": {
"name": "TechCorp Solutions GmbH",
"description": "Leading technology company specializing in AI solutions and business automation",
"business_entity": "GmbH",
"registration": {
"tax_id": "12345678901",
"registered_value": "123456789",
"country": "DE"
},
"registration_number": {
"value": "HRB 123456",
"authority": "Amtsgericht München"
},
"has_logo": true,
"workspace_id": [
"550e8400-e29b-41d4-a716-446655440004"
],
"created_at": "2024-08-15T10:30:00Z",
"updated_at": "2024-12-01T14:22:00Z"
},
"relationships": {
"created_by": {
"data": {
"type": "user",
"id": "550e8400-e29b-41d4-a716-446655440020"
}
},
"people": {
"data": [
{
"type": "people",
"id": "550e8400-e29b-41d4-a716-446655440001"
}
]
},
"emails": {
"data": [
{
"type": "email",
"id": "550e8400-e29b-41d4-a716-446655440010"
}
]
},
"phones": {
"data": [
{
"type": "phone",
"id": "550e8400-e29b-41d4-a716-446655440011"
}
]
},
"web_links": {
"data": [
{
"type": "web_link",
"id": "550e8400-e29b-41d4-a716-446655440012"
}
]
},
"media": {
"data": [
{
"type": "media",
"id": "550e8400-e29b-41d4-a716-446655440014"
}
]
},
"documents": {
"data": [
{
"type": "document",
"id": "550e8400-e29b-41d4-a716-446655440016"
}
]
},
"locations": {
"data": [
{
"type": "location",
"id": "550e8400-e29b-41d4-a716-446655440013"
}
]
},
"workspaces": {
"data": [
{
"type": "workspace",
"id": "550e8400-e29b-41d4-a716-446655440004"
}
]
},
"parents": {
"data": [
{
"type": "company",
"id": "550e8400-e29b-41d4-a716-446655440017"
}
]
},
"subsidiaries": {
"data": [
{
"type": "company",
"id": "550e8400-e29b-41d4-a716-446655440018"
}
]
}
}
}
],
"included": [
{
"type": "people",
"id": "550e8400-e29b-41d4-a716-446655440001",
"attributes": {
"first_name": "Klaus",
"last_name": "Weber",
"full_name": "Klaus Weber",
"relationship_type": "owner",
"job_title": "Founder & CEO"
}
},
{
"type": "workspace",
"id": "550e8400-e29b-41d4-a716-446655440004",
"attributes": {
"name": "European Operations",
"description": "Main workspace for European business operations",
"created_at": "2024-01-10T08:15:00Z"
}
},
{
"type": "email",
"id": "550e8400-e29b-41d4-a716-446655440010",
"attributes": {
"value": "contact@techcorp.com",
"label": "work",
"is_verified": true,
"is_primary": true
}
},
{
"type": "phone",
"id": "550e8400-e29b-41d4-a716-446655440011",
"attributes": {
"value": "+491234567890",
"label": "work",
"is_verified": true,
"is_primary": true
}
},
{
"type": "web_link",
"id": "550e8400-e29b-41d4-a716-446655440012",
"attributes": {
"url": "https://www.linkedin.com/company/techcorp-solutions",
"platform": "linkedin",
"is_primary": true
}
},
{
"type": "location",
"id": "550e8400-e29b-41d4-a716-446655440013",
"attributes": {
"street": "Maximilianstrasse 123",
"city": "München",
"postal_code": "80539",
"country": "DE",
"is_primary": true,
"is_registered": true
}
},
{
"type": "media",
"id": "550e8400-e29b-41d4-a716-446655440014",
"attributes": {
"url": "https://cdn.techcorp.com/logo.png",
"media_type": "logo",
"is_primary": true
}
},
{
"type": "user",
"id": "550e8400-e29b-41d4-a716-446655440020",
"attributes": {
"first_name": "John",
"last_name": "Doe",
"email": "john.doe@techcorp.com",
"created_at": "2024-01-05T09:00:00Z"
}
},
{
"type": "document",
"id": "550e8400-e29b-41d4-a716-446655440016",
"attributes": {
"name": "Company Registration Certificate",
"file_name": "registration_certificate.pdf",
"mime_type": "application/pdf",
"size": 245760,
"is_public": false,
"created_at": "2024-08-15T10:30:00Z"
}
},
{
"type": "company",
"id": "550e8400-e29b-41d4-a716-446655440017",
"attributes": {
"name": "Global Tech Holdings",
"description": "Parent company of TechCorp Solutions",
"business_entity": "AG",
"relationship_type": "parent"
}
},
{
"type": "company",
"id": "550e8400-e29b-41d4-a716-446655440018",
"attributes": {
"name": "TechCorp Software Labs",
"description": "R&D subsidiary specializing in software development",
"business_entity": "GmbH",
"relationship_type": "subsidiary"
}
}
],
"meta": {
"pagination": {
"total": 2,
"count": 2,
"per_page": 25,
"current_page": 1,
"total_pages": 1
}
}
}{
"code": "UNAUTHORIZED",
"status": 401,
"title": "Unauthorized",
"message": "You are not authorized to access this resource",
"meta": {
"log_id": "65c669d4-679c-4a8b-b8c0-fbe37699bb5b"
}
}Get Companies
Retrieve a paginated list of companies. By default, only basic company data is returned with relationship IDs. Use the ‘include’ parameter to get detailed relationship data.
curl --request GET \
--url https://api.wellapp.ai/v1/companies \
--header 'Authorization: <authorization>'import requests
url = "https://api.wellapp.ai/v1/companies"
headers = {"Authorization": "<authorization>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: '<authorization>'}};
fetch('https://api.wellapp.ai/v1/companies', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.wellapp.ai/v1/companies",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: <authorization>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.wellapp.ai/v1/companies"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "<authorization>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.wellapp.ai/v1/companies")
.header("Authorization", "<authorization>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.wellapp.ai/v1/companies")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = '<authorization>'
response = http.request(request)
puts response.read_body{
"data": [
{
"type": "company",
"id": "550e8400-e29b-41d4-a716-446655440000",
"attributes": {
"name": "TechCorp Solutions GmbH",
"description": "Leading technology company specializing in AI solutions and business automation",
"business_entity": "GmbH",
"registration": {
"tax_id": "12345678901",
"registered_value": "123456789",
"country": "DE"
},
"registration_number": {
"value": "HRB 123456",
"authority": "Amtsgericht München"
},
"has_logo": true,
"workspace_id": [
"550e8400-e29b-41d4-a716-446655440004"
],
"created_at": "2024-08-15T10:30:00Z",
"updated_at": "2024-12-01T14:22:00Z"
},
"relationships": {
"created_by": {
"data": {
"type": "user",
"id": "550e8400-e29b-41d4-a716-446655440020"
}
},
"people": {
"data": [
{
"type": "people",
"id": "550e8400-e29b-41d4-a716-446655440001"
}
]
},
"emails": {
"data": [
{
"type": "email",
"id": "550e8400-e29b-41d4-a716-446655440010"
}
]
},
"phones": {
"data": [
{
"type": "phone",
"id": "550e8400-e29b-41d4-a716-446655440011"
}
]
},
"web_links": {
"data": [
{
"type": "web_link",
"id": "550e8400-e29b-41d4-a716-446655440012"
}
]
},
"media": {
"data": [
{
"type": "media",
"id": "550e8400-e29b-41d4-a716-446655440014"
}
]
},
"documents": {
"data": [
{
"type": "document",
"id": "550e8400-e29b-41d4-a716-446655440016"
}
]
},
"locations": {
"data": [
{
"type": "location",
"id": "550e8400-e29b-41d4-a716-446655440013"
}
]
},
"workspaces": {
"data": [
{
"type": "workspace",
"id": "550e8400-e29b-41d4-a716-446655440004"
}
]
},
"parents": {
"data": [
{
"type": "company",
"id": "550e8400-e29b-41d4-a716-446655440017"
}
]
},
"subsidiaries": {
"data": [
{
"type": "company",
"id": "550e8400-e29b-41d4-a716-446655440018"
}
]
}
}
}
],
"included": [
{
"type": "people",
"id": "550e8400-e29b-41d4-a716-446655440001",
"attributes": {
"first_name": "Klaus",
"last_name": "Weber",
"full_name": "Klaus Weber",
"relationship_type": "owner",
"job_title": "Founder & CEO"
}
},
{
"type": "workspace",
"id": "550e8400-e29b-41d4-a716-446655440004",
"attributes": {
"name": "European Operations",
"description": "Main workspace for European business operations",
"created_at": "2024-01-10T08:15:00Z"
}
},
{
"type": "email",
"id": "550e8400-e29b-41d4-a716-446655440010",
"attributes": {
"value": "contact@techcorp.com",
"label": "work",
"is_verified": true,
"is_primary": true
}
},
{
"type": "phone",
"id": "550e8400-e29b-41d4-a716-446655440011",
"attributes": {
"value": "+491234567890",
"label": "work",
"is_verified": true,
"is_primary": true
}
},
{
"type": "web_link",
"id": "550e8400-e29b-41d4-a716-446655440012",
"attributes": {
"url": "https://www.linkedin.com/company/techcorp-solutions",
"platform": "linkedin",
"is_primary": true
}
},
{
"type": "location",
"id": "550e8400-e29b-41d4-a716-446655440013",
"attributes": {
"street": "Maximilianstrasse 123",
"city": "München",
"postal_code": "80539",
"country": "DE",
"is_primary": true,
"is_registered": true
}
},
{
"type": "media",
"id": "550e8400-e29b-41d4-a716-446655440014",
"attributes": {
"url": "https://cdn.techcorp.com/logo.png",
"media_type": "logo",
"is_primary": true
}
},
{
"type": "user",
"id": "550e8400-e29b-41d4-a716-446655440020",
"attributes": {
"first_name": "John",
"last_name": "Doe",
"email": "john.doe@techcorp.com",
"created_at": "2024-01-05T09:00:00Z"
}
},
{
"type": "document",
"id": "550e8400-e29b-41d4-a716-446655440016",
"attributes": {
"name": "Company Registration Certificate",
"file_name": "registration_certificate.pdf",
"mime_type": "application/pdf",
"size": 245760,
"is_public": false,
"created_at": "2024-08-15T10:30:00Z"
}
},
{
"type": "company",
"id": "550e8400-e29b-41d4-a716-446655440017",
"attributes": {
"name": "Global Tech Holdings",
"description": "Parent company of TechCorp Solutions",
"business_entity": "AG",
"relationship_type": "parent"
}
},
{
"type": "company",
"id": "550e8400-e29b-41d4-a716-446655440018",
"attributes": {
"name": "TechCorp Software Labs",
"description": "R&D subsidiary specializing in software development",
"business_entity": "GmbH",
"relationship_type": "subsidiary"
}
}
],
"meta": {
"pagination": {
"total": 2,
"count": 2,
"per_page": 25,
"current_page": 1,
"total_pages": 1
}
}
}{
"code": "UNAUTHORIZED",
"status": 401,
"title": "Unauthorized",
"message": "You are not authorized to access this resource",
"meta": {
"log_id": "65c669d4-679c-4a8b-b8c0-fbe37699bb5b"
}
}Complex Usage Example
Advanced Company Filtering with Full Context
This example demonstrates advanced filtering with multiple parameters, relationship inclusion, business entity filtering, sorting, and pagination for retrieving companies:curl -X GET "https://api.well.com/v1/companies?include=peoples,workspaces,emails,phones,web_links,locations,documents,media,categories,parents,subsidiaries&filter[workspace_id]=550e8400-e29b-41d4-a716-446655440000&filter[name]=TechCorp&filter[business_entity]=GmbH&filter[registration_tax_id]=12345678901&filter[registration_registered_value]=123456789&filter[country]=DE&filter[people_id]=550e8400-e29b-41d4-a716-446655440001&filter[email]=contact@techcorp.com&filter[phone_number]=+491234567890&filter[has_logo]=true&filter[created_at_from]=2024-01-01T00:00:00Z&filter[created_at_to]=2024-12-31T23:59:59Z&filter[updated_at_from]=2024-06-01T00:00:00Z&sort=-created_at&page[limit]=25&page[cursor]=eyJjcmVhdGVkX2F0IjoiMjAyNS0xMS0wMlQxMDozMDowMFoiLCJpZCI6ImNvbXBhbnk5LXV1aWQifQ==" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json"
- Include relationships: Retrieve complete data for people, workspaces, contact information, and documents
- Filter by workspace: Limit to companies in a specific workspace
- Search by name: Find companies with “TechCorp” in their name
- Filter by business entity: Only show German GmbH companies
- Registration filtering: Filter by tax ID and registration numbers
- Geographic filtering: Limit to companies in Germany
- Contact filtering: Find companies with specific email or phone
- Media filtering: Only show companies with logos
- Date range filtering: Limit to companies created/updated in specific periods
- Sorting: Order by creation date (newest first)
- Pagination: Get 25 results per page with cursor-based pagination
Filtering & sorting on related objects
Filter and sort on a related (included) object by nesting into the relationship — the same relationships you pass toinclude.
- To-one relations nest directly:
{ "issuer": { "name": { "_eq": "Acme" } } }, and sort by a dot-path:"orderBy": { "field": "issuer.name", "direction": "asc" }. - To-many relations must be quantified with
_some,_every, or_none:{ "items": { "_some": { "quantity": { "_gt": 1 } } } }. They are not directly sortable (a to-many sort needs an aggregate proxy). - Composite
composite_*columns are virtual — filter and sort on their underlying source fields, not on the composite.
include) and how to filter or sort on each:
| Relationship | Cardinality | Filter on a field | Sort by a field |
|---|---|---|---|
workspace | to-one (workspace) | { "workspace": { "name": { "_eq": … } } } | "field": "workspace.name" ✅ |
source_workspace_connector | to-one (workspace_connector) | { "source_workspace_connector": { "name": { "_eq": … } } } | "field": "source_workspace_connector.name" ✅ |
relations | to-many (company_relation) | { "relations": { "_some": { "field_name": { "_eq": … } } } } | aggregate proxy only ⚠️ |
people | to-many (company_person) | { "people": { "_some": { "field_name": { "_eq": … } } } } | aggregate proxy only ⚠️ |
social_links | to-many (company_web_link) | { "social_links": { "_some": { "field_name": { "_eq": … } } } } | aggregate proxy only ⚠️ |
locations | to-many (company_location) | { "locations": { "_some": { "field_name": { "_eq": … } } } } | aggregate proxy only ⚠️ |
emails | to-many (company_email) | { "emails": { "_some": { "field_name": { "_eq": … } } } } | aggregate proxy only ⚠️ |
phones | to-many (company_phone) | { "phones": { "_some": { "field_name": { "_eq": … } } } } | aggregate proxy only ⚠️ |
categories | to-many (company_category) | { "categories": { "_some": { "field_name": { "_eq": … } } } } | aggregate proxy only ⚠️ |
media | to-many (company_media) | { "media": { "_some": { "field_name": { "_eq": … } } } } | aggregate proxy only ⚠️ |
company_financial | to-one (company_financial) | { "company_financial": { "field_name": { "_eq": … } } } | "field": "company_financial.field_name" ✅ |
company_workspace_connectors | to-many (company_workspace_connector) | { "company_workspace_connectors": { "_some": { "field_name": { "_eq": … } } } } | aggregate proxy only ⚠️ |
field_name with any field of the related object. See its object-reference page for the full field list.
Filter by a to-one relation (and sort by it):
{
"root": "companies",
"whereClause": { "workspace": { "name": { "_ilike": "%acme%" } } },
"orderBy": { "field": "workspace.name", "direction": "asc" }
}
{
"root": "companies",
"whereClause": { "relations": { "_some": { "field_name": { "_gt": 0 } } } }
}
Headers
Bearer token for authentication
Query Parameters
Include detailed relationship data in the response. Comma-separated values supported.
workspace, company, people, documents, created_by, medias, web_links, emails, phones, categories, locations, people, parents, subsidiaries Filter companies created on or after this date
Filter companies created on or before this date
Filter companies updated on or after this date
Filter companies updated on or before this date
Filter companies by creator ID(s)
Filter companies by workspace ID(s)
Filter companies by external workspace ID(s)
Filter companies by email address(es)
Filter companies by phone number(s)
Filter companies by parent registration number(s)
Filter companies by associated document ID(s)
Filter companies by parent company ID(s)
Filter companies by parent company tax ID value(s)
Filter companies by parent company registration value(s)
Filter companies by primary domain URL(s)
Sort companies by field. Use - prefix for descending order.
created_at, -created_at, updated_at, -updated_at, issue_date, -issue_date, due_date, -due_date