> ## Documentation Index
> Fetch the complete documentation index at: https://docs.peoplecontext.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Company Enrichment API

> Enrich company profiles using LinkedIn company identifiers

## Endpoint

```http theme={null}
POST /v1/company/enrich
```

This endpoint enriches a company's profile by searching LinkedIn company data using various identifiers.

***

## Authentication

<ParamField header="Authorization" type="string" required>
  Bearer token with your API key: `Bearer YOUR_API_KEY`
</ParamField>

See the [Authentication Guide](/guides/authentication) for detailed setup instructions.

***

## Request Parameters

### Request Body (JSON)

At least one identifier is required:

<ParamField body="linkedin_slug" type="string">
  LinkedIn company slug (e.g., from linkedin.com/company/**openai**).

  **Example:** `"openai"`
</ParamField>

<ParamField body="linkedin_id" type="string">
  LinkedIn's internal company ID.

  **Example:** `"11130470"`
</ParamField>

<ParamField body="linkedin_url" type="string">
  Full LinkedIn company URL. The API will automatically extract the slug.

  **Example:** `"linkedin.com/company/openai"`

  **Example:** `"https://www.linkedin.com/company/openai/"`
</ParamField>

<ParamField body="company_id" type="string">
  Internal company ID from People Context API.

  **Example:** `"abc123"`
</ParamField>

<Note>
  **Identifier Priority**: Identifiers are tried in this order: `linkedin_slug` > `linkedin_id` > `linkedin_url` (slug extracted) > `company_id`. The API returns as soon as a match is found.
</Note>

***

## Response

### Success Response (200 OK)

Returns a JSON object containing the enriched company data.

<ResponseField name="matched" type="boolean">
  Whether a matching company was found in the database.
</ResponseField>

<ResponseField name="company" type="object | null">
  Company data object (null if no match found)

  <ResponseField name="company_id" type="string">
    Internal company ID
  </ResponseField>

  <ResponseField name="linkedin_slug" type="string">
    LinkedIn company slug
  </ResponseField>

  <ResponseField name="linkedin_id" type="string">
    LinkedIn's internal company ID
  </ResponseField>

  <ResponseField name="profile" type="object">
    Company profile information

    <ResponseField name="name" type="string">
      Company name
    </ResponseField>

    <ResponseField name="tagline" type="string">
      Company tagline/description
    </ResponseField>

    <ResponseField name="description" type="string">
      Full company description
    </ResponseField>

    <ResponseField name="industry" type="string">
      Industry category
    </ResponseField>

    <ResponseField name="company_size" type="string">
      Company size range (e.g., "51-200 employees")
    </ResponseField>

    <ResponseField name="employees" type="integer">
      Approximate employee count
    </ResponseField>

    <ResponseField name="founded" type="integer">
      Year founded
    </ResponseField>

    <ResponseField name="website" type="string">
      Company website URL
    </ResponseField>

    <ResponseField name="phone" type="string">
      Company phone number
    </ResponseField>

    <ResponseField name="specialties" type="array">
      Array of company specialties/focus areas
    </ResponseField>
  </ResponseField>

  <ResponseField name="headquarters" type="object">
    Headquarters location information

    <ResponseField name="city" type="string">
      City name
    </ResponseField>

    <ResponseField name="region" type="string">
      State/region code
    </ResponseField>

    <ResponseField name="country" type="string">
      Country name
    </ResponseField>

    <ResponseField name="postal_code" type="string">
      Postal/ZIP code
    </ResponseField>

    <ResponseField name="line1" type="string">
      Street address line 1
    </ResponseField>

    <ResponseField name="line2" type="string">
      Street address line 2
    </ResponseField>
  </ResponseField>

  <ResponseField name="images" type="object">
    Company media assets

    <ResponseField name="logo" type="string">
      Company logo URL
    </ResponseField>

    <ResponseField name="cover" type="string">
      Cover/banner image URL
    </ResponseField>
  </ResponseField>

  <Note>Additional fields may be present depending on the data available in the LinkedIn company profile.</Note>
</ResponseField>

### No Match Response (200 OK)

When no matching company is found:

```json theme={null}
{
  "matched": false,
  "company": null
}
```

### Error Responses

All error responses follow the standard format with a `detail` field:

```json theme={null}
{
  "detail": "Error message describing what went wrong"
}
```

**Error Status Codes:**

* **401 Unauthorized** - Missing or invalid API key
* **403 Forbidden** - Organization is inactive
* **422 Unprocessable Entity** - Validation error (missing required parameters or invalid values)
* **429 Too Many Requests** - Monthly request limit exceeded
* **500 Internal Server Error** - Unexpected server error (e.g., Elasticsearch connection failed)

***

## Examples

<CodeGroup>
  ```bash cURL theme={null}
  # Enrich by LinkedIn slug
  curl -X POST "https://api.peoplecontext.com/v1/company/enrich" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"linkedin_slug": "openai"}'

  # Enrich by LinkedIn ID
  curl -X POST "https://api.peoplecontext.com/v1/company/enrich" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"linkedin_id": "11130470"}'

  # Enrich by LinkedIn URL (slug extracted automatically)
  curl -X POST "https://api.peoplecontext.com/v1/company/enrich" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"linkedin_url": "linkedin.com/company/openai"}'
  ```

  ```python Python theme={null}
  import requests

  url = "https://api.peoplecontext.com/v1/company/enrich"
  headers = {
      "Authorization": "Bearer YOUR_API_KEY",
      "Content-Type": "application/json"
  }

  # Enrich by LinkedIn slug
  payload = {
      "linkedin_slug": "openai"
  }

  response = requests.post(url, headers=headers, json=payload)
  data = response.json()

  if data["matched"]:
      company = data["company"]
      print(f"Name: {company['profile']['name']}")
      print(f"Industry: {company['profile']['industry']}")
      print(f"Employees: {company['profile']['employees']}")
      print(f"Founded: {company['profile']['founded']}")
      print(f"Location: {company['headquarters']['city']}, {company['headquarters']['region']}")
  else:
      print("No match found")
  ```

  ```javascript JavaScript theme={null}
  // Enrich by LinkedIn slug
  const response = await fetch(
    'https://api.peoplecontext.com/v1/company/enrich',
    {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        linkedin_slug: 'openai'
      })
    }
  );

  const data = await response.json();

  if (data.matched) {
    const company = data.company;
    console.log(`Name: ${company.profile.name}`);
    console.log(`Industry: ${company.profile.industry}`);
    console.log(`Employees: ${company.profile.employees}`);
    console.log(`Location: ${company.headquarters.city}, ${company.headquarters.region}`);
  } else {
    console.log('No match found');
  }
  ```

  ```php PHP theme={null}
  <?php
  $ch = curl_init();

  $payload = json_encode([
      'linkedin_slug' => 'openai'
  ]);

  curl_setopt($ch, CURLOPT_URL, "https://api.peoplecontext.com/v1/company/enrich");
  curl_setopt($ch, CURLOPT_POST, true);
  curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_HTTPHEADER, [
      'Authorization: Bearer YOUR_API_KEY',
      'Content-Type: application/json'
  ]);

  $response = curl_exec($ch);
  curl_close($ch);

  $data = json_decode($response, true);

  if ($data['matched']) {
      $company = $data['company'];
      echo "Name: " . $company['profile']['name'] . "\n";
      echo "Industry: " . $company['profile']['industry'] . "\n";
      echo "Employees: " . $company['profile']['employees'] . "\n";
  }
  ?>
  ```
</CodeGroup>

***

## Sample Response

```json theme={null}
{
  "matched": true,
  "company": {
    "company_id": "abc123",
    "linkedin_slug": "openai",
    "linkedin_id": "11130470",
    "profile": {
      "name": "OpenAI",
      "tagline": "Creating safe AGI that benefits all of humanity.",
      "description": "OpenAI is an AI research and deployment company...",
      "industry": "Research Services",
      "company_size": "201-500 employees",
      "employees": 5701,
      "founded": 2015,
      "website": "https://openai.com",
      "phone": null,
      "specialties": [
        "Artificial Intelligence",
        "Machine Learning",
        "Natural Language Processing",
        "Research"
      ]
    },
    "headquarters": {
      "city": "San Francisco",
      "region": "CA",
      "country": "United States",
      "postal_code": "94110",
      "line1": "3180 18th St",
      "line2": null
    },
    "images": {
      "logo": "https://media.licdn.com/dms/image/...",
      "cover": "https://media.licdn.com/dms/image/..."
    }
  }
}
```

***

## Best Practices

<Tip>
  **URL Flexibility**: You can pass full LinkedIn URLs - the API automatically extracts the company slug. This is useful when scraping or working with raw LinkedIn links.
</Tip>

<Warning>
  **Rate Limits**: API requests are subject to rate limits based on your organization's plan. Monitor your monthly request count to avoid hitting limits.
</Warning>

<Note>
  **Data Freshness**: LinkedIn company data is refreshed monthly. Check the profile data for recent updates and employee counts.
</Note>

***

## Use Cases

* **Lead Enrichment**: Enrich company information from LinkedIn URLs in your CRM
* **Market Research**: Build company databases with detailed profile information
* **Sales Intelligence**: Get company size, industry, and location data for targeting
* **Data Validation**: Verify company information against LinkedIn's authoritative data

***

## Related

* [Person Enrichment API](/api-reference/person/enrich) - Enrich individual profiles
* [Quickstart](/quickstart) - Get started in 5 minutes
* [Introduction](/introduction) - Learn about People Context API