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

# API Overview

> Introduction to the Huntd External API

<Note>
  **Company Lookup is a paid feature.** It must be enabled for your organization before you can
  use these endpoints. [Contact Huntd](mailto:support@gethuntd.com) to enable it.
</Note>

Feel free to proceed to the Get Started page, copy the page as markdown, and give it as context to your favorite coding agent along with your API key. It will smoothly proceed with the integration.

## Available Endpoints

| Endpoint                                         | Method | Description                 |
| ------------------------------------------------ | ------ | --------------------------- |
| `/api/v1/external/company-lookup`                | POST   | Submit a company lookup job |
| `/api/v1/external/company-lookup/{jobId}/result` | GET    | Get lookup job result       |

## How It Works

1. **Submit a lookup** - POST a domain to start a lookup job
2. **Get job ID** - Receive a job ID immediately (async processing)
3. **Poll or webhook** - Either poll for results or receive them via webhook

## Request Format

All POST requests should include:

* `Content-Type: application/json` header
* `X-API-Key: your_api_key` header
* JSON request body

```bash theme={null}
curl -X POST https://api.gethuntd.com/api/v1/external/company-lookup \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -d '{"domain": "example.com"}'
```

## Response Format

### Success Response

```json theme={null}
{
  "success": true,
  "data": {
    "job_id": "job_1705596234567_a1b2c3d4",
    "domain": "example.com",
    "sources": ["source_name"],
    "scheduled_for": "immediate"
  }
}
```

### Error Response

```json theme={null}
{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message"
  }
}
```

## Credits

API usage is tracked via credits. Company lookups are charged **1 credit per contact** returned.

## Rate Limits

The API enforces rate limits. When rate limited, you'll receive a `429` response with `RATE_LIMIT_EXCEEDED` error code.