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](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.

Related

List Data Policies
List Data Policy Fields
List Data Policy Rules