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

# Overview

> Endpoint specification for receiving companies from Enginy

<Warning>
  **Important**: This section describes the API endpoint that **your system must implement** to receive
  companies from Enginy. This is not a Enginy API endpoint — it is the interface specification that Enginy
  will call on your CRM.
</Warning>

## Overview

When exporting companies from Enginy, Enginy will call your `/companies` endpoint to create companies in batch. Your endpoint must accept the companies and return the CRM IDs for each created company.

<Info>
  Companies are created before contacts during export, so contact-company associations can be established.
</Info>

***

## Create Companies

<Card title="Your Implementation Required" icon="triangle-exclamation" color="#f59e0b">
  This endpoint must be implemented on **your server**
</Card>

Enginy calls this endpoint to create companies in your CRM.

### Request

```http theme={null}
POST /companies
Content-Type: application/json
X-API-Key: <your-api-key>
```

### Request Body

```json theme={null}
{
  "companies": [
    {
      "externalId": "789",
      "name": "Acme Inc",
      "domain": "acme.com",
      "industry": "Technology",
      "numberOfEmployees": 150,
      "linkedinUrl": "https://linkedin.com/company/acme"
      // ... additional fields
    }
  ]
}
```

### Request Fields

| Field                           | Type   | Description                                                                 |
| ------------------------------- | ------ | --------------------------------------------------------------------------- |
| `companies`                     | array  | Array of company objects to create                                          |
| `companies[].externalId`        | string | **Required.** Enginy's internal company ID. Use this to map responses back. |
| `companies[].name`              | string | Company name                                                                |
| `companies[].domain`            | string | Company website domain                                                      |
| `companies[].industry`          | string | Industry classification                                                     |
| `companies[].numberOfEmployees` | number | Number of employees                                                         |
| `companies[].linkedinUrl`       | string | LinkedIn company page URL                                                   |
| `companies[].ownerId`           | string | Owner/assignee ID from your `/users` endpoint (if users are supported)      |

<Note>
  Additional fields from the company record will be included. Your CRM should gracefully handle unknown
  fields.
</Note>

<Info>
  **Owner Assignment**: If you implement the optional `/users` endpoint, Enginy will include an `ownerId`
  field when the user selects an owner during export. This allows companies to be assigned to specific CRM
  users.
</Info>

### Common Additional Fields

These fields may be included depending on the company data in Enginy:

| Field               | Type   | Description                                        |
| ------------------- | ------ | -------------------------------------------------- |
| `description`       | string | Company description                                |
| `location`          | string | Company headquarters location                      |
| `foundedYear`       | number | Year the company was founded                       |
| `revenue`           | string | Revenue range                                      |
| `companyType`       | string | Company type (public, private, etc.)               |
| `technologiesUsed`  | string | Technologies detected on company website           |
| `campaigns`         | string | Associated campaign names                          |
| `lastContactedBy`   | string | Last identity that contacted leads at this company |
| `leadCountries`     | string | Countries of leads at this company                 |
| `numberOfCountries` | number | Number of countries with leads                     |

### Financial Data Fields (if available)

| Field                 | Type   | Description                              |
| --------------------- | ------ | ---------------------------------------- |
| `fundingTotal`        | string | Total funding raised                     |
| `fundingStage`        | string | Current funding stage                    |
| `lastFundingAt`       | string | Date of last funding round (ISO format)  |
| `lastFundingType`     | string | Type of last funding (Series A, B, etc.) |
| `lastFundingTotal`    | string | Amount raised in last round              |
| `numFundingRounds`    | number | Total number of funding rounds           |
| `numInvestors`        | number | Number of investors                      |
| `companyLeadInvestor` | string | Lead investor name                       |

***

### Response

<Tabs>
  <Tab title="Success (201)">
    Return a `201 Created` status with the created company IDs.

    ```json theme={null}
    {
      "results": [
        {
          "externalId": "789",
          "crmId": "crm-company-012"
        }
      ]
    }
    ```

    | Field                  | Type   | Description                                  |
    | ---------------------- | ------ | -------------------------------------------- |
    | `results`              | array  | Array of created company mappings            |
    | `results[].externalId` | string | The `externalId` from the request            |
    | `results[].crmId`      | string | **Required.** Your CRM's ID for this company |
  </Tab>

  <Tab title="Partial Success (201)">
    If some companies fail, return success for those that worked.

    ```json theme={null}
    {
      "results": [
        {
          "externalId": "789",
          "crmId": "crm-company-012"
        }
      ],
      "errors": [
        {
          "externalId": "790",
          "error": "Company with this domain already exists"
        }
      ]
    }
    ```
  </Tab>

  <Tab title="Error (4xx/5xx)">
    Return an appropriate error status if the entire batch fails.

    ```json theme={null}
    {
      "error": "Invalid request",
      "message": "Missing required field: companies"
    }
    ```
  </Tab>
</Tabs>

***

## Batch Size

Enginy sends companies in batches of up to **100 companies** per request. Your endpoint should be able to handle this batch size efficiently.

***

## Testing Your Endpoint

Test your companies endpoint with this curl command:

```bash theme={null}
curl -X POST https://your-crm.com/companies \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "companies": [
      {
        "externalId": "test-789",
        "name": "Test Company",
        "domain": "testcompany.com",
        "industry": "Technology"
      }
    ]
  }'
```

Expected response:

```json theme={null}
{
  "results": [
    {
      "externalId": "test-789",
      "crmId": "your-crm-company-id-here"
    }
  ]
}
```

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Contacts API" icon="user" href="/api-reference/custom-crm/contacts">
    Implement the contacts endpoint
  </Card>

  <Card title="Associations API" icon="link" href="/api-reference/custom-crm/associations">
    Link contacts to companies
  </Card>

  <Card title="Examples" icon="code" href="/api-reference/custom-crm/examples">
    See complete implementation examples
  </Card>
</CardGroup>