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.

Dialects are organization-scoped and shared across all schemas within the organization. Updating a dialect affects all schemas that reference it on subsequent extraction runs.

GET/v1/dialects

List dialects

curl -H "Authorization: Bearer $TALONIC_API_KEY" \
  "https://api.talonic.com/v1/dialects"

List Response

Response fields

dataarrayArray of dialect objects.

data[].idstringDialect UUID.

data[].namestringHuman-readable dialect name.

data[].versionintegerCurrent version number. Increments on each update.

data[].configobjectFormatting configuration with date_format, number_locale, delimiter, null_representation, encoding, and boolean_format.

data[].created_atstringISO 8601 creation timestamp.

data[].updated_atstringISO 8601 last update timestamp.

data[].linksobjectRelated resource URLs.

data[].links.selfstringURL to fetch this dialect by ID.

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.

POST/v1/dialects

Body parameters

name*stringHuman-readable name for the dialect. Unique per organization.

date_formatstringDate format string (e.g. YYYY-MM-DD, DD/MM/YYYY, MM-DD-YYYY).

number_localestringBCP 47 locale tag for number formatting (e.g. en-US, de-DE, fr-FR).

delimiterstringCSV field delimiter character (e.g. comma, semicolon, tab).

null_representationstringString to use for null/missing values in output (e.g. empty string, N/A, NULL).

encodingstringOutput character encoding (e.g. utf-8, ISO-8859-1).

boolean_formatstring[]Exactly two elements: [truthy, falsy] string representations.

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

400validation_errorMissing required name field or invalid boolean_format (must be a two-element array).

401unauthorizedMissing or invalid API key.

429rate_limitedToo many requests. Retry after the period indicated in the Retry-After header.

Frequently asked questions

What happens if I omit config fields when creating a dialect?+

Omitted fields are simply left unset in the 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?+

Yes. Dialects are designed to be shared across schemas within your organization. When you update a shared dialect, all schemas referencing it pick up the new formatting rules on their next extraction run.

What date format strings are supported?+

Dialects accept standard date format tokens: `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?+

Yes, dialect names are unique within an organization. Creating a second dialect with an existing name fails, so pick descriptive names like `European CSV` or `US Standard` and rename via `PUT /v1/dialects/:id` if conventions change.

Manage Dialect

List Schemas