---
title: "Start a bulk job"
method: POST
path: "/bulk/jobs"
tags: ["Bulk"]
---

# Start a bulk job

`POST /bulk/jobs`

## Request

- Base URL: `https://app.1lookup.io/api/v1`
- URL: `https://app.1lookup.io/api/v1/bulk/jobs`
- Auth: HTTP bearer

Runs one product over up to 100,000 inputs in the background. Each row costs what a single lookup costs; the account must hold enough credits for every row up front. Poll the status, read the results page by page, or pass `webhook_url` to be called when the job completes.

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `type` 'hlr_lookup' | 'nt_lookup' | 'mnp_lookup' | 'email_validation' | 'reverse_email_append' | 'domain_authority' | 'domain_age' | 'backlink_overview' | 'keyword_metrics' | 'company_firmographics' | 'b2b_contact_append' | 'business_verify' | 'business_lookup' | 'company_profile_lookup' | 'linkedin_profile_lookup' | 'linkedin_company_lookup' | 'linkedin_email_finder' | 'social_profile_check' | 'property_lookup' | 'social_post_lookup' | 'video_transcript' | 'audience_demographics' | 'link_in_bio_lookup', required: Product to run. `email_validation` is email verification.
  - `inputs` string[], required: One input per row, in the form the product's single-lookup endpoint takes: a phone number, an email address, a domain, a URL and so on.
  - `webhook_url` string: https URL to call when the job completes. Optional.

## Response `200`

Idempotent replay: a job with this `Idempotency-Key` already exists, and it is returned instead of a new one.

- object
  - `success` true, required
  - `data` BulkJobCreated, required
    - `job_id` string, required
    - `status` string, required: processing for a new job; the job's current status on an idempotent replay.
    - `accepted` integer, required: Rows accepted.
    - `webhook_url` string: The completion webhook, when one was registered.
    - `webhook_secret` string: Returned once, at creation, when a webhook was registered. Use it to verify the `X-1Lookup-Signature` header on the completion webhook.

## Other responses

- `202`: Job accepted and processing.
- `400`: `INVALID_REQUEST`: The body is not valid JSON; `INVALID_TYPE`: `type` is not one of the bulk job types; `INVALID_INPUT`: The input does not match the expected format; `INPUT_LIMIT_EXCEEDED`: `inputs` has more than 100,000 rows; `INVALID_WEBHOOK_URL`: `webhook_url` is not an https URL that can receive webhooks
- `401`: `UNAUTHORIZED`: Invalid or missing API key
- `402`: The account does not hold enough credits for every row. The body says how many are needed and suggests a plan.
- `403`: `UPGRADE_REQUIRED`: The account has no paid plan, and API access needs one. Upgrade at https://app.1lookup.io/billing?tab=plan; `INSUFFICIENT_SCOPE`: The call was signed with an AI connector (MCP) sign-in, which can only reach /phone, /email, /ip and /account. Use an API key; `UNSUPPORTED_AUTH_CONTEXT`: Bulk jobs need a direct API key
- `409`: `IDEMPOTENCY_CONFLICT`: A request with this `Idempotency-Key` is still being processed. Retry shortly; `ACCOUNT_CONFIGURATION_ERROR`: The organization has no active user to own the job
- `429`: `RATE_LIMIT_EXCEEDED`: Too many requests
- `500`: `INTERNAL_ERROR`: Internal server error
- `503`: `SERVICE_UNAVAILABLE`: The lookup service, or the API key check, is temporarily unavailable. Nothing was charged; retry after `Retry-After` seconds

---

[API](https://skmtc.dev/1lookup/apis/1lookup-api.md) · [All operations](https://skmtc.dev/1lookup/apis/1lookup-api/llms.txt) · [OpenAPI document](https://skmtc.dev/1lookup/apis/1lookup-api/revisions/57b6d8ba04ac?raw)