# Create Batch Enrichment

Create a batch enrichment job by uploading a CSV.
**How it works**
1. Upload a `.csv` file (one column: `handle` or `email`)
2. Choose the enrichment mode (handle: `raw`/`full`, email: `basic`)
3. Use the returned `batch_id` to check status and download results

**Request**
- `multipart/form-data`
- `file`: CSV (max 10MB)
- Mode fields depend on whether you’re enriching by `handle` or `email`

**Credits**
- Credits are deducted **per successfully enriched record**
- The credit rate follows the corresponding single-enrichment pricing (handle `raw`/`full`, or email enrichment)
- If no data is returned for a record, **0 credits** are deducted for that record

**Checking completion**
Poll `GET /public/v1/enrichment/batch/{batch_id}/status/` every 30–60 seconds until the job finishes. Status values:
- `queued` — waiting to start
- `processing` — actively enriching records
- `finished` — all records done; download results via `GET /public/v1/enrichment/batch/{batch_id}/`
- `failed` — job failed
- `paused_insufficient_credits` — top up credits and call the resume endpoint

This API is polling-based. There are no webhooks or push notifications.
<div class="ic-ai-prompt-root" data-endpoint="batch-create"></div>

Endpoint: POST /public/v1/enrichment/batch/
Version: 1.0.0
Security: Bearer

## Request fields (multipart/form-data):

  - `file` (string, required)
    CSV file containing creators to enrich (max 10MB, single column: handle or email)

  - `platform` (string)
    Social media platform (required for handle-based enrichment)
    Enum: "instagram", "youtube", "tiktok", "twitter", "twitch", "onlyfans"

  - `enrichment_mode` (string, required)
    Enrichment mode: 'raw' or 'full' for handle-based, 'basic' or 'advanced' for email-based
    Enum: "raw", "full", "basic"

  - `email_required` (string)
    Email requirement for handle-based full enrichment. Default: "preferred"
    Enum: "must_have", "preferred"

  - `include_lookalikes` (boolean)
    Include lookalike creators for handle-based full enrichment. Default: false

  - `include_audience_data` (boolean)
    Include audience data for handle-based full enrichment. Default: true

  - `exclude_platforms` (string)
    Platforms to exclude from response
    Enum: "instagram", "youtube", "tiktok", "twitter", "twitch", "onlyfans"

  - `min_followers` (integer)

## Response 200 fields (application/json):

  - `batch_id` (string, required)
    Unique identifier for the batch enrichment job

  - `status` (string, required)
    Current status of the batch job (processing, finished, failed, validating)

  - `created_at` (string, required)
    Timestamp when the batch was created

  - `platform` (string)
    Platform used for enrichment (for handle-based enrichment)

  - `og_input_number` (integer, required)
    Total number of records in the input file

  - `type_report` (string, required)
    Type of enrichment: ENRICH_BY_HANDLE or ENRICH_BY_EMAIL

  - `enrichment_mode` (string)
    Enrichment mode: raw, full, basic

  - `message` (string, required)
    Human-readable message about the batch status

## Response 400 fields (application/json):

  - `error` (any)
    Human-readable description of what went wrong. Shape varies per endpoint: string on most paths, DRF field-error object on validation paths of creators_api enrich/* and enrichment_batch_api create, list of strings on discovery filter validation. See the per-endpoint example response.
    Example: Insufficient credits.

  - `error_code` (string, required)
    Machine-readable snake_case slug identifying the error class. Stable across API versions; **the only field guaranteed present on every public-API error**. Use for programmatic branching instead of parsing `error`.
    Example: insufficient_credits

  - `message` (string)
    Optional long-form detail sibling to `error`. Present on endpoints that historically returned both a short label and a long explanation (rate limits, polling, batch state, insufficient_credits on resume).
    Example: Poll every 30-60 seconds. Excessive polling results in rate limiting.

  - `retry_after` (integer)
    Seconds the caller should wait before retrying. Present on 429s where the OLD endpoint set it; mirrored in the `Retry-After` HTTP header.
    Example: 60

  - `available_credits` (number)
    Credits currently available. Present on the 403 insufficient_credits response of `POST /public/v1/enrichment/batch/{id}/resume/`.

  - `required_minimum` (number)
    Minimum credits needed. Pairs with `available_credits`.

  - `current_status` (string)
    Current resource state. Present on 400 responses where the operation requires a different state (e.g. `batch_not_ready`, `batch_not_resumable`).

  - `active_batches` (integer)
    Active batch count when `error_code: batch_limit_reached`.

  - `max_allowed` (integer)
    Per-client batch ceiling. Pairs with `active_batches`.

## Response 403 fields (application/json):

  - `error` (any)
    Human-readable description of what went wrong. Shape varies per endpoint: string on most paths, DRF field-error object on validation paths of creators_api enrich/* and enrichment_batch_api create, list of strings on discovery filter validation. See the per-endpoint example response.
    Example: Insufficient credits.

  - `error_code` (string, required)
    Machine-readable snake_case slug identifying the error class. Stable across API versions; **the only field guaranteed present on every public-API error**. Use for programmatic branching instead of parsing `error`.
    Example: insufficient_credits

  - `message` (string)
    Optional long-form detail sibling to `error`. Present on endpoints that historically returned both a short label and a long explanation (rate limits, polling, batch state, insufficient_credits on resume).
    Example: Poll every 30-60 seconds. Excessive polling results in rate limiting.

  - `retry_after` (integer)
    Seconds the caller should wait before retrying. Present on 429s where the OLD endpoint set it; mirrored in the `Retry-After` HTTP header.
    Example: 60

  - `available_credits` (number)
    Credits currently available. Present on the 403 insufficient_credits response of `POST /public/v1/enrichment/batch/{id}/resume/`.

  - `required_minimum` (number)
    Minimum credits needed. Pairs with `available_credits`.

  - `current_status` (string)
    Current resource state. Present on 400 responses where the operation requires a different state (e.g. `batch_not_ready`, `batch_not_resumable`).

  - `active_batches` (integer)
    Active batch count when `error_code: batch_limit_reached`.

  - `max_allowed` (integer)
    Per-client batch ceiling. Pairs with `active_batches`.

## Response 409 fields (application/json):

  - `error` (any)
    Human-readable description of what went wrong. Shape varies per endpoint: string on most paths, DRF field-error object on validation paths of creators_api enrich/* and enrichment_batch_api create, list of strings on discovery filter validation. See the per-endpoint example response.
    Example: Insufficient credits.

  - `error_code` (string, required)
    Machine-readable snake_case slug identifying the error class. Stable across API versions; **the only field guaranteed present on every public-API error**. Use for programmatic branching instead of parsing `error`.
    Example: insufficient_credits

  - `message` (string)
    Optional long-form detail sibling to `error`. Present on endpoints that historically returned both a short label and a long explanation (rate limits, polling, batch state, insufficient_credits on resume).
    Example: Poll every 30-60 seconds. Excessive polling results in rate limiting.

  - `retry_after` (integer)
    Seconds the caller should wait before retrying. Present on 429s where the OLD endpoint set it; mirrored in the `Retry-After` HTTP header.
    Example: 60

  - `available_credits` (number)
    Credits currently available. Present on the 403 insufficient_credits response of `POST /public/v1/enrichment/batch/{id}/resume/`.

  - `required_minimum` (number)
    Minimum credits needed. Pairs with `available_credits`.

  - `current_status` (string)
    Current resource state. Present on 400 responses where the operation requires a different state (e.g. `batch_not_ready`, `batch_not_resumable`).

  - `active_batches` (integer)
    Active batch count when `error_code: batch_limit_reached`.

  - `max_allowed` (integer)
    Per-client batch ceiling. Pairs with `active_batches`.

## Response 429 fields (application/json):

  - `error` (any)
    Human-readable description of what went wrong. Shape varies per endpoint: string on most paths, DRF field-error object on validation paths of creators_api enrich/* and enrichment_batch_api create, list of strings on discovery filter validation. See the per-endpoint example response.
    Example: Insufficient credits.

  - `error_code` (string, required)
    Machine-readable snake_case slug identifying the error class. Stable across API versions; **the only field guaranteed present on every public-API error**. Use for programmatic branching instead of parsing `error`.
    Example: insufficient_credits

  - `message` (string)
    Optional long-form detail sibling to `error`. Present on endpoints that historically returned both a short label and a long explanation (rate limits, polling, batch state, insufficient_credits on resume).
    Example: Poll every 30-60 seconds. Excessive polling results in rate limiting.

  - `retry_after` (integer)
    Seconds the caller should wait before retrying. Present on 429s where the OLD endpoint set it; mirrored in the `Retry-After` HTTP header.
    Example: 60

  - `available_credits` (number)
    Credits currently available. Present on the 403 insufficient_credits response of `POST /public/v1/enrichment/batch/{id}/resume/`.

  - `required_minimum` (number)
    Minimum credits needed. Pairs with `available_credits`.

  - `current_status` (string)
    Current resource state. Present on 400 responses where the operation requires a different state (e.g. `batch_not_ready`, `batch_not_resumable`).

  - `active_batches` (integer)
    Active batch count when `error_code: batch_limit_reached`.

  - `max_allowed` (integer)
    Per-client batch ceiling. Pairs with `active_batches`.