Create account metadata
create-account-metadataCreate a new account-level metadata field definition.
Use this tool when:
The user asks for a new metadata field to track some piece of information on their documents
You need a metadata field to exist before writing values to it with update-document-metadata-values
Call list-account-metadata first: the account may already have a field for what the user wants, and fynk provides a range of system metadata fields that cannot be re-created under the same name.
name is the programmatic identifier (lowercase letters, digits and underscores only) and display_name is what
the user sees. Write display_name in Title Case, the way fynk's own fields are named ("Signing Date", "Contract
Value"), rather than copying the user's phrasing verbatim - a request for "a product colour metadata" should still
produce product_colour / "Product Colour".
select and multi_select fields require select_values (the allowed options); no other field type accepts them.
These strings are literally what the user picks from in the UI, so write them as presentable labels, capitalised
like display_name: "Red", "Green", "Blue", not the "red, green or blue" lifted out of the request.
name and value_type are fixed at creation and cannot be changed afterwards, and it is worth getting the rest
right first time rather than leaving a correction to make later. So confirm any detail the user has not spelled out
instead of guessing at it - in particular the exact select_values strings, since a request like "a colour field
with red, green or blue" names the options without settling how they should read.
prompt and keywords decide whether fynk's AI analyses fill this field in - a prompt puts the field into them,
keywords only assist it and do nothing on their own. This is how a new field is normally set up: fynk's own
creation form turns AI analysis on by default and requires both. So propose a prompt and keywords drawn from
what the field is for rather than silently leaving them out, and omit both only for a field the user wants to fill
in by hand. Set a description as well - it is what tells a user configuring the field what it holds.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Programmatic name of the field, unique within the account (lowercase letters, digits and underscores only, max 255 characters), e.g. "discount_rate". Cannot be changed after creation | |
| prompt | No | What the AI analyses should extract for this field, and what puts the field into them (max 1024 characters). Define what the value is, then qualify it the way fynk's own fields do - what counts, what does not, and what to do when the document is not explicit - over several sentences where that helps. The "Net Rent" field reads: "The net rent for the property, which is the rent excluding any taxes or costs e.g. VAT. It must be explicitly stated in the contract as net rent per month. Derive the currency unit from the parties to the contract if it is not explicitly stated." A single vague line extracts poorly | |
| keywords | No | Comma-separated keywords that help the AI analyses locate the field in a document (max 1024 characters). List the terms as they would appear in a contract, including synonyms and the equivalents in other languages the account's documents are written in - the "Net Rent" field carries "net rent, netto miete, netto kaltmiete, kaltmiete, nettomiete pro monat". Send these alongside a `prompt`; they have no effect without one | |
| value_type | Yes | Controls the kinds of values the field accepts (e.g. "text", "number", "currency", "date", "select"). Cannot be changed after creation | |
| description | No | What the field holds, shown to users configuring it (max 1024 characters) | |
| display_name | Yes | Human-readable name shown in the UI, in Title Case (max 255 characters), e.g. "Discount Rate" | |
| select_values | No | Required for the "select" and "multi_select" value types, and rejected for every other type: the options a user picks from, written as presentable labels, e.g. ["Red", "Green", "Blue"] | |
| is_contract_value | No | Whether the field counts towards a document's calculated contract value. Only allowed when value_type is "currency" or "currency_duration". Defaults to false | |
| relevant_document_type_uuids | No | The document types the field is meaningful for, as uuids from list-account-document-types. Omit to make the field relevant for every document type, which is the usual choice; send an empty list or null to make it relevant for none |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Internal name of the metadata field | |
| type | No | The type of the metadata field, which defines where its value comes from. account: Custom metadata fields that are specific to your account system_reference: Pre-defined useful metadata fields provided by fynk system_autofilled: Fields that are automatically filled by the system in response to events, like "Signing completion date" system_computed: Fields that are calculated by the system based on other metadata values. e.g. "Signing duration" is the difference between "Signing date" and "Signed date" system: Other system-provided metadata fields | |
| uuid | No | Do not show to the user unless they ask for it | |
| settings | No | Extra configuration for the field. Not present means there is nothing to restrict | |
| value_type | No | Controls the kinds of values that can be assigned to the metadata | |
| _entity_type | No | Only relevant for tooling. Do not show to the user | |
| display_name | No | Human-readable name of the metadata field | |
| select_values | No | When value_type is "select" or "multi_select", defines the allowed values. For these types of metadata, ONLY these values are possible. Absent for every other value type | |
| is_contract_value | No | Whether this field counts towards a document's calculated contract value. Only meaningful when value_type is "currency" or "currency_duration" | |
| overridden_fields | No | Only for a "system_reference" field the account has configured differently to how fynk provides it, and absent otherwise: the update-account-metadata arguments it has changed, e.g. ["display_name", "select_values"]. Send reset_to_fynk_default to that tool to put all of them back | |
| relevant_document_types | No | Names of the document types this field is meaningful for. Empty together with relevant_for_all_document_types false means the field is not in use for any document type, so charting it will likely produce no data | |
| relevant_for_all_document_types | No | When true, the field is meaningful for every document type and relevant_document_types is empty |