---
title: "Submit one bid, or up to 500 as {\"bids\": [...]}"
method: POST
path: "/vendor/bids"
tags: ["bids"]
---

# Submit one bid, or up to 500 as {"bids": \[...\]}

`POST /vendor/bids`

## Request

- Base URL: `https://justbidit.ai/api/v1`
- URL: `https://justbidit.ai/api/v1/vendor/bids`
- Auth: API key in header `X-Vendor-API-Key`

## Request body

- union
  - BidInput
    - `amount` number, required: Price, or a rate for finance requests
    - `currency` string
    - `delivery_days` integer, nullable: Used when offer_details is absent
    - `external_id` string: Idempotency key; a repeat returns the earlier bid
    - `offer_details` object: Known keys only: pitch, note, message, terms, summary, delivery_days and the bid-form fields of GET /bids/schema; other keys and nested values are dropped, text is capped (bid_core.clean_offer_details)
    - `pitch` string: Used when offer_details is absent
    - `request_id` string, required
  - object
    - `bids` BidInput[], required
      - `amount` number, required: Price, or a rate for finance requests
      - `currency` string
      - `delivery_days` integer, nullable: Used when offer_details is absent
      - `external_id` string: Idempotency key; a repeat returns the earlier bid
      - `offer_details` object: Known keys only: pitch, note, message, terms, summary, delivery_days and the bid-form fields of GET /bids/schema; other keys and nested values are dropped, text is capped (bid_core.clean_offer_details)
      - `pitch` string: Used when offer_details is absent
      - `request_id` string, required

## Response `200`

Per-bid results; each carries its own http_status (201 created, 200 idempotent replay, 4xx error)

- object
  - `failed` integer, required
  - `results` BidResult[], required
    - `bid_id` string
    - `error` string: missing_required, amount_must_be_positive, amount_not_numeric, request_not_found, request_not_open, not_eligible, duplicate_bid
    - `external_id` string, nullable
    - `http_status` integer, required
    - `idempotent_replay` boolean
    - `ok` boolean
    - `reason` string
    - `source` 'api' | 'csv'
    - `status` string
  - `success` integer, required

## Other responses

- `400`: `bids_must_be_list`
- `401`: `auth_required`: the X-Vendor-API-Key header is missing
- `403`: `invalid_key`: the key is unknown or revoked
- `413`: `batch_too_large`: more than 500 bids
- `429`: `rate_limited`: over the per-key limit (default 60 requests/minute)

---

[API](https://skmtc.dev/justbidit/apis/bidit-vendor-api.md) · [All operations](https://skmtc.dev/justbidit/apis/bidit-vendor-api/llms.txt) · [OpenAPI document](https://skmtc.dev/justbidit/apis/bidit-vendor-api/revisions/b21a33733026?raw)