List & Create Dialects
List and create output format dialects that set date formats, number locales, CSV delimiters, encoding, null representation, and boolean pairs for output.
A dialect defines how extracted values are formatted in output: date patterns, number locales, delimiters, and more. Rather than hardcoding format preferences into each schema, you create a dialect once with POST /v1/dialects and reference it across multiple schemas. This keeps output formatting consistent and easy to change globally.
A dialect controls six formatting dimensions: date format strings (e.g. YYYY-MM-DD vs DD/MM/YYYY), number locale (e.g. en-US uses commas for thousands, de-DE uses periods), CSV delimiter (comma, semicolon, tab), null representation (empty string, N/A, NULL), encoding (utf-8, latin-1), and boolean format pairs (e.g. ["Yes", "No"] or ["1", "0"]).
Every dialect is versioned automatically. When you update a dialect, the version field increments so downstream consumers can detect format changes. Schemas referencing the dialect pick up the new formatting rules on their next extraction run.
Use GET /v1/dialects to browse existing dialects and POST /v1/dialects to create new ones. Both endpoints are organization-scoped: you only see dialects owned by your organization. The list returns every dialect in a single response, sorted alphabetically by name, and dialect names are unique within an organization.
/v1/dialectsList dialects
curl -H "Authorization: Bearer $TALONIC_API_KEY" \
"https://api.talonic.com/v1/dialects"List Response
Response fields
Response
{
"data": [
{
"id": "d1a2b3c4-e5f6-7890-abcd-ef1234567890",
"name": "European CSV",
"version": 2,
"config": {
"date_format": "DD/MM/YYYY",
"number_locale": "de-DE",
"delimiter": ";",
"null_representation": "N/A",
"encoding": "utf-8",
"boolean_format": ["Ja", "Nein"]
},
"created_at": "2024-10-01T08:00:00.000Z",
"updated_at": "2024-11-15T14:30:00.000Z",
"links": {
"self": "/v1/dialects/d1a2b3c4-e5f6-7890-abcd-ef1234567890"
}
},
{
"id": "e2b3c4d5-f6a7-8901-bcde-f23456789012",
"name": "US Standard",
"version": 1,
"config": {
"date_format": "MM/DD/YYYY",
"number_locale": "en-US",
"delimiter": ",",
"null_representation": "",
"encoding": "utf-8",
"boolean_format": ["true", "false"]
},
"created_at": "2024-10-05T12:00:00.000Z",
"updated_at": "2024-10-05T12:00:00.000Z",
"links": {
"self": "/v1/dialects/e2b3c4d5-f6a7-8901-bcde-f23456789012"
}
}
]
}Create Dialect
Create a new dialect with a required name and any of the six optional formatting fields. Omitted fields are left unset in the dialect config; output rendered with the dialect falls back to platform default formatting for those dimensions. New dialects start at version 1.
/v1/dialectsBody parameters
Request body
{
"name": "Japanese Output",
"date_format": "YYYY年MM月DD日",
"number_locale": "ja-JP",
"delimiter": ",",
"null_representation": "—",
"encoding": "utf-8",
"boolean_format": ["はい", "いいえ"]
}Response (201 Created)
{
"id": "f3c4d5e6-a7b8-9012-cdef-345678901234",
"name": "Japanese Output",
"version": 1,
"config": {
"date_format": "YYYY年MM月DD日",
"number_locale": "ja-JP",
"delimiter": ",",
"null_representation": "—",
"encoding": "utf-8",
"boolean_format": ["はい", "いいえ"]
},
"created_at": "2024-12-01T09:00:00.000Z",
"updated_at": "2024-12-01T09:00:00.000Z",
"links": {
"self": "/v1/dialects/f3c4d5e6-a7b8-9012-cdef-345678901234"
}
}Errors
Error responses
Frequently asked questions
What happens if I omit config fields when creating a dialect?+
config object, and output rendered with the dialect falls back to platform default formatting for those dimensions. You only need to specify the fields you want to customize.Can multiple schemas share the same dialect?+
What date format strings are supported?+
YYYY for four-digit year, MM for zero-padded month, DD for zero-padded day, and common separators like -, /, ., or literal characters. For example, DD.MM.YYYY produces dates like 15.03.2024.Are dialect names unique?+
European CSV or US Standard and rename via PUT /v1/dialects/:id if conventions change.