> ## Documentation Index
> Fetch the complete documentation index at: https://www.integrate.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# ETL: Trading Partners

> Define the partners you exchange files with and the versioned partner profiles that describe what each partner expects for a transaction set.

## 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.

> [!NOTE]
>
> 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](https://www.integrate.io/docs/etl/partner-profile-validation-rules.md) 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

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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.

## Related

> **[ETL: Partner Profile Validation Rules](https://www.integrate.io/docs/etl/partner-profile-validation-rules.md)**

> **[ETL: EDI X12 Source](https://www.integrate.io/docs/etl/using-components-edi-x12-source.md)**

> **[ETL: File Storage Destination](https://www.integrate.io/docs/etl/using-components-file-storage-destination.md)**

> **[ETL: PGP Keys](https://www.integrate.io/docs/etl/pgp-keys-account-level.md)**


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.