Trading Partner Connectors

Trading partner connectors are reusable templates for onboarding EDI trading partners. Each connector defines pre-configured field values and fields the user must set for connections, exports, imports, and EDI profiles.

Connectors support expression-based conditions that control when certain field configurations apply. Publishing a connector makes it available to all accounts but requires the allowedToPublishTPConnectors permission.

Trading partner connector schema

List trading partner connectors

get

/v1/tpconnectors

Returns all trading partner connectors visible to the caller. Published connectors are visible to everyone; unpublished connectors are visible only to their owner.

The list response is a summary shape — it includes _id, name, _userId, helpURL, timestamps, and the categorization fields (type, region, model, baseName) when set, but omits published and supportedBy. Use GET by ID to retrieve the full configuration.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

publishedOnlystring · enumOptional

When set to true, only published connectors are returned.

Example: truePossible values:

baseNamestringOptional

Filter to connectors whose baseName exactly matches this value — typically one trading partner's group of connector variants. Must be supplied once; repeating the parameter returns 422 invalid_query_param. Returns 204 when nothing matches.

Example: Acme Corp

distinctstring · enumOptional

Changes the response shape: instead of connector objects, returns a sorted array of the distinct baseName values across published connectors (unpublished connectors are excluded even for their owner). Combine with other filters to scope the set. Returns 204 when no published connector has a baseName. Any value other than baseName fails with 422 invalid_query_param ("distinct must be 'baseName'.").

Possible values:

Responses

200

Successfully retrieved list of trading partner connectors. With ?distinct=baseName the body is instead a sorted array of strings (the distinct baseName values), e.g. ["Acme Corp", "Bravo Inc"].

application/json

Trading partner connector with metadata. The list endpoint returns a summary shape (omits published and supportedBy but includes type, region, model, and baseName when set); GET by ID returns the full configuration.

namestringRequired

Connector name. Must be unique across all published connectors.

Example: AS2 EDI X12 Connector

publishedbooleanOptional

Whether this connector is published and available platform-wide. Requires the allowedToPublishTPConnectors permission — without it, this field is silently ignored.

Default: false

helpURLany ofOptional

URL to documentation for this trading partner connector. May be an empty string when no documentation link exists.

Example: https://docs.celigo.com/hc/en-us/articles/trading-partners

anyOptional

typestringOptional

Categorizes the connector by the transport its templates configure. Allowed values are configured per deployment — FTP, AS2, and S3 by default. Absent from responses when never set (connectors created before this field existed omit it).

Example: AS2

regionstringOptional

Geographic region the trading partner operates in, used to group connectors in the catalog. Defaults to North America at creation when omitted; allowed values are configured per deployment (North America, European Union, Canada, USA, and Australia by default). Connectors created before this field existed omit it.

Example: North America

modelstringOptional

Business-model variant of the trading partner relationship, such as Dropship, Warehouse, or DVS. Defaults to none at creation when omitted, meaning the connector has no business-model variant; allowed values are configured per deployment. Connectors created before this field existed omit it.

Example: Dropship

baseNamestringOptional

Shared base name that groups related connector variants for the same trading partner — for example, a partner's AS2 and FTP connectors. Only present when set. Filter the list with the baseName query parameter to retrieve one group.

Example: Acme Corp

_idstring · objectIdRead-onlyRequired

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

Example: 5f8d43a1b9e5a80011a35f2c

createdAtstring · date-timeRead-onlyRequired

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

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

lastModifiedstring · date-timeRead-onlyRequired

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

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

deletedAtstring · nullableRead-onlyOptional

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

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

_userIdstring · objectIdRead-onlyRequired

User who owns or created this trading partner connector.

Example: 6316f2b1e37e79778a43391c

204

No trading partner connectors exist, or none matches the supplied filter.

401

Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.

Note: the 401 response is produced by the auth middleware before the request reaches the endpoint handler, so it does not follow the standard {errors: [...]} envelope. Instead the body is a bare {message: string} object with no code, no errors array. Callers handling 401s should key off the HTTP status and the message string, not try to destructure an errors[].

application/json

422

The baseName query parameter was supplied more than once (or is otherwise not a single string), or distinct was set to a value other than baseName.

application/json

get/v1/tpconnectors

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

[
  {
    "_id": "66a8da952ae7e03e6e4c21ed",
    "name": "AAFES AS2",
    "createdAt": "2024-07-30T12:20:37.904Z",
    "lastModified": "2026-05-04T12:21:47.361Z",
    "_userId": "6316f2b1e37e79778a43391c",
    "helpURL": "https://docs.celigo.com/hc/en-us/articles/39875657389595"
  },
  {
    "_id": "66a8da972a54be163b5610a5",
    "name": "AAFES FTP",
    "createdAt": "2024-07-30T12:20:39.110Z",
    "lastModified": "2026-05-04T12:21:47.542Z",
    "_userId": "6316f2b1e37e79778a43391c",
    "helpURL": "https://docs.celigo.com/hc/en-us/articles/39875657389595"
  },
  {
    "_id": "6a55bd1004eae44075e8250e",
    "name": "Acme Corp FTP",
    "createdAt": "2026-07-14T04:37:36.576Z",
    "lastModified": "2026-07-14T04:37:36.576Z",
    "_userId": "6316f2b1e37e79778a43391c",
    "type": "FTP",
    "region": "North America",
    "model": "Dropship",
    "baseName": "Acme Corp"
  }
]

Create a trading partner connector

post

/v1/tpconnectors

Creates a new trading partner connector. Only name is required. Setting published: true requires the allowedToPublishTPConnectors permission; without it the field is silently ignored.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

Request schema for creating or updating a trading partner connector. Only name is required for creation. Connection preConfiguredFields must include a type path (e.g. ftp or as2) and export/import must include file.type set to filedefinition -- these are validated when published is true.

namestringRequired

Connector name. Must be unique across all published connectors.

Example: AS2 EDI X12 Connector

publishedbooleanOptional

Whether this connector is published and available platform-wide. Requires the allowedToPublishTPConnectors permission — without it, this field is silently ignored.

Default: false

helpURLany ofOptional

URL to documentation for this trading partner connector. May be an empty string when no documentation link exists.

Example: https://docs.celigo.com/hc/en-us/articles/trading-partners

anyOptional

typestringOptional

Example: AS2

regionstringOptional

Example: North America

modelstringOptional

Example: Dropship

baseNamestringOptional

Example: Acme Corp

Responses

201

Trading partner connector created successfully.

application/json

namestringRequired

Connector name. Must be unique across all published connectors.

Example: AS2 EDI X12 Connector

publishedbooleanOptional

Whether this connector is published and available platform-wide. Requires the allowedToPublishTPConnectors permission — without it, this field is silently ignored.

Default: false

helpURLany ofOptional

URL to documentation for this trading partner connector. May be an empty string when no documentation link exists.

Example: https://docs.celigo.com/hc/en-us/articles/trading-partners

anyOptional

typestringOptional

Example: AS2

regionstringOptional

Example: North America

modelstringOptional

Example: Dropship

baseNamestringOptional

Example: Acme Corp

_idstring · objectIdRead-onlyRequired

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

Example: 5f8d43a1b9e5a80011a35f2c

createdAtstring · date-timeRead-onlyRequired

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

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

lastModifiedstring · date-timeRead-onlyRequired

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

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

deletedAtstring · nullableRead-onlyOptional

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

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

_userIdstring · objectIdRead-onlyRequired

User who owns or created this trading partner connector.

Example: 6316f2b1e37e79778a43391c

400

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

application/json

401

Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.

application/json

422

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

application/json

post/v1/tpconnectors

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

{
  "name": "Acme Corp FTP"
}

{
  "_id": "6a07d850f8b91b72d73fd4ab",
  "_userId": "5c9d42dad46d11272527e301",
  "name": "Acme Corp FTP",
  "published": false,
  "region": "North America",
  "model": "none",
  "createdAt": "2026-05-16T02:37:04.403Z",
  "lastModified": "2026-05-16T02:37:04.403Z"
}

Get a trading partner connector

get

/v1/tpconnectors/{_id}

Returns the complete configuration of a trading partner connector, including all supportedBy sections. Unpublished connectors are only visible to their owner. The list endpoint returns a summary that omits published and supportedBy.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

_idstring · objectIdRequired

The unique identifier of the trading partner connector.

Example: 5f8d43a1b9e5a80011a35f2c

Responses

200

Trading partner connector retrieved successfully.

application/json

namestringRequired

Connector name. Must be unique across all published connectors.

Example: AS2 EDI X12 Connector

publishedbooleanOptional

Whether this connector is published and available platform-wide. Requires the allowedToPublishTPConnectors permission — without it, this field is silently ignored.

Default: false

helpURLany ofOptional

URL to documentation for this trading partner connector. May be an empty string when no documentation link exists.

Example: https://docs.celigo.com/hc/en-us/articles/trading-partners

anyOptional

typestringOptional

Example: AS2

regionstringOptional

Example: North America

modelstringOptional

Example: Dropship

baseNamestringOptional

Example: Acme Corp

_idstring · objectIdRead-onlyRequired

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

Example: 5f8d43a1b9e5a80011a35f2c

createdAtstring · date-timeRead-onlyRequired

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

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

lastModifiedstring · date-timeRead-onlyRequired

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

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

deletedAtstring · nullableRead-onlyOptional

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

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

_userIdstring · objectIdRead-onlyRequired

User who owns or created this trading partner connector.

Example: 6316f2b1e37e79778a43391c

401

Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.

application/json

404

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

application/json

get/v1/tpconnectors/{_id}

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

{
  "_id": "66a8da972a54be163b5610a5",
  "_userId": "6316f2b1e37e79778a43391c",
  "name": "AAFES FTP",
  "published": true,
  "helpURL": "https://docs.celigo.com/hc/en-us/articles/39875657389595",
  "createdAt": "2024-07-30T12:20:39.110Z",
  "lastModified": "2026-05-04T12:21:47.542Z",
  "supportedBy": {
    "connection": {
      "preConfiguredFields": [
        {
          "path": "type",
          "values": [
            "ftp"
          ]
        },
        {
          "path": "ftp.type",
          "values": [
            "sftp"
          ]
        }
      ],
      "fieldsUserMustSet": [
        {
          "path": "name"
        },
        {
          "path": "ftp.username"
        },
        {
          "path": "ftp.password"
        },
        {
          "path": "ftp.hostURI",
          "values": [
            " "
          ]
        }
      ]
    },
    "export": {
      "preConfiguredFields": [
        {
          "path": "file.type",
          "values": [
            "filedefinition"
          ]
        }
      ],
      "fieldsUserMustSet": [
        {
          "path": "name"
        },
        {
          "path": "ftp.directoryPath"
        }
      ]
    },
    "import": {
      "preConfiguredFields": [
        {
          "path": "file.type",
          "values": [
            "filedefinition"
          ]
        }
      ],
      "fieldsUserMustSet": [
        {
          "path": "name"
        },
        {
          "path": "ftp.directoryPath"
        }
      ]
    },
    "ediProfile": {
      "preConfiguredFields": [
        {
          "path": "fileType",
          "values": [
            "edix12"
          ]
        },
        {
          "path": "tpInterchangeId",
          "values": [
            "001695568GP"
          ]
        },
        {
          "path": "tpGroupId",
          "values": [
            "001695568GP"
          ]
        }
      ],
      "fieldsUserMustSet": [
        {
          "path": "myInterchangeId"
        },
        {
          "path": "myGroupId"
        }
      ]
    }
  }
}

Update a trading partner connector

put

/v1/tpconnectors/{_id}

Replaces a trading partner connector. This is a full replace and an upsert -- if no connector exists for the given ID, one is created. When published is set to true, the supportedBy sections are validated for required fields.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

_idstring · objectIdRequired

The unique identifier of the trading partner connector.

Example: 5f8d43a1b9e5a80011a35f2c

Body

namestringRequired

Connector name. Must be unique across all published connectors.

Example: AS2 EDI X12 Connector

publishedbooleanOptional

Whether this connector is published and available platform-wide. Requires the allowedToPublishTPConnectors permission — without it, this field is silently ignored.

Default: false

helpURLany ofOptional

URL to documentation for this trading partner connector. May be an empty string when no documentation link exists.

Example: https://docs.celigo.com/hc/en-us/articles/trading-partners

anyOptional

typestringOptional

Example: AS2

regionstringOptional

Example: North America

modelstringOptional

Example: Dropship

baseNamestringOptional

Example: Acme Corp

Responses

200

Trading partner connector updated successfully.

application/json

namestringRequired

Connector name. Must be unique across all published connectors.

Example: AS2 EDI X12 Connector

publishedbooleanOptional

Whether this connector is published and available platform-wide. Requires the allowedToPublishTPConnectors permission — without it, this field is silently ignored.

Default: false

helpURLany ofOptional

URL to documentation for this trading partner connector. May be an empty string when no documentation link exists.

Example: https://docs.celigo.com/hc/en-us/articles/trading-partners

anyOptional

typestringOptional

Example: AS2

regionstringOptional

Example: North America

modelstringOptional

Example: Dropship

baseNamestringOptional

Example: Acme Corp

_idstring · objectIdRead-onlyRequired

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

Example: 5f8d43a1b9e5a80011a35f2c

createdAtstring · date-timeRead-onlyRequired

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

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

lastModifiedstring · date-timeRead-onlyRequired

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

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

deletedAtstring · nullableRead-onlyOptional

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

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

_userIdstring · objectIdRead-onlyRequired

User who owns or created this trading partner connector.

Example: 6316f2b1e37e79778a43391c

400

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

application/json

401

Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.

application/json

422

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

application/json

put/v1/tpconnectors/{_id}

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

{
  "name": "Acme Corp SFTP (updated)",
  "helpURL": "https://docs.celigo.com/hc/en-us/articles/12345"
}

{
  "_id": "6a07d850f8b91b72d73fd4ab",
  "_userId": "5c9d42dad46d11272527e301",
  "name": "Acme Corp SFTP (updated)",
  "published": false,
  "helpURL": "https://docs.celigo.com/hc/en-us/articles/12345",
  "createdAt": "2026-05-16T02:37:04.403Z",
  "lastModified": "2026-05-16T02:40:31.064Z"
}

Delete a trading partner connector

delete

/v1/tpconnectors/{_id}

Soft-deletes a trading partner connector.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

_idstring · objectIdRequired

The unique identifier of the trading partner connector.

Example: 5f8d43a1b9e5a80011a35f2c

Responses

204

Trading partner connector deleted successfully.

No content

401

Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.

application/json

404

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

application/json

delete/v1/tpconnectors/{_id}

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

No content

PreviousTools

NextUsers

Last updated 16 days ago

Was this helpful?