Skip to main content

Update Data Policy

Update the name or description of a data policy via PATCH: partial semantics, empty string clears, and metadata changes never touch captured run snapshots.

Update the metadata of an existing data policy: its name, its description, or both. This endpoint changes policy-level metadata only; the transformation logic lives on the policy's versions and is authored separately. Resolution runs that already captured a policy snapshot are never affected by metadata changes.

This is a PATCH endpoint: include only the properties you want to change and omitted properties keep their current values. Sending an empty body is a no-op that returns the current policy with its fields and rules inlined. To clear a description, send an empty string — the API distinguishes an omitted property (keep the current value) from an empty one (overwrite), and null is rejected by validation. The same limits as creation apply: name 1-255 characters, description up to 2,000.

status is not writable here: it advances through the policy lifecycle as versions are authored and finalized, and metadata updates never touch it. Nor can this endpoint modify fields or rules — a policy's transformation logic is versioned and edited through the policy editor, which forks a new draft version rather than mutating history. This separation keeps PATCH safe to call from automation: nothing a metadata update does can change what a pipeline executes.

PATCH/v1/data-policies/{id}

Path parameters

id*uuidData policy UUID.

Body parameters

namestringUpdated policy name, 1-255 characters. Omit to keep the current name.
descriptionstringUpdated policy description, up to 2,000 characters. An empty string clears it; omit to keep the current value.

Request body

{
  "name": "Invoice Normalization v2",
  "description": "Updated: added VAT normalization rules"
}

Response

Response fields

idstringData policy UUID.
namestringUpdated policy name.
descriptionstring | nullUpdated policy description.
statusstringPolicy status (unchanged by metadata updates).
created_atstringISO 8601 creation timestamp.
updated_atstringISO 8601 last update timestamp (advanced by this call).
linksobjectURLs to the policy and its subresources.

curl

curl -s -X PATCH https://api.talonic.com/v1/data-policies/p1a2b3c4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer tlnc_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"name":"Invoice Normalization v2"}'

Response

{
  "id": "p1a2b3c4-e5f6-7890-abcd-ef1234567890",
  "name": "Invoice Normalization v2",
  "description": "Updated: added VAT normalization rules",
  "status": "published",
  "created_at": "2024-10-01T09:00:00.000Z",
  "updated_at": "2024-10-20T08:15:00.000Z",
  "links": {
    "self": "/v1/data-policies/p1a2b3c4-e5f6-7890-abcd-ef1234567890",
    "versions": "/v1/data-policies/p1a2b3c4-e5f6-7890-abcd-ef1234567890/versions",
    "fields": "/v1/data-policies/p1a2b3c4-e5f6-7890-abcd-ef1234567890/fields",
    "rules": "/v1/data-policies/p1a2b3c4-e5f6-7890-abcd-ef1234567890/rules"
  }
}

Errors

Error responses

400bad_requestInvalid request body.
401unauthorizedMissing or invalid API key.
404not_foundData policy not found or does not belong to your organization.
429rate_limitedToo many requests. Retry after the period indicated in the Retry-After header.
Renaming a policy is safe at any time: pipelines reference policies by UUID and resolution runs keep their own snapshot, so a rename never changes execution behavior.

Note the response-shape difference between the two paths: an update that changes at least one property returns the policy header (with links), while an empty body falls through to the full GET read and returns the header with fields and rules inlined. If your client parses the response, branch on the presence of fields — or simply follow links.self after updating when you need the complete view.

Frequently asked questions

Does updating a policy affect running resolutions?+
No. Resolution runs capture a snapshot of the policy at creation time. Updates to the policy only affect future resolution runs. Completed and in-flight runs are unaffected.
Do I need to provide all fields in the update?+
No. This is a PATCH endpoint, so you only need to include the fields you want to change. Omitted fields retain their current values.
Can I change the fields and rules through this endpoint?+
No. This endpoint updates policy-level metadata (name and description) only. The transformation logic lives on the policy's versions and is authored through the policy editor; use the fields and rules read endpoints to inspect it.
How do I clear a policy's description?+
Send `{"description": ""}`. Omitting the property keeps the current value, and `null` fails validation with `400` — PATCH semantics here distinguish "not mentioned" from "set to empty".

Related

Get Data Policy
List Data Policies
List Data Policy Versions
Delete Data Policy