Vendors

Vendors in BenchKey are your parts suppliers and distributors. This API manages supplier contact details and returns stored integration settings. MobileSentrix order tracking isn’t available for your shop yet. We’re waiting on MobileSentrix to approve connections for more shops.

The vendor object

{
  "object": "vendor",
  "id": 12,
  "name": "Parts Depot Inc.",
  "contact_name": "Alex Rivera",
  "email": "orders@partsdepot.example.com",
  "phone": "800-555-0199",
  "website": "https://partsdepot.example.com",
  "address": "4501 Industrial Blvd, Austin, TX 78745",
  "domain": "partsdepot.example.com",
  "notes": "Net-30 terms. Preferred for LCD panels.",
  "active": true,
  "api_configured": false,
  "api_adapter": null,
  "created_at": "2024-06-10T18:30:00.000Z"
}

Field	Type	Description
id	integer	Unique vendor ID
name	string	Vendor / supplier name
contact_name	string|null	Primary contact person
email	string|null	Contact email address
phone	string|null	Contact phone number
website	string|null	Vendor website URL
address	string|null	Mailing or warehouse address
domain	string|null	Supplier email domain
notes	string|null	Internal notes about this vendor
active	boolean	Whether this vendor is active
api_configured	boolean	Whether a supplier API integration is configured
api_adapter	string|null	Supplier API adapter key, if configured
created_at	string	ISO-8601 timestamp of when the vendor was created

---

List vendors

GET /api/v1/vendors

Returns a cursor-paginated list of vendors ordered by ID ascending.

Scope required: vendors.read

Query parameters

Parameter	Type	Description
q	string	Search by name or domain (partial match)
active	boolean	Filter by active status. Accepts true, false, 1, or 0 only, any other value returns 400 invalid_param
limit	integer	Page size, 1–100 (default: 20)
cursor	string	Opaque cursor from a previous response’s next_cursor

curl

curl "https://app.benchkey.com/api/v1/vendors?limit=10&active=true" \
  -H "Authorization: Bearer bk_live_01J8X4_kvWz9nP3mRqTs7uYeBfGhDjLa"

Node.js

const res = await fetch(
  "https://app.benchkey.com/api/v1/vendors?limit=10&active=true",
  { headers: { Authorization: "Bearer bk_live_01J8X4_kvWz9nP3mRqTs7uYeBfGhDjLa" } }
);
const { data, has_more, next_cursor } = await res.json();

Response

{
  "object": "list",
  "data": [
    {
      "object": "vendor",
      "id": 12,
      "name": "Parts Depot Inc.",
      "contact_name": "Alex Rivera",
      "email": "orders@partsdepot.example.com",
      "phone": "800-555-0199",
      "website": "https://partsdepot.example.com",
      "address": "4501 Industrial Blvd, Austin, TX 78745",
      "domain": "partsdepot.example.com",
      "notes": "Net-30 terms. Preferred for LCD panels.",
      "active": true,
      "api_configured": false,
      "api_adapter": null,
      "created_at": "2024-06-10T18:30:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

See Pagination for how to page through results.

---

Retrieve a vendor

GET /api/v1/vendors/:id

Returns a single vendor by its integer ID.

Scope required: vendors.read

curl

curl "https://app.benchkey.com/api/v1/vendors/12" \
  -H "Authorization: Bearer bk_live_01J8X4_kvWz9nP3mRqTs7uYeBfGhDjLa"

Node.js

const res = await fetch(
  "https://app.benchkey.com/api/v1/vendors/12",
  { headers: { Authorization: "Bearer bk_live_01J8X4_kvWz9nP3mRqTs7uYeBfGhDjLa" } }
);
const vendor = await res.json();

Response

Returns the vendor object. Returns 404 if no vendor with that ID exists.

---

Create a vendor

POST /api/v1/vendors

Creates a new vendor in your supplier catalog.

Scope required: vendors.write

Request body

Field	Required	Max length	Description
name	yes	200 chars	Vendor / supplier name
contact_name	no	200 chars	Primary contact person
email	no	320 chars	Contact email address
phone	no	50 chars	Contact phone number
website	no	500 chars	Vendor website URL
address	no	500 chars	Mailing or warehouse address
domain	no	255 chars	Supplier email domain (e.g. "partsdepot.example.com")
notes	no	5000 chars	Internal notes

All optional string fields must be strings if supplied (not numbers or booleans); fields exceeding their max length return 400 invalid_field. The email field is validated as a proper email address, invalid addresses return 400 invalid_field.

curl

curl -X POST https://app.benchkey.com/api/v1/vendors \
  -H "Authorization: Bearer bk_live_01J8X4_kvWz9nP3mRqTs7uYeBfGhDjLa" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Parts Depot Inc.",
    "contact_name": "Alex Rivera",
    "email": "orders@partsdepot.example.com",
    "phone": "800-555-0199",
    "website": "https://partsdepot.example.com",
    "address": "4501 Industrial Blvd, Austin, TX 78745",
    "domain": "partsdepot.example.com",
    "notes": "Net-30 terms. Preferred for LCD panels."
  }'

Node.js

const res = await fetch("https://app.benchkey.com/api/v1/vendors", {
  method: "POST",
  headers: {
    Authorization: "Bearer bk_live_01J8X4_kvWz9nP3mRqTs7uYeBfGhDjLa",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Parts Depot Inc.",
    contact_name: "Alex Rivera",
    email: "orders@partsdepot.example.com",
    phone: "800-555-0199",
    website: "https://partsdepot.example.com",
    address: "4501 Industrial Blvd, Austin, TX 78745",
    domain: "partsdepot.example.com",
    notes: "Net-30 terms. Preferred for LCD panels.",
  }),
});
const vendor = await res.json(); // HTTP 201

Response

Returns the vendor object with HTTP 201.

---

Update a vendor

PATCH /api/v1/vendors/:id

Updates one or more fields on an existing vendor. Only fields present in the request body are changed.

Scope required: vendors.write

Request body

At least one of the following fields must be included. Length limits and string-type requirements are the same as for Create. Sending a field that is not in this list returns 400 invalid_field.

Field	Max length	Description
name	200 chars	Vendor / supplier name (cannot be empty)
contact_name	200 chars	Primary contact person
email	320 chars	Contact email address
phone	50 chars	Contact phone number
website	500 chars	Vendor website URL
address	500 chars	Mailing or warehouse address
domain	255 chars	Supplier email domain
notes	5000 chars	Internal notes

curl

curl -X PATCH "https://app.benchkey.com/api/v1/vendors/12" \
  -H "Authorization: Bearer bk_live_01J8X4_kvWz9nP3mRqTs7uYeBfGhDjLa" \
  -H "Content-Type: application/json" \
  -d '{ "notes": "Net-15 terms as of Q3. Preferred for screens." }'

Node.js

const res = await fetch("https://app.benchkey.com/api/v1/vendors/12", {
  method: "PATCH",
  headers: {
    Authorization: "Bearer bk_live_01J8X4_kvWz9nP3mRqTs7uYeBfGhDjLa",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ notes: "Net-15 terms as of Q3. Preferred for screens." }),
});
const vendor = await res.json();

Response

Returns the updated vendor object.

---

Error codes

HTTP status	Code	Meaning
400	invalid_query	A list filter parameter was supplied as an array or object instead of a single scalar value
400	invalid_param	active filter value is not a recognized boolean (true, false, 1, or 0)
400	invalid_id	The :id is not a positive integer
400	missing_field	Required field name is absent or empty
400	invalid_field	A string field exceeds its max length, is not a string, email is not a valid email address, or PATCH included an unrecognized field (active, api_adapter, etc. are not patchable)
400	nothing_to_update	PATCH body contains no recognized fields
404	not_found	No vendor with that ID exists
422	create_failed	Vendor could not be created (internal route error)
422	update_failed	Vendor could not be updated (internal route error)
403	insufficient_scope	API key lacks vendors.read or vendors.write

See Errors for the full error envelope format.