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

# Bulk Intelligence

> Upload a file of leads or companies and enrich every row in a single job.

## Endpoint

Use the people endpoint for lead/person rows:

```http theme={null}
POST https://api.sixtyfour.ai/bulk-intelligence/people
```

Use the company endpoint for company rows:

```http theme={null}
POST https://api.sixtyfour.ai/bulk-intelligence/company
```

> [card] [People API Reference](https://docs.sixtyfour.ai/api-reference/enrichment/people-intelligence-bulk.md)
>
> Full request/response schema for `POST /bulk-intelligence/people`.

> [card] [Company API Reference](https://docs.sixtyfour.ai/api-reference/enrichment/company-intelligence-bulk.md)
>
> Full request/response schema for `POST /bulk-intelligence/company`.

## Tiers

Bulk jobs use the same tiers and access rules as the single-record endpoints:

| Endpoint | Tiers |
| - | - |
| `/bulk-intelligence/people` | `micro`, `low` (default), `medium`, `high`, `scout`, `xhigh`, see [People Intelligence tiers](https://docs.sixtyfour.ai/api-reference/legacy/people-intelligence.md#tiers) |
| `/bulk-intelligence/company` | `micro`, `low` (default), `medium`, `high`, see [Company Intelligence tiers](https://docs.sixtyfour.ai/api-reference/legacy/company-intelligence.md#tiers) |

[Atlas](https://docs.sixtyfour.ai/atlas/integrations.md#bulk-intelligence) run options (`graph`, `max_credits`, `max_minutes`, `investigation_id`) are not accepted in `config`; each `xhigh` row runs one investigation on the default budget.

## Request format

Both endpoints take `multipart/form-data` with two parts:

| Part | Description |
| - | - |
| `file` | The records to enrich. Accepts `.csv`, `.json`, `.jsonl`, or `.ndjson`. |
| `config` | A JSON-encoded string describing the enrichment, what to return for each row. |

### Limits

| Limit | Value |
| - | - |
| File size | 100 MB |
| Rows per file | 100,000 |
| Config size | 1,000,000 characters |

For the submission rate limit, see [Rate Limits](https://docs.sixtyfour.ai/api-reference/rate-limits.md#intelligence-and-contact).

## The `config` object

`config` takes the same options as the single-record request, minus the input record itself (each row is the input), plus three bulk-only fields. Unknown keys are rejected.

| Field | Type | Default | Description |
| - | - | - | - |
| `struct` | object | required | The fields to return for each row. |
| `tier` | string | `low` | Research depth. See [Tiers](#tiers). |
| `research_plan` | string (≤ 100,000 chars) | None | Plain-language guidance on where and how to look. |
| `field_confidence` | boolean | off | Add per-field [confidence scoring](https://docs.sixtyfour.ai/api-reference/endpoint/field-confidence.md). |
| `webhook_url` | string (HTTPS) | None | Receive the result files by POST when the job finishes. |
| `find_people`, `people_focus_prompt` (≤ 10,000 chars), `lead_struct`, `full_org_chart` | None | , | Company endpoint only. Same meaning as on [Company Intelligence](https://docs.sixtyfour.ai/api-reference/legacy/company-intelligence.md#request-parameters). |
| `columns` | array of strings | all columns | Subset of uploaded columns to use as input. |
| `result_formats` | array of strings | `["csv"]` | Output files to save. See below. |
| `save_json` | boolean | `false` | Also save the results as a JSON file. |

```json theme={null}
{
  "struct": {
    "email": "The individual's email address",
    "linkedin": "LinkedIn URL for the person"
  },
  "tier": "low",
  "field_confidence": true,
  "result_formats": ["csv", "ndjson"],
  "webhook_url": "https://your-server.com/webhooks/sixtyfour"
}
```

For struct value formats, supported types, and casting, see [Struct & Type Casting](https://docs.sixtyfour.ai/guides/struct-and-type-casting.md).

`result_formats` lists the output files. CSV is always produced; add `"ndjson"` for typed values (numbers, booleans and nested objects). Each format is its own `results` entry; pick by `filename` extension.

## Submitting a job

```bash cURL theme={null}
curl -X POST "https://api.sixtyfour.ai/bulk-intelligence/people" \
  -H "x-api-key: YOUR_API_KEY" \
  -F "file=@leads.csv" \
  -F 'config={
    "struct": {
      "email": "The individual'\''s email address",
      "linkedin": "LinkedIn URL for the person",
      "title": "The individual'\''s job title"
    }
  }'
```

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

config = {
    "struct": {
        "email": "The individual's email address",
        "linkedin": "LinkedIn URL for the person",
        "title": "The individual's job title"
    }
}

with open("leads.csv", "rb") as f:
    response = requests.post(
        "https://api.sixtyfour.ai/bulk-intelligence/people",
        headers={"x-api-key": "YOUR_API_KEY"},
        files={"file": ("leads.csv", f, "text/csv")},
        data={"config": json.dumps(config)}
    )

response.raise_for_status()
task_id = response.json()["task_id"]
```

```javascript JavaScript theme={null}
import { readFile } from "node:fs/promises";

const form = new FormData();
form.append("file", new Blob([await readFile("leads.csv")], { type: "text/csv" }), "leads.csv");
form.append("config", JSON.stringify({
  struct: {
    email: "The individual's email address",
    linkedin: "LinkedIn URL for the person",
    title: "The individual's job title"
  }
}));

const response = await fetch("https://api.sixtyfour.ai/bulk-intelligence/people", {
  method: "POST",
  headers: { "x-api-key": "YOUR_API_KEY" },
  body: form
});

if (!response.ok) throw new Error(`Submission failed: ${response.status}`);
const { task_id } = await response.json();
```

The response includes the job handle and the cost estimate:

```json theme={null}
{
  "task_id": "9b1f9d2e-...",
  "status": "RUNNING",
  "row_count": 2500,
  "estimated_cost_cents": 25000,
  "estimated_cost_credits": 2500
}
```

## Polling for results

Poll `GET /job-status/{task_id}` until `status` is no longer `running`. A completed job carries `results` (signed links to the output files), `results_url` (the run in the Sixtyfour app) and `charge_credits`, and no inline `result`. See [Async Jobs](https://docs.sixtyfour.ai/api-reference/legacy.md) for statuses, polling and retention.

The final enriched file is the `results` entry with the highest `block_number`. An entry for a file of at most 200 rows and 512 KB also holds the rows in its own `results` field.

CSV downloads are escaped for spreadsheets by default, so a phone number `+14155550123` downloads as `'+14155550123`. Append `?spreadsheet_safe=false` to the `download_url` to get the file as stored, or read the NDJSON file. See [Spreadsheet-safe CSV](https://docs.sixtyfour.ai/api-reference/workflows/workflows-execution.md#spreadsheet-safe-csv).

### Tracking progress while running

While `status` is `running`, a bulk response includes a `progress` object with the number of rows enriched so far out of the total submitted:

```json theme={null}
{
  "status": "running",
  "id": "9b1f9d2e-...",
  "start_time": "2026-06-10T00:00:00Z",
  "progress": {
    "completed": 120,
    "total": 500
  }
}
```

> [!NOTE]
>
> Download links are signed URLs that expire after 15 minutes, poll again for fresh links, and require your `x-api-key` header when fetching.

```bash cURL theme={null}
# Check status. For a polling loop that honors Retry-After, see /api-reference/legacy.
curl "https://api.sixtyfour.ai/job-status/TASK_ID" \
  -H "x-api-key: YOUR_API_KEY"

# When status is "completed", download the result (no redirects, pass your key directly).
# spreadsheet_safe=false returns the values as stored, without spreadsheet escaping.
curl -o enriched.csv \
  -H "x-api-key: YOUR_API_KEY" \
  "SIGNED_DOWNLOAD_URL?spreadsheet_safe=false"
```

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

deadline = time.monotonic() + 2 * 60 * 60  # give up after 2 hours

while True:
    poll_resp = requests.get(
        f"https://api.sixtyfour.ai/job-status/{task_id}",
        headers={"x-api-key": "YOUR_API_KEY"}
    )
    if poll_resp.status_code in (429, 503):
        # Over the polling budget, or status briefly unavailable: the job keeps running.
        time.sleep(float(poll_resp.headers.get("Retry-After", 30)))
        continue
    poll_resp.raise_for_status()
    status = poll_resp.json()

    if status["status"] == "completed":
        # The final stage has the highest block_number. If you requested NDJSON,
        # CSV and NDJSON share that block_number, pick by filename extension.
        final_block = max(f["block_number"] or 0 for f in status["results"])
        suffix = ".csv"  # use ".ndjson" if you requested NDJSON output
        final = next(
            (f for f in status["results"]
             if (f["block_number"] or 0) == final_block and f["filename"].endswith(suffix)),
            None,
        )
        if final is None:
            raise RuntimeError(f"No {suffix} file in results")
        download = requests.get(
            final["download_url"],
            headers={"x-api-key": "YOUR_API_KEY"},
            # Values as stored, without spreadsheet escaping.
            params={"spreadsheet_safe": "false"},
            # Downloads are served directly by api.sixtyfour.ai; never
            # forward your API key across a redirect.
            allow_redirects=False
        )
        if download.status_code != 200:
            raise RuntimeError(f"Download failed: {download.status_code}")
        with open(final["filename"], "wb") as out:
            out.write(download.content)
        break
    if status["status"] != "running":
        raise RuntimeError(f"Job {status['status']}")
    if time.monotonic() > deadline:
        raise TimeoutError("Job didn't complete within 2 hours")

    time.sleep(30)
```

```javascript JavaScript theme={null}
const deadline = Date.now() + 2 * 60 * 60 * 1000; // give up after 2 hours

while (true) {
  const pollResponse = await fetch(
    `https://api.sixtyfour.ai/job-status/${task_id}`,
    { headers: { "x-api-key": "YOUR_API_KEY" } }
  );
  if (pollResponse.status === 429 || pollResponse.status === 503) {
    // Over the polling budget, or status briefly unavailable: the job keeps running.
    const retryAfter = Number(pollResponse.headers.get("Retry-After") ?? 30);
    await new Promise(r => setTimeout(r, retryAfter * 1000));
    continue;
  }
  if (!pollResponse.ok) throw new Error(`Status check failed: ${pollResponse.status}`);
  const status = await pollResponse.json();

  if (status.status === "completed") {
    // The final stage has the highest block_number. If you requested NDJSON,
    // CSV and NDJSON share that block_number, pick by filename extension.
    const finalBlock = Math.max(...status.results.map(f => f.block_number ?? 0));
    const suffix = ".csv"; // use ".ndjson" if you requested NDJSON output
    const final = status.results.find(
      f => (f.block_number ?? 0) === finalBlock && f.filename.endsWith(suffix)
    );
    if (!final) throw new Error(`No ${suffix} file in results`);
    // Values as stored, without spreadsheet escaping.
    const downloadUrl = new URL(final.download_url);
    downloadUrl.searchParams.set("spreadsheet_safe", "false");
    // Downloads are served directly by api.sixtyfour.ai; redirect: "error"
    // ensures your API key is never forwarded across a redirect.
    const data = await fetch(downloadUrl, {
      headers: { "x-api-key": "YOUR_API_KEY" },
      redirect: "error"
    });
    if (!data.ok) throw new Error(`Download failed: ${data.status}`);
    // write data to disk or stream it onward
    break;
  }
  if (status.status !== "running") {
    throw new Error(`Job ${status.status}`);
  }
  if (Date.now() > deadline) {
    throw new Error("Job didn't complete within 2 hours");
  }
  await new Promise(r => setTimeout(r, 30000));
}
```

## Webhook callback

Pass `webhook_url` in the config to receive the result when the job completes. The callback's `run_id` is the job's `task_id`, and `results_download_url` links the enriched CSV for 15 minutes. See [Outgoing Webhooks](https://docs.sixtyfour.ai/api-reference/webhooks/outgoing.md#workflow-webhooks) for the payload.

With `webhook_url`, the final `results` file adds three columns: `webhook_status_code`, `webhook_response` and `webhook_success`.

> [!NOTE]
>
> Webhook URLs must use HTTPS and resolve to a public address. The URL is validated when you submit and again at delivery time.

## Idempotency

Send an `Idempotency-Key` header (up to 255 characters) to make submissions retry-safe. The key is scoped to your organization and the endpoint, and kept for 24 hours. Resubmitting with the same key returns the original job instead of starting a new one, with `status` set to that job's current status in uppercase, such as `RUNNING` or `COMPLETED`:

```json theme={null}
{
  "task_id": "9b1f9d2e-...",
  "status": "RUNNING",
  "already_started": true
}
```

A replay omits `row_count` and the cost estimate.

## Failure behavior

Rows that fail enrichment pass through un-enriched; one bad row does not fail the job. A file that cannot be parsed is rejected before anything runs. A job that fails as a whole reports `failed` with no `error`.

## Pricing

The submit response carries `estimated_cost_credits`; a start your balance does not cover is refused with [`402`](https://docs.sixtyfour.ai/api-reference/legacy/errors#402-payment-required). See [Credit Costs](https://docs.sixtyfour.ai/guides/credits-and-pricing.md) for the price of each tier.

## Related

* [Batch Processing](https://docs.sixtyfour.ai/guides/batch-processing.md)
* [Async Jobs](https://docs.sixtyfour.ai/api-reference/async-jobs.md)
* [Handling Errors](https://docs.sixtyfour.ai/api-reference/errors.md)
* [Credit Costs](https://docs.sixtyfour.ai/guides/credits-and-pricing.md)

> [!NOTE]
>
> For new integrations, see [Bulk Intelligence](https://docs.sixtyfour.ai/api-reference/endpoint/bulk-intelligence.md).


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