What is a Reference ID?

A Reference ID is an opaque identifier produced by Werk24 to link the same object (e.g., a feature) across results returned by different Asks. With it, you can correlate extracted artifacts—such as features, balloons, and meta data—without re-matching geometry or text.

Why Use Reference IDs?

Reliable correlation across independent Asks (e.g., AskFeatures ↔ AskBalloons).
Order-agnostic joins: results arrive asynchronously; reference_id lets you join without assuming timing or ordering.
Less brittle than string/geometry matching (tolerates minor OCR/segmentation differences).

Reference IDs are created by Werk24. You should treat them as opaque strings (even if they look like integers) and never depend on ordering, continuity, or formatting.

Scope & Guarantees

Uniqueness (job scope): Unique within a single processing job (file/version/variant).
Stability (job scope): Stable across all Asks for that job. The same object returns the same reference_id everywhere it appears.
No cross-job guarantees: Re-uploads, different variants, or changed preprocessing may yield different IDs.
Per-page context: When relevant, IDs are unique per job, but correlation is often combined with page_index for robustness.
Cardinality: One object → one reference_id. Multiple artifacts that describe the same object (balloon, dimension, callout) will share it.

Example: Features ↔ Balloons

Features (excerpt)

{
    "ask_version": "v2",
    "ask_type": "FEATURES",
    "page_type": "COMPONENT_DRAWING",
    "dimensions": [
        {
            "reference_id": 0,
            "label": "12 ±0.1",
            "confidence": {
                "score": "0.96"
            },
            "quantity": 1,
            "size": {
                "value": "12",
                "unit": "mm",
                "size_type": "LINEAR",
                "tolerance": {
                    "tolerance_grade": "12",
                    "deviation_lower": "-0.1",
                    "deviation_upper": "0.1",
                    "fit": null,
                    "is_theoretically_exact": false,
                    "is_reference": false,
                    "is_general_tolerance": false,
                    "is_approximation": false
                }
            }
        }
    ],
    ...
}

Balloons (excerpt)

{
  "balloons": [
    {
      "reference_id": "0",
      "center": [55, 30],
    }
  ]
}

Best Practices

Treat as strings: Even if IDs look numeric, cast to string to avoid type surprises.
Join with page context: Use (reference_id, page_index) when available to reduce accidental collisions in edge cases.
Don’t assume order/contiguity: reference_id values are not sorted, sequential, or gap-free.
Design for partial arrivals: Hooks fire as results are ready; keep a staging store and upsert on arrival.
Avoid re-IDing: Never “mint” your own IDs to replace Werk24's reference_id for internal joins within the same job. Instead, map Werk24 IDs to your own stable keys if needed.

FAQ

Is a Reference ID globally unique? No. It’s unique within a job and stable across all Asks for that job.

Can I choose the value of reference_id? No. It is assigned by Werk24. If you need your own IDs, map them to reference_id in your database.

Do I always need page_index to join? Not strictly, but including it makes joins more robust—especially on very dense drawings or multi-page documents.

Quick Checklist

[ ] Join across Asks by (reference_id, page_index).
[ ] Treat IDs as opaque strings; never rely on ordering.
[ ] Upsert results as they arrive (asynchronous Hooks).
[ ] Maintain a mapping to your internal IDs if needed across jobs.
[ ] Log and flag any artifacts missing reference_id.