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
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).
Processor catalog, keyed by processor name.
Processor catalog keyed by processor name. Each value describes the processor's label, purpose, and input/output media types.
Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.
Note: the 401 response is produced by the auth middleware before the
request reaches the endpoint handler, so it does not follow the
standard {errors: [...]} envelope. Instead the body is a bare
{message: string} object with no code, no errors array. Callers
handling 401s should key off the HTTP status and the message string,
not try to destructure an errors[].
GET /v1/processors HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"handlebars": {
"name": "handlebars",
"label": "Handlebars",
"description": "Handlebars template processor.",
"ruleMediaType": "text",
"dataMediaType": "json",
"resultMediaType": "text"
},
"javascript": {
"name": "javascript",
"label": "JavaScript",
"description": "JavaScript hook processor.",
"ruleMediaType": "javascript",
"dataMediaType": "json",
"resultMediaType": "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.
The XML data to parse (as a string).
<orders><order><id>101</id><item>Widget</item></order></orders>Parsed JSON records.
Response from a parser processor (csvParser, xmlParser).
When groupByFields is used in the request, the dataRecordTraceKeys
and traceKeysDuplicate fields are omitted from the response and data
becomes an array of arrays (each inner array is one group of records).
Always json for parser processors.
Parsed records. Normally an array of objects. When groupByFields
is used, becomes an array of arrays (grouped records).
Processing time in milliseconds.
Whether any duplicate trace keys were detected. Omitted when
groupByFields is used.
Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.
Note: the 401 response is produced by the auth middleware before the
request reaches the endpoint handler, so it does not follow the
standard {errors: [...]} envelope. Instead the body is a bare
{message: string} object with no code, no errors array. Callers
handling 401s should key off the HTTP status and the message string,
not try to destructure an errors[].
Invalid XPath expression or processing rule error.
POST /v1/processors/xmlParser HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 252
{
"data": "<orders><order><id>101</id><item>Widget</item></order><order><id>102</id><item>Gadget</item></order></orders>",
"rules": {
"resourcePath": "/orders/order",
"doc": {
"fileParser": true,
"parsers": [
{
"type": "xml",
"version": 1,
"rules": {
"V0_json": false
}
}
]
}
}
}{
"mediaType": "json",
"data": [
{
"id": "101",
"item": "Widget"
},
{
"id": "102",
"item": "Gadget"
}
],
"duration": 1,
"dataRecordTraceKeys": [
null,
null
],
"traceKeysDuplicate": false
}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.
The CSV data to parse.
name,email,age Alice,alice@example.com,30 Bob,bob@example.com,25Parsed JSON records.
Response from a parser processor (csvParser, xmlParser).
When groupByFields is used in the request, the dataRecordTraceKeys
and traceKeysDuplicate fields are omitted from the response and data
becomes an array of arrays (each inner array is one group of records).
Always json for parser processors.
Parsed records. Normally an array of objects. When groupByFields
is used, becomes an array of arrays (grouped records).
Processing time in milliseconds.
Whether any duplicate trace keys were detected. Omitted when
groupByFields is used.
Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.
Note: the 401 response is produced by the auth middleware before the
request reaches the endpoint handler, so it does not follow the
standard {errors: [...]} envelope. Instead the body is a bare
{message: string} object with no code, no errors array. Callers
handling 401s should key off the HTTP status and the message string,
not try to destructure an errors[].
POST /v1/processors/csvParser HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 168
{
"data": "name,email,age\nAlice,alice@example.com,30\nBob,bob@example.com,25",
"rules": {
"columnDelimiter": ",",
"hasHeaderRow": true
},
"options": {
"includeEmptyValues": false
}
}{
"mediaType": "json",
"data": [
{
"name": "Alice",
"email": "alice@example.com",
"age": "30"
},
{
"name": "Bob",
"email": "bob@example.com",
"age": "25"
}
],
"duration": 0,
"dataRecordTraceKeys": [
null,
null
],
"traceKeysDuplicate": false
}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.
Records to convert to CSV. Accepts a flat array of objects
(e.g. [{"a":"1"}, {"a":"2"}]) or an array of arrays for
batch processing (e.g. [[{"a":"1"}], [{"a":"2"}]]). Each
object's keys become column names when includeHeader is
true.
Generated CSV data.
Response from a generator processor (csvDataGenerator, structuredFileGenerator).
Always text for generator processors.
Generated text output (CSV, EDI, or other structured format).
Processing time in milliseconds.
Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.
Note: the 401 response is produced by the auth middleware before the
request reaches the endpoint handler, so it does not follow the
standard {errors: [...]} envelope. Instead the body is a bare
{message: string} object with no code, no errors array. Callers
handling 401s should key off the HTTP status and the message string,
not try to destructure an errors[].
POST /v1/processors/csvDataGenerator HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 169
{
"data": [
{
"name": "Alice",
"email": "alice@example.com"
},
{
"name": "Bob",
"email": "bob@example.com"
}
],
"rules": {
"columnDelimiter": ",",
"rowDelimiter": "\n",
"includeHeader": true
}
}{
"mediaType": "text",
"data": "name,email\nAlice,alice@example.com\nBob,bob@example.com\n",
"duration": 0
}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.
The raw structured file content to parse.
HDR~John~Doe DTL~100~USDParsed JSON records.
Response from the structuredFileParser processor.
Always json for the structured file parser.
Processing time in milliseconds.
When true, duplicate trace keys were detected in the output records.
Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.
Note: the 401 response is produced by the auth middleware before the
request reaches the endpoint handler, so it does not follow the
standard {errors: [...]} envelope. Instead the body is a bare
{message: string} object with no code, no errors array. Callers
handling 401s should key off the HTTP status and the message string,
not try to destructure an errors[].
File definition validation error or missing required segment.
POST /v1/processors/structuredFileParser HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 324
{
"data": "HDR~John~Doe\nDTL~100~USD",
"rules": {
"fileDefinition": {
"name": "simple-delimited",
"version": "1",
"format": "delimited",
"delimited": {
"rowDelimiter": "\n",
"colDelimiter": "~"
},
"rules": [
{
"name": "HDR",
"elements": [
{
"name": "firstName"
},
{
"name": "lastName"
}
]
},
{
"name": "DTL",
"elements": [
{
"name": "amount"
},
{
"name": "currency"
}
]
}
]
}
}
}{
"mediaType": "json",
"data": [
{
"HDR": {
"firstName": "John",
"lastName": "Doe"
},
"DTL": {
"amount": "100",
"currency": "USD"
}
}
],
"recordLevelErrors": [],
"duration": 1,
"dataRecordTraceKeys": [
null
],
"traceKeysDuplicate": false
}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).
Generated structured file content.
Response from a generator processor (csvDataGenerator, structuredFileGenerator).
Always text for generator processors.
Generated text output (CSV, EDI, or other structured format).
Processing time in milliseconds.
Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.
Note: the 401 response is produced by the auth middleware before the
request reaches the endpoint handler, so it does not follow the
standard {errors: [...]} envelope. Instead the body is a bare
{message: string} object with no code, no errors array. Callers
handling 401s should key off the HTTP status and the message string,
not try to destructure an errors[].
File definition validation error.
POST /v1/processors/structuredFileGenerator HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 245
{
"data": [
{}
],
"rules": {
"name": "simple-delimited",
"version": "1",
"format": "delimited",
"delimited": {
"rowDelimiter": "\n",
"colDelimiter": "~"
},
"rules": [
{
"name": "HDR",
"elements": [
{
"name": "firstName",
"value": "John"
},
{
"name": "lastName",
"value": "Doe"
}
]
}
]
}
}{
"mediaType": "text",
"data": "HDR~John~Doe\n",
"duration": 0
}Last updated
Was this helpful?