Bulk upsert projects

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 fixed ladder of identifiers; a match is updated, no match creates a new project. Rows are processed independently, each in its own transaction, so one bad row never fails the batch.

This is the /api/v2/ successor of the legacy POST /api/company/bulk-upsert/projects/ route, with the same matching ladder, the same per-row error envelope, and the same nested budget write. Keys are camelCase on the wire.

Endpoint

POST /api/v2/{companyId}/bulk-upsert/projects/

Body: JSON array of project rows, at most 50 per request. A longer array, or a body that is not an array, is refused whole with 400. Requires an API key with master-data:write.

Matching order

For each row the API walks these lookups in order, within your company only. The first lookup that matches exactly one project wins. If no lookup matches, a new project is created.

1. id: UUID of a project in your company. Does not fall through: an unknown id fails the row with unknown_id, because falling through could update an unrelated project.
2. externalId: the reference of the project in your system, usually its UUID or key in the ERP. An unknown value falls through to the next lookups, so a first sync can link projects you already track by number.
3. projectNumber + parent: parent is the parent project’s projectNumber.
4. projectNumber alone. Only evaluated when lookup 3 finds nothing.
5. costCenter
6. name

If a lookup finds several projects the row is rejected with ambiguous_match and the candidate ids; matching does not continue to the next lookup. If a project matched by lookup 3 to 6 already carries a different externalId than the row, the row is rejected with external_id_conflict rather than silently re-linked.

Field resolution

Reference fields are given by name, matching the sync systems these routes serve:

• parent: projectNumber of an existing project, or null to clear. Unknown number: parent_not_found.
• legalEntity: name of an existing legal entity, or null to clear. Unknown name: legal_entity_not_found.
• approvers, budgetOwners: list of email addresses of active users in your company. Any unknown email: users_not_found, with the unresolved emails under details.unresolved.
• members: list of user ids or emails, same rule.
• deliveryAddress, invoiceAddress: id of a company address that belongs to your company.
• participatingDepartments, projectDeliveryAddresses: accepted and ignored. They are read-only on the v2 project resource.

Budget

Two levels of control:

• totalProjectBudget (or budget.amount, they are the same value) sets the total. Hivebuy keeps a budget row per project whose amount follows this total, valid for the company’s budget year. Omit totalProjectBudgetCurrency to use the company currency.
• budget.usedBudget, budget.pendingBudget, budget.remainingBudget are normally computed by Hivebuy from purchase requests (pending) and orders and invoices (used). If your system is the source of truth for consumption, send them inside budget to override the computed values. An override skips Hivebuy’s own recalculation for that write. It holds until the next purchase request or invoice event on the project, which recalculates and overwrites it. Last write wins, by design: re-send your figures on every sync run.

Rules for the budget object: only the keys you send change; all money values are decimal strings in one currency, matching the stored budget’s currency (amountCurrency if you send it, the company currency otherwise); when amount, usedBudget and remainingBudget are all present, amount must equal usedBudget + pendingBudget + remainingBudget. A violation fails that row with validation_error and the field-level detail under details.budget.

The upserted entry echoes the row as you sent it, so it shows the budget you submitted, not the stored figures. Read the stored figures back with GET /api/v2/{companyId}/projects/{id}/.

Partial updates

A matched project is updated like PATCH: fields you omit are not modified. To clear a list field send an empty list; to clear a scalar reference send null.

Response

Always 200 once the top-level validation passes. Two arrays, in row order:

• upserted: one entry per stored row, the row as you sent it plus id and action (created or updated).
• errors: one entry per failed row, with your row under data, a machine-readable errorCode, a message, and where possible errorField and details.

Errors

Per-row errorCode values: unknown_id, invalid_id, ambiguous_match, external_id_conflict, parent_not_found, legal_entity_not_found, users_not_found, departments_not_found, validation_error, unexpected. Whole-request refusals (400) carry a plain {"error": …} body with received and upsertLimit when the array is too long.