---
title: "Creates a vendor."
method: POST
path: "/api/v1/vendors"
tags: ["Vendors"]
---

# Creates a vendor.

`POST /api/v1/vendors`

## Request

- Base URL: `https://app.flexonthejob.com`
- URL: `https://app.flexonthejob.com/api/v1/vendors`
- Auth: HTTP bearer

Requires `ManageVendors` and an `Idempotency-Key` header. Same as "New Vendor" in the
app: the name must be unique in the organization (active or not). Attributed to the key's creator.
Example: `{ "name": "Acme Supply", "contactEmail": "orders@acme.example" }`.

## Request body

- VendorWriteApiRequest: Body of `POST /api/v1/vendors` (`name` required) and `PATCH /api/v1/vendors/{id}` (only the fields sent change; `""` clears a field, except `name`). Example: `{ "name": "Acme Supply", "contactEmail": "orders@acme.example", "defaultShippingCompany": "UPS" }`.
  - `name` string, nullable: Vendor name, 1..100 characters, unique in the organization. Required on create. Example: `Acme Supply`.
  - `description` string, nullable: Free-text notes, up to 500 characters.
  - `contactName` string, nullable: Main contact's name, up to 100 characters.
  - `contactEmail` string, nullable: Main contact's email, up to 100 characters. Example: `orders@acme.example`.
  - `contactPhone` string, nullable: Main contact's phone, up to 20 characters. Example: `555-0100`.
  - `website` string, nullable: Vendor website, up to 500 characters.
  - `defaultShippingCompany` string, nullable: Carrier the vendor usually ships with, up to 100 characters. Example: `UPS`.
  - `isActive` boolean, nullable: False deactivates the vendor (kept for history, not offered on new orders). Defaults to `true` on create.

## Response `201`

Created; `Location` points at the new vendor.

- VendorDto: A vendor (supplier) the organization buys from, as returned by `/api/v1/vendors`. Use the id as `vendorId` when creating a purchase order.
  - `id` integer: Numeric id, usable in `/api/v1/vendors/{id}` and as a purchase order's `vendorId`. Example: `7`.
  - `syncId` string, uuid: Stable cross-device id; also the pagination cursor.
  - `name` string: Vendor name, unique in the organization. Example: `Acme Supply`.
  - `description` string, nullable: Free-text notes about the vendor; null when not recorded.
  - `contactName` string, nullable: Main contact's name; null when not recorded. Example: `Dana Ruiz`.
  - `contactEmail` string, nullable: Main contact's email; null when not recorded. Example: `orders@acme.example`.
  - `contactPhone` string, nullable: Main contact's phone, as typed; null when not recorded. Example: `555-0100`.
  - `website` string, nullable: Vendor website; null when not recorded. Example: `https://acme.example`.
  - `defaultShippingCompany` string, nullable: Carrier the vendor usually ships with; null when not recorded. Example: `UPS`.
  - `isActive` boolean: False for a deactivated vendor: kept for history, not offered on new orders and refused as a new order's `vendorId`.
  - `createdAt` string, date-time: UTC creation time (ISO-8601).
  - `updatedAt` string, date-time: UTC last modification time (ISO-8601).

## Other responses

- `400`: Malformed body or missing `Idempotency-Key`.
- `401`: Unauthorized
- `403`: Forbidden
- `409`: A vendor with this name already exists, or the key's creator is unknown on this server.
- `422`: A field is unacceptable (blank name, invalid email, too long); the field is listed in `errors`.
- `429`: Too Many Requests

---

[API](https://skmtc.dev/flexonthejob/apis/flex-api.md) · [All operations](https://skmtc.dev/flexonthejob/apis/flex-api/llms.txt) · [OpenAPI document](https://skmtc.dev/flexonthejob/apis/flex-api/revisions/19c8f4d27acf?raw)