---
title: "Upload a weekly bulk file for a portal-download state (e.g. TX)"
method: POST
path: "/api/v1/pipeline/upload-bulk-file"
tags: ["pipeline"]
---

# Upload a weekly bulk file for a portal-download state (e.g. TX)

`POST /api/v1/pipeline/upload-bulk-file`

## Request

- Base URL: `https://app.goodleads.club` (the document declares no server; this is the origin it was published from)
- URL: `https://app.goodleads.club/api/v1/pipeline/upload-bulk-file`
- Auth: API key in header `X-API-Key`

Validate and stage a manually downloaded SOS bulk file.

Accepts the original `.zip` from the portal (CW….zip fixed-width, or BFD_W….zip JSON shards) or the unzipped `.txt` / `.json`.
Validates the file against the state's data contract (fixed-width line
length, presence of entity records) and rejects look-alike products —
e.g. uploading the TX comma-delimited "List" CSV fails here with a clear
message instead of failing mid-pipeline.

Returns `input_file`: pass it to POST /api/v1/pipeline/trigger along with
a stage list that includes `pull`.

## Response `200`

Successful Response

- BulkUploadResponse
  - `input_file` string, required
  - `filename` string, required
  - `state` string, required
  - `entity_count` integer, required
  - `line_count` integer, required
  - `size_bytes` integer, required
  - `repaired_line_count` integer

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/goodleads/apis/formation-gtm-api.md) · [All operations](https://skmtc.dev/goodleads/apis/formation-gtm-api/llms.txt) · [OpenAPI document](https://skmtc.dev/goodleads/apis/formation-gtm-api/revisions/2068d13a82cf?raw)