> ## 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.
# Get Lookup Result
> Retrieve the result of a company lookup job.
```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 response = 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 response.json();
if (response.status === 200) {
console.log('Job completed');
} else if (response.status === 202) {
console.log('Job still processing...');
}
```
```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(f"Status: {data['status']}")
```
```json 200 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,
"verifiedAt": "2024-01-18T12:25:00.000Z",
"status": "verified"
}
]
}
],
"credits_used": 1,
"created_at": "2024-01-18T12:30:00.000Z"
}
```
```json 202 theme={null}
{
"job_id": "job_1705596234567_a1b2c3d4",
"status": "processing",
"message": "Job is still processing. Please try again later."
}
```
```json 400 theme={null}
{
"success": false,
"error": {
"code": "INVALID_REQUEST",
"message": "Job ID is required"
}
}
```
```json 401 theme={null}
{
"success": false,
"error": {
"code": "INVALID_API_KEY",
"message": "API key is missing, invalid, malformed, or disabled"
}
}
```
```json 403 theme={null}
{
"success": false,
"error": {
"code": "ACCESS_DENIED",
"message": "You do not have access to this job"
}
}
```
```json 500 theme={null}
{
"job_id": "job_1705596234567_a1b2c3d4",
"domain": "example.com",
"source": "source_name",
"status": "error",
"contacts": [],
"credits_used": 0,
"created_at": "2024-01-18T12:30:00.000Z",
"error_code": "COMPANY_NOT_FOUND",
"message": "We could not find a company for this domain. Please verify the domain."
}
```
## Overview
Retrieve the result of a company lookup job.
## Path Parameters
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | --------------------------------- |
| `jobId` | string | Yes | Job ID from the lookup submission |
## Response Status Codes
| HTTP Code | Status | Description |
| --------- | ------------ | --------------------------------- |
| 200 | `success` | Job completed |
| 202 | `processing` | Job still processing |
| 202 | `queued` | Job waiting for daily limit reset |
| 500 | `error` | Job failed |
## Response Fields (Success/Error)
| Field | Type | Description |
| -------------- | ------- | ------------------------------------------- |
| `job_id` | string | The job identifier |
| `domain` | string | The domain that was looked up |
| `source` | string | Data source used for the lookup |
| `status` | string | Job status: `success` or `error` |
| `contacts` | array | Array of contacts found |
| `credits_used` | integer | Credits consumed (1 per contact) |
| `created_at` | string | ISO 8601 timestamp |
| `error_code` | string | Error code (only when status is `error`) |
| `message` | string | Error message (only when status is `error`) |
## Response Fields (Processing)
When the job is still processing (not yet in database):
| Field | Type | Description |
| --------- | ------ | ------------------- |
| `job_id` | string | The job identifier |
| `status` | string | Always `processing` |
| `message` | string | Status message |
## Response Fields (Queued)
When the job is queued due to daily limit:
| Field | Type | Description |
| --------------------------- | ------- | ----------------------------------------- |
| `job_id` | string | The job identifier |
| `domain` | string | The domain that was looked up |
| `source` | string | Data source used for the lookup |
| `status` | string | Always `queued` |
| `contacts` | array | Empty array |
| `credits_used` | integer | 0 |
| `created_at` | string | ISO 8601 timestamp |
| `message` | string | Status message |
| `scheduled_processing_time` | string | When the job will be processed (ISO 8601) |
## Contact Object
Each contact in the `contacts` array contains:
| Field | Type | Description |
| ---------------- | ------ | ----------------------------------- |
| `first_name` | string | Contact's first name |
| `last_name` | string | Contact's last name |
| `email` | string | Contact's email address |
| `job_title` | string | Contact's job title |
| `linkedin_url` | string | LinkedIn profile URL |
| `company` | string | Company name |
| `company_domain` | string | Company domain |
| `verifications` | array | Verification status for each source |
## Verification Object
Each verification in the `verifications` array contains:
| Field | Type | Description |
| ------------ | ------------ | ----------------------------------------------------- |
| `source` | string | Source name |
| `isVerified` | boolean/null | `true` if verified, `false` if not, `null` if pending |
| `verifiedAt` | string | ISO 8601 timestamp of when verification was performed |
| `status` | string | Status message |
| `error` | string | Error message (if verification failed) |
Only contacts with `isVerified: true` for the requested source are returned in the response.
## Polling Strategy
When polling for results:
1. Start polling after 5-10 seconds
2. Use exponential backoff (e.g., 5s, 10s, 20s)
3. Stop after 5 minutes
```javascript theme={null}
async function pollForResult(jobId, maxAttempts = 10) {
const baseDelay = 5000;
for (let attempt = 0; attempt < maxAttempts; attempt++) {
const response = await fetch(
`https://api.gethuntd.com/api/v1/external/company-lookup/${jobId}/result`,
{ headers: { 'X-API-Key': process.env.HUNTD_API_KEY } }
);
if (response.status !== 202) {
return await response.json();
}
await new Promise(r => setTimeout(r, baseDelay * Math.pow(2, attempt)));
}
throw new Error('Job timed out');
}
```
## Errors
| HTTP | Error Code | Description |
| ---- | ---------------------- | ---------------------------------------------------------------------------- |
| 400 | `INVALID_REQUEST` | Job ID is required |
| 401 | `INVALID_API_KEY` | API key is missing, invalid, malformed, or disabled |
| 403 | `ACCESS_DENIED` | You do not have access to this job |
| 500 | `COMPANY_NOT_FOUND` | We could not find a company for this domain. Please verify the domain. |
| 500 | `INSUFFICIENT_CREDITS` | Insufficient credits to complete this request. Please contact administrator. |
| 500 | `INTERNAL_ERROR` | Something went wrong. Please try again. |
## OpenAPI
````yaml GET /api/v1/external/company-lookup/{jobId}/result
openapi: 3.0.3
info:
title: Huntd External API
version: 1.0.0
description: >-
The Huntd External API provides programmatic access to company contact
lookup services.
contact:
name: Huntd Support
email: support@gethuntd.com
servers:
- url: https://api.gethuntd.com
description: Production API
security:
- ApiKeyAuth: []
paths:
/api/v1/external/company-lookup/{jobId}/result:
get:
tags:
- Company Lookup
summary: Get Lookup Result
description: Retrieve the result of a company lookup job.
operationId: getCompanyLookupResult
parameters:
- name: jobId
in: path
required: true
description: The job ID returned from the company lookup submission
schema:
type: string
example: job_1705596234567_a1b2c3d4
responses:
'200':
description: Job completed successfully
content:
application/json:
schema:
$ref: '#/components/schemas/CompanyLookupResultResponse'
example:
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
verifiedAt: '2024-01-18T12:25:00.000Z'
status: verified
credits_used: 1
created_at: '2024-01-18T12:30:00.000Z'
'202':
description: Job still processing or queued
content:
application/json:
schema:
$ref: '#/components/schemas/CompanyLookupProcessingResponse'
examples:
processing:
summary: Job still processing
value:
job_id: job_1705596234567_a1b2c3d4
status: processing
message: Job is still processing. Please try again later.
queued:
summary: Job queued due to daily limit
value:
job_id: job_1705596234567_a1b2c3d4
domain: example.com
source: source_name
status: queued
contacts: []
credits_used: 0
created_at: '2024-01-18T12:30:00.000Z'
message: >-
Job queued due to daily limit. Processing resumes when
limit resets.
scheduled_processing_time: '2024-01-19T00:00:00.000Z'
'400':
description: Invalid request
content:
application/json:
schema:
$ref: '#/components/schemas/GetResultError'
example:
success: false
error:
code: INVALID_REQUEST
message: Job ID is required
'401':
description: Invalid API key
content:
application/json:
schema:
$ref: '#/components/schemas/GetResultError'
example:
success: false
error:
code: INVALID_API_KEY
message: API key is missing, invalid, malformed, or disabled
'403':
description: Access denied
content:
application/json:
schema:
$ref: '#/components/schemas/GetResultError'
example:
success: false
error:
code: ACCESS_DENIED
message: You do not have access to this job
'500':
description: Job failed
content:
application/json:
schema:
$ref: '#/components/schemas/CompanyLookupResultResponse'
example:
job_id: job_1705596234567_a1b2c3d4
domain: example.com
source: source_name
status: error
contacts: []
credits_used: 0
created_at: '2024-01-18T12:30:00.000Z'
error_code: COMPANY_NOT_FOUND
message: >-
We could not find a company for this domain. Please verify the
domain.
components:
schemas:
CompanyLookupResultResponse:
type: object
properties:
job_id:
type: string
example: job_1705596234567_a1b2c3d4
domain:
type: string
example: example.com
source:
type: string
description: Data source used for the lookup
status:
type: string
enum:
- success
- error
description: Job result status
contacts:
type: array
description: Array of contacts found at the company
items:
$ref: '#/components/schemas/Contact'
credits_used:
type: integer
description: Number of credits consumed (1 credit per contact)
example: 5
created_at:
type: string
format: date-time
message:
type: string
description: Status message (for error status)
error_code:
type: string
description: Error code if status is error
CompanyLookupProcessingResponse:
type: object
description: Response when job is still processing or queued
properties:
job_id:
type: string
example: job_1705596234567_a1b2c3d4
status:
type: string
enum:
- processing
- queued
description: Current job status
message:
type: string
description: Status message
domain:
type: string
description: Only present for queued jobs
source:
type: string
description: Only present for queued jobs
contacts:
type: array
items:
$ref: '#/components/schemas/Contact'
description: Empty array for queued jobs
credits_used:
type: integer
description: Only present for queued jobs
created_at:
type: string
format: date-time
description: Only present for queued jobs
scheduled_processing_time:
type: string
format: date-time
description: When the queued job will be processed (only for queued status)
GetResultError:
type: object
description: Error response for get lookup result endpoint
properties:
success:
type: boolean
enum:
- false
error:
type: object
properties:
code:
type: string
enum:
- INVALID_REQUEST
- INVALID_API_KEY
- ACCESS_DENIED
- COMPANY_NOT_FOUND
- INSUFFICIENT_CREDITS
- INTERNAL_ERROR
message:
type: string
Contact:
type: object
description: Contact information for a person at the company
properties:
first_name:
type: string
description: Contact's first name
example: John
last_name:
type: string
description: Contact's last name
example: Doe
email:
type: string
format: email
description: Contact's email address
example: john.doe@example.com
job_title:
type: string
description: Contact's job title
example: Senior Software Engineer
linkedin_url:
type: string
format: uri
description: Contact's LinkedIn profile URL
example: https://linkedin.com/in/johndoe
company:
type: string
description: Company name
example: Example Corp
company_domain:
type: string
description: Company domain
example: example.com
verifications:
type: array
description: Verification status for each source
items:
$ref: '#/components/schemas/ContactVerification'
ContactVerification:
type: object
description: Verification status for a specific source
properties:
source:
type: string
description: Source name
example: source_name
isVerified:
type: boolean
nullable: true
description: >-
Whether the contact is verified for this source (true, false, or
null if pending)
example: true
verifiedAt:
type: string
format: date-time
description: When the verification was performed
status:
type: string
description: Verification status message
error:
type: string
description: Error message if verification failed
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-API-Key
description: 'API key in format: hntd_{id}_{secret}'
````