Skip to main content

Rules & Writer Profile

Read and replace the workspace rules that derive field values and the writer profile a fill reads for user sources, through /v1/doc-gen/rules and /profile.

Two small resources feed the fields that are not plain data columns. A rule derives one value from a row, the values entered for the document and the day; a field with a rule source reads one by name. The writer profile holds the details of the person writing the letter (name, initials, title, department and signature line); a field with a user source reads one of them. Rules belong to the workspace, and the profile belongs to the person behind the key (the OAuth user, or the key's creator).

PUT /v1/doc-gen/rules replaces the whole set: the submitted list is exactly what the workspace is left with, and rules not in it are deleted. An entry without a name or without a definition object is dropped. The definition is a JSON object whose shape depends on the rule kind; an unreadable definition yields no value when the rule is evaluated, and the field is then reported as missing rather than filled with a guess. Read the current set first and send it back with your changes, because a partial list deletes the rest.

The profile field names are German because they mirror the writer block of German business letters: name, kuerzel (initials), titel, bereich (department) and unterschrift (signature line). Before a person saves a profile, GET returns defaults derived from their name. PUT replaces the stored profile, a part left out is saved empty (the name falls back to the person's name), and values are trimmed and cut at 200 characters. A key that belongs to no person has no profile to save and is refused with 422; such a key can pass a profile on a generation request for that batch only.

GET/v1/doc-gen/rules

Rule fields

name*stringThe name a rule source refers to, 1 to 120 characters.
descriptionstringUp to 500 characters.
definition*objectThe rule, a JSON object whose shape depends on the rule kind. An unreadable definition yields no value when evaluated.
PUT/v1/doc-gen/rules

Body fields

rules*object[]Up to 500 rules, each { name, description?, definition }. Entries without a name or a definition object are dropped.

cURL: Replace the rules

curl -X PUT "https://api.talonic.com/v1/doc-gen/rules" \
  -H "Authorization: Bearer $TALONIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "rules": [
      {
        "name": "closing_phrase",
        "description": "Closing line by language",
        "definition": { "...": "rule definition" }
      }
    ]
  }'
GET/v1/doc-gen/profile

Profile fields

namestringThe writer's name.
kuerzelstringThe writer's initials.
titelstringThe writer's title.
bereichstringThe writer's department.
unterschriftstringThe signature line.
PUT/v1/doc-gen/profile

cURL: Save the profile

curl -X PUT "https://api.talonic.com/v1/doc-gen/profile" \
  -H "Authorization: Bearer $TALONIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Mara Voss",
    "kuerzel": "MV",
    "titel": "Contract Manager",
    "bereich": "Procurement",
    "unterschrift": "Mara Voss, Procurement"
  }'
PUT on both resources replaces rather than merges. A rules list that omits an existing rule deletes it, and a profile that omits titel saves it empty. Read first, change the copy, and send the whole result back.

Frequently asked questions

Do I need to save a profile before generating?+
No. Until a person saves one, GET returns defaults derived from their name and a fill reads those. Save a profile when fields with a user source should print a title, department or signature line.
Can a key without a person generate with a profile?+
Yes, for one batch. A key that belongs to no person cannot save a profile (422), but the generation request accepts a profile object with name, kuerzel, titel, bereich and unterschrift for that batch only. The saved profile is unchanged.
What is the shape of a rule definition?+
A JSON object whose shape depends on the rule kind. The API stores it as submitted and evaluates it when a field with a rule source is filled. An unreadable definition yields no value, so the field is reported as missing instead of filled with a guess.

Related

Document Generation Overview
Word Templates
Generate Documents