> For the complete documentation index, see [llms.txt](https://developer.celigo.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.celigo.com/api/api-reference/parsers-and-generators.md).

# Parsers & Generators

Stateless data transformation processors that convert between raw formats (XML, CSV, EDI) and structured JSON. Parsers accept raw data and return JSON records; generators accept JSON and produce formatted output.

These are one-shot transformation calls — they do not create or modify any resources. Use them to test parsing rules, preview file definitions, or transform data outside of a flow.

### Processor descriptor schema

## The ProcessorDescriptor object

```json
{"openapi":"3.2.0","info":{"title":"Parsers & Generators","version":"1.0.0"},"components":{"schemas":{"ProcessorDescriptor":{"type":"object","required":["name","label","description","dataMediaType","resultMediaType","ruleMediaType"],"description":"Metadata describing a single processor type.","properties":{"name":{"type":"string","description":"Processor key (matches the enclosing object key)."},"label":{"type":"string","description":"Human-readable label shown in the UI."},"description":{"type":"string","description":"Short description of the processor's behavior."},"ruleMediaType":{"type":"string","description":"Media type of the processor's rule/template field. Typical values\ninclude `text`, `json`, `javascript`."},"dataMediaType":{"type":"string","description":"Media type the processor expects for the input data."},"resultMediaType":{"type":"string","description":"Media type the processor emits as its result."},"ruleJsonSchema":{"type":"object","additionalProperties":true,"description":"JSON Schema describing the processor's rule structure. Only\npresent on processors with a formal schema (e.g. exportDataConverter)."},"helperFunctions":{"type":"object","additionalProperties":{"type":"string"},"description":"Map of helper function names to usage templates. Only present\non the handlebars processor."}}}}}}
```

## List available flow processor types

> Returns the catalog of processor types the flow engine supports — filter,\
> transform, handlebars, javascript, mapper, CSV/XML parser / generator,\
> branch filter, merge, etc. Each entry carries a label, description, and\
> the input/output media types the processor accepts. The response is\
> keyed by processor name (not an array).

```json
{"openapi":"3.2.0","info":{"title":"Parsers & Generators","version":"1.0.0"},"tags":[{"name":"Parsers & Generators","description":"Stateless data transformation processors that convert between raw formats\n(XML, CSV, EDI) and structured JSON. Parsers accept raw data and return\nJSON records; generators accept JSON and produce formatted output.\n\nThese are one-shot transformation calls — they do not create or modify\nany resources. Use them to test parsing rules, preview file definitions,\nor transform data outside of a flow.\n\n## Processor descriptor schema\n\n{% openapi-schemas spec=\"processor\" schemas=\"ProcessorDescriptor\" grouped=\"true\" %}"}],"servers":[{"url":"https://api.integrator.io","description":"Production (US / default region)"},{"url":"https://api.eu.integrator.io","description":"Production (EU region)"},{"url":"https://api.au.integrator.io","description":"Production (AU region)"},{"url":"https://api.ca.integrator.io","description":"Production (CA region)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"ProcessorsResponse":{"type":"object","description":"Processor catalog keyed by processor name. Each value describes the\nprocessor's label, purpose, and input/output media types.","additionalProperties":{"$ref":"#/components/schemas/ProcessorDescriptor"}},"ProcessorDescriptor":{"type":"object","required":["name","label","description","dataMediaType","resultMediaType","ruleMediaType"],"description":"Metadata describing a single processor type.","properties":{"name":{"type":"string","description":"Processor key (matches the enclosing object key)."},"label":{"type":"string","description":"Human-readable label shown in the UI."},"description":{"type":"string","description":"Short description of the processor's behavior."},"ruleMediaType":{"type":"string","description":"Media type of the processor's rule/template field. Typical values\ninclude `text`, `json`, `javascript`."},"dataMediaType":{"type":"string","description":"Media type the processor expects for the input data."},"resultMediaType":{"type":"string","description":"Media type the processor emits as its result."},"ruleJsonSchema":{"type":"object","additionalProperties":true,"description":"JSON Schema describing the processor's rule structure. Only\npresent on processors with a formal schema (e.g. exportDataConverter)."},"helperFunctions":{"type":"object","additionalProperties":{"type":"string"},"description":"Map of helper function names to usage templates. Only present\non the handlebars processor."}}}},"responses":{"401-unauthorized":{"description":"Unauthorized. The request lacks a valid bearer token, or the provided token\nfailed to authenticate.\n\nNote: the 401 response is produced by the auth middleware **before** the\nrequest reaches the endpoint handler, so it does **not** follow the\nstandard `{errors: [...]}` envelope. Instead the body is a bare\n`{message: string}` object with no `code`, no `errors` array. Callers\nhandling 401s should key off the HTTP status and the `message` string,\nnot try to destructure an `errors[]`.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable description of the auth failure. Known values:\n- `\"Unauthorized\"` — no `Authorization` header on the request.\n- `\"Bearer Authentication Failed\"` — header present but token\n  is invalid, revoked, or expired."}},"required":["message"]}}}}}},"paths":{"/v1/processors":{"get":{"operationId":"listProcessorTypes","tags":["Parsers & Generators"],"summary":"List available flow processor types","description":"Returns the catalog of processor types the flow engine supports — filter,\ntransform, handlebars, javascript, mapper, CSV/XML parser / generator,\nbranch filter, merge, etc. Each entry carries a label, description, and\nthe input/output media types the processor accepts. The response is\nkeyed by processor name (not an array).","responses":{"200":{"description":"Processor catalog, keyed by processor name.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProcessorsResponse"}}}},"401":{"$ref":"#/components/responses/401-unauthorized"}}}}}}
```

## Convert XML to JSON

> Parses XML data into JSON records using the specified parsing rules\
> and resource path.\
> \
> \*\*Resource path format\*\* — Use XPath-style slash-separated paths\
> (e.g. \`/root/item\`). Dot-separated paths (e.g. \`root.item\`) do not\
> work.\
> \
> \*\*Legacy vs modern output\*\* — Without \`doc.parsers\` configured, or\
> with \`V0\_json: true\`, the parser produces a legacy format where\
> element text appears as \`\[{"\_": "value"}]\` arrays and attributes\
> appear under a \`$\` key. Setting \`V0\_json: false\` produces clean\
> key-value pairs and flattens attributes into the record.\
> \
> When \`groupByFields\` is used the response shape changes: \`data\`\
> becomes an array of arrays and \`dataRecordTraceKeys\` /\
> \`traceKeysDuplicate\` are omitted.\
> \
> Invalid XML returns a 422 with code \`cannot\_parse\_xml\`.\
> Namespaced XPath expressions (e.g. \`ns:element\`) return a 422\
> with code \`invalid\_xpath\`.

```json
{"openapi":"3.2.0","info":{"title":"Parsers & Generators","version":"1.0.0"},"tags":[{"name":"Parsers & Generators","description":"Stateless data transformation processors that convert between raw formats\n(XML, CSV, EDI) and structured JSON. Parsers accept raw data and return\nJSON records; generators accept JSON and produce formatted output.\n\nThese are one-shot transformation calls — they do not create or modify\nany resources. Use them to test parsing rules, preview file definitions,\nor transform data outside of a flow.\n\n## Processor descriptor schema\n\n{% openapi-schemas spec=\"processor\" schemas=\"ProcessorDescriptor\" grouped=\"true\" %}"}],"servers":[{"url":"https://api.integrator.io","description":"Production (US / default region)"},{"url":"https://api.eu.integrator.io","description":"Production (EU region)"},{"url":"https://api.au.integrator.io","description":"Production (AU region)"},{"url":"https://api.ca.integrator.io","description":"Production (CA region)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"ParserResponse":{"type":"object","description":"Response from a parser processor (`csvParser`, `xmlParser`).\n\nWhen `groupByFields` is used in the request, the `dataRecordTraceKeys`\nand `traceKeysDuplicate` fields are omitted from the response and `data`\nbecomes an array of arrays (each inner array is one group of records).","properties":{"mediaType":{"type":"string","description":"Always `json` for parser processors.","enum":["json"]},"data":{"description":"Parsed records. Normally an array of objects. When `groupByFields`\nis used, becomes an array of arrays (grouped records).","oneOf":[{"type":"array","items":{"type":"object","additionalProperties":true}},{"type":"array","items":{"type":"array","items":{"type":"object","additionalProperties":true}}}]},"duration":{"type":"integer","description":"Processing time in milliseconds."},"dataRecordTraceKeys":{"type":"array","items":{"type":["string","null"]},"description":"Trace keys for each output record (nullable entries). Omitted\nwhen `groupByFields` is used."},"traceKeysDuplicate":{"type":"boolean","description":"Whether any duplicate trace keys were detected. Omitted when\n`groupByFields` is used."}}}},"responses":{"401-unauthorized":{"description":"Unauthorized. The request lacks a valid bearer token, or the provided token\nfailed to authenticate.\n\nNote: the 401 response is produced by the auth middleware **before** the\nrequest reaches the endpoint handler, so it does **not** follow the\nstandard `{errors: [...]}` envelope. Instead the body is a bare\n`{message: string}` object with no `code`, no `errors` array. Callers\nhandling 401s should key off the HTTP status and the `message` string,\nnot try to destructure an `errors[]`.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable description of the auth failure. Known values:\n- `\"Unauthorized\"` — no `Authorization` header on the request.\n- `\"Bearer Authentication Failed\"` — header present but token\n  is invalid, revoked, or expired."}},"required":["message"]}}}}}},"paths":{"/v1/processors/xmlParser":{"post":{"operationId":"parseXml","tags":["Parsers & Generators"],"summary":"Convert XML to JSON","description":"Parses XML data into JSON records using the specified parsing rules\nand resource path.\n\n**Resource path format** — Use XPath-style slash-separated paths\n(e.g. `/root/item`). Dot-separated paths (e.g. `root.item`) do not\nwork.\n\n**Legacy vs modern output** — Without `doc.parsers` configured, or\nwith `V0_json: true`, the parser produces a legacy format where\nelement text appears as `[{\"_\": \"value\"}]` arrays and attributes\nappear under a `$` key. Setting `V0_json: false` produces clean\nkey-value pairs and flattens attributes into the record.\n\nWhen `groupByFields` is used the response shape changes: `data`\nbecomes an array of arrays and `dataRecordTraceKeys` /\n`traceKeysDuplicate` are omitted.\n\nInvalid XML returns a 422 with code `cannot_parse_xml`.\nNamespaced XPath expressions (e.g. `ns:element`) return a 422\nwith code `invalid_xpath`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"string","description":"The XML data to parse (as a string)."},"rules":{"type":"object","description":"Parsing rules. At minimum, provide `resourcePath` to select\nwhich XML elements become records. Add `doc.parsers` to\ncontrol the output format.","properties":{"resourcePath":{"type":"string","description":"Slash-separated path to the repeating element in the XML\n(e.g. `/root/items/item`). Each matching element becomes\none output record."},"groupByFields":{"type":"array","items":{"type":"string"},"description":"Group parsed records by these field names. Changes the\nresponse `data` to an array of arrays and omits\n`dataRecordTraceKeys` and `traceKeysDuplicate`."},"sortByFields":{"type":"array","items":{"type":"string"}},"doc":{"type":"object","properties":{"fileParser":{"type":"boolean"},"parsers":{"type":"array","description":"Array of parser configurations. Typically contains a\nsingle XML parser entry.","items":{"type":"object","properties":{"type":{"type":"string","enum":["xml"]},"version":{"type":"integer"},"rules":{"type":"object","properties":{"V0_json":{"type":"boolean","description":"When `false`, produces clean key-value output\nand flattens XML attributes into the record.\nWhen `true` (default), uses legacy format with\n`_` and `$` keys."},"trimSpaces":{"type":"boolean","description":"Trim leading/trailing whitespace from text nodes."},"stripNewLineChars":{"type":"boolean","description":"Remove newline characters from text nodes."},"attributePrefix":{"type":"string","description":"Prefix prepended to XML attribute names in the\nJSON output (e.g. `@` produces `@id`). Only\nactive when `V0_json` is `false`."},"textNodeName":{"type":"string","description":"Property name for text content in mixed-content\nelements. Defaults to `&txt`. Only active when\n`V0_json` is `false`."},"listNodes":{"type":"array","items":{"type":"string"},"description":"Element names that should always be arrays in the\noutput, even when containing a single item. Only\nactive when `V0_json` is `false`."},"includeNodes":{"type":"array","items":{"type":"string"},"description":"Only include these element names in the output.\nAll other elements are dropped. Only active when\n`V0_json` is `false`."},"excludeNodes":{"type":"array","items":{"type":"string"},"description":"Exclude these element names from the output. Only\nactive when `V0_json` is `false`."},"mixedNodes":{"type":"array","items":{"type":"string"},"description":"Element names that contain mixed content (text\ninterleaved with child elements). Text is\nextracted into the `textNodeName` property. Only\nactive when `V0_json` is `false`."}}}}}}}}}}}}}}},"responses":{"200":{"description":"Parsed JSON records.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ParserResponse"}}}},"401":{"$ref":"#/components/responses/401-unauthorized"},"422":{"description":"Invalid XPath expression or processing rule error.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["invalid_xpath","cannot_parse_xml"]},"message":{"type":"string"},"source":{"type":"string"},"resolved":{"type":"boolean"},"occurredAt":{"type":"integer"},"path":{"type":"string"}}}}}}}}}}}
```

## Convert CSV to JSON

> Parses CSV data into JSON records using the specified delimiter and\
> formatting rules.\
> \
> Both \`data\` and \`rules\` are technically optional — omitting either\
> returns an empty result rather than an error. When \`hasHeaderRow\` is\
> false, columns are named \`Column0\`, \`Column1\`, etc. When\
> \`includeEmptyValues\` is true, missing values become JSON \`null\`\
> instead of being omitted from the record.\
> \
> When \`groupByFields\` is used the response shape changes: \`data\`\
> becomes an array of arrays (grouped records) and the\
> \`dataRecordTraceKeys\` / \`traceKeysDuplicate\` fields are omitted.\
> This is a stateless transformation. All values are returned as\
> strings, even numeric CSV columns.

```json
{"openapi":"3.2.0","info":{"title":"Parsers & Generators","version":"1.0.0"},"tags":[{"name":"Parsers & Generators","description":"Stateless data transformation processors that convert between raw formats\n(XML, CSV, EDI) and structured JSON. Parsers accept raw data and return\nJSON records; generators accept JSON and produce formatted output.\n\nThese are one-shot transformation calls — they do not create or modify\nany resources. Use them to test parsing rules, preview file definitions,\nor transform data outside of a flow.\n\n## Processor descriptor schema\n\n{% openapi-schemas spec=\"processor\" schemas=\"ProcessorDescriptor\" grouped=\"true\" %}"}],"servers":[{"url":"https://api.integrator.io","description":"Production (US / default region)"},{"url":"https://api.eu.integrator.io","description":"Production (EU region)"},{"url":"https://api.au.integrator.io","description":"Production (AU region)"},{"url":"https://api.ca.integrator.io","description":"Production (CA region)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"ParserResponse":{"type":"object","description":"Response from a parser processor (`csvParser`, `xmlParser`).\n\nWhen `groupByFields` is used in the request, the `dataRecordTraceKeys`\nand `traceKeysDuplicate` fields are omitted from the response and `data`\nbecomes an array of arrays (each inner array is one group of records).","properties":{"mediaType":{"type":"string","description":"Always `json` for parser processors.","enum":["json"]},"data":{"description":"Parsed records. Normally an array of objects. When `groupByFields`\nis used, becomes an array of arrays (grouped records).","oneOf":[{"type":"array","items":{"type":"object","additionalProperties":true}},{"type":"array","items":{"type":"array","items":{"type":"object","additionalProperties":true}}}]},"duration":{"type":"integer","description":"Processing time in milliseconds."},"dataRecordTraceKeys":{"type":"array","items":{"type":["string","null"]},"description":"Trace keys for each output record (nullable entries). Omitted\nwhen `groupByFields` is used."},"traceKeysDuplicate":{"type":"boolean","description":"Whether any duplicate trace keys were detected. Omitted when\n`groupByFields` is used."}}}},"responses":{"401-unauthorized":{"description":"Unauthorized. The request lacks a valid bearer token, or the provided token\nfailed to authenticate.\n\nNote: the 401 response is produced by the auth middleware **before** the\nrequest reaches the endpoint handler, so it does **not** follow the\nstandard `{errors: [...]}` envelope. Instead the body is a bare\n`{message: string}` object with no `code`, no `errors` array. Callers\nhandling 401s should key off the HTTP status and the `message` string,\nnot try to destructure an `errors[]`.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable description of the auth failure. Known values:\n- `\"Unauthorized\"` — no `Authorization` header on the request.\n- `\"Bearer Authentication Failed\"` — header present but token\n  is invalid, revoked, or expired."}},"required":["message"]}}}}}},"paths":{"/v1/processors/csvParser":{"post":{"operationId":"parseCsv","tags":["Parsers & Generators"],"summary":"Convert CSV to JSON","description":"Parses CSV data into JSON records using the specified delimiter and\nformatting rules.\n\nBoth `data` and `rules` are technically optional — omitting either\nreturns an empty result rather than an error. When `hasHeaderRow` is\nfalse, columns are named `Column0`, `Column1`, etc. When\n`includeEmptyValues` is true, missing values become JSON `null`\ninstead of being omitted from the record.\n\nWhen `groupByFields` is used the response shape changes: `data`\nbecomes an array of arrays (grouped records) and the\n`dataRecordTraceKeys` / `traceKeysDuplicate` fields are omitted.\nThis is a stateless transformation. All values are returned as\nstrings, even numeric CSV columns.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"string","description":"The CSV data to parse."},"rules":{"type":"object","description":"Parsing rules controlling delimiters, headers, and grouping.","properties":{"columnDelimiter":{"type":"string","description":"Column delimiter character (e.g. `,`, `\\t`)."},"rowDelimiter":{"type":"string","description":"Row delimiter (e.g. `\\n`, `|`)."},"trimSpaces":{"type":"boolean","description":"When true, trims leading and trailing spaces from parsed values."},"hasHeaderRow":{"type":"boolean","description":"When true, the first row is treated as column headers. When false,\ncolumns are named Column0, Column1, etc."},"rowsPerRecord":{"type":"boolean"},"rowsToSkip":{"type":"integer","description":"Number of rows to skip before parsing begins."},"multipleRowsPerRecord":{"type":"boolean"},"keyColumns":{"type":"array","items":{"type":"string"},"description":"Group consecutive rows into multi-row records by\nthese column names. When a new value appears in a\nkey column, a new record group starts. Changes the\nresponse `data` to an array of arrays."},"disableQuoteAndStripEnclosingQuotes":{"type":"boolean","description":"Disables CSV quote handling and strips enclosing\nquotes from values."},"groupByFields":{"type":"array","items":{"type":"string"},"description":"Group parsed records by these field names. Changes the\nresponse `data` to an array of arrays and omits\n`dataRecordTraceKeys` and `traceKeysDuplicate`."},"sortByFields":{"type":"array","items":{"type":"string"}}}},"options":{"type":"object","properties":{"includeEmptyValues":{"type":"boolean","description":"When true, empty CSV values are returned as JSON `null`.\nWhen false (default), empty values are omitted from the\nrecord."}}}}}}}},"responses":{"200":{"description":"Parsed JSON records.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ParserResponse"}}}},"401":{"$ref":"#/components/responses/401-unauthorized"}}}}}}
```

## Generate CSV from JSON

> Generates CSV output from JSON records using the specified delimiter\
> and formatting rules.\
> \
> The response always has \`mediaType: "text"\` and does not include\
> \`dataRecordTraceKeys\` or \`traceKeysDuplicate\`. This is a stateless\
> transformation.

```json
{"openapi":"3.2.0","info":{"title":"Parsers & Generators","version":"1.0.0"},"tags":[{"name":"Parsers & Generators","description":"Stateless data transformation processors that convert between raw formats\n(XML, CSV, EDI) and structured JSON. Parsers accept raw data and return\nJSON records; generators accept JSON and produce formatted output.\n\nThese are one-shot transformation calls — they do not create or modify\nany resources. Use them to test parsing rules, preview file definitions,\nor transform data outside of a flow.\n\n## Processor descriptor schema\n\n{% openapi-schemas spec=\"processor\" schemas=\"ProcessorDescriptor\" grouped=\"true\" %}"}],"servers":[{"url":"https://api.integrator.io","description":"Production (US / default region)"},{"url":"https://api.eu.integrator.io","description":"Production (EU region)"},{"url":"https://api.au.integrator.io","description":"Production (AU region)"},{"url":"https://api.ca.integrator.io","description":"Production (CA region)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"GeneratorResponse":{"type":"object","description":"Response from a generator processor (`csvDataGenerator`, `structuredFileGenerator`).","properties":{"mediaType":{"type":"string","description":"Always `text` for generator processors.","enum":["text"]},"data":{"type":"string","description":"Generated text output (CSV, EDI, or other structured format)."},"duration":{"type":"integer","description":"Processing time in milliseconds."}}}},"responses":{"401-unauthorized":{"description":"Unauthorized. The request lacks a valid bearer token, or the provided token\nfailed to authenticate.\n\nNote: the 401 response is produced by the auth middleware **before** the\nrequest reaches the endpoint handler, so it does **not** follow the\nstandard `{errors: [...]}` envelope. Instead the body is a bare\n`{message: string}` object with no `code`, no `errors` array. Callers\nhandling 401s should key off the HTTP status and the `message` string,\nnot try to destructure an `errors[]`.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable description of the auth failure. Known values:\n- `\"Unauthorized\"` — no `Authorization` header on the request.\n- `\"Bearer Authentication Failed\"` — header present but token\n  is invalid, revoked, or expired."}},"required":["message"]}}}}}},"paths":{"/v1/processors/csvDataGenerator":{"post":{"operationId":"generateCsv","tags":["Parsers & Generators"],"summary":"Generate CSV from JSON","description":"Generates CSV output from JSON records using the specified delimiter\nand formatting rules.\n\nThe response always has `mediaType: \"text\"` and does not include\n`dataRecordTraceKeys` or `traceKeysDuplicate`. This is a stateless\ntransformation.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"Records to convert to CSV. Accepts a flat array of objects\n(e.g. `[{\"a\":\"1\"}, {\"a\":\"2\"}]`) or an array of arrays for\nbatch processing (e.g. `[[{\"a\":\"1\"}], [{\"a\":\"2\"}]]`). Each\nobject's keys become column names when `includeHeader` is\ntrue.","oneOf":[{"type":"array","items":{"type":"object","additionalProperties":true}},{"type":"array","items":{"type":"array","items":{"type":"object","additionalProperties":true}}}]},"rules":{"type":"object","description":"Generation rules controlling delimiters, headers, and\nformatting.","properties":{"columnDelimiter":{"type":"string","description":"Column delimiter character (e.g. `,`, `\\t`)."},"rowDelimiter":{"type":"string","description":"Row delimiter character (default `\\n`). Appended after\neach row including the last unless\n`truncateLastRowDelimiter` is true."},"includeHeader":{"type":"boolean","description":"When true, includes a header row with column names in the output."},"truncateLastRowDelimiter":{"type":"boolean","description":"When true, omits the trailing row delimiter after the\nlast data row."},"replaceTabWithSpace":{"type":"boolean","description":"Replace tab characters in values with spaces."},"replaceNewlineWithSpace":{"type":"boolean","description":"Replace newline characters in values with spaces."},"wrapWithQuotes":{"type":"boolean","description":"Wrap every value (including headers) in double quotes."},"customHeaderRows":{"type":"array","items":{"type":"string"},"description":"Custom header lines prepended before the column header\nrow and data rows. Each string becomes one line in the\noutput."}}}}}}}},"responses":{"200":{"description":"Generated CSV data.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeneratorResponse"}}}},"401":{"$ref":"#/components/responses/401-unauthorized"}}}}}}
```

## Parse structured file (EDI) to JSON

> Parses EDI or other structured/delimited file data into JSON using\
> a file definition (parsing rules). Commonly used for X12 and EDIFACT\
> documents.\
> \
> The file definition must be provided inside a \`rules.fileDefinition\`\
> wrapper object, or referenced by ID via \`rules.\_fileDefinitionId\`.\
> This differs from the generator endpoint which places definition\
> fields directly in \`rules\`.\
> \
> The response includes a \`recordLevelErrors\` array not present on\
> other processor responses. This is a stateless transformation.\
> Provide the file definition inline via \`rules.fileDefinition\` or\
> reference an existing one via \`rules.\_fileDefinitionId\` (not both).\
> The generator endpoint places definition fields directly in \`rules\`\
> (no \`fileDefinition\` wrapper).\
> \
> \*\*Required file definition fields\*\* — \`name\`, \`version\` (string\
> \`"1"\` or \`"2"\`), \`format\` (\`delimited\`, \`delimited/x12\`,\
> \`delimited/edifact\`, or \`fixed\`), and the corresponding format\
> sub-object (\`delimited\` or \`fixed\`) with at least \`rowDelimiter\`\
> and \`colDelimiter\` (for delimited) or \`rowDelimiter\` and\
> \`paddingChar\` (for fixed). The \`rules\` property defines the\
> segment/element hierarchy.

```json
{"openapi":"3.2.0","info":{"title":"Parsers & Generators","version":"1.0.0"},"tags":[{"name":"Parsers & Generators","description":"Stateless data transformation processors that convert between raw formats\n(XML, CSV, EDI) and structured JSON. Parsers accept raw data and return\nJSON records; generators accept JSON and produce formatted output.\n\nThese are one-shot transformation calls — they do not create or modify\nany resources. Use them to test parsing rules, preview file definitions,\nor transform data outside of a flow.\n\n## Processor descriptor schema\n\n{% openapi-schemas spec=\"processor\" schemas=\"ProcessorDescriptor\" grouped=\"true\" %}"}],"servers":[{"url":"https://api.integrator.io","description":"Production (US / default region)"},{"url":"https://api.eu.integrator.io","description":"Production (EU region)"},{"url":"https://api.au.integrator.io","description":"Production (AU region)"},{"url":"https://api.ca.integrator.io","description":"Production (CA region)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"StructuredFileParserResponse":{"type":"object","description":"Response from the `structuredFileParser` processor.","properties":{"mediaType":{"type":"string","description":"Always `json` for the structured file parser.","enum":["json"]},"data":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"Parsed records from the structured file."},"recordLevelErrors":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"Per-record errors encountered during parsing (e.g. missing required\nsegments or element validation failures)."},"duration":{"type":"integer","description":"Processing time in milliseconds."},"dataRecordTraceKeys":{"type":"array","items":{"type":["string","null"]},"description":"Trace keys for each output record (nullable entries)."},"traceKeysDuplicate":{"type":"boolean","description":"When true, duplicate trace keys were detected in the output records."}}}},"responses":{"401-unauthorized":{"description":"Unauthorized. The request lacks a valid bearer token, or the provided token\nfailed to authenticate.\n\nNote: the 401 response is produced by the auth middleware **before** the\nrequest reaches the endpoint handler, so it does **not** follow the\nstandard `{errors: [...]}` envelope. Instead the body is a bare\n`{message: string}` object with no `code`, no `errors` array. Callers\nhandling 401s should key off the HTTP status and the `message` string,\nnot try to destructure an `errors[]`.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable description of the auth failure. Known values:\n- `\"Unauthorized\"` — no `Authorization` header on the request.\n- `\"Bearer Authentication Failed\"` — header present but token\n  is invalid, revoked, or expired."}},"required":["message"]}}}}}},"paths":{"/v1/processors/structuredFileParser":{"post":{"operationId":"parseStructuredFile","tags":["Parsers & Generators"],"summary":"Parse structured file (EDI) to JSON","description":"Parses EDI or other structured/delimited file data into JSON using\na file definition (parsing rules). Commonly used for X12 and EDIFACT\ndocuments.\n\nThe file definition must be provided inside a `rules.fileDefinition`\nwrapper object, or referenced by ID via `rules._fileDefinitionId`.\nThis differs from the generator endpoint which places definition\nfields directly in `rules`.\n\nThe response includes a `recordLevelErrors` array not present on\nother processor responses. This is a stateless transformation.\nProvide the file definition inline via `rules.fileDefinition` or\nreference an existing one via `rules._fileDefinitionId` (not both).\nThe generator endpoint places definition fields directly in `rules`\n(no `fileDefinition` wrapper).\n\n**Required file definition fields** — `name`, `version` (string\n`\"1\"` or `\"2\"`), `format` (`delimited`, `delimited/x12`,\n`delimited/edifact`, or `fixed`), and the corresponding format\nsub-object (`delimited` or `fixed`) with at least `rowDelimiter`\nand `colDelimiter` (for delimited) or `rowDelimiter` and\n`paddingChar` (for fixed). The `rules` property defines the\nsegment/element hierarchy.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["data","rules"],"properties":{"data":{"type":"string","description":"The raw structured file content to parse."},"rules":{"type":"object","description":"Provide either a `fileDefinition` object with the full\ndefinition inline, or a `_fileDefinitionId` to reference\nan existing file definition resource.","properties":{"fileDefinition":{"type":"object","description":"Inline file definition. Must include `name`, `version`,\n`format`, the format-specific sub-object, and `rules`.","properties":{"name":{"type":"string"},"description":{"type":"string"},"version":{"type":"string","enum":["1","2"]},"format":{"type":"string","description":"File format type.","enum":["delimited","delimited/x12","delimited/edifact","fixed"]},"delimited":{"type":"object","description":"Required when `format` starts with `delimited`.","properties":{"rowSuffix":{"type":"string"},"rowDelimiter":{"type":"string","description":"Row delimiter (required)."},"colDelimiter":{"type":"string","description":"Column delimiter (required for delimited)."},"compositeDelimiter":{"type":"string","description":"Composite element delimiter (EDI formats)."}}},"fixed":{"type":"object","description":"Required when `format` is `fixed`.","properties":{"rowSuffix":{"type":"string"},"rowDelimiter":{"type":"string","description":"Row delimiter (required)."},"paddingChar":{"type":"string","description":"Padding character (required, single char)."}}},"skipEmptyEndColDelimiter":{"type":"boolean"},"skipIntermittentEmptyLines":{"type":"boolean"},"skipEDIValidation":{"type":"boolean"},"skipEDIProfileValidation":{"type":"boolean"},"rules":{"description":"Segment/element hierarchy. Can be an array of\nsegment objects or a single root container object\nwith `children`.","oneOf":[{"title":"Segment array","type":"array","items":{"type":"object","additionalProperties":true}},{"title":"Root container","type":"object","additionalProperties":true}]}},"required":["name","version","format","rules"]},"_fileDefinitionId":{"type":"string","description":"Reference an existing file definition by ID instead of\nproviding an inline definition."},"resourcePath":{"type":"string","description":"Dot-separated path into the parsed document to select\nwhich segment's data to return as records."}}},"options":{"type":"object","properties":{"ediProfile":{"type":"object","additionalProperties":true,"description":"Optional EDI profile for ISA/GS envelope context."}}}}}}}},"responses":{"200":{"description":"Parsed JSON records.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StructuredFileParserResponse"}}}},"401":{"$ref":"#/components/responses/401-unauthorized"},"422":{"description":"File definition validation error or missing required segment.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"source":{"type":"string"},"code":{"type":"string","description":"Error code. Common values: `file_definition_error`,\n`missing_row`, `WRONG_MAX_OCCURRENCE`."},"resolved":{"type":"boolean"},"occurredAt":{"type":"integer"},"path":{"type":"string"}}}}}}}}}}}
```

## Generate structured file (EDI) from JSON

> Generates EDI or other structured/delimited file content from JSON\
> records using a file definition (generation rules). Commonly used\
> for producing X12 and EDIFACT documents.\
> \
> Unlike the parser endpoint, the generator places file definition\
> fields directly in \`rules\` (no \`fileDefinition\` wrapper). Each\
> element in the definition must include a \`value\` property containing\
> the literal text to output for that field.\
> \
> The \`data\` field must be an array of objects. Each object in the\
> array represents one document to generate. The response has\
> \`mediaType: "text"\` and does not include \`dataRecordTraceKeys\` or\
> \`traceKeysDuplicate\`.\
> \
> \*\*Required file definition fields\*\* — \`name\`, \`version\` (string\
> \`"1"\` or \`"2"\`), \`format\`, the format sub-object with\
> \`rowDelimiter\` + \`colDelimiter\` (and optionally \`rowSuffix\`), and\
> \`rules\` defining segments with elements that each have \`name\` and\
> \`value\`. This is a stateless transformation. File definition fields\
> go directly in \`rules\` (no \`fileDefinition\` wrapper, unlike the\
> parser endpoint).

```json
{"openapi":"3.2.0","info":{"title":"Parsers & Generators","version":"1.0.0"},"tags":[{"name":"Parsers & Generators","description":"Stateless data transformation processors that convert between raw formats\n(XML, CSV, EDI) and structured JSON. Parsers accept raw data and return\nJSON records; generators accept JSON and produce formatted output.\n\nThese are one-shot transformation calls — they do not create or modify\nany resources. Use them to test parsing rules, preview file definitions,\nor transform data outside of a flow.\n\n## Processor descriptor schema\n\n{% openapi-schemas spec=\"processor\" schemas=\"ProcessorDescriptor\" grouped=\"true\" %}"}],"servers":[{"url":"https://api.integrator.io","description":"Production (US / default region)"},{"url":"https://api.eu.integrator.io","description":"Production (EU region)"},{"url":"https://api.au.integrator.io","description":"Production (AU region)"},{"url":"https://api.ca.integrator.io","description":"Production (CA region)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"GeneratorResponse":{"type":"object","description":"Response from a generator processor (`csvDataGenerator`, `structuredFileGenerator`).","properties":{"mediaType":{"type":"string","description":"Always `text` for generator processors.","enum":["text"]},"data":{"type":"string","description":"Generated text output (CSV, EDI, or other structured format)."},"duration":{"type":"integer","description":"Processing time in milliseconds."}}}},"responses":{"401-unauthorized":{"description":"Unauthorized. The request lacks a valid bearer token, or the provided token\nfailed to authenticate.\n\nNote: the 401 response is produced by the auth middleware **before** the\nrequest reaches the endpoint handler, so it does **not** follow the\nstandard `{errors: [...]}` envelope. Instead the body is a bare\n`{message: string}` object with no `code`, no `errors` array. Callers\nhandling 401s should key off the HTTP status and the `message` string,\nnot try to destructure an `errors[]`.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable description of the auth failure. Known values:\n- `\"Unauthorized\"` — no `Authorization` header on the request.\n- `\"Bearer Authentication Failed\"` — header present but token\n  is invalid, revoked, or expired."}},"required":["message"]}}}}}},"paths":{"/v1/processors/structuredFileGenerator":{"post":{"operationId":"generateStructuredFile","tags":["Parsers & Generators"],"summary":"Generate structured file (EDI) from JSON","description":"Generates EDI or other structured/delimited file content from JSON\nrecords using a file definition (generation rules). Commonly used\nfor producing X12 and EDIFACT documents.\n\nUnlike the parser endpoint, the generator places file definition\nfields directly in `rules` (no `fileDefinition` wrapper). Each\nelement in the definition must include a `value` property containing\nthe literal text to output for that field.\n\nThe `data` field must be an array of objects. Each object in the\narray represents one document to generate. The response has\n`mediaType: \"text\"` and does not include `dataRecordTraceKeys` or\n`traceKeysDuplicate`.\n\n**Required file definition fields** — `name`, `version` (string\n`\"1\"` or `\"2\"`), `format`, the format sub-object with\n`rowDelimiter` + `colDelimiter` (and optionally `rowSuffix`), and\n`rules` defining segments with elements that each have `name` and\n`value`. This is a stateless transformation. File definition fields\ngo directly in `rules` (no `fileDefinition` wrapper, unlike the\nparser endpoint).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["data","rules"],"properties":{"data":{"type":"array","description":"Array of record objects. Each object represents one\ndocument to generate. The generator uses element `value`\nproperties from the rules, not field values from these\nobjects.","items":{"type":"object","additionalProperties":true}},"rules":{"type":"object","description":"File definition placed directly at this level (no\n`fileDefinition` wrapper). Must include `name`, `version`,\n`format`, the format sub-object, and `rules`.","required":["name","version","format","rules"],"properties":{"name":{"type":"string"},"description":{"type":"string"},"version":{"type":"string","enum":["1","2"]},"format":{"type":"string","description":"File format type.","enum":["delimited","delimited/x12","delimited/edifact","fixed"]},"delimited":{"type":"object","description":"Required when `format` starts with `delimited`.","properties":{"rowSuffix":{"type":"string","description":"Appended after each row."},"rowDelimiter":{"type":"string","description":"Row delimiter (required)."},"colDelimiter":{"type":"string","description":"Column delimiter (required for delimited)."},"compositeDelimiter":{"type":"string","description":"Composite element delimiter (EDI formats)."}}},"fixed":{"type":"object","description":"Required when `format` is `fixed`.","properties":{"rowSuffix":{"type":"string"},"rowDelimiter":{"type":"string","description":"Row delimiter (required)."},"paddingChar":{"type":"string","description":"Padding character (required, single char)."}}},"skipEmptyEndColDelimiter":{"type":"boolean"},"rules":{"type":"array","description":"Array of segment definitions. Each segment has a `name`\nand `elements` array. Each element must have `name` and\n`value` (the literal text to output).","items":{"type":"object","additionalProperties":true}}},"additionalProperties":true},"options":{"type":"object","properties":{"ediProfile":{"type":"object","additionalProperties":true,"description":"Optional EDI profile for ISA/GS envelope context."}}}}}}}},"responses":{"200":{"description":"Generated structured file content.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeneratorResponse"}}}},"401":{"$ref":"#/components/responses/401-unauthorized"},"422":{"description":"File definition validation error.","content":{"application/json":{"schema":{"type":"object","properties":{"source":{"type":"string"},"code":{"type":"string","description":"Error code. Typically `INVALID_FILE_DEFINITION` or\n`wrong_data_type`."},"message":{"type":"string"},"details":{"type":"array","description":"Detailed validation errors.","items":{"type":"object","properties":{"path":{"type":"string"},"message":{"type":"string"},"name":{"type":"string"}}}},"path":{"type":"string"}}}}}}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developer.celigo.com/api/api-reference/parsers-and-generators.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.