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

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.

Manage Dialect

List Schemas