ERP handover REST API
The handover API exposes released bills of materials and related documents as immutable packages. Your ERP integrator can retrieve them, map articles and import them into your business workflow. Once released, packages can be read without an open confBuild editor.
Status (9 October 2026): The REST API and editor handover are deployed and available. Owners of private projects create project-scoped credentials directly in the BOM dialog. Agree a pilot scope with us for integration into your ERP. This is a foundation for custom integration; it does not imply a ready-made SAP, Microsoft Dynamics or Odoo connector.
Download OpenAPI 3.1 · Download Python example
Release a package
- Open your own saved project in the confBuild editor, then open its Bill of materials.
- Check the positions and active filters. ERP handover uses exactly the displayed positions, including search and hidden-row filters. This can be a partial assembly.
- Optionally enter an external reference, such as an ERP quote number. JSON and CSV are generated automatically from the submitted BOM.
- Optionally attach PDF, STEP or DXF files and confirm that they belong to this snapshot. Their bytes are stored unchanged; the API does not automatically verify CAD/drawing revision matching.
- Confirm and select Release package. You receive a release ID, sequence number and data coverage warnings.
Releases never change. Model changes require reopening the current BOM and creating a new release. “Released” records your handover decision, not automatic engineering certification.
After a connection failure, retry with identical fields and files in the same browser tab. Session storage retains the pending request across reopening the dialog or reloading that tab. Only a fingerprint and retry identifier are stored, never BOMs or credentials. Select the same attachments again and enter the same external reference. After acknowledged success, publishing again creates a new package. With session storage disabled, protection lasts only until the page reloads; a new tab or changed input is a new request.
Create a credential
Use API credentials for this project in the same dialog. A new secret is shown once; only its hash is stored on the server. Use Copy credential to transfer it into your ERP server’s secure configuration, then hide it. The list distinguishes active, expired and revoked credentials.
The credential can only read releases of this one project. It cannot edit models, publish packages or manage credentials. UI-created keys expire after 90 days; the management API permits 1–365 days. Each project allows 20 active keys. Revoke a key in the dialog to stop further access. Copies already downloaded remain with their recipients.
This first version supports the owner of a privately stored project. Shared company projects/public templates must first be copied into your own project collection. Deleting the source project or losing ownership prevents further API reads.
Base URL and first request
The production base URL is:
https://app.confbuild.com/api/v1
The live OpenAPI endpoint also serves the current contract. All private endpoints require Authorization: Bearer …. Keep credentials on your server, never in public JavaScript or URLs.
# Set CONFBUILD_API_KEY securely in your environment first.
curl --fail-with-body \
-H "Authorization: Bearer $CONFBUILD_API_KEY" \
'https://app.confbuild.com/api/v1/releases?limit=25'
The response contains items and nextCursor. Each release has an ascending sequence. Persist the highest fully processed sequence and pass it as cursor for subsequent polls. nextCursor: null only means there is no further page right now; retain your last processed sequence.
curl --fail-with-body \
-H "Authorization: Bearer $CONFBUILD_API_KEY" \
"https://app.confbuild.com/api/v1/releases/$RELEASE_ID/bom"
Endpoints
| Method | Path | Purpose |
|---|---|---|
| GET | /releases?cursor=0&limit=25 |
Project releases in ascending order |
| GET | /releases/{id} |
Metadata, warnings and document manifest |
| GET | /releases/{id}/bom |
Frozen BOM JSON |
| GET | /releases/{id}/documents |
Documents with media type, size and SHA-256 |
| GET | /releases/{id}/documents/{documentId} |
Authorized download |
| GET | /openapi.json |
Public API description |
Management endpoints POST /releases, GET/POST /keys and DELETE /keys/{id} require a current Firebase ID token from the project owner, not a read key. Pass projectId as a query parameter for GET/DELETE or in the JSON body for POST. The confBuild dialog handles this. OpenAPI provides complete request schemas for custom management clients.
POST /releases requires an Idempotency-Key of 16–128 letters, digits, hyphens or underscores. Repeating the same content/key returns the same release (200); a new release returns 201. Reusing a key with different content returns 409. After a timeout retry the same body and key.
Data contract
| Field | Meaning |
|---|---|
articleNumber |
Internal article number from the BOM, otherwise null |
manufacturerPartNumber |
Manufacturer article number, separate from the internal number |
lineId |
Identity of a BOM grouping, not an automatic ERP article identifier |
quantity, unit |
Quantity and piece, meter, sqm, kg or liter |
sourcing |
make, buy or unknown |
material |
Material label from the BOM |
mechanicalMaterialId, materialStatus |
The initial editor adapter reports null / unknown; do not infer verified physical material IDs from labels |
articleRevision |
Unknown (null) in the initial editor adapter |
sourceRevision |
Project-provided revision label; not proof of a server-verified CAD revision |
contentHash |
SHA-256 of the normalized handover payload and document manifest |
externalReference |
Optional link to your ERP quote/order |
For custom publication clients: required names, lineId and entries in sourceIds/assemblies must contain non-whitespace text. Outer whitespace is trimmed; blank optional labels become null and remain identifiable as missing data. Text labels allow up to 500 characters, lineId 128 and source identifiers 250; limits apply before trimming. position is a positive integer up to 9,007,199,254,740,991. Send unknown sources as an empty array []. Line identifiers must remain unique after trimming.
JSON is the authoritative structured format. CSV is a flat subset with spreadsheet formula prefixes escaped. Attachments carry provenance: publisher-attested; generated BOM documents use generated-from-bom. Verify downloaded sizes and SHA-256 hashes against the manifest.
This version excludes prices, stock, routings and full model parameters. Missing article, material or source data remain null or carry warnings. ERP article mapping and engineering-to-manufacturing BOM conversion belong to the customer-specific integration.
Limits and errors
Up to 2,000 positions and 600 KB normalized metadata/BOM per release. Up to eight optional attachments, 3 MiB each and 6 MiB combined; request size at most 9 MiB. Filenames allow ASCII letters, digits, spaces, dots, hyphens and underscores, with PDF/STEP/STP/DXF extensions.
120 authenticated requests per key or owner per minute; key creation additionally allows five and publishing attempts ten per owner per minute. 429 includes Retry-After: 60. Additional ingress protection may apply earlier.
| HTTP status | Action |
|---|---|
| 400 | Correct fields, identifiers or pagination |
| 401 | Missing, expired or revoked credential/sign-in |
| 403 | Operation exceeds the credential’s scope |
| 404 | Project, release or document is not accessible |
| 405 | HTTP method unsupported for this endpoint |
| 409 | Idempotency conflict or active-key limit |
| 413 | Package exceeds size limits |
| 429 | Retry after the indicated delay |
| 431 | Reduce request header size |
| 503 | Temporary or integrity error; do not advance the processing cursor |
Errors return { "error": { "code": "…", "message": "…", "requestId": "…" } }. The same ID appears in X-Request-Id, including rejected oversized packages. Supply the request ID to support, never your credential. Errors from an upstream hosting or network layer may differ.
Consumer example
The Python example uses only the Python 3 standard library. It downloads packages and attachments, verifies sizes and SHA-256 hashes, and advances the cursor only after a complete verified download. After an interruption, rerunning reuses already verified files and downloads corrupted files again. Temporary network failures and HTTP 429/502/503/504 receive up to four attempts, with delays of 2, 4 and 8 seconds or Retry-After (capped at 60 seconds). Authentication failures stop immediately. Response sizes and increasing cursors are checked. Run only one consumer per output directory.
# Provide CONFBUILD_API_KEY securely first.
python3 confbuild-handover-pull.py
Optional CONFBUILD_API_BASE and CONFBUILD_OUTPUT_DIR select the API address and output directory. After credential rotation, use a new output directory or deliberately reset the checkpoint. The example does not write to an ERP; add your customer-specific import after downloading.