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

# API Overview

> Introduction to the Huntd External API

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.