File Definitions

File definitions describe the structure and parsing rules for structured files (CSV, fixed-width, EDI X12, EDI EDIFACT). Exports and imports that process file-based data reference a file definition to control how rows, columns, segments, and elements are parsed or generated.

Four formats are supported: delimited (CSV/TSV), delimited/x12 (EDI X12), delimited/edifact (EDI EDIFACT), and fixed (fixed-width). EDI formats require a globalId linking to a standard document definition.

File definition schema

List file definitions

get

/v1/filedefinitions

Returns file definitions configured in the account.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

includestringOptional

Comma-separated list of fields to project into each returned record. Triggers summary projection: the response contains a minimal identity set (_id, name, plus resource-specific fields) with the requested fields added on top. Supports dot notation for nested fields. Mutually exclusive with exclude.

Example: _integrationId,disabled,lastModified

excludestringOptional

Comma-separated list of fields to strip from the default response. Unlike include, does not trigger summary projection — returns the full record with the named fields removed. Protected identity fields (e.g. name) cannot be stripped. Mutually exclusive with include.

Example: createdAt,lastModified

externalIdstringOptional

Filter to file definitions matching this exact external identifier.

Example: ext-filedef-12345

limitinteger · min: 1 · max: 1000Optional

Maximum number of file definitions to return per page.

Example: 100

Responses

200

List of file definitions.

application/json

204

No file definitions exist in the account.

401

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[].

application/json

get/v1/filedefinitions

GET /v1/filedefinitions HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

[
  {
    "_id": "69150aa2578417f9fa410317",
    "name": "Costco 850",
    "version": "2",
    "format": "delimited/x12",
    "globalId": "525b2a50-b8e5-4d01-b0ae-bf7fa4228ea2",
    "skipEmptyEndColDelimiter": true,
    "skipEDIValidation": true,
    "skipEDIProfileValidation": true,
    "delimited": {
      "rowSuffix": "~",
      "rowDelimiter": "\n",
      "colDelimiter": "*"
    },
    "rules": [
      {
        "required": true,
        "maxOccurrence": 1,
        "elements": [
          {
            "name": "ISA",
            "value": "ISA"
          }
        ]
      }
    ],
    "lastModified": "2025-11-12T22:30:58.442Z",
    "sandbox": false
  }
]

Create a file definition

post

/v1/filedefinitions

Creates a new file definition.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

Request schema for creating or updating a file definition.

namestring · min: 1 · max: 100Required

Human-readable name for the file definition.

Example: Invoice EDI 810

descriptionstring · max: 10240Optional

Optional detailed description of the file definition's purpose and format.

Example: Defines the structure for parsing incoming EDI 810 invoice documents

versionstring · enumRequired

Schema version of the file definition. Only incremented for breaking changes.

Example: 1Possible values:

formatstring · enumRequired

The file format this definition describes.

Possible values:

documentTypestring · enumOptional

EDI document type for acknowledgement documents.

Possible values:

globalIdstringOptional

Global identifier mapping to a known EDI standard document definition.

Required for EDI formats (delimited/x12 or delimited/edifact) when the account has an EDI license enabled. Must reference a valid entry in the standard file definitions metadata. Immutable after creation.

Example: 3c7a8f2e-1234-5678-9abc-def012345678

strictbooleanOptional

Whether to fail on all validation errors.

Reserved for future use.

skipEmptyEndColDelimiterbooleanOptional

Whether to skip trailing empty column delimiters at the end of rows.

skipIntermittentEmptyLinesbooleanOptional

Whether to remove empty rows found in the file content during parsing.

escapeReleaseCharbooleanOptional

Whether to handle escape/release characters in delimited data. Primarily relevant for EDI EDIFACT format.

skipEDIValidationbooleanOptional

Whether to skip EDI structural validation during parsing.

skipEDIProfileValidationbooleanOptional

Whether to skip EDI profile-level validation during parsing.

Default: false

externalIdstringOptional

External identifier for correlating this file definition with an external system.

Example: ext-filedef-12345

Responses

201

File definition created.

application/json

File definition object as returned by the API.

namestring · min: 1 · max: 100Required

Human-readable name for the file definition.

Example: Invoice EDI 810

descriptionstring · max: 10240Optional

Optional detailed description of the file definition's purpose and format.

Example: Defines the structure for parsing incoming EDI 810 invoice documents

versionstring · enumRequired

Schema version of the file definition. Only incremented for breaking changes.

Example: 1Possible values:

formatstring · enumRequired

The file format this definition describes.

Possible values:

documentTypestring · enumOptional

EDI document type for acknowledgement documents.

Possible values:

globalIdstringOptional

Global identifier mapping to a known EDI standard document definition.

Required for EDI formats (delimited/x12 or delimited/edifact) when the account has an EDI license enabled. Must reference a valid entry in the standard file definitions metadata. Immutable after creation.

Example: 3c7a8f2e-1234-5678-9abc-def012345678

strictbooleanOptional

Whether to fail on all validation errors.

Reserved for future use.

skipEmptyEndColDelimiterbooleanOptional

Whether to skip trailing empty column delimiters at the end of rows.

skipIntermittentEmptyLinesbooleanOptional

Whether to remove empty rows found in the file content during parsing.

escapeReleaseCharbooleanOptional

Whether to handle escape/release characters in delimited data. Primarily relevant for EDI EDIFACT format.

skipEDIValidationbooleanOptional

Whether to skip EDI structural validation during parsing.

skipEDIProfileValidationbooleanOptional

Whether to skip EDI profile-level validation during parsing.

Default: false

externalIdstringOptional

External identifier for correlating this file definition with an external system.

Example: ext-filedef-12345

_idstring · objectIdRead-onlyRequired

Unique identifier for the resource. Format is a 24-character hexadecimal string.

Example: 5f8d43a1b9e5a80011a35f2c

createdAtstring · date-timeRead-onlyOptional

Timestamp when the resource was created. Set automatically and cannot be modified.

Example: 2023-04-01T09:15:32Z

lastModifiedstring · date-timeRead-onlyRequired

Timestamp when the resource was last updated. Changes whenever any property is modified.

Example: 2023-04-15T14:30:15Z

deletedAtstring · nullableRead-onlyOptional

Timestamp when the resource was soft-deleted. When null or absent, the resource is active.

Example: 2023-05-20T11:45:32Z

_templateIdstring · objectIdRead-onlyOptional

Template this file definition was created from.

Example: 5f8d43a1b9e5a80011a35f2c

_sourceIdstring · objectIdRead-onlyOptional

Source identifier for tracking the definition's origin.

Example: 5f8d43a1b9e5a80011a35f2c

400

Bad request. The server could not understand the request because of malformed syntax or invalid parameters.

application/json

401

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[].

application/json

422

Unprocessable entity. The request was well-formed but was unable to be followed due to semantic errors.

application/json

post/v1/filedefinitions

POST /v1/filedefinitions HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 242

{
  "name": "Customer CSV Import",
  "version": "1",
  "format": "delimited",
  "delimited": {
    "rowDelimiter": "\n",
    "colDelimiter": ","
  },
  "rules": [
    {
      "required": true,
      "maxOccurrence": 1,
      "elements": [
        {
          "name": "customer_id"
        },
        {
          "name": "customer_name"
        },
        {
          "name": "email"
        }
      ]
    }
  ]
}

{
  "_id": "5f8d43a1b9e5a80011a35f2c",
  "name": "Customer CSV Import",
  "version": "1",
  "format": "delimited",
  "delimited": {
    "rowDelimiter": "\n",
    "colDelimiter": ","
  },
  "rules": [
    {
      "required": true,
      "maxOccurrence": 1,
      "elements": [
        {
          "name": "customer_id"
        },
        {
          "name": "customer_name"
        },
        {
          "name": "email"
        }
      ]
    }
  ],
  "lastModified": "2026-06-09T18:05:33.612Z",
  "sandbox": false
}

Get a file definition

get

/v1/filedefinitions/{_id}

Returns the complete configuration including parsing rules.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

_idstring · objectIdRequired

File definition ID.

Example: 69150aa2578417f9fa410317

Responses

200

File definition.

application/json

File definition object as returned by the API.

namestring · min: 1 · max: 100Required

Human-readable name for the file definition.

Example: Invoice EDI 810

descriptionstring · max: 10240Optional

Optional detailed description of the file definition's purpose and format.

Example: Defines the structure for parsing incoming EDI 810 invoice documents

versionstring · enumRequired

Schema version of the file definition. Only incremented for breaking changes.

Example: 1Possible values:

formatstring · enumRequired

The file format this definition describes.

Possible values:

documentTypestring · enumOptional

EDI document type for acknowledgement documents.

Possible values:

globalIdstringOptional

Global identifier mapping to a known EDI standard document definition.

Required for EDI formats (delimited/x12 or delimited/edifact) when the account has an EDI license enabled. Must reference a valid entry in the standard file definitions metadata. Immutable after creation.

Example: 3c7a8f2e-1234-5678-9abc-def012345678

strictbooleanOptional

Whether to fail on all validation errors.

Reserved for future use.

skipEmptyEndColDelimiterbooleanOptional

Whether to skip trailing empty column delimiters at the end of rows.

skipIntermittentEmptyLinesbooleanOptional

Whether to remove empty rows found in the file content during parsing.

escapeReleaseCharbooleanOptional

Whether to handle escape/release characters in delimited data. Primarily relevant for EDI EDIFACT format.

skipEDIValidationbooleanOptional

Whether to skip EDI structural validation during parsing.

skipEDIProfileValidationbooleanOptional

Whether to skip EDI profile-level validation during parsing.

Default: false

externalIdstringOptional

External identifier for correlating this file definition with an external system.

Example: ext-filedef-12345

_idstring · objectIdRead-onlyRequired

Unique identifier for the resource. Format is a 24-character hexadecimal string.

Example: 5f8d43a1b9e5a80011a35f2c

createdAtstring · date-timeRead-onlyOptional

Timestamp when the resource was created. Set automatically and cannot be modified.

Example: 2023-04-01T09:15:32Z

lastModifiedstring · date-timeRead-onlyRequired

Timestamp when the resource was last updated. Changes whenever any property is modified.

Example: 2023-04-15T14:30:15Z

deletedAtstring · nullableRead-onlyOptional

Timestamp when the resource was soft-deleted. When null or absent, the resource is active.

Example: 2023-05-20T11:45:32Z

_templateIdstring · objectIdRead-onlyOptional

Template this file definition was created from.

Example: 5f8d43a1b9e5a80011a35f2c

_sourceIdstring · objectIdRead-onlyOptional

Source identifier for tracking the definition's origin.

Example: 5f8d43a1b9e5a80011a35f2c

401

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[].

application/json

404

Not found. The requested resource does not exist or is not visible to the caller.

application/json

get/v1/filedefinitions/{_id}

GET /v1/filedefinitions/{_id} HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "_id": "69150aa2578417f9fa410317",
  "name": "Costco 850",
  "version": "2",
  "format": "delimited/x12",
  "description": "Purchase Order",
  "globalId": "525b2a50-b8e5-4d01-b0ae-bf7fa4228ea2",
  "skipEmptyEndColDelimiter": true,
  "skipEDIValidation": true,
  "skipEDIProfileValidation": true,
  "delimited": {
    "rowSuffix": "~",
    "rowDelimiter": "\n",
    "colDelimiter": "*"
  },
  "rules": [
    {
      "required": true,
      "maxOccurrence": 1,
      "elements": [
        {
          "name": "ISA",
          "value": "ISA"
        }
      ]
    }
  ],
  "lastModified": "2025-11-12T22:30:58.442Z",
  "sandbox": false
}

Update a file definition

put

/v1/filedefinitions/{_id}

Replaces the file definition with the provided configuration. This is a full replace -- include all fields you want to keep. format cannot be changed between fixed and delimited families after creation, and globalId is immutable for EDI formats.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

_idstring · objectIdRequired

File definition ID.

Example: 69150aa2578417f9fa410317

Body

Request schema for creating or updating a file definition.

namestring · min: 1 · max: 100Required

Human-readable name for the file definition.

Example: Invoice EDI 810

descriptionstring · max: 10240Optional

Optional detailed description of the file definition's purpose and format.

Example: Defines the structure for parsing incoming EDI 810 invoice documents

versionstring · enumRequired

Schema version of the file definition. Only incremented for breaking changes.

Example: 1Possible values:

formatstring · enumRequired

The file format this definition describes.

Possible values:

documentTypestring · enumOptional

EDI document type for acknowledgement documents.

Possible values:

globalIdstringOptional

Global identifier mapping to a known EDI standard document definition.

Required for EDI formats (delimited/x12 or delimited/edifact) when the account has an EDI license enabled. Must reference a valid entry in the standard file definitions metadata. Immutable after creation.

Example: 3c7a8f2e-1234-5678-9abc-def012345678

strictbooleanOptional

Whether to fail on all validation errors.

Reserved for future use.

skipEmptyEndColDelimiterbooleanOptional

Whether to skip trailing empty column delimiters at the end of rows.

skipIntermittentEmptyLinesbooleanOptional

Whether to remove empty rows found in the file content during parsing.

escapeReleaseCharbooleanOptional

Whether to handle escape/release characters in delimited data. Primarily relevant for EDI EDIFACT format.

skipEDIValidationbooleanOptional

Whether to skip EDI structural validation during parsing.

skipEDIProfileValidationbooleanOptional

Whether to skip EDI profile-level validation during parsing.

Default: false

externalIdstringOptional

External identifier for correlating this file definition with an external system.

Example: ext-filedef-12345

Responses

200

Updated file definition.

application/json

File definition object as returned by the API.

namestring · min: 1 · max: 100Required

Human-readable name for the file definition.

Example: Invoice EDI 810

descriptionstring · max: 10240Optional

Optional detailed description of the file definition's purpose and format.

Example: Defines the structure for parsing incoming EDI 810 invoice documents

versionstring · enumRequired

Schema version of the file definition. Only incremented for breaking changes.

Example: 1Possible values:

formatstring · enumRequired

The file format this definition describes.

Possible values:

documentTypestring · enumOptional

EDI document type for acknowledgement documents.

Possible values:

globalIdstringOptional

Global identifier mapping to a known EDI standard document definition.

Required for EDI formats (delimited/x12 or delimited/edifact) when the account has an EDI license enabled. Must reference a valid entry in the standard file definitions metadata. Immutable after creation.

Example: 3c7a8f2e-1234-5678-9abc-def012345678

strictbooleanOptional

Whether to fail on all validation errors.

Reserved for future use.

skipEmptyEndColDelimiterbooleanOptional

Whether to skip trailing empty column delimiters at the end of rows.

skipIntermittentEmptyLinesbooleanOptional

Whether to remove empty rows found in the file content during parsing.

escapeReleaseCharbooleanOptional

Whether to handle escape/release characters in delimited data. Primarily relevant for EDI EDIFACT format.

skipEDIValidationbooleanOptional

Whether to skip EDI structural validation during parsing.

skipEDIProfileValidationbooleanOptional

Whether to skip EDI profile-level validation during parsing.

Default: false

externalIdstringOptional

External identifier for correlating this file definition with an external system.

Example: ext-filedef-12345

_idstring · objectIdRead-onlyRequired

Unique identifier for the resource. Format is a 24-character hexadecimal string.

Example: 5f8d43a1b9e5a80011a35f2c

createdAtstring · date-timeRead-onlyOptional

Timestamp when the resource was created. Set automatically and cannot be modified.

Example: 2023-04-01T09:15:32Z

lastModifiedstring · date-timeRead-onlyRequired

Timestamp when the resource was last updated. Changes whenever any property is modified.

Example: 2023-04-15T14:30:15Z

deletedAtstring · nullableRead-onlyOptional

Timestamp when the resource was soft-deleted. When null or absent, the resource is active.

Example: 2023-05-20T11:45:32Z

_templateIdstring · objectIdRead-onlyOptional

Template this file definition was created from.

Example: 5f8d43a1b9e5a80011a35f2c

_sourceIdstring · objectIdRead-onlyOptional

Source identifier for tracking the definition's origin.

Example: 5f8d43a1b9e5a80011a35f2c

400

Bad request. The server could not understand the request because of malformed syntax or invalid parameters.

application/json

401

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[].

application/json

404

Not found. The requested resource does not exist or is not visible to the caller.

application/json

put/v1/filedefinitions/{_id}

PUT /v1/filedefinitions/{_id} HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 388

{
  "name": "Costco 850",
  "version": "2",
  "format": "delimited/x12",
  "description": "Purchase Order",
  "globalId": "525b2a50-b8e5-4d01-b0ae-bf7fa4228ea2",
  "skipEmptyEndColDelimiter": true,
  "skipEDIValidation": false,
  "skipEDIProfileValidation": true,
  "delimited": {
    "rowSuffix": "~",
    "rowDelimiter": "\n",
    "colDelimiter": "*"
  },
  "rules": [
    {
      "required": true,
      "maxOccurrence": 1,
      "elements": [
        {
          "name": "ISA",
          "value": "ISA"
        }
      ]
    }
  ]
}

{
  "_id": "69150aa2578417f9fa410317",
  "name": "Costco 850",
  "version": "2",
  "format": "delimited/x12",
  "description": "Purchase Order",
  "globalId": "525b2a50-b8e5-4d01-b0ae-bf7fa4228ea2",
  "skipEmptyEndColDelimiter": true,
  "skipEDIValidation": false,
  "skipEDIProfileValidation": true,
  "delimited": {
    "rowSuffix": "~",
    "rowDelimiter": "\n",
    "colDelimiter": "*"
  },
  "rules": [
    {
      "required": true,
      "maxOccurrence": 1,
      "elements": [
        {
          "name": "ISA",
          "value": "ISA"
        }
      ]
    }
  ],
  "lastModified": "2025-11-20T08:14:27.310Z",
  "sandbox": false
}

Delete a file definition

delete

/v1/filedefinitions/{_id}

Soft-deletes a file definition. Retained in the recycle bin for 30 days.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

_idstring · objectIdRequired

File definition ID.

Example: 69150aa2578417f9fa410317

Responses

204

File definition deleted.

No content

401

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[].

application/json

404

Not found. The requested resource does not exist or is not visible to the caller.

application/json

delete/v1/filedefinitions/{_id}

DELETE /v1/filedefinitions/{_id} HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

List dependencies of a file definition

get

/v1/filedefinitions/{_id}/dependencies

Returns the set of resources that depend on the specified resource. The response is an object whose keys are dependent-resource types (e.g. flows, imports) and whose values are arrays of dependency entries. Returns {} when no dependents exist, including for well-formatted but nonexistent IDs.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

_idstring · objectIdRequired

Resource ID.

Example: 69150aa2578417f9fa410317

Responses

200

Dependency map. Keys are resource-type strings; values are arrays of dependency entries. Returns {} when no dependents exist.

application/json

Map of dependent-resource types to arrays of dependency entries. Keys are plural resource type strings (e.g. flows, imports, connections). An empty object {} means no dependents.

401

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[].

application/json

get/v1/filedefinitions/{_id}/dependencies

GET /v1/filedefinitions/{_id}/dependencies HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{}