thecompaniesapi/sdk-php

PHP SDK for The Companies API

v1.0.1 2025-07-22 23:20 UTC

Requires

• php: >=8.0
• guzzlehttp/guzzle: ^7.0

Requires (Dev)

• phpunit/phpunit: ^10.0|^11.0
• vlucas/phpdotenv: ^5.0

MIT

• The Companies API SARL

README

A fully-featured PHP SDK for The Companies API, providing type-safe access to company data, locations, industries, technologies, job titles, lists, and more.

If you need more details about a specific endpoint, you can find the corresponding documentation in the API reference.

You can also contact us on our livechat if you have any questions.

🚀 Features

• Expose all our 30+ endpoints and gives access to 50M+ companies from your codebase
• Type-safe API client with full access to our OpenAPI schemas
• Real-time company enrichment with both synchronous and asynchronous options
• Powerful search capabilities with filters, sorting and pagination
• Create and manage your company lists
• Track and monitor enrichment actions and requests
• Generate detailed analytics and insights for searches and lists
• Natural language querying for structured company information
• Lightweight with minimal dependencies

📦 Installation

Install the SDK using Composer:

composer require thecompaniesapi/sdk-php

🔑 Initialize the client

Get your API token from your settings page and initialize our client.

The API token is required to authenticate your requests and should be kept secure. Never commit your API token to version control or share it publicly.

<?php

require_once 'vendor/autoload.php';

use TheCompaniesApi\Sdk\Client;

$client = new Client([
    'apiToken' => 'your-api-token',
]);

🏬 Companies

Search companies

📖 Documentation

🕹️ Use case: How to build a company search engine with our API

🔍 To learn more about our query system, please read our documentation.

// Search companies by industry and size
$response = $client->searchCompanies([
    'query' => [
        ['attribute' => 'about.industries', 'operator' => 'or', 'sign' => 'equals', 'values' => ['computer-software']],
        ['attribute' => 'about.totalEmployees', 'operator' => 'or', 'sign' => 'equals', 'values' => ['10-50']]
    ],
    'size' => 25
]);

$companies = $response->data->companies; // Companies that match the query
$meta = $response->data->meta; // Meta information

Search companies by name

📖 Documentation

🕹️ Use case: Add a company search with autocomplete to your application

$response = $client->searchCompaniesByName([
    'name' => 'The Companies API',
    'size' => 2
]);

$companies = $response->data->companies; // Companies that match the name
$meta = $response->data->meta; // Meta information

Search companies using a prompt

📖 Documentation

// Search 25 companies for a specific prompt
$response = $client->searchCompaniesByPrompt([
    'prompt' => 'SaaS Companies in the United States with more than 100 employees',
    'size' => 25
]);

$companies = $response->data->companies; // Companies that match the prompt
$meta = $response->data->meta; // Meta information

Search similar companies

📖 Documentation

// Search 25 companies that are similar to Crisp and Intercom
$response = $client->searchSimilarCompanies([
    'domains' => ['crisp.chat', 'intercom.com'],
    'size' => 25
]);

$companies = $response->data->companies; // Companies that are similar to the domains
$meta = $response->data->meta; // Meta information

Count companies matching your query

📖 Documentation

// Count how many companies are in the computer-software industry
$response = $client->countCompanies([
    'query' => [
        [
            'attribute' => 'about.industries',
            'operator' => 'or',
            'sign' => 'equals',
            'values' => ['computer-software']
        ]
    ]
]);

$count = $response->data; // Number of companies that match the query

Enrich a company from a domain name

📖 Documentation

// Fetch company data from our database without enrichment (faster response)
$response = $client->fetchCompany('microsoft.com');

$company = $response->data; // The company profile

// Fetch company data and re-analyze it in real-time to get fresh, up-to-date information (slower but more accurate)
$response = $client->fetchCompany('microsoft.com', [
    'refresh' => true
]);

$company = $response->data; // The company profile

Enrich a company from an email

📖 Documentation

🕹️ Use case: Enrich your users at signup with the latest information about their company

// Fetch the company profile behind a professional email address
$response = $client->fetchCompanyByEmail([
    'email' => '[e-mail]'
]);

$company = $response->data; // The company profile

Enrich a company from a social network URL

📖 Documentation

// Fetch the company profile behind a social network URL
$response = $client->fetchCompanyBySocial([
    'linkedin' => 'https://www.linkedin.com/company/apple'
]);

$company = $response->data; // The company profile

Find a company email patterns

📖 Documentation

// Fetch the company email patterns for a specific domain
$response = $client->fetchCompanyEmailPatterns('apple.com');

$patterns = $response->data; // The company email patterns

Ask a question about a company

📖 Documentation

// Ask what products a company offers using its domain
$response = $client->askCompany('microsoft.com', [
    'question' => 'What products does this company offer?',
    'model' => 'large', // 'small' is also available
    'fields' => [
        [
            'key' => 'products',
            'type' => 'array|string',
            'description' => 'The products that the company offers'
        ]
    ]
]);

$answer = $response->data->answer; // Structured AI response
$meta = $response->data->meta; // Meta information

Fetch the context of a company

📖 Documentation

// Get AI-generated strategic insights about a company
$response = $client->fetchCompanyContext('microsoft.com');

$context = $response->data->context; // Includes market, model, differentiators, etc.
$meta = $response->data->meta; // Meta information

Fetch analytics data for a query or your lists

📖 Documentation

// Analyze company distribution by business type
$response = $client->fetchCompaniesAnalytics([
    'attribute' => 'about.businessType',
    'query' => [
        [
            'attribute' => 'locations.headquarters.country.code',
            'operator' => 'or',
            'sign' => 'equals',
            'values' => ['us', 'gb', 'fr']
        ]
    ]
]);

$analytics = $response->data->data; // Aggregated values
$meta = $response->data->meta; // Meta information

Export analytics data in multiple formats for a search

📖 Documentation

// Export analytics to CSV
$response = $client->exportCompaniesAnalytics([
    'format' => 'csv',
    'attributes' => ['about.industries', 'about.totalEmployees'],
    'query' => [
        [
            'attribute' => 'technologies.active',
            'operator' => 'or',
            'sign' => 'equals',
            'values' => ['shopify']
        ]
    ]
]);

$analytics = $response->data->data; // Aggregated values
$meta = $response->data->meta; // Meta information

🎯 Actions

Request an action on one or more companies

📖 Documentation

// Request an enrichment job on multiple companies
$response = $client->requestAction([
    'domains' => ['microsoft.com', 'apple.com'],
    'job' => 'enrich-companies',
    'estimate' => false
]);

$actions = $response->data->actions; // Track this via fetchActions
$meta = $response->data->meta; // Meta information

Fetch the actions for your account

📖 Documentation

// Fetch recent actions
$response = $client->fetchActions([
    'status' => 'completed',
    'page' => 1,
    'size' => 5
]);

$actions = $response->data->actions; // Actions that match the query
$meta = $response->data->meta; // Meta information

Retry a failed action

📖 Documentation

// Retry a failed action
$response = $client->retryAction('action-id-123', [
    'reason' => 'Network timeout resolved'
]);

$action = $response->data; // Updated action status

🏭 Industries

Search industries

📖 Documentation

// Search industries by keyword
$response = $client->searchIndustries([
    'search' => 'software',
    'size' => 10
]);

$industries = $response->data->industries; // Industries that match the keyword
$meta = $response->data->meta; // Meta information

Find similar industries

📖 Documentation

// Find industries similar to given ones
$response = $client->searchIndustriesSimilar([
    'industries' => ['saas', 'fintech']
]);

$similar = $response->data->industries; // Industries that are similar to the given ones
$meta = $response->data->meta; // Meta information

⚛️ Technologies

Search technologies

📖 Documentation

// Search technologies by keyword
$response = $client->searchTechnologies([
    'search' => 'shopify',
    'size' => 10
]);

$technologies = $response->data->technologies; // Technologies that match the keyword
$meta = $response->data->meta; // Meta information

🌍 Locations

Search cities

📖 Documentation

// Search cities by name
$response = $client->searchCities([
    'search' => 'new york',
    'size' => 5
]);

$cities = $response->data->cities; // Cities that match the name
$meta = $response->data->meta; // Meta information

Search counties

📖 Documentation

// Search counties by name
$response = $client->searchCounties([
    'search' => 'orange',
    'size' => 5
]);

$counties = $response->data->counties; // Counties that match the name
$meta = $response->data->meta; // Meta information

Search states

📖 Documentation

// Search states by name
$response = $client->searchStates([
    'search' => 'california',
    'size' => 5
]);

$states = $response->data->states; // States that match the name
$meta = $response->data->meta; // Meta information

Search countries

📖 Documentation

// Search countries by name
$response = $client->searchCountries([
    'search' => 'france',
    'size' => 5
]);

$countries = $response->data->countries; // Countries that match the name
$meta = $response->data->meta; // Meta information

Search continents

📖 Documentation

// Search continents by name
$response = $client->searchContinents([
    'search' => 'asia',
    'size' => 5
]);

$continents = $response->data->continents; // Continents that match the name
$meta = $response->data->meta; // Meta information

💼 Job titles

Enrich a job title from its name

📖 Documentation

// Enrich "chief marketing officer"
$response = $client->enrichJobTitles([
    'name' => 'chief marketing officer'
]);

$jobTitle = $response->data; // Contains department, seniority, etc.

📋 Lists

Fetch your lists

📖 Documentation

// Fetch your lists
$response = $client->fetchLists();

$lists = $response->data->lists; // Lists that match the query
$meta = $response->data->meta; // Meta information

Create a list of companies

📖 Documentation

// Create a list of companies
$response = $client->createList([
    'name' => 'My SaaS List',
    'type' => 'companies'
]);

$newList = $response->data; // The new list

Update a list

📖 Documentation

// Update a list
$response = $client->updateList('1234', [
    'name' => 'Updated SaaS List',
    'description' => 'Updated list description'
]);

$updatedList = $response->data; // The updated list

Delete a list

📖 Documentation

// Delete a list
$response = $client->deleteList('1234');

$result = $response->data; // Deletion confirmation

Fetch companies in your list

📖 Documentation

// Fetch companies in a list
$response = $client->fetchCompaniesInList('1234');

$companies = $response->data->companies; // Companies that match the list
$meta = $response->data->meta; // Meta information

Fetch companies in your list with POST body

📖 Documentation

// Fetch companies in a list with additional filtering
$response = $client->fetchCompaniesInListPost('1234', [
    'query' => [
        [
            'attribute' => 'about.totalEmployees',
            'operator' => 'or',
            'sign' => 'gte',
            'values' => ['100']
        ]
    ],
    'size' => 10
]);

$companies = $response->data->companies; // Filtered companies in the list
$meta = $response->data->meta; // Meta information

Get a specific company in your list

📖 Documentation

// Get a specific company in a list
$response = $client->fetchCompanyInList('1234', 'apple.com');

$company = $response->data; // The company in the list

Add or remove companies in your list

📖 Documentation

// Add companies to a list
$response = $client->toggleCompaniesInList('1234', [
    'companies' => ['apple.com', 'stripe.com'],
    'action' => 'add'
]);

$list = $response->data; // The updated list

// Remove companies from a list
$response = $client->toggleCompaniesInList('1234', [
    'companies' => ['apple.com'],
    'action' => 'remove'
]);

$list = $response->data; // The updated list

👥 Teams

Fetch your team

📖 Documentation

// Fetch your team details
$response = $client->fetchTeam('team-id-123');

$team = $response->data; // Your team details

Update your team

📖 Documentation

// Update your team
$response = $client->updateTeam('team-id-123', [
    'name' => 'Updated Team Name',
    'description' => 'Updated team description'
]);

$team = $response->data; // Updated team details

👤 User

Fetch current user information

📖 Documentation

// Fetch current user details
$response = $client->fetchUser();

$user = $response->data; // Current user information

🤖 Prompts

Fetch prompts history

📖 Documentation

// Fetch prompts history
$response = $client->fetchPrompts([
    'page' => 1,
    'size' => 10
]);

$prompts = $response->data->prompts; // Prompts history
$meta = $response->data->meta; // Meta information

Delete a prompt

📖 Documentation

// Delete a prompt
$response = $client->deletePrompt('prompt-id-123');

$result = $response->data; // Deletion confirmation

Query the product prompt

📖 Documentation

// Query the product prompt
$response = $client->productPrompt([
    'query' => 'Find companies similar to Slack',
    'context' => 'collaboration software'
]);

$result = $response->data; // Product prompt response

Convert a query to a segmentation

📖 Documentation

// Convert a natural language query to segmentation
$response = $client->promptToSegmentation([
    'prompt' => 'Companies in California with more than 100 employees'
]);

$segmentation = $response->data; // Generated segmentation query

🔧 Utilities

Fetch the health of the API

📖 Documentation

// Check API health status
$response = $client->fetchApiHealth();

$health = $response->data; // The health of the API

Fetch the OpenAPI schema

📖 Documentation

// Fetch OpenAPI schema
$response = $client->fetchOpenApi();

$schema = $response->data; // The OpenAPI schema

🔄 Advanced Usage

Using typed request/response objects

use TheCompaniesApi\Sdk\Generated\Requests\SearchCompaniesPostRequest;
use TheCompaniesApi\Sdk\Generated\Requests\CreateListRequest;

// Create a typed request object
$request = new SearchCompaniesPostRequest(
    query: [
        [
            'attribute' => 'about.industries',
            'operator' => 'or',
            'sign' => 'equals',
            'values' => ['technology']
        ]
    ],
    size: 25,
    page: 1
);

// Use the typed request
$response = $client->searchCompaniesPost($request);

// Create a list with typed request
$listRequest = new CreateListRequest(
    name: 'Tech Companies',
    type: 'companies'
);

$listResponse = $client->createList($listRequest);

Error handling

use TheCompaniesApi\Sdk\ApiException;

try {
    $response = $client->fetchCompany('invalid-domain');
} catch (ApiException $e) {
    echo "API Error: " . $e->getMessage() . "\n";
    echo "Status Code: " . $e->getStatusCode() . "\n";
    echo "Response Data: " . json_encode($e->getResponseData()) . "\n";
    
    // Check error type
    if ($e->isClientError()) {
        echo "Client error (4xx)\n";
    } elseif ($e->isServerError()) {
        echo "Server error (5xx)\n";
    } elseif ($e->isNetworkError()) {
        echo "Network error\n";
    }
}

Custom configuration

use TheCompaniesApi\Sdk\Configuration;

$config = new Configuration([
    'apiToken' => 'your-api-token',
    'baseUrl' => 'https://api.thecompaniesapi.com',
    'visitorId' => 'unique-visitor-id',
    'timeout' => 60,
    'verifySSL' => true,
    'defaultHeaders' => [
        'X-Custom-Header' => 'custom-value'
    ]
]);

$client = new Client($config);

📄 License

This SDK is released under the MIT License. See LICENSE for details.

🔗 Links

• The Companies API
• API Documentation
• TypeScript SDK
• Support & Live Chat