ETL: Trading Partners

Overview

A trading partner is the other side of a file exchange: the carrier, TPA, retailer, or any other organization you send files to or receive files from. A trading partner entry is account-level. It records the transport, the connection, the inbound and outbound paths, the filename pattern, the acknowledgement behaviour, and the contact details for one partner. What a partner expects for one transaction set in one direction lives in a partner profile. A partner can hold many profiles: one per transaction set, direction, and effective-date range. Use trading partners when:

You deliver EDI or other structured files to a partner’s SFTP server, S3 bucket, or Azure Blob container and need the partner’s requirements recorded in one place.
A partner’s spec changes on a known date and both the current and the next version must be live at once, each governing its own run dates.

Trading partner screens in the dashboard are enabled per account. If you do not see them, contact Integrate.io support.

Trading partner fields

Field	Description
`name`	Required. Up to 255 characters, unique per account, case-insensitive.
`partner_type`	Free-form label such as `carrier`, `tpa`, or `retailer`. Not restricted to a fixed list.
`transport`	Required. One of `sftp`, `s3`, `azure_blob`.
`connection_id`	Optional. An existing connection of the matching type. The connection must belong to the same account, and its type must match the transport. You can record a partner before its connection exists.
`inbound_path`, `outbound_path`	Directories on the partner endpoint for files you receive and files you send.
`filename_pattern`	Tokenised pattern for outbound file names. See below.
`ack_behaviour`	Required. One of `999`, `997`, `ta1`, `proprietary_report`, `none`.
`ack_window_hours`	Positive integer. Hours to wait for an acknowledgement before it counts as overdue. Must be blank when `ack_behaviour` is `none`.
`contact_name`, `contact_email`, `notes`	Contact details and free-form notes.

ack_behaviour: none is a valid configuration, not a misconfiguration. Some partners return nothing, and recording that keeps those feeds from showing as permanently pending.

Filename patterns

filename_pattern is a file name, never a path. It cannot contain /, \, .., or control characters. Write tokens in braces. Integrate.io rejects an unknown token at save time:

Token	Value
`{ccyymmdd}`	Render date as `YYYYMMDD`
`{yymmdd}`	Render date as `YYMMDD`
`{ccyymmddhhmmss}`	Render timestamp
`{hhmmss}`	Render time
`{partner}`	The partner’s name
`{group}`, `{seq}`, `{transaction_set}`, `{direction}`	Supplied by the delivery that renders the name

Example: {partner}_{transaction_set}_{ccyymmdd}_{seq}.edi

Partner profiles

A partner profile describes what a partner expects for one transaction set in one direction: envelope ids, cadence, file mode, and the flattened field names its validation rules may target. Profiles hold structure and delivery details only. They do not embed X12 specification content.

Field	Description
`transaction_set`	Required. For example `834`, `850`, or a custom label. Stored lower-case.
`direction`	Required. `outbound` or `inbound`.
`version`	Free-form spec version label.
`cadence`	One of `daily`, `weekly`, `monthly`, `on_change`.
`cadence_detail`	Free-form detail, for example a day of week.
`file_mode`	`full_file` or `change_file`.
`envelope`	Object of envelope ids, for example `{"ISA05":"ZZ","ISA06":"SENDERID"}`.
`grain_fields`	List of flattened field names, for example `["member_id","benefit_status"]`. These are the fields validation rules may target.
`effective_from`	Required. First date this version governs, inclusive.
`effective_to`	Last date, inclusive. Blank means open-ended.

Versioning by effective date

Profiles are versioned by effective date, never by “latest”. When a partner’s spec changes on a known date, you create a second profile for the same transaction set and direction with a later effective_from. A run dated December 15 resolves December’s profile; a run dated January 5 resolves January’s.

Two profiles for the same partner, transaction set, and direction cannot have overlapping date ranges. Integrate.io refuses an overlapping create or update and names both profiles in the error.
A run date with no effective profile is an error naming the date and the ranges that do exist. There is no silent fallback to the newest version.

Platform and account scope

A profile is either account-scoped or platform-scoped:

Account profiles belong to your account and one of your trading partners. You create and edit them.
Platform profiles are a shared library curated by Integrate.io. Every account can read them. They are read-only through the API: writes return 403.

An account profile can overlay a platform base (or another profile in your own account) through parent_profile_id. The overlay inherits version, cadence, cadence_detail, file_mode, and the grain fields it does not set itself. The envelope merges key by key, and the overlay’s keys win. That lets you override a single envelope id, such as ISA06, without restating the rest. Only one level of overlay is allowed, and the overlay’s transaction_set and direction must match its parent’s. While anything overlays a profile, the base profile’s transaction_set, direction, and parent_profile_id cannot be changed, and the base cannot be deleted. The error names the profiles that reference it.

Permissions

Reading trading partners and profiles requires the permission to view connections. Creating, updating, and deleting them requires the permission to create connections. Roles scoped to specific connection groups only see partners whose connection is in one of their groups; a partner with no connection is visible to every scoped role. Anything outside your account and the platform library reads as 404.

API

Endpoints

Method	Path	Purpose
`GET`	`/{account_id}/api/trading_partners`	List partners. Paginated with `offset` and `limit`.
`GET`	`/{account_id}/api/trading_partners/{id}`	Show one partner.
`POST`	`/{account_id}/api/trading_partners`	Create a partner, optionally with its first profile versions.
`PUT`	`/{account_id}/api/trading_partners/{id}`	Update a partner.
`DELETE`	`/{account_id}/api/trading_partners/{id}`	Delete a partner and its own profiles. Blocked with a `422` naming the references while another partner’s profile overlays one of its profiles.
`GET`	`/{account_id}/api/trading_partners/{id}/resolve_profile`	Resolve which profile governs a run date.
`GET`	`/{account_id}/api/partner_profiles`	List profiles visible to the account, including the platform library. Filter with `?trading_partner_id={id}`. Paginated.
`GET`	`/{account_id}/api/partner_profiles/{id}`	Show one profile, including its `resolved` view (parent merged with child).
`POST`	`/{account_id}/api/partner_profiles`	Create an account profile. `trading_partner_id` is required.
`PUT`	`/{account_id}/api/partner_profiles/{id}`	Update a profile. `403` for platform profiles.
`DELETE`	`/{account_id}/api/partner_profiles/{id}`	Delete a profile. Blocked with a `422` naming the overlays that reference it.

Create a partner with its first profile

curl -X POST "https://api.integrate.io/{account_id}/api/trading_partners" \
  -u "{api_key}:" \
  -H "Content-Type: application/json" \
  -d '{
    "trading_partner": {
      "name": "Acme Benefits Carrier",
      "partner_type": "carrier",
      "transport": "sftp",
      "connection_id": 123,
      "outbound_path": "/inbound/from-us",
      "filename_pattern": "{partner}_{transaction_set}_{ccyymmdd}_{seq}.edi",
      "ack_behaviour": "999",
      "ack_window_hours": 24,
      "contact_email": "edi@acme.example",
      "partner_profiles_attributes": [
        {
          "transaction_set": "834",
          "direction": "outbound",
          "cadence": "weekly",
          "file_mode": "full_file",
          "envelope": {"ISA05": "ZZ", "ISA06": "SENDERID"},
          "grain_fields": ["member_id", "benefit_status", "coverage_start"],
          "effective_from": "2026-01-01"
        }
      ]
    }
  }'

The partner and its first profile save in one transaction. A partner is never created with a half-written first version.

Resolve the profile for a run date

curl "https://api.integrate.io/{account_id}/api/trading_partners/{id}/resolve_profile?transaction_set=834&direction=outbound&on=2026-12-15" \
  -u "{api_key}:"

on is an ISO date and defaults to today. The response is the governing profile, including its resolved attributes. If no profile is effective on that date, or stored data leaves two effective at once, the response is a 422 naming the date and the ranges involved.

Overlay a platform base

curl -X POST "https://api.integrate.io/{account_id}/api/partner_profiles" \
  -u "{api_key}:" \
  -H "Content-Type: application/json" \
  -d '{
    "partner_profile": {
      "trading_partner_id": 45,
      "parent_profile_id": 7,
      "transaction_set": "834",
      "direction": "outbound",
      "envelope": {"ISA06": "OURSENDERID"},
      "effective_from": "2026-01-01"
    }
  }'

The overlay inherits the base’s cadence, file mode, and grain, and overrides only ISA06.

FAQ

Q: What happens during a spec change like open enrollment? Create the next version as a second profile with effective_from set to the cutover date, and set effective_to on the current one to the day before. Both are live at once, and each run date resolves the version that governs it. Q: Why is my delete blocked? Another profile overlays one of the profiles you are deleting. The 422 body names each reference. Remove or repoint those overlays first. Q: Can I edit a platform profile? No. Platform profiles are curated centrally and read-only through the API. Overlay one with an account profile and override the fields you need. Q: Why was my connection rejected? The connection must belong to the same account and match the transport: an sftp partner needs an SFTP connection, s3 needs an Amazon S3 connection, and azure_blob needs an Azure Blob Storage connection.

Getting Started

Packages & Workflows

Sources

Transformations

Expressions & Functions

Destinations

Scheduling, Jobs & Clusters

Alerts & Monitoring

Log Drains

Security & Access

Account Management

Overview

Trading partner fields

Filename patterns

Partner profiles

Versioning by effective date

Platform and account scope

Permissions

API

Endpoints

Create a partner with its first profile

Resolve the profile for a run date

Overlay a platform base

FAQ

ETL: Partner Profile Validation Rules

ETL: EDI X12 Source

ETL: File Storage Destination

ETL: PGP Keys

​Overview

​Trading partner fields

​Filename patterns

​Partner profiles

​Versioning by effective date

​Platform and account scope

​Permissions

​API

​Endpoints

​Create a partner with its first profile

​Resolve the profile for a run date

​Overlay a platform base

​FAQ

​Related

ETL: Partner Profile Validation Rules

ETL: EDI X12 Source

ETL: File Storage Destination

ETL: PGP Keys

Overview

Trading partner fields

Filename patterns

Partner profiles

Versioning by effective date

Platform and account scope

Permissions

API

Endpoints

Create a partner with its first profile

Resolve the profile for a run date

Overlay a platform base

FAQ

Related