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

# Quickstart

> Get started with the Huntd API in 5 minutes

<Tip>
  This page can be copied as markdown and given as context to any AI coding agent along with your Huntd API key for easy implementation.
</Tip>

## 1. Get your API Key

Contact your organization administrator to get an API key. Keys follow this format:

```
hntd_{id}_{secret}
```

<Warning>
  Keep your API key secret. Never expose it in client-side code.
</Warning>

## 2. Submit a Company Lookup

Look up contacts at any company by domain:

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

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.gethuntd.com/api/v1/external/company-lookup', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': process.env.HUNTD_API_KEY
    },
    body: JSON.stringify({ domain: 'example.com' })
  });

  const { data } = await response.json();
  console.log('Job ID:', data.job_id);
  ```

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

  response = requests.post(
      'https://api.gethuntd.com/api/v1/external/company-lookup',
      headers={
          'Content-Type': 'application/json',
          'X-API-Key': os.environ['HUNTD_API_KEY']
      },
      json={'domain': 'example.com'}
  )

  data = response.json()
  print(f"Job ID: {data['data']['job_id']}")
  ```
</CodeGroup>

You'll receive a job ID immediately:

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

## 3. Get Results

Poll for results using the job ID:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.gethuntd.com/api/v1/external/company-lookup/job_1705596234567_a1b2c3d4/result" \
    -H "X-API-Key: hntd_abc12345_yoursecretkey"
  ```

  ```javascript JavaScript theme={null}
  const jobId = 'job_1705596234567_a1b2c3d4';

  const result = await fetch(
    `https://api.gethuntd.com/api/v1/external/company-lookup/${jobId}/result`,
    { headers: { 'X-API-Key': process.env.HUNTD_API_KEY } }
  );

  const data = await result.json();
  console.log(data.contacts);
  ```

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

  job_id = 'job_1705596234567_a1b2c3d4'

  response = requests.get(
      f'https://api.gethuntd.com/api/v1/external/company-lookup/{job_id}/result',
      headers={'X-API-Key': os.environ['HUNTD_API_KEY']}
  )

  data = response.json()
  print(data['contacts'])
  ```
</CodeGroup>

When complete, you'll get the contacts:

```json theme={null}
{
  "job_id": "job_1705596234567_a1b2c3d4",
  "domain": "example.com",
  "source": "source_name",
  "status": "success",
  "contacts": [
    {
      "first_name": "John",
      "last_name": "Doe",
      "email": "john.doe@example.com",
      "job_title": "Senior Software Engineer",
      "linkedin_url": "https://linkedin.com/in/johndoe",
      "company": "Example Corp",
      "company_domain": "example.com",
      "verifications": [
        {
          "source": "source_name",
          "isVerified": true
        }
      ]
    }
  ],
  "credits_used": 1,
  "created_at": "2024-01-18T12:30:00.000Z"
}
```

<Tip>
  Instead of polling, you can provide a `webhook_url` when submitting the lookup to receive results automatically.
</Tip>

### Example with Webhook

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.gethuntd.com/api/v1/external/company-lookup \
    -H "Content-Type: application/json" \
    -H "X-API-Key: hntd_abc12345_yoursecretkey" \
    -d '{
      "domain": "example.com",
      "webhook_url": "https://yourapp.com/webhooks/huntd"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.gethuntd.com/api/v1/external/company-lookup', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': process.env.HUNTD_API_KEY
    },
    body: JSON.stringify({
      domain: 'example.com',
      webhook_url: 'https://yourapp.com/webhooks/huntd'
    })
  });

  const { data } = await response.json();
  console.log('Job ID:', data.job_id);
  // Results will be sent to your webhook URL when ready
  ```

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

  response = requests.post(
      'https://api.gethuntd.com/api/v1/external/company-lookup',
      headers={
          'Content-Type': 'application/json',
          'X-API-Key': os.environ['HUNTD_API_KEY']
      },
      json={
          'domain': 'example.com',
          'webhook_url': 'https://yourapp.com/webhooks/huntd'
      }
  )

  data = response.json()
  print(f"Job ID: {data['data']['job_id']}")
  # Results will be sent to your webhook URL when ready
  ```
</CodeGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="API Reference" icon="code" href="/api-reference/company-lookup/submit-lookup">
    Full API documentation
  </Card>

  <Card title="Webhooks" icon="webhook" href="/api-reference/webhooks">
    Set up webhook callbacks
  </Card>
</CardGroup>