Purchase requests (pre-release)

⚠️ Pre-release. This resource shipped in September 2026 and is being rolled out. The contract below is what the API answers today, but field names may still be adjusted before general availability, and the resource may not yet be enabled for your company. If a call answers 403 or 404 where this page says otherwise, contact Hivebuy support before building on it. Everything else on this site is stable.

Create purchase requests from an outside system and read them back. This is the entry point of the procurement flow: a request is what a person asks to buy, it goes through the company's approval flow, and once approved it becomes a purchase order (see the Purchase orders section). Typical callers are an intake form, a ticketing system, or an ERP that raises demand in Hivebuy.

Scopes

The two reads need transactional:read; the create needs transactional:write. A key holding only the read scope reaches both GETs and is refused on the POST.

Who the request is for

requestedBy is required and must name an active member of the company in the path, by user UUID or email. The request is filed for that person: they see it under their requests, their approval flow applies, and their default delivery address is the fallback. The API key's own user is never used for any of this.

How references resolve

Instead of forcing you to look up UUIDs first, most references accept a natural key, always scoped to the company in the path:

• category: UUID, name or GL account
• supplier: UUID, name or supplier number
• department: UUID, name or cost center
• legalEntity: UUID or name
• requestedBy / requestedFor with type user: UUID or email
• requestedFor with type department: UUID, name or cost center; with type project: UUID, name or project number
• address / invoiceAddress: UUID of one of the company's addresses (see the Addresses section). An address of another company is refused.
• customFields: entries matched by the field's name or label, case-insensitively. Mandatory custom fields must be present.

A reference that matches nothing, or matches more than one row, is a 400 naming the field. All errors in a request are collected and returned together.

Header and items

An item's category, supplier, department, address and invoiceAddress default to the header's values and may override them per line. requestedFor defaults to the requester. The delivery address falls back to the requester's default address in this company, then the company's default delivery address; if none exists the item is refused with a 400 on items.address.

Money

One currency per level (header and item), amounts as decimal strings in the responses. On input, send netAmount or grossAmount per item with vat as a percentage and netGross saying which one you sent; totals are computed by Hivebuy.

Reading requests

The list is paginated (25 per page, max 100), newest request number first, and filterable by status, request number, the linked order's numbers, requester and date. An unknown query parameter is a 400 naming it, so a misspelled filter cannot silently return the whole company. externalOrderNumber and clientExternalId are the linked purchase order's identifiers and are null until the request becomes an order.

Status codes

D draft · P pending · A approved · R rejected · C cancelled · CR change request.

Operations

• GET/api/v2/{companyId}/purchase-requests/: paginated list with filters.
• GET/api/v2/{companyId}/purchase-requests/{id}/: one request.
• POST/api/v2/{companyId}/purchase-requests/: create one, answers 201 with the same shape.