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

# Create Company Export

> Create an asynchronous export job to generate a downloadable file of companies

## Overview

This endpoint creates an asynchronous export job that generates a downloadable file containing company data for a specific date range. The export is processed in the background and returns a presigned download URL when complete.

Use this endpoint when you need to extract large volumes of company data efficiently. For real-time needs, use the [List Companies](/api-reference/endpoint/list-companies) endpoint instead.

<Info>
  **When to use exports**: Exports are ideal for bulk data extraction (10,000+ companies). For smaller datasets, use the paginated list endpoint.
</Info>

## Request Body

### Required Parameters

<ParamField body="start_date" type="string" required>
  Start date and time for exporting companies in `YYYY-MM-DD HH:MM:SS` format. Exports companies created from this timestamp in your space's timezone.

  Example: `2024-01-15 00:00:00`
</ParamField>

<ParamField body="end_date" type="string" required>
  End date and time for exporting companies in `YYYY-MM-DD HH:MM:SS` format. Must be after `start_date`. Exports companies created until this timestamp in your space's timezone.

  Example: `2024-01-15 23:59:59`
</ParamField>

## Response

### Success Response (202 Accepted)

<ResponseField name="export_id" type="integer">
  Unique identifier for the export job. Use this to check status with the [Get Company Export](/api-reference/endpoint/get-company-export) endpoint.
</ResponseField>

<ResponseField name="status" type="string">
  Current status of the export. Will be `queued` immediately after creation.
</ResponseField>

### Error Response

<ResponseField name="message" type="string">
  Error description explaining what went wrong
</ResponseField>

## Export File Format

Completed exports are delivered as **gzipped NDJSON** (Newline-Delimited JSON) files. Each line contains a complete JSON object representing one company record.

```json theme={null}
{"id":123,"domain":"example.com","created_at":"2024-01-15T10:23:45Z"}
{"id":124,"domain":"acme.co","created_at":"2024-01-15T14:12:33Z"}
```

This format is ideal for streaming and processing large files line-by-line without loading the entire file into memory.

## Example Requests

<CodeGroup>
  ```bash cURL theme={null}
  # Create export for a date range
  curl -X POST "https://app.cometly.com/public-api/v1/companies/exports" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -d '{
      "start_date": "2024-01-15 00:00:00",
      "end_date": "2024-01-15 23:59:59"
    }'
  ```

  ```javascript JavaScript theme={null}
  // Create export for a date range
  const response = await fetch('https://app.cometly.com/public-api/v1/companies/exports', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Accept': 'application/json',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      start_date: '2024-01-15 00:00:00',
      end_date: '2024-01-15 23:59:59'
    })
  });

  const data = await response.json();
  console.log(`Export created: ${data.export_id}, Status: ${data.status}`);
  ```

  ```php PHP theme={null}
  <?php
  $baseUrl = 'https://app.cometly.com/public-api/v1/companies/exports';
  $headers = [
      'Authorization: Bearer YOUR_API_KEY',
      'Accept: application/json',
      'Content-Type: application/json'
  ];

  $data = json_encode([
      'start_date' => '2024-01-15 00:00:00',
      'end_date' => '2024-01-15 23:59:59'
  ]);

  $ch = curl_init();
  curl_setopt($ch, CURLOPT_URL, $baseUrl);
  curl_setopt($ch, CURLOPT_POST, true);
  curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
  curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

  $response = curl_exec($ch);
  $result = json_decode($response, true);
  curl_close($ch);

  echo "Export created: {$result['export_id']}, Status: {$result['status']}\n";
  ?>
  ```

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

  base_url = 'https://app.cometly.com/public-api/v1/companies/exports'
  headers = {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Accept': 'application/json',
      'Content-Type': 'application/json'
  }

  data = {
      'start_date': '2024-01-15 00:00:00',
      'end_date': '2024-01-15 23:59:59'
  }

  response = requests.post(base_url, headers=headers, json=data)
  result = response.json()
  print(f"Export created: {result['export_id']}, Status: {result['status']}")
  ```
</CodeGroup>

## Status Codes

| Status Code | Description                                                                               |
| ----------- | ----------------------------------------------------------------------------------------- |
| 202         | Export job created and queued for processing                                              |
| 401         | Missing or invalid API key                                                                |
| 403         | API key doesn't have permission or subscription is inactive                               |
| 422         | Invalid parameters provided (check error message for details)                             |
| 429         | Too many requests - rate limit exceeded. See [Rate Limiting](/introduction/rate-limiting) |

## Next Steps

After creating an export, poll the [Get Company Export](/api-reference/endpoint/get-company-export) endpoint to check the status and retrieve the download URL when ready.

## Notes

* **Rate Limit**: This endpoint has a limit of **5 requests per minute** per Space. See [Rate Limiting](/introduction/rate-limiting) for details.
* **Processing Time**: Exports typically complete within seconds to a few minutes depending on data volume
* **Date Range**: Specify any date range using `start_date` and `end_date` (interpreted in your space's timezone)
* **Export Capacity**: Can handle 100,000+ companies per export efficiently
* **Status Checking**: Use the [Get Company Export](/api-reference/endpoint/get-company-export) endpoint to check status (30 requests/min limit)
* **File Expiration**: Download URLs expire after 15 minutes for security. Retrieve the file promptly after completion.
* **Security**: Export files use UUID-based filenames with time-limited presigned URLs to prevent unauthorized access
* **Date Filtering**: Companies are filtered by `created_at` timestamp - only companies created within the specified date range are included