Golden records API

Golden 3.0.0 public API reference. Parameters, responses, and schemas for supported customer operations.

34 operations.

GET /api/golden/duplicates/record-counts

Records with at least one possible duplicate, per entity.

Operation ID: getDuplicateRecordCounts

For each visible entity, counts distinct records in at least one non-ignored duplicate group. This counts records, not groups, and respects the caller’s data scope. Requires the ADMIN, STEWARD or VIEWER role.

Security: bearerAuth

Responses

GET /api/golden/{entity}/buckets

Retrieves buckets for an entity.

Operation ID: getBuckets

Finds a retrieves buckets associated to an entity of potentially duplicated records, using different filtering, sorting and paging criteria. Entity must be enabled. Requires the ADMIN, STEWARD or VIEWER role.

Security: bearerAuth

Parameters

Responses

DELETE /api/golden/{entity}/buckets/delete/{bucket}

Deletes a bucket.

Operation ID: deleteBucket

Locates a bucket associated to an entity and deletes the bucket and the records in the bucket. The record deletion can be physical or logical (but bucket deletion is always physical). Entity must be enabled. Requires the ADMIN or STEWARD role.

Security: bearerAuth

Parameters

Request body

Responses

POST /api/golden/{entity}/buckets/disconnect/{bucket}

Disconnects a bucket.

Operation ID: disconnectBucket

Locates a bucket associated to an entity and records that its records are different from each other: every record is marked as unrelated to every other one (_metadata._unrelated, by set-union with what it already listed). Nothing is deleted and the group is not recomposed: the records stay in the bucket, and a merge whose selection holds any of these pairs is refused unless it crosses the separation on purpose. Entity must be enabled. Requires the ADMIN or STEWARD role.

Security: bearerAuth

Parameters

Request body

Responses

POST /api/golden/{entity}/buckets/disconnect/{bucket}/records

Disconnects a subset of records from a bucket.

Operation ID: disconnectRecordsFromBucket

Marks the records identified by ‘recordIds’ as unrelated to the rest of the bucket’s records (and vice versa); the remaining records keep their pairwise relationships untouched. Nobody leaves the bucket: a merge whose selection holds one of these pairs is refused unless it crosses the separation on purpose. Existing _unrelated entries on the touched records are preserved. Entity must be enabled. Requires the ADMIN or STEWARD role.

Security: bearerAuth

Parameters

Request body

Responses

PUT /api/golden/{entity}/buckets/escalate/{bucket}

Escalates a bucket to an administrator, with a note.

Operation ID: escalateBucket

A steward who may read a group but not decide it — a mixed group, with members outside their data scope — hands it to an administrator. The group stays as it is; it is flagged, with the actor, the time and the note, and the administrator’s list filters on it. Requires the ADMIN or STEWARD role; the group must have at least one member in the caller’s data scope.

Security: bearerAuth

Parameters

Request body

Responses

PUT /api/golden/{entity}/buckets/ignore/{bucket}

Sets ignore flag for a bucket.

Operation ID: ignoreBucket

Locates a bucket associated to an entity and sets the ignore flag to true to ignore the bucket. Entity must be enabled. Requires the ADMIN role: ignoring is a judgement about the grouping rather than about the records in it, and the group leaves every duplicates list once it is set.

Security: bearerAuth

Parameters

Request body

Responses

POST /api/golden/{entity}/buckets/merge/{bucket}

Merges a bucket.

Operation ID: mergeBucket

Locates a bucket associated to an entity and merges the records in the bucket. The merge is done using the record generated automatically using the merger resource. A bucket holding two records recorded as different (_metadata._unrelated, written by a disconnect) is refused with 409 naming the pair, unless ‘crossSeparations’ is set: then a comment is mandatory and only the crossed pairs are revoked. The survivor inherits every other separation of the records it absorbs. Entity must be enabled. Requires the ADMIN or STEWARD role.

Security: bearerAuth

Parameters

Request body

Responses

PUT /api/golden/{entity}/buckets/resolve-escalation/{bucket}

Clears the escalation of a bucket.

Operation ID: resolveBucketEscalation

The administrator has looked at the escalated group; the flag, the actor and the note are cleared. Requires the ADMIN role.

Security: bearerAuth

Parameters

Responses

POST /api/golden/{entity}/buckets/split/{bucket}

Splits a bucket.

Operation ID: splitBucket

Locates a bucket associated to an entity and splits (modifies) the records using the calculated split records or provided ones. Entity must be enabled. Requires the ADMIN or STEWARD role.

Security: bearerAuth

Parameters

Request body

Responses

PUT /api/golden/{entity}/buckets/unignore/{bucket}

Sets ignore flag for a bucket.

Operation ID: unignoreBucket

Locates a bucket associated to an entity and sets the ignore flag to false to consider the bucket. Entity must be enabled. Requires the ADMIN role, as its counterpart does: undoing a decision is the same decision.

Security: bearerAuth

Parameters

Request body

Responses

GET /api/golden/{entity}/buckets/{bucket}

Retrieves one bucket.

Operation ID: getBucket

Locates a certain bucket by identifier, associated to an entity, and returns the bucket of potentially duplicated records. Entity must be enabled. Requires the ADMIN, STEWARD or VIEWER role.

Security: bearerAuth

Parameters

Responses

DELETE /api/golden/{entity}/delete

Deletes a golden record from an entity.

Operation ID: deleteRecord

Locates a golden record by identifier into the indicated entity (table) and deletes it. Entity must be enabled. If the entity has history enabled then logical delete will take place, otherwise physical delete. Record audit information is not returned. An optional comment is recorded on the REMOVE audit event. Requires the ADMIN or STEWARD role.

Security: bearerAuth

Parameters

Request body

Responses

GET /api/golden/{entity}/duplicates/clusters

Retrieves the logical duplicate clusters of an entity.

Operation ID: getDuplicateClusters

Lists logical duplicate groups and their distinct record counts. Groups share at least one record across their candidate groups. By default, fully resolved groups are excluded; pass resolved=true to list them. Requires the ADMIN, STEWARD or VIEWER role.

Security: bearerAuth

Parameters

Responses

GET /api/golden/{entity}/duplicates/clusters/{clusterId}

Retrieves one logical cluster (union of its buckets).

Operation ID: getCluster

Locates a logical cluster by id (the MIN bucket id) and returns the UNION of records across all of its buckets, deduped. Falls back to a single bucket if no cluster row exists. Entity must be enabled. Requires the ADMIN, STEWARD or VIEWER role.

Security: bearerAuth

Parameters

Responses

DELETE /api/golden/{entity}/duplicates/clusters/{clusterId}/delete

Deletes a whole cluster.

Operation ID: deleteCluster

Deletes the union of records across all buckets of the logical cluster (and the now-empty buckets). The record deletion can be physical or logical. Entity must be enabled. Requires the ADMIN or STEWARD role.

Security: bearerAuth

Parameters

Request body

Responses

DELETE /api/golden/{entity}/duplicates/clusters/{clusterId}/delete/records

Deletes a subset of a cluster’s records.

Operation ID: deleteRecordsFromCluster

Deletes the named records of the logical cluster, leaving the rest untouched. The record deletion can be physical or logical. Entity must be enabled. Requires the ADMIN or STEWARD role.

Security: bearerAuth

Parameters

Request body

Responses

POST /api/golden/{entity}/duplicates/clusters/{clusterId}/disconnect

Disconnects a whole cluster.

Operation ID: disconnectCluster

Disconnects all records across all buckets of the logical cluster, marking them mutually unrelated (_metadata._unrelated, by set-union with what each already listed). The cluster is left exactly as the index formed it — the index does not read _unrelated — and what keeps the records apart is the merge, which refuses a selection holding any of these pairs unless it crosses the separation on purpose. Entity must be enabled. Requires the ADMIN or STEWARD role.

Security: bearerAuth

Parameters

Request body

Responses

POST /api/golden/{entity}/duplicates/clusters/{clusterId}/disconnect/records

Disconnects a subset of records from a cluster.

Operation ID: disconnectRecordsFromCluster

Marks the records identified by ‘recordIds’ as unrelated to the rest of the cluster’s union (and vice versa); the remaining records keep their relationships untouched. Nobody leaves the cluster: a merge whose selection holds one of these pairs is refused unless it crosses the separation on purpose. Existing _unrelated entries are preserved. Entity must be enabled. Requires the ADMIN or STEWARD role.

Security: bearerAuth

Parameters

Request body

Responses

PUT /api/golden/{entity}/duplicates/clusters/{clusterId}/escalate

Escalates a cluster to an administrator, with a note.

Operation ID: escalateCluster

The cluster variant of the bucket escalation: the flag is written on every bucket of the cluster. Requires the ADMIN or STEWARD role; the cluster must have at least one member in the caller’s data scope.

Security: bearerAuth

Parameters

Request body

Responses

GET /api/golden/{entity}/duplicates/clusters/{clusterId}/evaluate

Exhaustively compares every pair of records in one cluster.

Operation ID: evaluateCluster

Runs the entity’s classifier over every pair of the cluster’s records — n(n-1)/2 comparisons, computed on demand and never stored. The stored classification only measures adjacent pairs; this is the expert’s deeper look, which is why it is a separate call with a hard size cap instead of part of the cluster read. Entity must be enabled. Requires the ADMIN, STEWARD or VIEWER role.

Security: bearerAuth

Parameters

Responses

PUT /api/golden/{entity}/duplicates/clusters/{clusterId}/ignore

Sets ignore flag for a whole cluster.

Operation ID: ignoreCluster

Sets the ignore flag to true on every bucket of the logical cluster, clearing their classification. Entity must be enabled. Requires the ADMIN role: ignoring is a judgement about the grouping rather than about the records in it, and the cluster leaves every duplicates list once it is set.

Security: bearerAuth

Parameters

Request body

Responses

POST /api/golden/{entity}/duplicates/clusters/{clusterId}/merge

Merges a whole cluster.

Operation ID: mergeCluster

Merges the union of records across all buckets of the logical cluster into a single golden record. A cluster holding two records recorded as different (_metadata._unrelated) is refused with 409 naming the pair, unless ‘crossSeparations’ is set: then a comment is mandatory and only the crossed pairs are revoked. The survivor inherits every other separation of the records it absorbs. Entity must be enabled. Requires the ADMIN or STEWARD role.

Security: bearerAuth

Parameters

Request body

Responses

POST /api/golden/{entity}/duplicates/clusters/{clusterId}/merge/records

Merges a subset of a cluster’s records.

Operation ID: mergeRecordsFromCluster

Merges the named records of the logical cluster into a single golden record, leaving the rest of the cluster untouched. At least two records. A pick holding two records recorded as different (_metadata._unrelated) is refused with 409 naming the pair, unless ‘crossSeparations’ is set: then a comment is mandatory and only the crossed pairs are revoked. Entity must be enabled. Requires the ADMIN or STEWARD role.

Security: bearerAuth

Parameters

Request body

Responses

POST /api/golden/{entity}/duplicates/clusters/{clusterId}/merge/records/preview

Computes the record a subset merge would produce, without merging.

Operation ID: previewMergeOfRecordsFromCluster

Runs the entity’s merger and pipeline over the named records of the logical cluster and returns the golden record the merge would produce. Nothing is written: no record, no bucket, no history and no audit event. The cluster read already publishes this candidate for the WHOLE cluster (its merged member); this is the same answer for a subset, which had no way of being asked for. Validated exactly as the merge is — the entity must be enabled and indexing, the cluster must not be ignored, every named record must be in it, there must be at least two, and a pick holding two records recorded as different is refused with 409 unless ‘crossSeparations’ is set — because a preview that answered where the merge would refuse would be believed. Requires the ADMIN, STEWARD or VIEWER role.

Security: bearerAuth

Parameters

Request body

Responses

PUT /api/golden/{entity}/duplicates/clusters/{clusterId}/resolve-escalation

Clears the escalation of a cluster.

Operation ID: resolveClusterEscalation

The cluster variant of the bucket resolution. Requires the ADMIN role.

Security: bearerAuth

Parameters

Responses

POST /api/golden/{entity}/duplicates/clusters/{clusterId}/split

Splits a whole cluster.

Operation ID: splitCluster

Splits (modifies) the union of records across all buckets of the logical cluster using the calculated split records. Entity must be enabled. Requires the ADMIN or STEWARD role.

Security: bearerAuth

Parameters

Request body

Responses

PUT /api/golden/{entity}/duplicates/clusters/{clusterId}/unignore

Clears ignore flag for a whole cluster.

Operation ID: unignoreCluster

Sets the ignore flag to false on every bucket of the logical cluster, (re)classifying them. Entity must be enabled. Requires the ADMIN role, as its counterpart does: undoing a decision is the same decision.

Security: bearerAuth

Parameters

Request body

Responses

POST /api/golden/{entity}/merge/undo

Undoes the merge that produced a record.

Operation ID: undoMerge

Recovers the records a merge absorbed from the entity’s history relation and deletes the record it produced, which is archived in their place. The records named are taken from the survivor’s own ‘_metadata._merged’, not from the request. Answers 409 when the entity keeps no history (there is nothing archived to recover), when the record is not the result of a merge, when the record was itself merged again (undo that merge first) or when one of the absorbed records is no longer in history. Entity must be enabled. Requires the ADMIN or STEWARD role.

Security: bearerAuth

Parameters

Request body

Responses

GET /api/golden/{entity}/records/{recordId}/index-status

Returns the indexing status (PENDING / INDEXED / FAILED) of a record.

Operation ID: recordIndexStatus

Reports indexing status for a record stored by an asynchronous upsert. Returns INDEXED when the record has no pending or failed indexing work. Requires the ADMIN or STEWARD role.

Security: bearerAuth

Parameters

Responses

POST /api/golden/{entity}/search

Searches golden records in an entity.

Operation ID: searchRecords

Searches golden records considering indicated entity and search conditions. Entity must be enabled. The search criteria is expressed as a record that should meet the requirements of the dataset associated to this entity. Requires the ADMIN, STEWARD or VIEWER role.

Security: bearerAuth

Parameters

Request body

Responses

GET /api/golden/{entity}/search/capabilities

States what an entity can be searched by.

Operation ID: searchCapabilities

Returns searchable fields, supported matching modes, free-text availability, and whether source identifiers can be searched. Use these capabilities to build a search form for the entity. Requires the ADMIN, STEWARD or VIEWER role.

Security: bearerAuth

Parameters

Responses

POST /api/golden/{entity}/search/text

Searches golden records in an entity by free text.

Operation ID: searchRecordsByText

Searches an entity with one line of text, the way a search bar does. Whitespace separates terms and double quotes hold a phrase together; every term is probed against every searchable field and against the identifier, and a record that matches more of the terms ranks higher. Records from the history table are included in the same result, with a merged one resolved forward to the record that survived it. Requires the ADMIN, STEWARD or VIEWER role.

Security: bearerAuth

Parameters

Request body

Responses

POST /api/golden/{entity}/upsert

Updates or inserts a golden record in an entity.

Operation ID: upsertRecord

Updates or inserts a golden record into indicated entity. Entity must be enabled. The indicated record is searched: if found, then the record will be updated; if not found, the record will be considered as new and inserted. When the update flag forces an update, the record must already exist (matched by id or by the dataset’s single identity column); otherwise the operation fails with 409 and nothing is inserted. If more than one record is found in the search, only the first one will be updated. Requires the ADMIN or STEWARD role.

Security: bearerAuth

Parameters

Request body

Responses