> ## 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](https://docs.cometly.com/api-reference/endpoint/list-companies.md) endpoint instead.

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

## Request Body

### Required Parameters

**start\_date** `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`

**end\_date** `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`

## Response

### Success Response (202 Accepted)

**export\_id** `string`

Unique identifier for the export job. Use this to check status with the [Get Company Export](https://docs.cometly.com/api-reference/endpoint/get-company-export.md) endpoint.

**status** `string`

Current status of the export. Will be `queued` immediately after creation.

### Error Response

**message** `string`

Error description explaining what went wrong

## 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

```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']}")
```

## 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](https://docs.cometly.com/introduction/rate-limiting.md) |

## Next Steps

After creating an export, poll the [Get Company Export](https://docs.cometly.com/api-reference/endpoint/get-company-export.md) 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](https://docs.cometly.com/introduction/rate-limiting.md) 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](https://docs.cometly.com/api-reference/endpoint/get-company-export.md) 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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.