Skip to main content

Create Data Policy

Create a data policy: a named container for field transformation rules, lookup cascades, and normalization logic applied during resolution. Write scope.

Create a new data policy: a named, versioned container for the transformation rules and output fields that normalize your extracted values. The policy starts empty with status draft. After creation, define its output contract and transformation logic; the policy only does useful work once it has at least one field and one rule.

Choose a name descriptive enough to distinguish the policy from others in the workspace, and use the optional description to document what the policy targets: the document types it applies to and the normalization strategies it employs. Both help later when a pipeline builder picks policies for a Resolve stage. name accepts 1-255 characters and description up to 2,000; a value beyond either limit is rejected with 400 before anything is created.

Creation is atomic with versioning: the platform mints the policy row and its version 1 (status draft) in one transaction, and points the policy's current-version pointer at it. Every subsequent write resolves the editable version from that pointer, so the policy is immediately editable — in the policy editor and via imports — the moment this call returns. The version also anchors the audit trail: List Data Policy Versions starts at 1 for every policy created here.

The 201 response is the same policy header shape the list returns, including the links object: links.fields and links.rules are the read URLs for the contract you author next, and links.self accepts PATCH for metadata updates and DELETE for removal. Once authored, wire the policy into a Spec's Resolve stage — its UUID goes into the rail stage's policy_ids — or run it standalone through a resolution.

POST/v1/data-policies

Body parameters

name*stringHuman-readable policy name, 1-255 characters.
descriptionstringOptional description of the policy purpose, up to 2,000 characters.

Request body

{
  "name": "Invoice Normalization",
  "description": "Standardize currency codes, country names, and date formats"
}

Response

Response fields (201 Created)

idstringData policy UUID.
namestringPolicy name.
descriptionstring | nullPolicy description.
statusstringInitial policy status: draft.
created_atstringISO 8601 creation timestamp.
updated_atstringISO 8601 last update timestamp.
linksobjectURLs to the policy and its subresources (self, versions, fields, rules).

curl

curl -s -X POST https://api.talonic.com/v1/data-policies \
  -H "Authorization: Bearer tlnc_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"name":"Invoice Normalization","description":"Standardize currency codes, country names, and date formats"}'

Response (201 Created)

{
  "id": "p1a2b3c4-e5f6-7890-abcd-ef1234567890",
  "name": "Invoice Normalization",
  "description": "Standardize currency codes, country names, and date formats",
  "status": "draft",
  "created_at": "2024-10-01T09:00:00.000Z",
  "updated_at": "2024-10-01T09:00: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 or missing required fields.
401unauthorizedMissing or invalid API key.
429rate_limitedToo many requests. Retry after the period indicated in the Retry-After header.
A freshly created policy has no fields or rules yet. It resolves nothing until its output contract and transformation logic are defined; the fields and rules read endpoints let you verify the configuration at any time.

Frequently asked questions

What should I do after creating a policy?+
Define its output fields and add transformation rules, then wire it into a pipeline's Resolve stage. The policy is not useful until it has at least one field and one rule configured; use the fields and rules endpoints to verify the configuration.
Can I rename a policy after creation?+
Yes. Use the PATCH /v1/data-policies/{id} endpoint to update the name or description. Renaming does not affect existing resolution runs, which keep their own snapshot of the policy.
What does the draft status mean?+
A new policy starts as draft while its fields and rules are being authored. Its status advances (e.g. to published) as it is finalized for use in resolution.
What are the validation limits on name and description?+
name is required and must be 1-255 characters; description is optional with a 2,000-character cap. A request exceeding either limit is rejected with 400 bad_request and no policy or version row is created.