List & Create Dialects

List all output format dialects and create new ones. Dialects configure date formats, number locales, delimiters, encoding, and boolean pairs for consistent output.

Dialects define how extracted values are formatted in output. Rather than hardcoding format preferences into each schema, you create a dialect once 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.

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 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 name and optional formatting fields. Any omitted config fields use platform defaults: YYYY-MM-DD for dates, en-US for numbers, , for delimiter, empty string for nulls, utf-8 for encoding, and ["true", "false"] for booleans.

POST/v1/dialects

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