Hivebuy API v2 ## Sections • [Hivebuy External API (v2)](https://documentation.hivebuy.de/hivebuy-external-api-v2.md): The Hivebuy External API is a versioned API for machine-to-machine integrations: ERP sync, master-data management, archiving, BI, payment runs. The… • [Companies](https://documentation.hivebuy.de/companies.md): Discover which companies your API key is entitled to use. Every other endpoint in this API is scoped to one of these company ids. A tenant-wide key… • [List accessible companies](https://documentation.hivebuy.de/companies/list-accessible-companies.md): Returns the companies this API key may use, ordered by name. Which companies that is depends on the kind of key: A tenant-wide key lists every… • [Addresses](https://documentation.hivebuy.de/addresses.md): Full CRUD on company addresses. This API is the first place a scoped API key can manage addresses at all. type accepts company , billing , shipping… • [List addresses](https://documentation.hivebuy.de/addresses/list-addresses.md): Paginated company addresses, by name. This API is the first place a scoped key can manage addresses at all. It also lists personal and manual… • [Create an address](https://documentation.hivebuy.de/addresses/create-an-address.md): Creates an address. street , houseNumber , postalCode and city are required. type accepts only company , billing , shipping and office ; personal and… • [Get an address](https://documentation.hivebuy.de/addresses/get-an-address.md): One address by id. Soft delete: the row disappears from the list but stays retrievable by id with deleted set. PUT , PATCH and DELETE against an… • [Replace an address](https://documentation.hivebuy.de/addresses/replace-an-address.md): Replaces the writable fields. Unsetting the company’s last default delivery or default invoice address is a 400 : a company must always have one of… • [Update an address](https://documentation.hivebuy.de/addresses/update-an-address.md): Updates the fields you send. {"defaultDelivery": true} moves the default here too. Requires master-data:write . • [Delete an address](https://documentation.hivebuy.de/addresses/delete-an-address.md): Soft-deletes the address, and unlinks it from every legal entity first. Soft delete: the row disappears from the list but stays retrievable by id… • [Catalogues](https://documentation.hivebuy.de/catalogues.md): Full CRUD on catalogues. Needs the Catalogues feature enabled for the company on top of External API ; when it is off every verb returns 403 , rather… • [List catalogues](https://documentation.hivebuy.de/catalogues/list-catalogues.md): Paginated catalogues of one company, by name. Needs the Catalogues feature on top of External API . When it is off, every verb here returns 403 ,… • [Create a catalogue](https://documentation.hivebuy.de/catalogues/create-a-catalogue.md): Creates a catalogue. names is required and is a locale-keyed object. Only names , description , emoji and legalEntities are writable; departments and… • [Get a catalogue](https://documentation.hivebuy.de/catalogues/get-a-catalogue.md): One catalogue by id. Soft delete: the row disappears from the list but stays retrievable by id with deleted set. PUT , PATCH and DELETE against an… • [Replace a catalogue](https://documentation.hivebuy.de/catalogues/replace-a-catalogue.md): Replaces the four writable fields. Requires master-data:write . • [Update a catalogue](https://documentation.hivebuy.de/catalogues/update-a-catalogue.md): Updates the fields you send. Requires master-data:write . • [Delete a catalogue](https://documentation.hivebuy.de/catalogues/delete-a-catalogue.md): Soft-deletes the catalogue. Soft delete: the row disappears from the list but stays retrievable by id with deleted set. PUT , PATCH and DELETE… • [Categories](https://documentation.hivebuy.de/categories.md): Full CRUD on purchase categories. One field set serves read and write, and children carries the whole subtree of a category, so a single list call… • [List categories](https://documentation.hivebuy.de/categories/list-categories.md): Paginated categories of one company, newest first by default, the one resource on this API that does not default to name . children carries the whole… • [Create a category](https://documentation.hivebuy.de/categories/create-a-category.md): Creates a category. names is required and is a locale-keyed object. parent must be a category of the same company; anything else is a 400 . company… • [Get a category](https://documentation.hivebuy.de/categories/get-a-category.md): One category by id, including its full subtree in children . Soft delete: the row disappears from the list but stays retrievable by id with deleted… • [Replace a category](https://documentation.hivebuy.de/categories/replace-a-category.md): Replaces the writable fields of a category. Fields you omit are reset to their defaults; use PATCH to change a few. Requires master-data:write . • [Update a category](https://documentation.hivebuy.de/categories/update-a-category.md): Updates the fields you send and leaves the rest alone. Requires master-data:write . • [Delete a category](https://documentation.hivebuy.de/categories/delete-a-category.md): Soft-deletes a category, but the side effects are permanent and are not undone by restoring the row: approval-flow conditions naming the category are… • [Bulk upsert categories](https://documentation.hivebuy.de/categories/bulk-upsert-categories.md): Send a JSON array of rows, at most 50 per request. The response is always 200 with two arrays in row order: upserted (the row as you sent it plus id… • [Contracts](https://documentation.hivebuy.de/contracts.md): Full CRUD on contracts, the agreements behind recurring spend: leases, licenses, service and framework agreements, supplier contracts. Requires the… • [List contracts](https://documentation.hivebuy.de/contracts/list-contracts.md): Newest first by default. ?status= and ?contractType= narrow by word, repeated keys and comma lists accepted, unknown values are a 400 listing the… • [Create a contract](https://documentation.hivebuy.de/contracts/create-a-contract.md): Creates a contract. name is required. owner must be an active member of this company; department , category and companySupplier must belong to it.… • [Get a contract](https://documentation.hivebuy.de/contracts/get-a-contract.md): One contract. Soft-deleted rows are returned here too, so a caller holding an id can still read what it deleted. Requires master-data:read , and the… • [Replace a contract](https://documentation.hivebuy.de/contracts/replace-a-contract.md): Replaces the writable fields. Keys only the read shape carries ( files , the …Currency siblings, the computed totals) are accepted and ignored, so a… • [Update a contract](https://documentation.hivebuy.de/contracts/update-a-contract.md): Changes only what you send. To update the recurrence in place, include its id inside the recurrence object. Requires master-data:write , and the… • [Delete a contract](https://documentation.hivebuy.de/contracts/delete-a-contract.md): Soft delete, the row is recoverable and stays readable by id. The side effects are not: every catalogue item linked to the contract is deactivated,… • [Departments](https://documentation.hivebuy.de/departments.md): Full CRUD on departments. Members, approvers and budget owners are nested user objects when you read and plain user ids when you write; every id must… • [List departments](https://documentation.hivebuy.de/departments/list-departments.md): Paginated departments of one company, by name. Members, approvers and budget owners are nested user objects on read and plain ids on write. Unlike… • [Create a department](https://documentation.hivebuy.de/departments/create-a-department.md): Creates a department. name is required. Every id in members , approvers and budgetOwners must be an active member of this company, and legalEntity… • [Get a department](https://documentation.hivebuy.de/departments/get-a-department.md): One department by id. Soft delete: the row disappears from the list but stays retrievable by id with deleted set. PUT , PATCH and DELETE against an… • [Replace a department](https://documentation.hivebuy.de/departments/replace-a-department.md): Replaces the writable fields. Omitted user lists are cleared; use PATCH to keep them. Requires master-data:write . • [Update a department](https://documentation.hivebuy.de/departments/update-a-department.md): Updates the fields you send. The response is the read shape, with users nested. Requires master-data:write . • [Delete a department](https://documentation.hivebuy.de/departments/delete-a-department.md): Soft-deletes the department. Soft delete: the row disappears from the list but stays retrievable by id with deleted set. PUT , PATCH and DELETE… • [Bulk upsert departments](https://documentation.hivebuy.de/departments/bulk-upsert-departments.md): Send a JSON array of rows, at most 50 per request. The response is always 200 with two arrays in row order: upserted (the row as you sent it plus id… • [Invoices](https://documentation.hivebuy.de/invoices.md): Read-only access to a company's invoices, including line items, taxes, linked purchase orders, and files. By default, list results exclude… • [List invoices](https://documentation.hivebuy.de/invoices/list-invoices.md): Paginated invoices of one company, newest first by default. Unless you filter by status explicitly, uploads classified as not-an-invoice ( NI ) or… • [Get invoice](https://documentation.hivebuy.de/invoices/get-invoice.md): One invoice by ID. Unlike the list, this returns the invoice regardless of status, so an ID you already hold always resolves. • [Catalogue items](https://documentation.hivebuy.de/catalogue-items.md): Full CRUD on catalogue items, plus a bulk upsert. A catalogue item is a product. Prices, barcodes and attachments live on its variants , so every… • [List catalogue items](https://documentation.hivebuy.de/catalogue-items/list-catalogue-items.md): Paginated catalogue items of one company, with their variants nested in full. The response is the standard envelope: totalRecords , totalPages ,… • [Create a catalogue item](https://documentation.hivebuy.de/catalogue-items/create-a-catalogue-item.md): Creates one catalogue item with its variants. names , category and itemVariants are required, and itemVariants may not be empty. category and… • [Bulk upsert catalogue items](https://documentation.hivebuy.de/catalogue-items/bulk-upsert-catalogue-items.md): Upserts up to 50 catalogue items in one call, matched within this company only. Matching. Each row is matched by id first. Send the item’s id to… • [Get a catalogue item](https://documentation.hivebuy.de/catalogue-items/get-a-catalogue-item.md): One catalogue item by id, with its variants. This route also reaches soft-deleted items, so an item that has left the list is still readable here.… • [Replace a catalogue item](https://documentation.hivebuy.de/catalogue-items/replace-a-catalogue-item.md): Replaces the writable fields of the item, including its whole variant list. Variants. A variant you send with an id updates that variant. A variant… • [Update a catalogue item](https://documentation.hivebuy.de/catalogue-items/update-a-catalogue-item.md): Updates the fields you send and leaves the rest alone. itemVariants is not merged. If you send it, it replaces the whole list under the same rules as… • [Delete a catalogue item](https://documentation.hivebuy.de/catalogue-items/delete-a-catalogue-item.md): Soft-deletes the item. The row is never destroyed. It leaves the list, stays readable by GET /api/v2/{companyId}/items/{id}/ , and its id stops… • [Legal entities](https://documentation.hivebuy.de/legal-entities.md): Full CRUD on legal entities. Needs the Legal entity feature enabled for the company on top of External API ; without it every verb here is 403 . The… • [List legal entities](https://documentation.hivebuy.de/legal-entities/list-legal-entities.md): Paginated legal entities of one company, by name. Needs the Legal entity feature on top of External API ; without it every verb here is 403 . Unlike… • [Create a legal entity](https://documentation.hivebuy.de/legal-entities/create-a-legal-entity.md): Creates a legal entity. name is required. The three link lists are writable, and isDefault is required on every entry , it decides the ordering of… • [Get a legal entity](https://documentation.hivebuy.de/legal-entities/get-a-legal-entity.md): One legal entity by id, with departments, users, categories and the three link lists nested in full. Soft delete: the row disappears from the list… • [Replace a legal entity](https://documentation.hivebuy.de/legal-entities/replace-a-legal-entity.md): Replaces the writable fields. A link list you omit is treated as empty, so PUT without legalEntityDeliveryAddresses clears the delivery-address links… • [Update a legal entity](https://documentation.hivebuy.de/legal-entities/update-a-legal-entity.md): Updates the fields you send; link lists you omit are left untouched. Requires master-data:write . • [Delete a legal entity](https://documentation.hivebuy.de/legal-entities/delete-a-legal-entity.md): Soft-deletes the legal entity. Soft delete: the row disappears from the list but stays retrievable by id with deleted set. PUT , PATCH and DELETE… • [Bulk upsert legal entities](https://documentation.hivebuy.de/legal-entities/bulk-upsert-legal-entities.md): Send a JSON array of rows, at most 50 per request. The response is always 200 with two arrays in row order: upserted (the row as you sent it plus id… • [Projects](https://documentation.hivebuy.de/projects.md): Full CRUD on projects, plus a bulk upsert. participatingDepartments and projectDeliveryAddresses are readable but server-maintained. budget is… • [List projects](https://documentation.hivebuy.de/projects/list-projects.md): Paginated projects of one company, by name. Unlike the in-app endpoint, results are not narrowed to the projects the key user is assigned to: a key… • [Create a project](https://documentation.hivebuy.de/projects/create-a-project.md): Creates a project. name is required. parent , legalEntity , deliveryAddress and invoiceAddress must belong to this company; a deleted address is… • [Get a project](https://documentation.hivebuy.de/projects/get-a-project.md): One project by id, including its budget and the departments participating in it. Soft delete: the row disappears from the list but stays retrievable… • [Replace a project](https://documentation.hivebuy.de/projects/replace-a-project.md): Replaces the writable fields. The read-only trio ( budget , participatingDepartments , projectDeliveryAddresses ) is unaffected. Requires… • [Update a project](https://documentation.hivebuy.de/projects/update-a-project.md): Updates the fields you send, closing a project is {"status": "C", "active": false} . budget accepts the nested budget write: usedBudget ,… • [Delete a project](https://documentation.hivebuy.de/projects/delete-a-project.md): Soft-deletes the project. Soft delete: the row disappears from the list but stays retrievable by id with deleted set. PUT , PATCH and DELETE against… • [Bulk upsert projects](https://documentation.hivebuy.de/projects/bulk-upsert-projects.md): Create or update many projects in one request. Send a JSON array of project rows. Each row is matched against the projects of the URL company using a… • [Purchase orders](https://documentation.hivebuy.de/purchase-orders.md): Read a company's purchase orders, report progress back on them, and attach documents. This is the pair of surfaces an order-fulfilling system… • [List purchase orders](https://documentation.hivebuy.de/purchase-orders/list-purchase-orders.md): Paginated, highest order number first. Note pageSize defaults to 10 and caps at 30 on this resource, not the 25/100 used elsewhere: a purchase order… • [Set a purchase order status](https://documentation.hivebuy.de/purchase-orders/set-a-purchase-order-status.md): Report progress on an order: set its status, record your own sync result, set the supplier order number, or release an on-hold order to the supplier.… • [Get a purchase order](https://documentation.hivebuy.de/purchase-orders/get-a-purchase-order.md): One order by its UUID (the uuid field on the read shape). The legacy endpoint answered 405 here; this one works. Requires transactional:read . • [Attach a document to a purchase order](https://documentation.hivebuy.de/purchase-orders/attach-a-document-to-a-purchase-order.md): Attaches one file to the order. Send JSON with a base64 file , or multipart with a file part. The effective ceiling is about 1.9 MB (a 2.5 MB body… • [Suppliers](https://documentation.hivebuy.de/suppliers.md): Full CRUD on suppliers. This is the buyer-side supplier record: from a client's perspective, the supplier. Whether a record is backed by one of… • [List suppliers](https://documentation.hivebuy.de/suppliers/list-suppliers.md): Paginated suppliers of one company, by name. Narrow with search (name, supplier number, external supplier number). Two behaviour differences from the… • [Create a supplier](https://documentation.hivebuy.de/suppliers/create-a-supplier.md): Creates a supplier. name is required. Credentials and punchout identity (login, password, secret key, punchout and cXML URLs, party ids) are never… • [Get a supplier](https://documentation.hivebuy.de/suppliers/get-a-supplier.md): One supplier by id. This is the buyer-side supplier record. Whether it is backed by one of Hivebuy’s integrated suppliers is not exposed, in any… • [Replace a supplier](https://documentation.hivebuy.de/suppliers/replace-a-supplier.md): Replaces the writable fields. The eight assigned* visibility fields, files and budgets are read-only and unaffected. Requires master-data:write . • [Update a supplier](https://documentation.hivebuy.de/suppliers/update-a-supplier.md): Updates the fields you send. To change one companySupplierLegalEntities link, send it with its id . Requires master-data:write . • [Delete a supplier](https://documentation.hivebuy.de/suppliers/delete-a-supplier.md): Soft-deletes the supplier. Soft delete: the row disappears from the list but stays retrievable by id with deleted set. PUT , PATCH and DELETE against… • [Bulk upsert suppliers](https://documentation.hivebuy.de/suppliers/bulk-upsert-suppliers.md): Send a JSON array of rows, at most 50 per request. The response is always 200 with two arrays in row order: upserted (the row as you sent it plus id… • [Users](https://documentation.hivebuy.de/users.md): The people directory: who works in this company, in what roles, under which supervisor. Built for syncing from an HR system (an “HRIS”: Personio,… • [List the company members](https://documentation.hivebuy.de/users/list-the-company-members.md): The URL company’s members, ordered by email. roles and supervisor are the URL company’s membership values. Deactivated members are included; service… • [Batch upsert users](https://documentation.hivebuy.de/users/batch-upsert-users.md): POST a JSON array of up to 50 items. Each is matched by email and walked down the ladder on the section page: email-change mode ( newEmail ),… • [Retrieve one member](https://documentation.hivebuy.de/users/retrieve-one-member.md): One member of the URL company. Requires master-data:read . • [Purchase requests (pre-release)](https://documentation.hivebuy.de/purchase-requests-pre-release.md): ⚠️ 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… • [List purchase requests](https://documentation.hivebuy.de/purchase-requests-pre-release/list-purchase-requests.md): Pre-release. See the section page before building on this. Paginated, newest request number first. Every filter is optional and an unknown query… • [Create a purchase request](https://documentation.hivebuy.de/purchase-requests-pre-release/create-a-purchase-request.md): Pre-release. See the section page before building on this. Creates the request in the company in the path and answers 201 with the same shape the… • [Retrieve a purchase request](https://documentation.hivebuy.de/purchase-requests-pre-release/retrieve-a-purchase-request.md): Pre-release. See the section page before building on this. One request by UUID. Same shape as a list row. Requires transactional:read .