Skip to main content

Assembly Configs

Configure how a Spec composes grouped documents into one record with an anchor plus amendments. List, create, update, and delete assembly profiles via the API.

An assembly config tells a Spec how to compose several documents that belong together into a single composed record. Documents are grouped by grouping_field. Within a group, the anchor_field (matched against anchor_values) identifies the base document, and amendment documents may override only the fields listed in amendable_fields. Conflicts are resolved by override_rule_id, which defaults to newer-signed-overrides.

This is the configuration behind the Assembly stage of the Spec rail. A common shape is a base contract plus signed amendments: the base is the anchor, later signed amendments override the negotiated terms, and signed_field plus date_field drive the conflict ordering. Each Spec holds one row per assembly profile, and the list endpoint returns them ordered by creation time.

Every body field is optional at the schema level, but a profile only composes usefully once grouping_field and anchor_field are set — an assembly stage referencing a config with neither has nothing to group or anchor on. Field names refer to the Spec's own extracted fields (the field_name values on the schema), not display labels, so keep them in sync when you rename fields.

Note that PATCH replaces the whole profile rather than merging: every column is rewritten from the request body, so a field you omit resets to null (or, for override_rule_id, back to newer-signed-overrides). Read the config first, modify the fields you want, and send the complete object back — the same read-modify-write pattern the [delivery config](spec-delivery) uses.

GET/v1/schemas/{id}/assembly-configs
POST/v1/schemas/{id}/assembly-configs

Body parameters

namestringProfile name (max 200 characters).
grouping_fieldstringField whose value groups documents into one composed record.
anchor_fieldstringField that identifies the anchor (base) document within a group.
anchor_valuesstring[]Values of anchor_field that mark a document as the group anchor.
signed_fieldstringField indicating a document is signed.
date_fieldstringField used to order documents by date.
amendable_fieldsstring[]Fields an amendment document is allowed to override on the anchor.
override_rule_idstringConflict-resolution rule id (max 100 characters). Default: newer-signed-overrides

Create an assembly profile

curl -X POST https://api.talonic.com/v1/schemas/a1b2c3d4-e5f6-7890-abcd-ef1234567890/assembly-configs \
  -H "Authorization: Bearer tlnc_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Contract + amendments",
    "grouping_field": "contract_number",
    "anchor_field": "document_kind",
    "anchor_values": ["base_contract"],
    "signed_field": "is_signed",
    "date_field": "effective_date",
    "amendable_fields": ["price", "term_months", "renewal_terms"]
  }'
PATCH/v1/schemas/{id}/assembly-configs/{configId}
DELETE/v1/schemas/{id}/assembly-configs/{configId}

Response

Assembly config fields

idstringAssembly config UUID.
schema_idstringSpec (schema) UUID this config belongs to.
namestring | nullProfile name.
grouping_fieldstring | nullField that groups documents into one composed record.
anchor_fieldstring | nullField identifying the anchor document.
anchor_valuesstring[]Values that mark the anchor.
signed_fieldstring | nullField indicating signed status.
date_fieldstring | nullField used to order documents by date.
amendable_fieldsstring[]Fields an amendment may override.
override_rule_idstringConflict-resolution rule id.
created_atstringISO 8601 creation timestamp.
updated_atstringISO 8601 update timestamp.

Response (POST create)

{
  "id": "ab12cd34-ef56-7890-abcd-ef1234567890",
  "schema_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Contract + amendments",
  "grouping_field": "contract_number",
  "anchor_field": "document_kind",
  "anchor_values": ["base_contract"],
  "signed_field": "is_signed",
  "date_field": "effective_date",
  "amendable_fields": ["price", "term_months", "renewal_terms"],
  "override_rule_id": "newer-signed-overrides",
  "created_at": "2024-09-14T10:32:00.000Z",
  "updated_at": "2024-09-14T10:32:00.000Z"
}

PATCH and DELETE return { "ok": true }.

amendable_fields is a whitelist. An amendment document can only override the fields you list here. Everything else stays as it is on the anchor document, even if the amendment carries a value.

Errors

Error responses

400validation_errorInvalid body, or a field exceeds its length limit.
401unauthorizedMissing or invalid API key.
404not_foundNo Spec (schema) with this ID exists for your organization.
429rate_limitedToo many requests. Retry after the period indicated in the Retry-After header.

Frequently asked questions

What is the anchor document?+
Within a group of documents sharing the same grouping_field value, the anchor is the base document. It is identified by anchor_field matching one of anchor_values. Amendments compose on top of the anchor.
Can an amendment change any field on the anchor?+
No. It can only override the fields listed in amendable_fields. All other fields keep their anchor values. This protects the base record from unintended changes.
How are conflicts between amendments resolved?+
By override_rule_id, which defaults to newer-signed-overrides: a newer, signed amendment wins over older ones. signed_field and date_field supply the inputs for that ordering.
Does PATCH merge my changes into the existing profile?+
No — it rewrites every column from the request body, so omitted fields reset to null and override_rule_id falls back to newer-signed-overrides. Fetch the config from the list endpoint, edit the fields you want, and PATCH the complete object back.

Related

Coherence Rules
Delivery Config