# Trading Partner Connectors

## List trading partner connectors

> Returns a list of all trading partner connectors.\
> Supports filtering to only return published connectors via the \`publishedOnly\` query parameter.\
> If no connectors exist, a 204 response with no body will be returned.<br>

````json
{"openapi":"3.1.0","info":{"title":"Trading Partner Connectors","version":"1.0.0"},"servers":[{"url":"https://api.integrator.io","description":"Production (US / default region)"},{"url":"https://api.eu.integrator.io","description":"Production (EU region)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"parameters":{"Include":{"name":"include","in":"query","required":false,"description":"Comma-separated list of fields to project into each returned record.\nTriggers **summary projection** on supported list endpoints: the server\nreturns a minimal identity set for each record (`_id`, `name`, plus a\nresource-specific always-on set like `adaptorType` on exports/imports,\nor richer defaults on `ashares`, `audit`, `httpconnectors`, `transfers`,\netc.) and adds any listed fields that exist on the record. Listed fields\nthe record doesn't carry are silently dropped.\n\nDot notation is supported for projecting nested sub-fields — e.g.\n`include=ftp.directoryPath` on `/v1/exports` returns just that nested\nfield inside `ftp` for FTP-type exports (and omits `ftp` entirely for\nnon-FTP exports).\n\nRules:\n- Value regex is `{a-z A-Z . _}` (letters, dots, underscores) plus the\n  comma separator; digits are also accepted in practice. Any other\n  character returns **400 `invalid_query_params`**.\n- Empty value (`include=`) or bare `include` is ignored — the full\n  default record is returned.\n- `include` and `exclude` are **mutually exclusive**. Passing both\n  returns **400 `invalid_query_params`**: *\"Please provide either\n  include or exclude param in the request query and not both.\"*\n- Array-bracket syntax (`include[]=...`) is not supported and can return\n  a 500.\n- Only list endpoints honor projection — on GET-by-id the parameter is\n  silently ignored.\n- A small set of list endpoints explicitly reject both `include` and\n  `exclude` with **400 `invalid_query_params`** and a message of the form\n  *\"Include or exclude query params are not applicable for `<resource>`\n  resource.\"* Known rejections: `/v1/ediprofiles`, `/v1/environments`,\n  `/v1/iClients`, `/v1/lookupcaches`, `/v1/tags`.","schema":{"type":"string"}},"Exclude":{"name":"exclude","in":"query","required":false,"description":"Comma-separated list of fields to remove from the default response on\nsupported list endpoints. Unlike `include`, `exclude` does NOT trigger\nsummary projection — callers get the standard full-record shape with the\nnamed fields stripped out.\n\nRules:\n- Value regex is `{a-z A-Z . _}` (letters, dots, underscores) plus the\n  comma separator; digits are also accepted in practice. Any other\n  character returns **400 `invalid_query_params`**.\n- Empty value (`exclude=`) is ignored.\n- Certain protected identity fields **cannot be stripped** — e.g.\n  `exclude=name` on `/v1/exports` is silently ignored and `name` remains\n  in the response. Protected sets vary per resource.\n- `include` and `exclude` are **mutually exclusive**. Passing both\n  returns **400 `invalid_query_params`**: *\"Please provide either\n  include or exclude param in the request query and not both.\"*\n- Only list endpoints honor stripping — on GET-by-id the parameter is\n  silently ignored.\n- A small set of list endpoints explicitly reject both `include` and\n  `exclude` with **400 `invalid_query_params`** and a message of the form\n  *\"Include or exclude query params are not applicable for `<resource>`\n  resource.\"* Known rejections: `/v1/ediprofiles`, `/v1/environments`,\n  `/v1/iClients`, `/v1/lookupcaches`, `/v1/tags`.","schema":{"type":"string"}}},"schemas":{"Response":{"type":"object","description":"Response schema for trading partner connector operations.\n\nContains the complete connector configuration including metadata and all\nsupportedBy sections with conditions, pre-configured fields, and fields\nthe user must set.\n","allOf":[{"$ref":"#/components/schemas/Request"},{"type":"object","properties":{"_id":{"type":"string","format":"objectId","readOnly":true,"description":"Unique identifier for the trading partner connector"},"createdAt":{"type":"string","format":"date-time","readOnly":true,"description":"Timestamp when the connector was created"},"lastModified":{"type":"string","format":"date-time","readOnly":true,"description":"Timestamp when the connector was last modified"},"_userId":{"type":"string","format":"objectId","description":"User who owns or created this trading partner connector"}}}]},"Request":{"type":"object","description":"Request schema for creating or updating a trading partner connector.\n\nTrading partner connectors define reusable templates for onboarding EDI trading\npartners. They specify which fields are pre-configured and which fields the user\nmust provide for connections, exports, imports, and EDI profiles.\n\nWhen `published` is true, the connector's `supportedBy` sections are validated\nto ensure all required fields are present. For example:\n- Connection must have a pre-configured `type` field (either \"ftp\" or \"as2\")\n- Export/import must have a pre-configured `file.type` set to \"filedefinition\"\n- EDI profile must have the appropriate mandatory fields for x12 or edifact\n","properties":{"name":{"type":"string","description":"Name of the trading partner connector. Must be unique across all published\nconnectors. Used to identify the connector during trading partner onboarding.\n"},"published":{"type":"boolean","default":false,"description":"Whether this connector is published and available for use across the platform.\n\nOnly users with the `allowedToPublishTPConnectors` permission can set this\nto true. When publishing, all `supportedBy` sections are validated to ensure\nrequired fields are present. Published connector names must be unique.\n"},"helpURL":{"type":"string","description":"URL to documentation for this trading partner connector.\n"},"supportedBy":{"type":"object","description":"Defines the field configurations for each resource type involved in trading\npartner onboarding. Each section specifies conditions, pre-configured fields,\nand fields the user must set.\n","properties":{"ediProfile":{"$ref":"#/components/schemas/SupportedBySection"},"export":{"$ref":"#/components/schemas/SupportedBySection"},"import":{"$ref":"#/components/schemas/SupportedBySection"},"connection":{"$ref":"#/components/schemas/ConnectionSupportedBySection"}}}},"required":["name"]},"SupportedBySection":{"type":"object","description":"A section within `supportedBy` that defines conditions, pre-configured field values,\nand fields the user must set when creating a trading partner resource (connection,\nexport, import, or EDI profile).\n\nConditions use expression-based filters to control which field configurations apply\nbased on resource attributes. Pre-configured fields are automatically set, while\nfields the user must set require input during trading partner onboarding.\n","properties":{"conditions":{"type":"array","description":"Array of condition objects. Each condition contains an expression-based filter\nthat can be referenced by `_conditionIds` in `preConfiguredFields` and\n`fieldsUserMustSet` to conditionally apply those field configurations.\n","items":{"type":"object","properties":{"_id":{"type":"string","format":"objectId","description":"Unique identifier for this condition, referenced by `_conditionIds` in field entries"},"condition":{"$ref":"#/components/schemas/Filter"}}}},"preConfiguredFields":{"type":"array","description":"Array of fields that are automatically set to predefined values when creating\na trading partner resource using this connector. These fields are not editable\nby the user during onboarding.\n","items":{"$ref":"#/components/schemas/PreConfiguredField"}},"fieldsUserMustSet":{"type":"array","description":"Array of fields that the user must provide values for during trading partner\nonboarding. These fields may have suggested values or constraints.\n","items":{"$ref":"#/components/schemas/FieldUserMustSet"}}}},"Filter":{"type":"object","description":"Configuration for selectively processing records based on specified criteria. This object enables\nprecise control over which items are included or excluded from processing operations.\n\n**Filter behavior**\n\nWhen configured, the filter is applied before processing begins:\n- Items that match the filter criteria are processed\n- Items that don't match are completely skipped\n- No partial processing is performed\n\n**Implementation approaches**\n\nThere are two distinct filtering mechanisms available:\n\n**Rule-Based Filtering (`type: \"expression\"`)**\n- **Best For**: Common filtering patterns based on standard attributes\n- **Capabilities**: Filter by names, values, dates, numerical ranges, text patterns\n- **Advantages**: Declarative, no coding required, consistent performance\n- **Configuration**: Define rules in the `expression` object\n- **Use When**: You have clear, static criteria for selection\n\n**Script-Based Filtering (`type: \"script\"`)**\n- **Best For**: Complex logic, dynamic criteria, or business rules\n- **Capabilities**: Full programmatic control, access to complete metadata\n- **Advantages**: Maximum flexibility, can implement any filtering logic\n- **Configuration**: Reference a script in the `script` object\n- **Use When**: Simple rules aren't sufficient or logic needs to be dynamic\n","properties":{"type":{"type":"string","description":"Determines which filtering mechanism to use. This choice affects which properties\nmust be configured and how filtering logic is implemented.\n\n**Available types**\n\n**Rule-Based Filtering (`\"expression\"`)**\n- **Required Config**: The `expression` object with rule definitions\n- **Behavior**: Evaluates declarative rules against item attributes\n- **Best For**: Common patterns like name matching, date ranges, value limits\n- **Advantages**: Simpler to configure, no custom code required\n\n**Script-Based Filtering (`\"script\"`)**\n- **Required Config**: The `script` object with _scriptId and function\n- **Behavior**: Executes custom JavaScript to determine which items to process\n- **Best For**: Complex conditions, business logic, dynamic criteria\n- **Advantages**: Maximum flexibility, can implement any logic\n\n**Implementation guidance**\n\n1. For standard filtering needs (name, size, date), use `\"expression\"`\n2. For complex logic or conditions not covered by expressions, use `\"script\"`\n3. When selecting a type, you must configure the corresponding object:\n    - `type: \"expression\"` requires the `expression` object\n    - `type: \"script\"` requires the `script` object\n","enum":["expression","script"]},"expression":{"type":"object","description":"Configuration for declarative rule-based filtering. This object enables filtering\nitems based on common attributes without requiring custom code.\n\n**Usage context**\n\nThis object is REQUIRED when `filter.type` is set to \"expression\" and should not be\nconfigured otherwise. It provides a standardized way to define filtering rules that\ncan match against item attributes like name, type, value, date, and other properties.\n\n**Implementation guidance**\n\nThe expression system uses a rule-based approach where:\n- Rules can be combined with AND/OR logic\n- Each rule can check a specific attribute\n- Multiple conditions can be applied (ranges, pattern matching, exact matches)\n\n**Common filter patterns**\n\n1. **Pattern matching**: Using wildcards like `*` and `?`\n2. **Value range filtering**: Numbers between min and max values\n3. **Date range filtering**: Items created/modified within specific time ranges\n4. **Status checking**: Items with specific status values or properties\n\nFor AI agents: Rule-based filtering should be your first choice when the filtering criteria\ncan be expressed in terms of standard attributes. Only use script-based filtering when\nmore complex logic is required.\n","properties":{"version":{"type":"string","description":"Version identifier for the expression format. Currently only version \"1\" is supported.\n\nThis field ensures future compatibility if the expression format evolves. Always set to \"1\"\nfor current implementations.\n","enum":["1"]},"rules":{"type":"array","description":"Expression array defining filter conditions using prefix notation. The first element is the operator,\nfollowed by its operands which may themselves be nested expression arrays.\n\nThe rule expression follows this pattern:\n- First element: Operator name (string)\n- Remaining elements: Operands for that operator (values or nested expressions)\n\n**Expression structure**\n\nFilter expressions use a prefix notation where operators appear before their operands:\n```\n[operator, operand1, operand2, ...]\n```\n\n**Comparison Operators**\n- `\"equals\"`: Exact match (equals)\n- `\"notequals\"`: Not equal to value (not equals)\n- `\"greaterthan\"`: Value is greater than specified value (is greater than)\n- `\"greaterthanequals\"`: Value is greater than or equal to specified value (is greater than or equals)\n- `\"lessthan\"`: Value is less than specified value (is less than)\n- `\"lessthanequals\"`: Value is less than or equal to specified value (is less than or equals)\n- `\"startswith\"`: String starts with specified prefix (starts with)\n- `\"endswith\"`: String ends with specified suffix (ends with)\n- `\"contains\"`: String contains specified substring (contains)\n- `\"doesnotcontain\"`: String does not contain specified substring (does not contain)\n- `\"isempty\"`: Field is empty or null (is empty)\n- `\"isnotempty\"`: Field contains a value (is not empty)\n- `\"matches\"`: Matches specified pattern (matches)\n\n**Logical Operators**\n- `\"and\"`: All conditions must be true\n- `\"or\"`: At least one condition must be true\n- `\"not\"`: Negates the condition\n\n**Field Access and Type Conversion**\n- `\"extract\"`: Access a field from the item by name\n- `\"settings\"`: Access a custom setting from the flow, flow step, or integration configuration\n- `\"boolean\"`: Convert value to Boolean type\n- `\"epochtime\"`: Convert value to Epoch Time (Unix timestamp)\n- `\"number\"`: Convert value to Number type\n- `\"string\"`: Convert value to String type\n\n**Field Access Details**\n\n**Using `extract` to access record fields:**\n- Retrieves values from the current record being processed\n- Can access nested properties using dot notation (e.g., `\"customer.email\"`)\n- Returns the raw field value which may need type conversion\n\n**Using `settings` to access configuration values:**\n- Retrieves values from the integration's configuration settings\n- Supports different scopes with prefix notation:\n  - `flow.settingName`: Access flow-level settings\n  - `export.settingName`: Access export-level settings\n  - `import.settingName`: Access import-level settings\n  - `integration.settingName`: Access integration-level settings\n- Useful for dynamic filtering based on configuration\n\n**Field Transformations**\n- `\"lowercase\"`: Convert string to lowercase\n- `\"uppercase\"`: Convert string to uppercase\n- `\"ceiling\"`: Round number up to the nearest integer\n- `\"floor\"`: Round number down to the nearest integer\n- `\"abs\"`: Get absolute value of a number\n\nType conversion operators are often necessary when comparing extracted field values against literals or when the field type doesn't match the comparison operator's expected type. For example:\n\n```json\n[\n  \"equals\",\n  [\n    \"number\",  // Convert to number before comparison\n    [\n      \"extract\",\n      \"quantity\"\n    ]\n  ],\n  100\n]\n```\n\nExample with datetime conversion:\n```json\n[\n  \"greaterthan\",\n  [\n    \"epochtime\",  // Convert to Unix timestamp before comparison\n    [\n      \"extract\",\n      \"createdDate\"\n    ]\n  ],\n  1609459200000  // January 1, 2021 as Unix timestamp in milliseconds\n]\n```\n\nExample with transformations:\n```json\n[\n  \"and\",\n  [\n    \"matches\",\n    [\n      \"lowercase\",  // Convert to lowercase before matching\n      [\n        \"string\",\n        [\n          \"extract\",\n          \"categories\"\n        ]\n      ]\n    ],\n    \"netsuite\"\n  ],\n  [\n    \"notequals\",\n    [\n      \"string\",\n      [\n        \"extract\",\n        \"recurrence.pattern.type\"\n      ]\n    ],\n    \"\"\n  ]\n]\n```\n\nExample comparing a record field with a flow setting:\n```json\n[\n  \"equals\",\n  [\n    \"string\",\n    [\n      \"extract\",\n      \"trantype\"\n    ]\n  ],\n  [\n    \"string\",\n    [\n      \"settings\",\n      \"flow.trantype\"\n    ]\n  ]\n]\n```\n\n**Examples**\n\nExample 1: Status field is not equal to \"cancelled\"\n```json\n[\n  \"notequals\",\n  [\n    \"extract\",\n    \"status\"\n  ],\n  \"cancelled\"\n]\n```\n\nExample 2: Filename starts with \"HC\"\n```json\n[\n  \"startswith\",\n  [\n    \"extract\",\n    \"filename\"\n  ],\n  \"HC\"\n]\n```\n\nExample 3: Amount is greater than 100\n```json\n[\n  \"greaterthan\",\n  [\n    \"number\",\n    [\n      \"extract\",\n      \"amount\"\n    ]\n  ],\n  100\n]\n```\n\nExample 4: Order date is after January 1, 2023\n```json\n[\n  \"greaterthan\",\n  [\n    \"extract\",\n    \"orderDate\"\n  ],\n  \"2023-01-01T00:00:00Z\"\n]\n```\n\nExample 5: Category contains any of [\"Urgent\", \"High Priority\"]\n```json\n[\n  \"anyof\",\n  [\n    \"extract\",\n    \"category\"\n  ],\n  [\"Urgent\", \"High Priority\"]\n]\n```\n","items":{"oneOf":[{"title":"String","type":"string"},{"title":"Number","type":"number"},{"title":"Boolean","type":"boolean"},{"title":"Object","type":"object"},{"title":"Array","type":"array"}]}}}},"script":{"type":"object","description":"Configuration for programmable script-based filtering. This object enables complex, custom\nfiltering logic beyond what expression-based filtering can provide.\n\n**Usage context**\n\nThis object is REQUIRED when `filter.type` is set to \"script\" and should not be configured\notherwise. It provides a way to execute custom JavaScript code to determine which items\nshould be processed.\n\n**Implementation approach**\n\nScript-based filtering works by:\n1. Executing the specified function from the referenced script\n2. Passing item data to the function\n3. Using the function's return value (true/false) to determine inclusion\n\n**Common use cases**\n\nScript filtering is ideal for:\n- Complex business logic that can't be expressed as simple rules\n- Dynamic filtering criteria that change based on external factors\n- Content-based filtering that requires deep inspection\n- Advanced pattern matching beyond simple wildcards\n- Multi-stage filtering with intermediate logic\n\nFor AI agents: Only use script-based filtering when expression-based filtering is insufficient.\nScript filtering requires maintaining custom code, which adds complexity to the integration.\n","properties":{"_scriptId":{"type":"string","description":"Reference to the Script resource that contains the filtering logic. This must be a valid\nObjectId of a Script resource that exists in the system.\n\nThe referenced script must contain the function specified in the `function` field\nand must be written to handle filtering specifically. The script receives\nitem data as its input and must return a boolean value indicating whether\nto process the item (true) or skip it (false).\n\nFormat: 24-character hexadecimal string (MongoDB ObjectId)\n"},"function":{"type":"string","description":"Name of the function within the script to execute for filtering decisions. This function\nmust exist in the script referenced by _scriptId.\n\n**Function requirements**\n\nThe specified function must:\n- Accept item data as its first parameter\n- Return a boolean value (true to process the item, false to skip it)\n- Handle errors gracefully\n- Execute efficiently (as it may run for many items)\n\n**Function signature**\n\n```javascript\nfunction filterItems(itemData) {\n  // itemData contains properties of the item being evaluated\n  // Custom logic here\n  return true; // or false to skip the item\n}\n```\n\nFor AI agents: Ensure the function name exactly matches a function defined in the\nreferenced script, as mismatches will cause the filter to fail.\n"}}}}},"PreConfiguredField":{"type":"object","description":"A field that is automatically set to a predefined value during trading partner\nonboarding. The `path` identifies which field on the target resource to set,\nand `values` provides the value(s) to assign.\n","properties":{"path":{"type":"string","description":"Dot-notation path of the field on the target resource to set.\n"},"values":{"type":"array","description":"Value(s) to assign to the field. Typically a single-element array.\n","items":{"oneOf":[{"title":"String","type":"string"},{"title":"Number","type":"number"},{"title":"Boolean","type":"boolean"},{"title":"Object","type":"object"}]}},"_conditionIds":{"type":"array","description":"References to condition IDs that must be satisfied for this field to apply.\nIf empty or absent, the field always applies.\n","items":{"type":"string","format":"objectId"}}}},"FieldUserMustSet":{"type":"object","description":"A field that the user must provide a value for during trading partner onboarding.\n","properties":{"path":{"type":"string","description":"Dot-notation path of the field on the target resource that the user must set.\n"},"values":{"type":"array","description":"Optional suggested or constrained values for the field.\n","items":{"oneOf":[{"title":"String","type":"string"},{"title":"Number","type":"number"},{"title":"Boolean","type":"boolean"},{"title":"Object","type":"object"}]}},"_conditionIds":{"type":"array","description":"References to condition IDs that must be satisfied for this field to apply.\n","items":{"type":"string","format":"objectId"}},"helpURL":{"type":"string","description":"URL to documentation for this field"},"labelOverride":{"type":"string","description":"Custom label to display for this field in the UI instead of the default"}}},"ConnectionSupportedBySection":{"type":"object","description":"The `supportedBy.connection` section. Identical to other supportedBy sections\nbut `fieldsUserMustSet` entries may include an `inputType` to control the\nUI input widget type.\n","properties":{"conditions":{"type":"array","description":"Array of condition objects for the connection section.\n","items":{"type":"object","properties":{"_id":{"type":"string","format":"objectId","description":"Unique identifier for this condition"},"condition":{"$ref":"#/components/schemas/Filter"}}}},"preConfiguredFields":{"type":"array","description":"Fields automatically set on the connection during trading partner onboarding.\n","items":{"$ref":"#/components/schemas/PreConfiguredField"}},"fieldsUserMustSet":{"type":"array","description":"Fields the user must provide for the connection. May include `inputType`\nto control the UI input widget.\n","items":{"$ref":"#/components/schemas/ConnectionFieldUserMustSet"}}}},"ConnectionFieldUserMustSet":{"type":"object","description":"A field that the user must provide a value for on the connection during\ntrading partner onboarding. Extends the base field with an `inputType`\nproperty to control the UI input widget.\n","properties":{"inputType":{"type":"string","enum":["number","password","uri"],"description":"The type of input widget to render in the UI for this field.\nOnly applicable to connection fields.\n"},"path":{"type":"string","description":"Dot-notation path of the field on the connection that the user must set.\n"},"values":{"type":"array","description":"Optional suggested or constrained values for the field.\n","items":{"oneOf":[{"title":"String","type":"string"},{"title":"Number","type":"number"},{"title":"Boolean","type":"boolean"},{"title":"Object","type":"object"}]}},"_conditionIds":{"type":"array","description":"References to condition IDs that must be satisfied for this field to apply.\n","items":{"type":"string","format":"objectId"}},"helpURL":{"type":"string","description":"URL to documentation for this field"},"labelOverride":{"type":"string","description":"Custom label to display for this field in the UI"}}}},"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/tpconnectors":{"get":{"summary":"List trading partner connectors","description":"Returns a list of all trading partner connectors.\nSupports filtering to only return published connectors via the `publishedOnly` query parameter.\nIf no connectors exist, a 204 response with no body will be returned.\n","operationId":"listTradingPartnerConnectors","tags":["Trading Partner Connectors"],"parameters":[{"name":"publishedOnly","in":"query","description":"When set to \"true\", only published connectors are returned.\n","required":false,"schema":{"type":"string","enum":["true","false"]}},{"$ref":"#/components/parameters/Include"},{"$ref":"#/components/parameters/Exclude"}],"responses":{"200":{"description":"Successfully retrieved list of trading partner connectors","headers":{"Link":{"description":"RFC-5988 pagination links. When more pages remain, includes a `<...>; rel=\"next\"` entry;\nabsent on the final page.\n","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Response"}}}}},"204":{"description":"No trading partner connectors exist"},"401":{"$ref":"#/components/responses/401-unauthorized"}}}}}}
````

## Create a trading partner connector

> Creates a new trading partner connector that defines reusable templates\
> for onboarding EDI trading partners.\
> \
> The \`published\` flag can only be set by users with the\
> \`allowedToPublishTPConnectors\` permission. Published connector names\
> must be unique across all published connectors.<br>

````json
{"openapi":"3.1.0","info":{"title":"Trading Partner Connectors","version":"1.0.0"},"servers":[{"url":"https://api.integrator.io","description":"Production (US / default region)"},{"url":"https://api.eu.integrator.io","description":"Production (EU region)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"Request":{"type":"object","description":"Request schema for creating or updating a trading partner connector.\n\nTrading partner connectors define reusable templates for onboarding EDI trading\npartners. They specify which fields are pre-configured and which fields the user\nmust provide for connections, exports, imports, and EDI profiles.\n\nWhen `published` is true, the connector's `supportedBy` sections are validated\nto ensure all required fields are present. For example:\n- Connection must have a pre-configured `type` field (either \"ftp\" or \"as2\")\n- Export/import must have a pre-configured `file.type` set to \"filedefinition\"\n- EDI profile must have the appropriate mandatory fields for x12 or edifact\n","properties":{"name":{"type":"string","description":"Name of the trading partner connector. Must be unique across all published\nconnectors. Used to identify the connector during trading partner onboarding.\n"},"published":{"type":"boolean","default":false,"description":"Whether this connector is published and available for use across the platform.\n\nOnly users with the `allowedToPublishTPConnectors` permission can set this\nto true. When publishing, all `supportedBy` sections are validated to ensure\nrequired fields are present. Published connector names must be unique.\n"},"helpURL":{"type":"string","description":"URL to documentation for this trading partner connector.\n"},"supportedBy":{"type":"object","description":"Defines the field configurations for each resource type involved in trading\npartner onboarding. Each section specifies conditions, pre-configured fields,\nand fields the user must set.\n","properties":{"ediProfile":{"$ref":"#/components/schemas/SupportedBySection"},"export":{"$ref":"#/components/schemas/SupportedBySection"},"import":{"$ref":"#/components/schemas/SupportedBySection"},"connection":{"$ref":"#/components/schemas/ConnectionSupportedBySection"}}}},"required":["name"]},"SupportedBySection":{"type":"object","description":"A section within `supportedBy` that defines conditions, pre-configured field values,\nand fields the user must set when creating a trading partner resource (connection,\nexport, import, or EDI profile).\n\nConditions use expression-based filters to control which field configurations apply\nbased on resource attributes. Pre-configured fields are automatically set, while\nfields the user must set require input during trading partner onboarding.\n","properties":{"conditions":{"type":"array","description":"Array of condition objects. Each condition contains an expression-based filter\nthat can be referenced by `_conditionIds` in `preConfiguredFields` and\n`fieldsUserMustSet` to conditionally apply those field configurations.\n","items":{"type":"object","properties":{"_id":{"type":"string","format":"objectId","description":"Unique identifier for this condition, referenced by `_conditionIds` in field entries"},"condition":{"$ref":"#/components/schemas/Filter"}}}},"preConfiguredFields":{"type":"array","description":"Array of fields that are automatically set to predefined values when creating\na trading partner resource using this connector. These fields are not editable\nby the user during onboarding.\n","items":{"$ref":"#/components/schemas/PreConfiguredField"}},"fieldsUserMustSet":{"type":"array","description":"Array of fields that the user must provide values for during trading partner\nonboarding. These fields may have suggested values or constraints.\n","items":{"$ref":"#/components/schemas/FieldUserMustSet"}}}},"Filter":{"type":"object","description":"Configuration for selectively processing records based on specified criteria. This object enables\nprecise control over which items are included or excluded from processing operations.\n\n**Filter behavior**\n\nWhen configured, the filter is applied before processing begins:\n- Items that match the filter criteria are processed\n- Items that don't match are completely skipped\n- No partial processing is performed\n\n**Implementation approaches**\n\nThere are two distinct filtering mechanisms available:\n\n**Rule-Based Filtering (`type: \"expression\"`)**\n- **Best For**: Common filtering patterns based on standard attributes\n- **Capabilities**: Filter by names, values, dates, numerical ranges, text patterns\n- **Advantages**: Declarative, no coding required, consistent performance\n- **Configuration**: Define rules in the `expression` object\n- **Use When**: You have clear, static criteria for selection\n\n**Script-Based Filtering (`type: \"script\"`)**\n- **Best For**: Complex logic, dynamic criteria, or business rules\n- **Capabilities**: Full programmatic control, access to complete metadata\n- **Advantages**: Maximum flexibility, can implement any filtering logic\n- **Configuration**: Reference a script in the `script` object\n- **Use When**: Simple rules aren't sufficient or logic needs to be dynamic\n","properties":{"type":{"type":"string","description":"Determines which filtering mechanism to use. This choice affects which properties\nmust be configured and how filtering logic is implemented.\n\n**Available types**\n\n**Rule-Based Filtering (`\"expression\"`)**\n- **Required Config**: The `expression` object with rule definitions\n- **Behavior**: Evaluates declarative rules against item attributes\n- **Best For**: Common patterns like name matching, date ranges, value limits\n- **Advantages**: Simpler to configure, no custom code required\n\n**Script-Based Filtering (`\"script\"`)**\n- **Required Config**: The `script` object with _scriptId and function\n- **Behavior**: Executes custom JavaScript to determine which items to process\n- **Best For**: Complex conditions, business logic, dynamic criteria\n- **Advantages**: Maximum flexibility, can implement any logic\n\n**Implementation guidance**\n\n1. For standard filtering needs (name, size, date), use `\"expression\"`\n2. For complex logic or conditions not covered by expressions, use `\"script\"`\n3. When selecting a type, you must configure the corresponding object:\n    - `type: \"expression\"` requires the `expression` object\n    - `type: \"script\"` requires the `script` object\n","enum":["expression","script"]},"expression":{"type":"object","description":"Configuration for declarative rule-based filtering. This object enables filtering\nitems based on common attributes without requiring custom code.\n\n**Usage context**\n\nThis object is REQUIRED when `filter.type` is set to \"expression\" and should not be\nconfigured otherwise. It provides a standardized way to define filtering rules that\ncan match against item attributes like name, type, value, date, and other properties.\n\n**Implementation guidance**\n\nThe expression system uses a rule-based approach where:\n- Rules can be combined with AND/OR logic\n- Each rule can check a specific attribute\n- Multiple conditions can be applied (ranges, pattern matching, exact matches)\n\n**Common filter patterns**\n\n1. **Pattern matching**: Using wildcards like `*` and `?`\n2. **Value range filtering**: Numbers between min and max values\n3. **Date range filtering**: Items created/modified within specific time ranges\n4. **Status checking**: Items with specific status values or properties\n\nFor AI agents: Rule-based filtering should be your first choice when the filtering criteria\ncan be expressed in terms of standard attributes. Only use script-based filtering when\nmore complex logic is required.\n","properties":{"version":{"type":"string","description":"Version identifier for the expression format. Currently only version \"1\" is supported.\n\nThis field ensures future compatibility if the expression format evolves. Always set to \"1\"\nfor current implementations.\n","enum":["1"]},"rules":{"type":"array","description":"Expression array defining filter conditions using prefix notation. The first element is the operator,\nfollowed by its operands which may themselves be nested expression arrays.\n\nThe rule expression follows this pattern:\n- First element: Operator name (string)\n- Remaining elements: Operands for that operator (values or nested expressions)\n\n**Expression structure**\n\nFilter expressions use a prefix notation where operators appear before their operands:\n```\n[operator, operand1, operand2, ...]\n```\n\n**Comparison Operators**\n- `\"equals\"`: Exact match (equals)\n- `\"notequals\"`: Not equal to value (not equals)\n- `\"greaterthan\"`: Value is greater than specified value (is greater than)\n- `\"greaterthanequals\"`: Value is greater than or equal to specified value (is greater than or equals)\n- `\"lessthan\"`: Value is less than specified value (is less than)\n- `\"lessthanequals\"`: Value is less than or equal to specified value (is less than or equals)\n- `\"startswith\"`: String starts with specified prefix (starts with)\n- `\"endswith\"`: String ends with specified suffix (ends with)\n- `\"contains\"`: String contains specified substring (contains)\n- `\"doesnotcontain\"`: String does not contain specified substring (does not contain)\n- `\"isempty\"`: Field is empty or null (is empty)\n- `\"isnotempty\"`: Field contains a value (is not empty)\n- `\"matches\"`: Matches specified pattern (matches)\n\n**Logical Operators**\n- `\"and\"`: All conditions must be true\n- `\"or\"`: At least one condition must be true\n- `\"not\"`: Negates the condition\n\n**Field Access and Type Conversion**\n- `\"extract\"`: Access a field from the item by name\n- `\"settings\"`: Access a custom setting from the flow, flow step, or integration configuration\n- `\"boolean\"`: Convert value to Boolean type\n- `\"epochtime\"`: Convert value to Epoch Time (Unix timestamp)\n- `\"number\"`: Convert value to Number type\n- `\"string\"`: Convert value to String type\n\n**Field Access Details**\n\n**Using `extract` to access record fields:**\n- Retrieves values from the current record being processed\n- Can access nested properties using dot notation (e.g., `\"customer.email\"`)\n- Returns the raw field value which may need type conversion\n\n**Using `settings` to access configuration values:**\n- Retrieves values from the integration's configuration settings\n- Supports different scopes with prefix notation:\n  - `flow.settingName`: Access flow-level settings\n  - `export.settingName`: Access export-level settings\n  - `import.settingName`: Access import-level settings\n  - `integration.settingName`: Access integration-level settings\n- Useful for dynamic filtering based on configuration\n\n**Field Transformations**\n- `\"lowercase\"`: Convert string to lowercase\n- `\"uppercase\"`: Convert string to uppercase\n- `\"ceiling\"`: Round number up to the nearest integer\n- `\"floor\"`: Round number down to the nearest integer\n- `\"abs\"`: Get absolute value of a number\n\nType conversion operators are often necessary when comparing extracted field values against literals or when the field type doesn't match the comparison operator's expected type. For example:\n\n```json\n[\n  \"equals\",\n  [\n    \"number\",  // Convert to number before comparison\n    [\n      \"extract\",\n      \"quantity\"\n    ]\n  ],\n  100\n]\n```\n\nExample with datetime conversion:\n```json\n[\n  \"greaterthan\",\n  [\n    \"epochtime\",  // Convert to Unix timestamp before comparison\n    [\n      \"extract\",\n      \"createdDate\"\n    ]\n  ],\n  1609459200000  // January 1, 2021 as Unix timestamp in milliseconds\n]\n```\n\nExample with transformations:\n```json\n[\n  \"and\",\n  [\n    \"matches\",\n    [\n      \"lowercase\",  // Convert to lowercase before matching\n      [\n        \"string\",\n        [\n          \"extract\",\n          \"categories\"\n        ]\n      ]\n    ],\n    \"netsuite\"\n  ],\n  [\n    \"notequals\",\n    [\n      \"string\",\n      [\n        \"extract\",\n        \"recurrence.pattern.type\"\n      ]\n    ],\n    \"\"\n  ]\n]\n```\n\nExample comparing a record field with a flow setting:\n```json\n[\n  \"equals\",\n  [\n    \"string\",\n    [\n      \"extract\",\n      \"trantype\"\n    ]\n  ],\n  [\n    \"string\",\n    [\n      \"settings\",\n      \"flow.trantype\"\n    ]\n  ]\n]\n```\n\n**Examples**\n\nExample 1: Status field is not equal to \"cancelled\"\n```json\n[\n  \"notequals\",\n  [\n    \"extract\",\n    \"status\"\n  ],\n  \"cancelled\"\n]\n```\n\nExample 2: Filename starts with \"HC\"\n```json\n[\n  \"startswith\",\n  [\n    \"extract\",\n    \"filename\"\n  ],\n  \"HC\"\n]\n```\n\nExample 3: Amount is greater than 100\n```json\n[\n  \"greaterthan\",\n  [\n    \"number\",\n    [\n      \"extract\",\n      \"amount\"\n    ]\n  ],\n  100\n]\n```\n\nExample 4: Order date is after January 1, 2023\n```json\n[\n  \"greaterthan\",\n  [\n    \"extract\",\n    \"orderDate\"\n  ],\n  \"2023-01-01T00:00:00Z\"\n]\n```\n\nExample 5: Category contains any of [\"Urgent\", \"High Priority\"]\n```json\n[\n  \"anyof\",\n  [\n    \"extract\",\n    \"category\"\n  ],\n  [\"Urgent\", \"High Priority\"]\n]\n```\n","items":{"oneOf":[{"title":"String","type":"string"},{"title":"Number","type":"number"},{"title":"Boolean","type":"boolean"},{"title":"Object","type":"object"},{"title":"Array","type":"array"}]}}}},"script":{"type":"object","description":"Configuration for programmable script-based filtering. This object enables complex, custom\nfiltering logic beyond what expression-based filtering can provide.\n\n**Usage context**\n\nThis object is REQUIRED when `filter.type` is set to \"script\" and should not be configured\notherwise. It provides a way to execute custom JavaScript code to determine which items\nshould be processed.\n\n**Implementation approach**\n\nScript-based filtering works by:\n1. Executing the specified function from the referenced script\n2. Passing item data to the function\n3. Using the function's return value (true/false) to determine inclusion\n\n**Common use cases**\n\nScript filtering is ideal for:\n- Complex business logic that can't be expressed as simple rules\n- Dynamic filtering criteria that change based on external factors\n- Content-based filtering that requires deep inspection\n- Advanced pattern matching beyond simple wildcards\n- Multi-stage filtering with intermediate logic\n\nFor AI agents: Only use script-based filtering when expression-based filtering is insufficient.\nScript filtering requires maintaining custom code, which adds complexity to the integration.\n","properties":{"_scriptId":{"type":"string","description":"Reference to the Script resource that contains the filtering logic. This must be a valid\nObjectId of a Script resource that exists in the system.\n\nThe referenced script must contain the function specified in the `function` field\nand must be written to handle filtering specifically. The script receives\nitem data as its input and must return a boolean value indicating whether\nto process the item (true) or skip it (false).\n\nFormat: 24-character hexadecimal string (MongoDB ObjectId)\n"},"function":{"type":"string","description":"Name of the function within the script to execute for filtering decisions. This function\nmust exist in the script referenced by _scriptId.\n\n**Function requirements**\n\nThe specified function must:\n- Accept item data as its first parameter\n- Return a boolean value (true to process the item, false to skip it)\n- Handle errors gracefully\n- Execute efficiently (as it may run for many items)\n\n**Function signature**\n\n```javascript\nfunction filterItems(itemData) {\n  // itemData contains properties of the item being evaluated\n  // Custom logic here\n  return true; // or false to skip the item\n}\n```\n\nFor AI agents: Ensure the function name exactly matches a function defined in the\nreferenced script, as mismatches will cause the filter to fail.\n"}}}}},"PreConfiguredField":{"type":"object","description":"A field that is automatically set to a predefined value during trading partner\nonboarding. The `path` identifies which field on the target resource to set,\nand `values` provides the value(s) to assign.\n","properties":{"path":{"type":"string","description":"Dot-notation path of the field on the target resource to set.\n"},"values":{"type":"array","description":"Value(s) to assign to the field. Typically a single-element array.\n","items":{"oneOf":[{"title":"String","type":"string"},{"title":"Number","type":"number"},{"title":"Boolean","type":"boolean"},{"title":"Object","type":"object"}]}},"_conditionIds":{"type":"array","description":"References to condition IDs that must be satisfied for this field to apply.\nIf empty or absent, the field always applies.\n","items":{"type":"string","format":"objectId"}}}},"FieldUserMustSet":{"type":"object","description":"A field that the user must provide a value for during trading partner onboarding.\n","properties":{"path":{"type":"string","description":"Dot-notation path of the field on the target resource that the user must set.\n"},"values":{"type":"array","description":"Optional suggested or constrained values for the field.\n","items":{"oneOf":[{"title":"String","type":"string"},{"title":"Number","type":"number"},{"title":"Boolean","type":"boolean"},{"title":"Object","type":"object"}]}},"_conditionIds":{"type":"array","description":"References to condition IDs that must be satisfied for this field to apply.\n","items":{"type":"string","format":"objectId"}},"helpURL":{"type":"string","description":"URL to documentation for this field"},"labelOverride":{"type":"string","description":"Custom label to display for this field in the UI instead of the default"}}},"ConnectionSupportedBySection":{"type":"object","description":"The `supportedBy.connection` section. Identical to other supportedBy sections\nbut `fieldsUserMustSet` entries may include an `inputType` to control the\nUI input widget type.\n","properties":{"conditions":{"type":"array","description":"Array of condition objects for the connection section.\n","items":{"type":"object","properties":{"_id":{"type":"string","format":"objectId","description":"Unique identifier for this condition"},"condition":{"$ref":"#/components/schemas/Filter"}}}},"preConfiguredFields":{"type":"array","description":"Fields automatically set on the connection during trading partner onboarding.\n","items":{"$ref":"#/components/schemas/PreConfiguredField"}},"fieldsUserMustSet":{"type":"array","description":"Fields the user must provide for the connection. May include `inputType`\nto control the UI input widget.\n","items":{"$ref":"#/components/schemas/ConnectionFieldUserMustSet"}}}},"ConnectionFieldUserMustSet":{"type":"object","description":"A field that the user must provide a value for on the connection during\ntrading partner onboarding. Extends the base field with an `inputType`\nproperty to control the UI input widget.\n","properties":{"inputType":{"type":"string","enum":["number","password","uri"],"description":"The type of input widget to render in the UI for this field.\nOnly applicable to connection fields.\n"},"path":{"type":"string","description":"Dot-notation path of the field on the connection that the user must set.\n"},"values":{"type":"array","description":"Optional suggested or constrained values for the field.\n","items":{"oneOf":[{"title":"String","type":"string"},{"title":"Number","type":"number"},{"title":"Boolean","type":"boolean"},{"title":"Object","type":"object"}]}},"_conditionIds":{"type":"array","description":"References to condition IDs that must be satisfied for this field to apply.\n","items":{"type":"string","format":"objectId"}},"helpURL":{"type":"string","description":"URL to documentation for this field"},"labelOverride":{"type":"string","description":"Custom label to display for this field in the UI"}}},"Response":{"type":"object","description":"Response schema for trading partner connector operations.\n\nContains the complete connector configuration including metadata and all\nsupportedBy sections with conditions, pre-configured fields, and fields\nthe user must set.\n","allOf":[{"$ref":"#/components/schemas/Request"},{"type":"object","properties":{"_id":{"type":"string","format":"objectId","readOnly":true,"description":"Unique identifier for the trading partner connector"},"createdAt":{"type":"string","format":"date-time","readOnly":true,"description":"Timestamp when the connector was created"},"lastModified":{"type":"string","format":"date-time","readOnly":true,"description":"Timestamp when the connector was last modified"},"_userId":{"type":"string","format":"objectId","description":"User who owns or created this trading partner connector"}}}]},"Error":{"type":"object","description":"Standard error response envelope returned by integrator.io APIs.","properties":{"errors":{"type":"array","description":"List of errors that occurred while processing the request.","items":{"type":"object","properties":{"code":{"oneOf":[{"type":"string"},{"type":"integer"}],"description":"Machine-readable error code. Usually a string like\n`invalid_ref`, `missing_required_field`, or `unauthorized`;\nmay be an **integer** when the error mirrors an upstream HTTP\nstatus (e.g. `500`) — most commonly returned by connection-ping\nand adaptor-proxy responses."},"message":{"type":"string","description":"Human-readable description of the error."},"field":{"type":"string","description":"Optional pointer to the document field that caused the error.\nUsed by structural validation errors (`missing_required_field`,\n`invalid_ref`) to indicate which field is at fault\n(e.g. `_id`, `type`, `http.baseURI`)."},"source":{"type":"string","description":"Optional origin layer for the error — e.g. `application` when\nthe error came from the remote system the adaptor called,\n`connector` when the adaptor itself rejected the request."}},"required":["message"]}}},"required":["errors"]}},"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"]}}}},"422-unprocessable-entity":{"description":"Unprocessable entity. The request was well-formed but was unable to be followed due to semantic errors.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/v1/tpconnectors":{"post":{"summary":"Create a trading partner connector","description":"Creates a new trading partner connector that defines reusable templates\nfor onboarding EDI trading partners.\n\nThe `published` flag can only be set by users with the\n`allowedToPublishTPConnectors` permission. Published connector names\nmust be unique across all published connectors.\n","operationId":"createTradingPartnerConnector","tags":["Trading Partner Connectors"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Request"}}}},"responses":{"201":{"description":"Trading partner connector created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Response"}}}},"401":{"$ref":"#/components/responses/401-unauthorized"},"422":{"$ref":"#/components/responses/422-unprocessable-entity"}}}}}}
````

## Get a trading partner connector

> Returns the complete configuration of a specific trading partner connector,\
> including all supportedBy sections with conditions, pre-configured fields,\
> and fields the user must set.\
> \
> For the dedicated list/get endpoints, only published connectors are returned\
> unless the requesting user owns the connector.<br>

````json
{"openapi":"3.1.0","info":{"title":"Trading Partner Connectors","version":"1.0.0"},"servers":[{"url":"https://api.integrator.io","description":"Production (US / default region)"},{"url":"https://api.eu.integrator.io","description":"Production (EU region)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"Response":{"type":"object","description":"Response schema for trading partner connector operations.\n\nContains the complete connector configuration including metadata and all\nsupportedBy sections with conditions, pre-configured fields, and fields\nthe user must set.\n","allOf":[{"$ref":"#/components/schemas/Request"},{"type":"object","properties":{"_id":{"type":"string","format":"objectId","readOnly":true,"description":"Unique identifier for the trading partner connector"},"createdAt":{"type":"string","format":"date-time","readOnly":true,"description":"Timestamp when the connector was created"},"lastModified":{"type":"string","format":"date-time","readOnly":true,"description":"Timestamp when the connector was last modified"},"_userId":{"type":"string","format":"objectId","description":"User who owns or created this trading partner connector"}}}]},"Request":{"type":"object","description":"Request schema for creating or updating a trading partner connector.\n\nTrading partner connectors define reusable templates for onboarding EDI trading\npartners. They specify which fields are pre-configured and which fields the user\nmust provide for connections, exports, imports, and EDI profiles.\n\nWhen `published` is true, the connector's `supportedBy` sections are validated\nto ensure all required fields are present. For example:\n- Connection must have a pre-configured `type` field (either \"ftp\" or \"as2\")\n- Export/import must have a pre-configured `file.type` set to \"filedefinition\"\n- EDI profile must have the appropriate mandatory fields for x12 or edifact\n","properties":{"name":{"type":"string","description":"Name of the trading partner connector. Must be unique across all published\nconnectors. Used to identify the connector during trading partner onboarding.\n"},"published":{"type":"boolean","default":false,"description":"Whether this connector is published and available for use across the platform.\n\nOnly users with the `allowedToPublishTPConnectors` permission can set this\nto true. When publishing, all `supportedBy` sections are validated to ensure\nrequired fields are present. Published connector names must be unique.\n"},"helpURL":{"type":"string","description":"URL to documentation for this trading partner connector.\n"},"supportedBy":{"type":"object","description":"Defines the field configurations for each resource type involved in trading\npartner onboarding. Each section specifies conditions, pre-configured fields,\nand fields the user must set.\n","properties":{"ediProfile":{"$ref":"#/components/schemas/SupportedBySection"},"export":{"$ref":"#/components/schemas/SupportedBySection"},"import":{"$ref":"#/components/schemas/SupportedBySection"},"connection":{"$ref":"#/components/schemas/ConnectionSupportedBySection"}}}},"required":["name"]},"SupportedBySection":{"type":"object","description":"A section within `supportedBy` that defines conditions, pre-configured field values,\nand fields the user must set when creating a trading partner resource (connection,\nexport, import, or EDI profile).\n\nConditions use expression-based filters to control which field configurations apply\nbased on resource attributes. Pre-configured fields are automatically set, while\nfields the user must set require input during trading partner onboarding.\n","properties":{"conditions":{"type":"array","description":"Array of condition objects. Each condition contains an expression-based filter\nthat can be referenced by `_conditionIds` in `preConfiguredFields` and\n`fieldsUserMustSet` to conditionally apply those field configurations.\n","items":{"type":"object","properties":{"_id":{"type":"string","format":"objectId","description":"Unique identifier for this condition, referenced by `_conditionIds` in field entries"},"condition":{"$ref":"#/components/schemas/Filter"}}}},"preConfiguredFields":{"type":"array","description":"Array of fields that are automatically set to predefined values when creating\na trading partner resource using this connector. These fields are not editable\nby the user during onboarding.\n","items":{"$ref":"#/components/schemas/PreConfiguredField"}},"fieldsUserMustSet":{"type":"array","description":"Array of fields that the user must provide values for during trading partner\nonboarding. These fields may have suggested values or constraints.\n","items":{"$ref":"#/components/schemas/FieldUserMustSet"}}}},"Filter":{"type":"object","description":"Configuration for selectively processing records based on specified criteria. This object enables\nprecise control over which items are included or excluded from processing operations.\n\n**Filter behavior**\n\nWhen configured, the filter is applied before processing begins:\n- Items that match the filter criteria are processed\n- Items that don't match are completely skipped\n- No partial processing is performed\n\n**Implementation approaches**\n\nThere are two distinct filtering mechanisms available:\n\n**Rule-Based Filtering (`type: \"expression\"`)**\n- **Best For**: Common filtering patterns based on standard attributes\n- **Capabilities**: Filter by names, values, dates, numerical ranges, text patterns\n- **Advantages**: Declarative, no coding required, consistent performance\n- **Configuration**: Define rules in the `expression` object\n- **Use When**: You have clear, static criteria for selection\n\n**Script-Based Filtering (`type: \"script\"`)**\n- **Best For**: Complex logic, dynamic criteria, or business rules\n- **Capabilities**: Full programmatic control, access to complete metadata\n- **Advantages**: Maximum flexibility, can implement any filtering logic\n- **Configuration**: Reference a script in the `script` object\n- **Use When**: Simple rules aren't sufficient or logic needs to be dynamic\n","properties":{"type":{"type":"string","description":"Determines which filtering mechanism to use. This choice affects which properties\nmust be configured and how filtering logic is implemented.\n\n**Available types**\n\n**Rule-Based Filtering (`\"expression\"`)**\n- **Required Config**: The `expression` object with rule definitions\n- **Behavior**: Evaluates declarative rules against item attributes\n- **Best For**: Common patterns like name matching, date ranges, value limits\n- **Advantages**: Simpler to configure, no custom code required\n\n**Script-Based Filtering (`\"script\"`)**\n- **Required Config**: The `script` object with _scriptId and function\n- **Behavior**: Executes custom JavaScript to determine which items to process\n- **Best For**: Complex conditions, business logic, dynamic criteria\n- **Advantages**: Maximum flexibility, can implement any logic\n\n**Implementation guidance**\n\n1. For standard filtering needs (name, size, date), use `\"expression\"`\n2. For complex logic or conditions not covered by expressions, use `\"script\"`\n3. When selecting a type, you must configure the corresponding object:\n    - `type: \"expression\"` requires the `expression` object\n    - `type: \"script\"` requires the `script` object\n","enum":["expression","script"]},"expression":{"type":"object","description":"Configuration for declarative rule-based filtering. This object enables filtering\nitems based on common attributes without requiring custom code.\n\n**Usage context**\n\nThis object is REQUIRED when `filter.type` is set to \"expression\" and should not be\nconfigured otherwise. It provides a standardized way to define filtering rules that\ncan match against item attributes like name, type, value, date, and other properties.\n\n**Implementation guidance**\n\nThe expression system uses a rule-based approach where:\n- Rules can be combined with AND/OR logic\n- Each rule can check a specific attribute\n- Multiple conditions can be applied (ranges, pattern matching, exact matches)\n\n**Common filter patterns**\n\n1. **Pattern matching**: Using wildcards like `*` and `?`\n2. **Value range filtering**: Numbers between min and max values\n3. **Date range filtering**: Items created/modified within specific time ranges\n4. **Status checking**: Items with specific status values or properties\n\nFor AI agents: Rule-based filtering should be your first choice when the filtering criteria\ncan be expressed in terms of standard attributes. Only use script-based filtering when\nmore complex logic is required.\n","properties":{"version":{"type":"string","description":"Version identifier for the expression format. Currently only version \"1\" is supported.\n\nThis field ensures future compatibility if the expression format evolves. Always set to \"1\"\nfor current implementations.\n","enum":["1"]},"rules":{"type":"array","description":"Expression array defining filter conditions using prefix notation. The first element is the operator,\nfollowed by its operands which may themselves be nested expression arrays.\n\nThe rule expression follows this pattern:\n- First element: Operator name (string)\n- Remaining elements: Operands for that operator (values or nested expressions)\n\n**Expression structure**\n\nFilter expressions use a prefix notation where operators appear before their operands:\n```\n[operator, operand1, operand2, ...]\n```\n\n**Comparison Operators**\n- `\"equals\"`: Exact match (equals)\n- `\"notequals\"`: Not equal to value (not equals)\n- `\"greaterthan\"`: Value is greater than specified value (is greater than)\n- `\"greaterthanequals\"`: Value is greater than or equal to specified value (is greater than or equals)\n- `\"lessthan\"`: Value is less than specified value (is less than)\n- `\"lessthanequals\"`: Value is less than or equal to specified value (is less than or equals)\n- `\"startswith\"`: String starts with specified prefix (starts with)\n- `\"endswith\"`: String ends with specified suffix (ends with)\n- `\"contains\"`: String contains specified substring (contains)\n- `\"doesnotcontain\"`: String does not contain specified substring (does not contain)\n- `\"isempty\"`: Field is empty or null (is empty)\n- `\"isnotempty\"`: Field contains a value (is not empty)\n- `\"matches\"`: Matches specified pattern (matches)\n\n**Logical Operators**\n- `\"and\"`: All conditions must be true\n- `\"or\"`: At least one condition must be true\n- `\"not\"`: Negates the condition\n\n**Field Access and Type Conversion**\n- `\"extract\"`: Access a field from the item by name\n- `\"settings\"`: Access a custom setting from the flow, flow step, or integration configuration\n- `\"boolean\"`: Convert value to Boolean type\n- `\"epochtime\"`: Convert value to Epoch Time (Unix timestamp)\n- `\"number\"`: Convert value to Number type\n- `\"string\"`: Convert value to String type\n\n**Field Access Details**\n\n**Using `extract` to access record fields:**\n- Retrieves values from the current record being processed\n- Can access nested properties using dot notation (e.g., `\"customer.email\"`)\n- Returns the raw field value which may need type conversion\n\n**Using `settings` to access configuration values:**\n- Retrieves values from the integration's configuration settings\n- Supports different scopes with prefix notation:\n  - `flow.settingName`: Access flow-level settings\n  - `export.settingName`: Access export-level settings\n  - `import.settingName`: Access import-level settings\n  - `integration.settingName`: Access integration-level settings\n- Useful for dynamic filtering based on configuration\n\n**Field Transformations**\n- `\"lowercase\"`: Convert string to lowercase\n- `\"uppercase\"`: Convert string to uppercase\n- `\"ceiling\"`: Round number up to the nearest integer\n- `\"floor\"`: Round number down to the nearest integer\n- `\"abs\"`: Get absolute value of a number\n\nType conversion operators are often necessary when comparing extracted field values against literals or when the field type doesn't match the comparison operator's expected type. For example:\n\n```json\n[\n  \"equals\",\n  [\n    \"number\",  // Convert to number before comparison\n    [\n      \"extract\",\n      \"quantity\"\n    ]\n  ],\n  100\n]\n```\n\nExample with datetime conversion:\n```json\n[\n  \"greaterthan\",\n  [\n    \"epochtime\",  // Convert to Unix timestamp before comparison\n    [\n      \"extract\",\n      \"createdDate\"\n    ]\n  ],\n  1609459200000  // January 1, 2021 as Unix timestamp in milliseconds\n]\n```\n\nExample with transformations:\n```json\n[\n  \"and\",\n  [\n    \"matches\",\n    [\n      \"lowercase\",  // Convert to lowercase before matching\n      [\n        \"string\",\n        [\n          \"extract\",\n          \"categories\"\n        ]\n      ]\n    ],\n    \"netsuite\"\n  ],\n  [\n    \"notequals\",\n    [\n      \"string\",\n      [\n        \"extract\",\n        \"recurrence.pattern.type\"\n      ]\n    ],\n    \"\"\n  ]\n]\n```\n\nExample comparing a record field with a flow setting:\n```json\n[\n  \"equals\",\n  [\n    \"string\",\n    [\n      \"extract\",\n      \"trantype\"\n    ]\n  ],\n  [\n    \"string\",\n    [\n      \"settings\",\n      \"flow.trantype\"\n    ]\n  ]\n]\n```\n\n**Examples**\n\nExample 1: Status field is not equal to \"cancelled\"\n```json\n[\n  \"notequals\",\n  [\n    \"extract\",\n    \"status\"\n  ],\n  \"cancelled\"\n]\n```\n\nExample 2: Filename starts with \"HC\"\n```json\n[\n  \"startswith\",\n  [\n    \"extract\",\n    \"filename\"\n  ],\n  \"HC\"\n]\n```\n\nExample 3: Amount is greater than 100\n```json\n[\n  \"greaterthan\",\n  [\n    \"number\",\n    [\n      \"extract\",\n      \"amount\"\n    ]\n  ],\n  100\n]\n```\n\nExample 4: Order date is after January 1, 2023\n```json\n[\n  \"greaterthan\",\n  [\n    \"extract\",\n    \"orderDate\"\n  ],\n  \"2023-01-01T00:00:00Z\"\n]\n```\n\nExample 5: Category contains any of [\"Urgent\", \"High Priority\"]\n```json\n[\n  \"anyof\",\n  [\n    \"extract\",\n    \"category\"\n  ],\n  [\"Urgent\", \"High Priority\"]\n]\n```\n","items":{"oneOf":[{"title":"String","type":"string"},{"title":"Number","type":"number"},{"title":"Boolean","type":"boolean"},{"title":"Object","type":"object"},{"title":"Array","type":"array"}]}}}},"script":{"type":"object","description":"Configuration for programmable script-based filtering. This object enables complex, custom\nfiltering logic beyond what expression-based filtering can provide.\n\n**Usage context**\n\nThis object is REQUIRED when `filter.type` is set to \"script\" and should not be configured\notherwise. It provides a way to execute custom JavaScript code to determine which items\nshould be processed.\n\n**Implementation approach**\n\nScript-based filtering works by:\n1. Executing the specified function from the referenced script\n2. Passing item data to the function\n3. Using the function's return value (true/false) to determine inclusion\n\n**Common use cases**\n\nScript filtering is ideal for:\n- Complex business logic that can't be expressed as simple rules\n- Dynamic filtering criteria that change based on external factors\n- Content-based filtering that requires deep inspection\n- Advanced pattern matching beyond simple wildcards\n- Multi-stage filtering with intermediate logic\n\nFor AI agents: Only use script-based filtering when expression-based filtering is insufficient.\nScript filtering requires maintaining custom code, which adds complexity to the integration.\n","properties":{"_scriptId":{"type":"string","description":"Reference to the Script resource that contains the filtering logic. This must be a valid\nObjectId of a Script resource that exists in the system.\n\nThe referenced script must contain the function specified in the `function` field\nand must be written to handle filtering specifically. The script receives\nitem data as its input and must return a boolean value indicating whether\nto process the item (true) or skip it (false).\n\nFormat: 24-character hexadecimal string (MongoDB ObjectId)\n"},"function":{"type":"string","description":"Name of the function within the script to execute for filtering decisions. This function\nmust exist in the script referenced by _scriptId.\n\n**Function requirements**\n\nThe specified function must:\n- Accept item data as its first parameter\n- Return a boolean value (true to process the item, false to skip it)\n- Handle errors gracefully\n- Execute efficiently (as it may run for many items)\n\n**Function signature**\n\n```javascript\nfunction filterItems(itemData) {\n  // itemData contains properties of the item being evaluated\n  // Custom logic here\n  return true; // or false to skip the item\n}\n```\n\nFor AI agents: Ensure the function name exactly matches a function defined in the\nreferenced script, as mismatches will cause the filter to fail.\n"}}}}},"PreConfiguredField":{"type":"object","description":"A field that is automatically set to a predefined value during trading partner\nonboarding. The `path` identifies which field on the target resource to set,\nand `values` provides the value(s) to assign.\n","properties":{"path":{"type":"string","description":"Dot-notation path of the field on the target resource to set.\n"},"values":{"type":"array","description":"Value(s) to assign to the field. Typically a single-element array.\n","items":{"oneOf":[{"title":"String","type":"string"},{"title":"Number","type":"number"},{"title":"Boolean","type":"boolean"},{"title":"Object","type":"object"}]}},"_conditionIds":{"type":"array","description":"References to condition IDs that must be satisfied for this field to apply.\nIf empty or absent, the field always applies.\n","items":{"type":"string","format":"objectId"}}}},"FieldUserMustSet":{"type":"object","description":"A field that the user must provide a value for during trading partner onboarding.\n","properties":{"path":{"type":"string","description":"Dot-notation path of the field on the target resource that the user must set.\n"},"values":{"type":"array","description":"Optional suggested or constrained values for the field.\n","items":{"oneOf":[{"title":"String","type":"string"},{"title":"Number","type":"number"},{"title":"Boolean","type":"boolean"},{"title":"Object","type":"object"}]}},"_conditionIds":{"type":"array","description":"References to condition IDs that must be satisfied for this field to apply.\n","items":{"type":"string","format":"objectId"}},"helpURL":{"type":"string","description":"URL to documentation for this field"},"labelOverride":{"type":"string","description":"Custom label to display for this field in the UI instead of the default"}}},"ConnectionSupportedBySection":{"type":"object","description":"The `supportedBy.connection` section. Identical to other supportedBy sections\nbut `fieldsUserMustSet` entries may include an `inputType` to control the\nUI input widget type.\n","properties":{"conditions":{"type":"array","description":"Array of condition objects for the connection section.\n","items":{"type":"object","properties":{"_id":{"type":"string","format":"objectId","description":"Unique identifier for this condition"},"condition":{"$ref":"#/components/schemas/Filter"}}}},"preConfiguredFields":{"type":"array","description":"Fields automatically set on the connection during trading partner onboarding.\n","items":{"$ref":"#/components/schemas/PreConfiguredField"}},"fieldsUserMustSet":{"type":"array","description":"Fields the user must provide for the connection. May include `inputType`\nto control the UI input widget.\n","items":{"$ref":"#/components/schemas/ConnectionFieldUserMustSet"}}}},"ConnectionFieldUserMustSet":{"type":"object","description":"A field that the user must provide a value for on the connection during\ntrading partner onboarding. Extends the base field with an `inputType`\nproperty to control the UI input widget.\n","properties":{"inputType":{"type":"string","enum":["number","password","uri"],"description":"The type of input widget to render in the UI for this field.\nOnly applicable to connection fields.\n"},"path":{"type":"string","description":"Dot-notation path of the field on the connection that the user must set.\n"},"values":{"type":"array","description":"Optional suggested or constrained values for the field.\n","items":{"oneOf":[{"title":"String","type":"string"},{"title":"Number","type":"number"},{"title":"Boolean","type":"boolean"},{"title":"Object","type":"object"}]}},"_conditionIds":{"type":"array","description":"References to condition IDs that must be satisfied for this field to apply.\n","items":{"type":"string","format":"objectId"}},"helpURL":{"type":"string","description":"URL to documentation for this field"},"labelOverride":{"type":"string","description":"Custom label to display for this field in the UI"}}},"Error":{"type":"object","description":"Standard error response envelope returned by integrator.io APIs.","properties":{"errors":{"type":"array","description":"List of errors that occurred while processing the request.","items":{"type":"object","properties":{"code":{"oneOf":[{"type":"string"},{"type":"integer"}],"description":"Machine-readable error code. Usually a string like\n`invalid_ref`, `missing_required_field`, or `unauthorized`;\nmay be an **integer** when the error mirrors an upstream HTTP\nstatus (e.g. `500`) — most commonly returned by connection-ping\nand adaptor-proxy responses."},"message":{"type":"string","description":"Human-readable description of the error."},"field":{"type":"string","description":"Optional pointer to the document field that caused the error.\nUsed by structural validation errors (`missing_required_field`,\n`invalid_ref`) to indicate which field is at fault\n(e.g. `_id`, `type`, `http.baseURI`)."},"source":{"type":"string","description":"Optional origin layer for the error — e.g. `application` when\nthe error came from the remote system the adaptor called,\n`connector` when the adaptor itself rejected the request."}},"required":["message"]}}},"required":["errors"]}},"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"]}}}},"404-not-found":{"description":"Not found. The requested resource does not exist or is not visible to the caller.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/v1/tpconnectors/{_id}":{"get":{"summary":"Get a trading partner connector","description":"Returns the complete configuration of a specific trading partner connector,\nincluding all supportedBy sections with conditions, pre-configured fields,\nand fields the user must set.\n\nFor the dedicated list/get endpoints, only published connectors are returned\nunless the requesting user owns the connector.\n","operationId":"getTradingPartnerConnectorById","tags":["Trading Partner Connectors"],"parameters":[{"name":"_id","in":"path","description":"The unique identifier of the trading partner connector","required":true,"schema":{"type":"string","format":"objectId"}}],"responses":{"200":{"description":"Trading partner connector retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Response"}}}},"401":{"$ref":"#/components/responses/401-unauthorized"},"404":{"$ref":"#/components/responses/404-not-found"}}}}}}
````

## Update a trading partner connector

> Updates an existing trading partner connector with the provided configuration.\
> This endpoint can also create a connector if no document exists for the given ID.\
> \
> When \`published\` is set to true, validation is enforced on the \`supportedBy\`\
> sections to ensure all required fields are present for connection, export,\
> import, and EDI profile configurations.<br>

````json
{"openapi":"3.1.0","info":{"title":"Trading Partner Connectors","version":"1.0.0"},"servers":[{"url":"https://api.integrator.io","description":"Production (US / default region)"},{"url":"https://api.eu.integrator.io","description":"Production (EU region)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"Request":{"type":"object","description":"Request schema for creating or updating a trading partner connector.\n\nTrading partner connectors define reusable templates for onboarding EDI trading\npartners. They specify which fields are pre-configured and which fields the user\nmust provide for connections, exports, imports, and EDI profiles.\n\nWhen `published` is true, the connector's `supportedBy` sections are validated\nto ensure all required fields are present. For example:\n- Connection must have a pre-configured `type` field (either \"ftp\" or \"as2\")\n- Export/import must have a pre-configured `file.type` set to \"filedefinition\"\n- EDI profile must have the appropriate mandatory fields for x12 or edifact\n","properties":{"name":{"type":"string","description":"Name of the trading partner connector. Must be unique across all published\nconnectors. Used to identify the connector during trading partner onboarding.\n"},"published":{"type":"boolean","default":false,"description":"Whether this connector is published and available for use across the platform.\n\nOnly users with the `allowedToPublishTPConnectors` permission can set this\nto true. When publishing, all `supportedBy` sections are validated to ensure\nrequired fields are present. Published connector names must be unique.\n"},"helpURL":{"type":"string","description":"URL to documentation for this trading partner connector.\n"},"supportedBy":{"type":"object","description":"Defines the field configurations for each resource type involved in trading\npartner onboarding. Each section specifies conditions, pre-configured fields,\nand fields the user must set.\n","properties":{"ediProfile":{"$ref":"#/components/schemas/SupportedBySection"},"export":{"$ref":"#/components/schemas/SupportedBySection"},"import":{"$ref":"#/components/schemas/SupportedBySection"},"connection":{"$ref":"#/components/schemas/ConnectionSupportedBySection"}}}},"required":["name"]},"SupportedBySection":{"type":"object","description":"A section within `supportedBy` that defines conditions, pre-configured field values,\nand fields the user must set when creating a trading partner resource (connection,\nexport, import, or EDI profile).\n\nConditions use expression-based filters to control which field configurations apply\nbased on resource attributes. Pre-configured fields are automatically set, while\nfields the user must set require input during trading partner onboarding.\n","properties":{"conditions":{"type":"array","description":"Array of condition objects. Each condition contains an expression-based filter\nthat can be referenced by `_conditionIds` in `preConfiguredFields` and\n`fieldsUserMustSet` to conditionally apply those field configurations.\n","items":{"type":"object","properties":{"_id":{"type":"string","format":"objectId","description":"Unique identifier for this condition, referenced by `_conditionIds` in field entries"},"condition":{"$ref":"#/components/schemas/Filter"}}}},"preConfiguredFields":{"type":"array","description":"Array of fields that are automatically set to predefined values when creating\na trading partner resource using this connector. These fields are not editable\nby the user during onboarding.\n","items":{"$ref":"#/components/schemas/PreConfiguredField"}},"fieldsUserMustSet":{"type":"array","description":"Array of fields that the user must provide values for during trading partner\nonboarding. These fields may have suggested values or constraints.\n","items":{"$ref":"#/components/schemas/FieldUserMustSet"}}}},"Filter":{"type":"object","description":"Configuration for selectively processing records based on specified criteria. This object enables\nprecise control over which items are included or excluded from processing operations.\n\n**Filter behavior**\n\nWhen configured, the filter is applied before processing begins:\n- Items that match the filter criteria are processed\n- Items that don't match are completely skipped\n- No partial processing is performed\n\n**Implementation approaches**\n\nThere are two distinct filtering mechanisms available:\n\n**Rule-Based Filtering (`type: \"expression\"`)**\n- **Best For**: Common filtering patterns based on standard attributes\n- **Capabilities**: Filter by names, values, dates, numerical ranges, text patterns\n- **Advantages**: Declarative, no coding required, consistent performance\n- **Configuration**: Define rules in the `expression` object\n- **Use When**: You have clear, static criteria for selection\n\n**Script-Based Filtering (`type: \"script\"`)**\n- **Best For**: Complex logic, dynamic criteria, or business rules\n- **Capabilities**: Full programmatic control, access to complete metadata\n- **Advantages**: Maximum flexibility, can implement any filtering logic\n- **Configuration**: Reference a script in the `script` object\n- **Use When**: Simple rules aren't sufficient or logic needs to be dynamic\n","properties":{"type":{"type":"string","description":"Determines which filtering mechanism to use. This choice affects which properties\nmust be configured and how filtering logic is implemented.\n\n**Available types**\n\n**Rule-Based Filtering (`\"expression\"`)**\n- **Required Config**: The `expression` object with rule definitions\n- **Behavior**: Evaluates declarative rules against item attributes\n- **Best For**: Common patterns like name matching, date ranges, value limits\n- **Advantages**: Simpler to configure, no custom code required\n\n**Script-Based Filtering (`\"script\"`)**\n- **Required Config**: The `script` object with _scriptId and function\n- **Behavior**: Executes custom JavaScript to determine which items to process\n- **Best For**: Complex conditions, business logic, dynamic criteria\n- **Advantages**: Maximum flexibility, can implement any logic\n\n**Implementation guidance**\n\n1. For standard filtering needs (name, size, date), use `\"expression\"`\n2. For complex logic or conditions not covered by expressions, use `\"script\"`\n3. When selecting a type, you must configure the corresponding object:\n    - `type: \"expression\"` requires the `expression` object\n    - `type: \"script\"` requires the `script` object\n","enum":["expression","script"]},"expression":{"type":"object","description":"Configuration for declarative rule-based filtering. This object enables filtering\nitems based on common attributes without requiring custom code.\n\n**Usage context**\n\nThis object is REQUIRED when `filter.type` is set to \"expression\" and should not be\nconfigured otherwise. It provides a standardized way to define filtering rules that\ncan match against item attributes like name, type, value, date, and other properties.\n\n**Implementation guidance**\n\nThe expression system uses a rule-based approach where:\n- Rules can be combined with AND/OR logic\n- Each rule can check a specific attribute\n- Multiple conditions can be applied (ranges, pattern matching, exact matches)\n\n**Common filter patterns**\n\n1. **Pattern matching**: Using wildcards like `*` and `?`\n2. **Value range filtering**: Numbers between min and max values\n3. **Date range filtering**: Items created/modified within specific time ranges\n4. **Status checking**: Items with specific status values or properties\n\nFor AI agents: Rule-based filtering should be your first choice when the filtering criteria\ncan be expressed in terms of standard attributes. Only use script-based filtering when\nmore complex logic is required.\n","properties":{"version":{"type":"string","description":"Version identifier for the expression format. Currently only version \"1\" is supported.\n\nThis field ensures future compatibility if the expression format evolves. Always set to \"1\"\nfor current implementations.\n","enum":["1"]},"rules":{"type":"array","description":"Expression array defining filter conditions using prefix notation. The first element is the operator,\nfollowed by its operands which may themselves be nested expression arrays.\n\nThe rule expression follows this pattern:\n- First element: Operator name (string)\n- Remaining elements: Operands for that operator (values or nested expressions)\n\n**Expression structure**\n\nFilter expressions use a prefix notation where operators appear before their operands:\n```\n[operator, operand1, operand2, ...]\n```\n\n**Comparison Operators**\n- `\"equals\"`: Exact match (equals)\n- `\"notequals\"`: Not equal to value (not equals)\n- `\"greaterthan\"`: Value is greater than specified value (is greater than)\n- `\"greaterthanequals\"`: Value is greater than or equal to specified value (is greater than or equals)\n- `\"lessthan\"`: Value is less than specified value (is less than)\n- `\"lessthanequals\"`: Value is less than or equal to specified value (is less than or equals)\n- `\"startswith\"`: String starts with specified prefix (starts with)\n- `\"endswith\"`: String ends with specified suffix (ends with)\n- `\"contains\"`: String contains specified substring (contains)\n- `\"doesnotcontain\"`: String does not contain specified substring (does not contain)\n- `\"isempty\"`: Field is empty or null (is empty)\n- `\"isnotempty\"`: Field contains a value (is not empty)\n- `\"matches\"`: Matches specified pattern (matches)\n\n**Logical Operators**\n- `\"and\"`: All conditions must be true\n- `\"or\"`: At least one condition must be true\n- `\"not\"`: Negates the condition\n\n**Field Access and Type Conversion**\n- `\"extract\"`: Access a field from the item by name\n- `\"settings\"`: Access a custom setting from the flow, flow step, or integration configuration\n- `\"boolean\"`: Convert value to Boolean type\n- `\"epochtime\"`: Convert value to Epoch Time (Unix timestamp)\n- `\"number\"`: Convert value to Number type\n- `\"string\"`: Convert value to String type\n\n**Field Access Details**\n\n**Using `extract` to access record fields:**\n- Retrieves values from the current record being processed\n- Can access nested properties using dot notation (e.g., `\"customer.email\"`)\n- Returns the raw field value which may need type conversion\n\n**Using `settings` to access configuration values:**\n- Retrieves values from the integration's configuration settings\n- Supports different scopes with prefix notation:\n  - `flow.settingName`: Access flow-level settings\n  - `export.settingName`: Access export-level settings\n  - `import.settingName`: Access import-level settings\n  - `integration.settingName`: Access integration-level settings\n- Useful for dynamic filtering based on configuration\n\n**Field Transformations**\n- `\"lowercase\"`: Convert string to lowercase\n- `\"uppercase\"`: Convert string to uppercase\n- `\"ceiling\"`: Round number up to the nearest integer\n- `\"floor\"`: Round number down to the nearest integer\n- `\"abs\"`: Get absolute value of a number\n\nType conversion operators are often necessary when comparing extracted field values against literals or when the field type doesn't match the comparison operator's expected type. For example:\n\n```json\n[\n  \"equals\",\n  [\n    \"number\",  // Convert to number before comparison\n    [\n      \"extract\",\n      \"quantity\"\n    ]\n  ],\n  100\n]\n```\n\nExample with datetime conversion:\n```json\n[\n  \"greaterthan\",\n  [\n    \"epochtime\",  // Convert to Unix timestamp before comparison\n    [\n      \"extract\",\n      \"createdDate\"\n    ]\n  ],\n  1609459200000  // January 1, 2021 as Unix timestamp in milliseconds\n]\n```\n\nExample with transformations:\n```json\n[\n  \"and\",\n  [\n    \"matches\",\n    [\n      \"lowercase\",  // Convert to lowercase before matching\n      [\n        \"string\",\n        [\n          \"extract\",\n          \"categories\"\n        ]\n      ]\n    ],\n    \"netsuite\"\n  ],\n  [\n    \"notequals\",\n    [\n      \"string\",\n      [\n        \"extract\",\n        \"recurrence.pattern.type\"\n      ]\n    ],\n    \"\"\n  ]\n]\n```\n\nExample comparing a record field with a flow setting:\n```json\n[\n  \"equals\",\n  [\n    \"string\",\n    [\n      \"extract\",\n      \"trantype\"\n    ]\n  ],\n  [\n    \"string\",\n    [\n      \"settings\",\n      \"flow.trantype\"\n    ]\n  ]\n]\n```\n\n**Examples**\n\nExample 1: Status field is not equal to \"cancelled\"\n```json\n[\n  \"notequals\",\n  [\n    \"extract\",\n    \"status\"\n  ],\n  \"cancelled\"\n]\n```\n\nExample 2: Filename starts with \"HC\"\n```json\n[\n  \"startswith\",\n  [\n    \"extract\",\n    \"filename\"\n  ],\n  \"HC\"\n]\n```\n\nExample 3: Amount is greater than 100\n```json\n[\n  \"greaterthan\",\n  [\n    \"number\",\n    [\n      \"extract\",\n      \"amount\"\n    ]\n  ],\n  100\n]\n```\n\nExample 4: Order date is after January 1, 2023\n```json\n[\n  \"greaterthan\",\n  [\n    \"extract\",\n    \"orderDate\"\n  ],\n  \"2023-01-01T00:00:00Z\"\n]\n```\n\nExample 5: Category contains any of [\"Urgent\", \"High Priority\"]\n```json\n[\n  \"anyof\",\n  [\n    \"extract\",\n    \"category\"\n  ],\n  [\"Urgent\", \"High Priority\"]\n]\n```\n","items":{"oneOf":[{"title":"String","type":"string"},{"title":"Number","type":"number"},{"title":"Boolean","type":"boolean"},{"title":"Object","type":"object"},{"title":"Array","type":"array"}]}}}},"script":{"type":"object","description":"Configuration for programmable script-based filtering. This object enables complex, custom\nfiltering logic beyond what expression-based filtering can provide.\n\n**Usage context**\n\nThis object is REQUIRED when `filter.type` is set to \"script\" and should not be configured\notherwise. It provides a way to execute custom JavaScript code to determine which items\nshould be processed.\n\n**Implementation approach**\n\nScript-based filtering works by:\n1. Executing the specified function from the referenced script\n2. Passing item data to the function\n3. Using the function's return value (true/false) to determine inclusion\n\n**Common use cases**\n\nScript filtering is ideal for:\n- Complex business logic that can't be expressed as simple rules\n- Dynamic filtering criteria that change based on external factors\n- Content-based filtering that requires deep inspection\n- Advanced pattern matching beyond simple wildcards\n- Multi-stage filtering with intermediate logic\n\nFor AI agents: Only use script-based filtering when expression-based filtering is insufficient.\nScript filtering requires maintaining custom code, which adds complexity to the integration.\n","properties":{"_scriptId":{"type":"string","description":"Reference to the Script resource that contains the filtering logic. This must be a valid\nObjectId of a Script resource that exists in the system.\n\nThe referenced script must contain the function specified in the `function` field\nand must be written to handle filtering specifically. The script receives\nitem data as its input and must return a boolean value indicating whether\nto process the item (true) or skip it (false).\n\nFormat: 24-character hexadecimal string (MongoDB ObjectId)\n"},"function":{"type":"string","description":"Name of the function within the script to execute for filtering decisions. This function\nmust exist in the script referenced by _scriptId.\n\n**Function requirements**\n\nThe specified function must:\n- Accept item data as its first parameter\n- Return a boolean value (true to process the item, false to skip it)\n- Handle errors gracefully\n- Execute efficiently (as it may run for many items)\n\n**Function signature**\n\n```javascript\nfunction filterItems(itemData) {\n  // itemData contains properties of the item being evaluated\n  // Custom logic here\n  return true; // or false to skip the item\n}\n```\n\nFor AI agents: Ensure the function name exactly matches a function defined in the\nreferenced script, as mismatches will cause the filter to fail.\n"}}}}},"PreConfiguredField":{"type":"object","description":"A field that is automatically set to a predefined value during trading partner\nonboarding. The `path` identifies which field on the target resource to set,\nand `values` provides the value(s) to assign.\n","properties":{"path":{"type":"string","description":"Dot-notation path of the field on the target resource to set.\n"},"values":{"type":"array","description":"Value(s) to assign to the field. Typically a single-element array.\n","items":{"oneOf":[{"title":"String","type":"string"},{"title":"Number","type":"number"},{"title":"Boolean","type":"boolean"},{"title":"Object","type":"object"}]}},"_conditionIds":{"type":"array","description":"References to condition IDs that must be satisfied for this field to apply.\nIf empty or absent, the field always applies.\n","items":{"type":"string","format":"objectId"}}}},"FieldUserMustSet":{"type":"object","description":"A field that the user must provide a value for during trading partner onboarding.\n","properties":{"path":{"type":"string","description":"Dot-notation path of the field on the target resource that the user must set.\n"},"values":{"type":"array","description":"Optional suggested or constrained values for the field.\n","items":{"oneOf":[{"title":"String","type":"string"},{"title":"Number","type":"number"},{"title":"Boolean","type":"boolean"},{"title":"Object","type":"object"}]}},"_conditionIds":{"type":"array","description":"References to condition IDs that must be satisfied for this field to apply.\n","items":{"type":"string","format":"objectId"}},"helpURL":{"type":"string","description":"URL to documentation for this field"},"labelOverride":{"type":"string","description":"Custom label to display for this field in the UI instead of the default"}}},"ConnectionSupportedBySection":{"type":"object","description":"The `supportedBy.connection` section. Identical to other supportedBy sections\nbut `fieldsUserMustSet` entries may include an `inputType` to control the\nUI input widget type.\n","properties":{"conditions":{"type":"array","description":"Array of condition objects for the connection section.\n","items":{"type":"object","properties":{"_id":{"type":"string","format":"objectId","description":"Unique identifier for this condition"},"condition":{"$ref":"#/components/schemas/Filter"}}}},"preConfiguredFields":{"type":"array","description":"Fields automatically set on the connection during trading partner onboarding.\n","items":{"$ref":"#/components/schemas/PreConfiguredField"}},"fieldsUserMustSet":{"type":"array","description":"Fields the user must provide for the connection. May include `inputType`\nto control the UI input widget.\n","items":{"$ref":"#/components/schemas/ConnectionFieldUserMustSet"}}}},"ConnectionFieldUserMustSet":{"type":"object","description":"A field that the user must provide a value for on the connection during\ntrading partner onboarding. Extends the base field with an `inputType`\nproperty to control the UI input widget.\n","properties":{"inputType":{"type":"string","enum":["number","password","uri"],"description":"The type of input widget to render in the UI for this field.\nOnly applicable to connection fields.\n"},"path":{"type":"string","description":"Dot-notation path of the field on the connection that the user must set.\n"},"values":{"type":"array","description":"Optional suggested or constrained values for the field.\n","items":{"oneOf":[{"title":"String","type":"string"},{"title":"Number","type":"number"},{"title":"Boolean","type":"boolean"},{"title":"Object","type":"object"}]}},"_conditionIds":{"type":"array","description":"References to condition IDs that must be satisfied for this field to apply.\n","items":{"type":"string","format":"objectId"}},"helpURL":{"type":"string","description":"URL to documentation for this field"},"labelOverride":{"type":"string","description":"Custom label to display for this field in the UI"}}},"Response":{"type":"object","description":"Response schema for trading partner connector operations.\n\nContains the complete connector configuration including metadata and all\nsupportedBy sections with conditions, pre-configured fields, and fields\nthe user must set.\n","allOf":[{"$ref":"#/components/schemas/Request"},{"type":"object","properties":{"_id":{"type":"string","format":"objectId","readOnly":true,"description":"Unique identifier for the trading partner connector"},"createdAt":{"type":"string","format":"date-time","readOnly":true,"description":"Timestamp when the connector was created"},"lastModified":{"type":"string","format":"date-time","readOnly":true,"description":"Timestamp when the connector was last modified"},"_userId":{"type":"string","format":"objectId","description":"User who owns or created this trading partner connector"}}}]},"Error":{"type":"object","description":"Standard error response envelope returned by integrator.io APIs.","properties":{"errors":{"type":"array","description":"List of errors that occurred while processing the request.","items":{"type":"object","properties":{"code":{"oneOf":[{"type":"string"},{"type":"integer"}],"description":"Machine-readable error code. Usually a string like\n`invalid_ref`, `missing_required_field`, or `unauthorized`;\nmay be an **integer** when the error mirrors an upstream HTTP\nstatus (e.g. `500`) — most commonly returned by connection-ping\nand adaptor-proxy responses."},"message":{"type":"string","description":"Human-readable description of the error."},"field":{"type":"string","description":"Optional pointer to the document field that caused the error.\nUsed by structural validation errors (`missing_required_field`,\n`invalid_ref`) to indicate which field is at fault\n(e.g. `_id`, `type`, `http.baseURI`)."},"source":{"type":"string","description":"Optional origin layer for the error — e.g. `application` when\nthe error came from the remote system the adaptor called,\n`connector` when the adaptor itself rejected the request."}},"required":["message"]}}},"required":["errors"]}},"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"]}}}},"422-unprocessable-entity":{"description":"Unprocessable entity. The request was well-formed but was unable to be followed due to semantic errors.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/v1/tpconnectors/{_id}":{"put":{"summary":"Update a trading partner connector","description":"Updates an existing trading partner connector with the provided configuration.\nThis endpoint can also create a connector if no document exists for the given ID.\n\nWhen `published` is set to true, validation is enforced on the `supportedBy`\nsections to ensure all required fields are present for connection, export,\nimport, and EDI profile configurations.\n","operationId":"updateTradingPartnerConnector","tags":["Trading Partner Connectors"],"parameters":[{"name":"_id","in":"path","description":"The unique identifier of the trading partner connector","required":true,"schema":{"type":"string","format":"objectId"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Request"}}}},"responses":{"200":{"description":"Trading partner connector updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Response"}}}},"401":{"$ref":"#/components/responses/401-unauthorized"},"422":{"$ref":"#/components/responses/422-unprocessable-entity"}}}}}}
````

## Delete a trading partner connector

> Deletes a trading partner connector. The connector is soft-deleted.<br>

```json
{"openapi":"3.1.0","info":{"title":"Trading Partner Connectors","version":"1.0.0"},"servers":[{"url":"https://api.integrator.io","description":"Production (US / default region)"},{"url":"https://api.eu.integrator.io","description":"Production (EU region)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"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"]}}}},"404-not-found":{"description":"Not found. The requested resource does not exist or is not visible to the caller.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","description":"Standard error response envelope returned by integrator.io APIs.","properties":{"errors":{"type":"array","description":"List of errors that occurred while processing the request.","items":{"type":"object","properties":{"code":{"oneOf":[{"type":"string"},{"type":"integer"}],"description":"Machine-readable error code. Usually a string like\n`invalid_ref`, `missing_required_field`, or `unauthorized`;\nmay be an **integer** when the error mirrors an upstream HTTP\nstatus (e.g. `500`) — most commonly returned by connection-ping\nand adaptor-proxy responses."},"message":{"type":"string","description":"Human-readable description of the error."},"field":{"type":"string","description":"Optional pointer to the document field that caused the error.\nUsed by structural validation errors (`missing_required_field`,\n`invalid_ref`) to indicate which field is at fault\n(e.g. `_id`, `type`, `http.baseURI`)."},"source":{"type":"string","description":"Optional origin layer for the error — e.g. `application` when\nthe error came from the remote system the adaptor called,\n`connector` when the adaptor itself rejected the request."}},"required":["message"]}}},"required":["errors"]}}},"paths":{"/v1/tpconnectors/{_id}":{"delete":{"summary":"Delete a trading partner connector","description":"Deletes a trading partner connector. The connector is soft-deleted.\n","operationId":"deleteTradingPartnerConnector","tags":["Trading Partner Connectors"],"parameters":[{"name":"_id","in":"path","description":"The unique identifier of the trading partner connector","required":true,"schema":{"type":"string","format":"objectId"}}],"responses":{"204":{"description":"Trading partner connector deleted successfully"},"401":{"$ref":"#/components/responses/401-unauthorized"},"404":{"$ref":"#/components/responses/404-not-found"}}}}}}
```


---

# Agent Instructions: 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:

```
GET https://developer.celigo.com/api/api-reference/trading-partner-connectors.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.