# Creator CSV imports

> Format, submit, and monitor agency creator-roster imports through Public API V1.
>
> Canonical URL: https://docs.creatorsjet.com/api/imports

Agency keys with `roster:write` can queue a CSV roster import. The endpoint accepts one multipart field named `file`.

## Limits

* CSV only
* Maximum file size: 2 MB
* Maximum creator rows: 500
* One queued or processing Public API import per agency
* An `Idempotency-Key` header is required
* Agency roster-capacity rules apply before the job is queued

## CSV columns

| Column             |    Required | Notes                                                                |
| ------------------ | ----------: | -------------------------------------------------------------------- |
| `username`         |         Yes | 3–50 letters, numbers, or hyphens; a leading `@` is removed          |
| `first_name`       |         Yes | Creator's first name                                                 |
| `last_name`        |         Yes | Creator's last name                                                  |
| `contact_email`    |         Yes | Valid email address                                                  |
| `bio`              |          No | Creator biography                                                    |
| `location`         |          No | City or free-form location                                           |
| `country`          |          No | Country                                                              |
| `tags`             |          No | Separate values with semicolons or commas                            |
| `languages`        |          No | Separate values with semicolons or commas                            |
| `avatar_url`       |          No | Must be blank for Public API V1; remote avatar ingestion is disabled |
| `instagram_handle` | Conditional | Handle, `@handle`, or supported profile URL                          |
| `tiktok_handle`    | Conditional | Handle, `@handle`, or supported profile URL                          |
| `youtube_handle`   | Conditional | Handle, `@handle`, or supported profile URL                          |
| `facebook_url`     | Conditional | Facebook profile URL or accepted identity                            |
| `linkedin_url`     | Conditional | LinkedIn profile URL or accepted identity                            |
| `x_handle`         | Conditional | X/Twitter handle, `@handle`, or profile URL                          |

Every row needs at least one social identity.

```csv
username,first_name,last_name,contact_email,bio,location,country,tags,languages,avatar_url,instagram_handle,tiktok_handle,youtube_handle,facebook_url,linkedin_url,x_handle
maria2,Maria,Lopez,maria@example.com,Lifestyle creator based in Paris,Paris,France,fashion; lifestyle,en; fr,,maria,,,,,
```

## Start an import

```bash
curl https://api.creatorsjet.com/public/v1/creator-imports \
  --request POST \
  --header "Authorization: Bearer $CREATORSJET_API_KEY" \
  --header "Idempotency-Key: roster-import-2026-08-14-001" \
  --form "file=@creators.csv;type=text/csv"
```

The API validates the file, queues accepted work, and returns `202`. Poll the returned import ID with `GET /creator-imports/{import_id}` using a key that has `roster:read`.

## Status and row results

Import status is one of:

* `queued`
* `running`
* `completed`
* `completed_with_errors`
* `failed`

Progress includes total, processed, created, attached-social, and failed counts. Each row may include a `creator_id`, automatically created agency `media_kit_id`, social IDs, and error messages.

Public imports do not silently attach a globally existing creator identity to another agency. An ambiguous external identity produces a row-level creator identity conflict. Fix the identity or resolve ownership in CreatorsJet before retrying that row.

## Sensitive data

CSV files contain creator contact information. Keep them out of logs and public support tickets, upload them only to the official API host, and retain them only as long as your workflow requires.