References

⚠️ 🚧 In progress, This integration is under active design and not yet available. The schema, field names, and behavior may change before general availability.

Overview

References represent the buyer's article master data, the items available for browsing, matching to offers, and ordering. Each reference describes a single article and may carry multiple logistics units representing alternative packaging options.

This endpoint enables buyers to:

• Push article master data from ERP or PLM systems into a buyer workspace
• Refresh references incrementally (idempotent upsert by code)
• Manage logistics-unit dimensions (weight, pieces, pallet density) per packaging option

🛠️ TBD — planned: a deleted_at timestamp, scoped either at the reference level or at the logistics-unit level. To be worked on.

Endpoints

Data Model

Structure

Each reference is a nested record with three optional collections:

• attributes[], EAV-style attributes (origin, variety, size, packaging, vat_rate, etc.)
• logistics_units[], one entry per packaging option (e.g. case, IFCO crate, half-pallet)
• metadata, partner-specific traceability payload

Important, grouping: one reference row per article. All packaging options for that article are collapsed into a single logistics_units[] array. Do not emit one reference per packaging option, the endpoint upserts by code, and repeated POSTs with the same code would overwrite prior logistics_units rows.

Idempotency

The code field is the idempotency key:

• Submitting a new code creates a new record
• Resubmitting an existing code fully replaces the reference (including attributes, logistics_units, and metadata)

Fields

product_kinds[]

The reference's category hierarchy as an ordered array, root → leaf. Each entry is { "code": "<code>", "name": "<label>" }. The server resolves each code against the workspace's product_kind.external_id per level and links the reference to the leaf node.

Example of a 3-level hierarchy:

1. Family, e.g. { "code": "001", "name": "Vegetables" }
2. Sub-family, e.g. { "code": "010", "name": "Salad" }
3. Article (leaf), e.g. { "code": "00012345", "name": "Tomato cherry 250g" }

attributes[]

Each item: { "attribute": "<key>", "value": "<string>" }. All values are sent as strings, numeric values are parsed server-side using the decimalseparator query parameter.

Omit empty values: do not send attributes (or metadata keys, or optional logistics-unit fields) whose value is empty, null, or a sentinel like "0" / "NULL" / "---" / "_". Omit the entry entirely rather than emitting "".

The list of attribute keys is open, partners send whatever is relevant for their integration. The engineering spec maintains the canonical per-partner catalogue.

logistics_units[]

Each entry describes one packaging option for the reference.

metadata

Partner-specific key-value pairs. Stored as-is for traceability and audit; Consentio does not interpret values. The list of keys is open, partners send whatever is relevant for their integration.

Creating References

Submit one or more references using POST /references. Both application/json and text/csv are accepted; CSV parsing is controlled by the csvseparator and decimalseparator query parameters.

Request

POST /v2/partner/{workspaceID}/references
Content-Type: application/json
Authorization: Bearer {token}

The request body is a ReferenceBulkRequest, see the API Reference for the full schema (PartnerReference, PartnerReferenceProductKind, PartnerReferenceAttribute, PartnerReferenceLogisticsUnit).

Partner-specific example payloads are shared separately during integration onboarding rather than embedded here, so the contract documented in this page stays generic.

Query parameters

Response

{
  "references": [
    {
      "id": 42,
      "code": "REF-001",
      "name": "Tomato cherry 250g",
      "status": "active",
      "...": "..."
    }
  ],
  "errors": []
}

Partial success

Each reference is processed independently. Successful items are returned in references, while errors for failed items are collected in errors:

{
  "references": [ { "id": 42, "code": "REF-001" } ],
  "errors": [
    "REF-002: unknown product_kinds[0].id 'XYZ'"
  ]
}

Retrieving References

Fetch existing references using GET /references with date filters.

Request

GET /v2/partner/{workspaceID}/references?from=2026-01-01T00:00:00Z&to=2026-04-30T23:59:59Z
Authorization: Bearer {token}

Query Parameters

Updating References

References support incremental updates over multiple API calls. To update an existing record, resubmit it with the same code. The record is fully replaced with the new values, including its nested attributes, logistics_units, and metadata.

Soft delete

Setting status: "inactive" is a soft delete, the row is kept (so internal IDs and audit trails are preserved) but hidden from active references. Reactivate by re-posting the same code with status: "active".

Integration Workflow

sequenceDiagram
    participant ERP as Buyer ERP / PLM
    participant API as Consentio API

    ERP->>API: POST /references
(article master data, batch up to 500)
    API-->>ERP: 200 OK (with Consentio IDs)

    Note over API: References stored;
logistics units linked to box_types

    loop References refresh (e.g. nightly)
        ERP->>API: POST /references (incremental updates)
        API-->>ERP: 200 OK
    end

    ERP->>API: GET /references?from=...&to=...
    API-->>ERP: References changed since last sync

Error Handling

Best Practices

1. One reference per article: group all packaging options for the same article under one code in logistics_units[]. Never split the same article across multiple references.

2. Stable codes: use a stable, partner-side identifier for code. This is the upsert key.

3. Stable box-type codes: prefer short, stable box_type_code values (e.g. COL, CRT, 2PL). Box dictionary entries are reusable across references.

4. Batch submissions: send up to 500 references per request to reduce API calls.

5. Stringified numerics: send numbers as strings (e.g. "5.5", "302.40"); the server parses using decimalseparator. This keeps JSON and CSV payloads identical.

6. Filter provisional data on the client: drop temporary or in-validation rows before posting.

7. Idempotent retries: failed requests are safe to retry, duplicates are prevented by the code key.