Implement Golden integration patterns

On this page

Choose an integration shape based on latency, volume, and who owns recovery. Golden supports synchronous record search and single-record writes alongside resource-driven table and entity operations.

Architects comparing web, synchronous, batch, delivery, and hybrid designs should first use Choose an enterprise integration approach.

Use this page to choose behavior and recovery strategy. Use the Golden API reference for exact record operations, the Table API for bulk work, and the schema catalog for request and response models.

Choose a pattern

Need	Pattern	Important constraint
Check for an existing subject during a transaction	Record-shaped search	Adds a synchronous dependency
Create or correct one entity record	Single-record upsert	Requires `STEWARD` or `ADMIN`
Process an extract or large record set	Configured table load and entity synchronization	Follow the returned task
Deliver mastered records downstream	Configured destination	Design the receiver for safe redelivery

Search before creating a source record

The search body is a record fragment shaped by the entity’s dataset. It is not a free-text query language.

import os
import requests

url = os.environ["GOLDEN_URL"]
token = os.environ["GOLDEN_TOKEN"]

response = requests.post(
    f"{url}/api/golden/sample-customer-entity/search",
    headers={"Authorization": f"Bearer {token}"},
    json={
        "record": {"email": "ana.garcia@example.com"},
        "audit": False,
        "options": {},
        "pageNumber": 0,
        "pageSize": 10,
    },
    timeout=5,
)
response.raise_for_status()

matches = response.json()["result"]

An empty result means the submitted criteria found no matching record. It does not prove the subject is absent under every possible criterion. Decide explicitly whether your caller fails open, fails closed, or asks for review when Golden is unavailable.

Upsert one record

POST /api/golden/{entity}/upsert accepts one record per request. It does not accept a records batch.

Use the complete read–correct–verify–restore example for Aurelia. It reads CRM-0001, preserves its business fields, removes response metadata and provenance from the request, and sends update:true with _id. Do not use sourceRef as Aurelia’s identity: its supplied dataset uses _id.

The response reports inserted, updated, and the resulting record. Keep the source identity stable and handle conflict responses as data-state decisions, not generic retry signals.

Control the write mode when the default search-then-write behavior is not safe:

Field	Default	Behavior
`insert`	`false`	Always insert a new record
`update`	`false`	Update an existing record and return an error when none is found
`options`	Default search behavior	Controls how an existing record is located
`transformation`	None	Transforms the record before lookup and write

Do not set insert and update together. Use forced update when creating a second record would be less safe than failing the request.

If a 409 response contains survivorId, the addressed record has already been merged. Continue with the surviving identifier instead of retrying the obsolete one.

Use this endpoint for controlled individual writes. For volume, configure a source, transformation or pipeline as needed, a target table, and a table load.

Follow indexing after a write

When an entity indexes writes asynchronously, query:

curl --fail-with-body --silent --show-error \
  --header "Authorization: Bearer ${GOLDEN_TOKEN}" \
  "${GOLDEN_URL}/api/golden/sample-customer-entity/records/${RECORD_ID}/index-status"

The response reports PENDING, INDEXED, or FAILED, together with the time first queued, last status change, attempt count, and an error when indexing failed. Wait for INDEXED before diagnosing a newly written record as missing from search.

Run bulk work through configured resources

Bulk ingestion and export use saved resources and create asynchronous work. Validate the resources with representative data, start the appropriate table or entity operation, and follow its returned task identifier.

configured source → optional transformation/pipeline → table
table → entity synchronization → searchable or resolved records
table → configured destination → downstream system

Do not implement bulk upsert by assuming the single-record endpoint accepts an array. The exact load and synchronization request schemas are available in the running explorer where the deployment enables it.

Deliver mastered data

Use a supported Kafka, HTTP, JDBC, or Golden-table destination for managed delivery. A timeout can leave the sender uncertain whether a write was applied, so downstream consumers should use stable record identity and tolerate a safe repeat where their protocol allows it.

Golden does not document a generic table-query language or change-feed endpoint. Do not use undocumented SQL-like filters for polling. Use the supported table record filters from Query table data through the API or a configured destination.

Handle failures

Status	Recommended response
`400`	Correct the request or data; do not retry unchanged
`401`	Obtain or replace the credential, then retry once
`403`	Stop; assign an appropriate role or change the workflow
`404`	Recheck the environment, path, and identifier
`409`	Read the conflict response and reconcile record state
`410`	Treat the addressed record as no longer available
`423`	Inspect whether the entity or resource is disabled or locked before retrying
`5xx`	Retry only according to the operation’s write safety and your recovery policy