---
title: "Create Batch Enrichment"
method: POST
path: "/public/v1/enrichment/batch/"
tags: ["Batch enrichment"]
---

# Create Batch Enrichment

`POST /public/v1/enrichment/batch/`

## Request

- Base URL: `https://api-dashboard.influencers.club`
- URL: `https://api-dashboard.influencers.club/public/v1/enrichment/batch/`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/influencers/apis/core-api-concepts/docs/public/v1/enrichment/batch/post.ts> (a function with typed inputs; its response is checked against the schema)

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>

## Request body `multipart/form-data`

- BatchEnrichmentInputRequest
  - `file` string, binary, required: CSV file containing creators to enrich (max 10MB, single column: handle or email)
  - `platform` 'instagram' | 'youtube' | 'tiktok' | 'twitter' | 'twitch' | 'onlyfans': Social media platform (required for handle-based enrichment)
  - `enrichment_mode` 'raw' | 'full' | 'basic', required: Enrichment mode: 'raw' or 'full' for handle-based, 'basic' for email-based
  - `metadata` object, nullable: Optional metadata as JSON object (e.g., {"campaign": "Q4 Outreach"})
  - `email_required` 'must_have' | 'preferred': Email requirement for handle-based full enrichment. Default: "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

## Response `200`

- BatchEnrichmentResponse
  - `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, date-time, required: Timestamp when the batch was created
  - `platform` string, nullable: Platform used for enrichment (for handle-based enrichment)
  - `metadata` object, nullable: Metadata provided with the batch
  - `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, nullable: Enrichment mode: raw, full, basic
  - `message` string, required: Human-readable message about the batch status

## Other responses

- `400`: Bad request — invalid input or unsupported state.
- `401`: Unauthorized — missing or invalid API key.
- `403`: Forbidden — caller is not permitted to perform this action.
- `409`: Conflict — total active-batch capacity reached.
- `422`: Unprocessable entity — validation failed.
- `429`: Too Many Requests — rate or capacity limit exceeded. Inspect the `Retry-After` header and the `retry_after` body field for the wait time in seconds.

## Changes

- **2026-09-18** `8e30ca66a18c`: 2 warning
  - removed the request property `exclude_platforms`
  - removed the request property `min_followers`
- **2026-08-18** `87e654ac822e`: 22 info
  - added the media type `application/json` for the response with the status `400`
  - added the non-success response with the status `409`
  - added the optional property `active_batches` to the response with the `403` status
  - added the optional property `active_batches` to the response with the `429` status
  - …18 more

[Operation history](https://skmtc.dev/influencers/apis/core-api-concepts/changes/public/v1/enrichment/batch/post.md)

---

[API](https://skmtc.dev/influencers/apis/core-api-concepts.md) - [All operations](https://skmtc.dev/influencers/apis/core-api-concepts/llms.txt) - [OpenAPI document](https://skmtc.dev/influencers/apis/core-api-concepts/revisions/11c76bf81bec?raw)