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

# List partners

> All trading partners (key hashes redacted)

### Response

`TradingPartner[]` — each element:

**ack\_sla\_hours** `integer,null (int32)`

Per-partner acknowledgment SLA in hours. Strict retailers chargeback on late 997s, so this overrides the global `EDI_ACK_SLA_HOURS` for monitoring and alerting. `None` falls back to the global SLA. Minimum: `0`.

**ack\_type** `string`

Which functional acknowledgment this partner receives: `997` (default) or `999` (Implementation Acknowledgment with IK3/IK4 error detail).

**api\_key\_hash** `string,null`

SHA-256 hex of this partner's API key, set via `POST /v1/partners/:id/api-key`. The plaintext key is never stored.

**as1** `As1Config,null`

Per-partner AS1 settings: the address we email outbound documents to.

**As1Config**

**partner\_email** `string` *required*

The partner mailbox that receives our EDI attachments.

**as2** `As2Config,null`

Per-partner AS2 relationship settings. Lives alongside the X12 envelope config on a trading partner; absent for partners that exchange files only.

**As2Config**

**compress\_outbound** `boolean`

Compress outbound payloads (CMS CompressedData, RFC 5402). Applied innermost: compress → sign → encrypt.

**encrypt\_outbound** `boolean`

Encrypt outbound payloads (S/MIME). Requires a \[`Security`] signer.

**mdn\_mode** `MdnMode`

How the partner returns MDN receipts. Allowed values: `'none'`, `'sync'`, `'async'`.

**mic\_algorithm** `MicAlgorithm`

MIC algorithm requested for the MDN and used to verify receipts. Allowed values: `'sha256'`, `'sha384'`, `'sha512'`.

**our\_as2\_id** `string` *required*

Our AS2 identifier (the value partners address messages to).

**partner\_as2\_id** `string` *required*

The partner's AS2 identifier.

**partner\_cert\_pem** `string,null`

The partner's X.509 certificate (PEM) — used to verify their inbound signatures, authenticate MDNs, and encrypt outbound payloads for them.

**partner\_receipt\_delivery\_url** `string,null`

Trusted partner HTTPS endpoint for receipts of inbound async messages. Must exactly match their Receipt-Delivery-Option. Distinct from our `receipt_delivery_url`, which receives receipts for outbound messages.

**partner\_url** `string` *required*

The partner's AS2 endpoint URL we POST outbound documents to.

**receipt\_delivery\_url** `string,null`

Public HTTPS callback endpoint for asynchronous receipts. Required when `mdn_mode` is `async`; sent as `Receipt-Delivery-Option` (RFC 4130).

**request\_signed\_mdn** `boolean`

Request a *signed* MDN (transport-level non-repudiation of receipt). Requires `partner_cert_pem`; unsigned or unverifiable receipts fail closed.

**require\_encrypted\_inbound** `boolean`

Require inbound messages from this partner to be encrypted. When set, a cleartext inbound message is rejected with a failure MDN. Defaults to `false`.

**require\_signed\_inbound** `boolean`

Require inbound messages from this partner to be signed. When set, an unsigned inbound message is rejected with a failure MDN instead of processed. Defaults to `false` (accept unsigned) to preserve existing behavior; enable it — together with `partner_cert_pem` — to mandate message authentication for a partner. Verification of the signature itself still depends on a configured certificate.

**sign\_outbound** `boolean`

Sign outbound payloads (S/MIME). Requires a \[`Security`] signer.

**auto\_ack\_855** `AutoAck855`

Automatic 855 acknowledgment of accepted inbound 850s: `off` (default) or `accept_all` (855 AC with every line IA, dispatched after the inbound commit; failures never fail the inbound document). Allowed values: `'off'`, `'accept_all'`.

**delimiters** `Delimiters`

The four delimiters that frame an X12 interchange. The element separator and segment terminator are dictated by the ISA segment itself; the component separator is ISA16. The repetition separator (ISA11) only exists in 00501+ interchanges.

**Delimiters**

**component** `string` *required*

**element** `string` *required*

**repetition** `string,null`

**segment** `string` *required*

**enforce\_business\_po\_identity** `boolean`

Reject a second original 850 for the same business PO, even with new control numbers. PostgreSQL retains this identity beyond document expiry.

**id** `string` *required*

Stable internal identifier, used in URLs and event payloads.

**label** `LabelProfile,null`

Per-partner label **placement profile** — the label facet of a partner companion guide. Controls the physical label (print width, length, darkness) and an optional partner-required mark. Defaults to a 4×6' thermal label at 203 dpi.

**LabelProfile**

**darkness** `integer,null (int32)`

Print darkness (ZPL `^MD`, 0–30); `None` leaves the printer default. Minimum: `0`.

**height\_dots** `integer (int32)`

Label length in dots (ZPL `^LL`). 1218 = 6' at 203 dpi. Minimum: `0`.

**partner\_mark** `string,null`

A partner-required mark printed at the label's top edge (e.g. a routing or department code the retailer mandates).

**width\_dots** `integer (int32)`

Print width in dots (ZPL `^PW`). 812 = 4' at 203 dpi. Minimum: `0`.

**name** `string` *required*

**our\_gs\_id** `string,null`

**our\_isa\_id** `string` *required*

**our\_isa\_qualifier** `string` *required*

Our ISA qualifier/ID for this relationship.

**outbound\_compliance** `OutboundCompliance`

Pre-send compliance gate for outbound 855/856/810 checked against the stored 850 (+860 changes): `off`, `warn` (default — send and report the issues), or `block` (refuse with 422 when any error-level issue exists). Allowed values: `'off'`, `'warn'`, `'block'`.

**overlay** `PartnerOverlay,null`

A per-partner outbound overlay: the configurable slice of a companion guide. Applied to a built X12 transaction set before enveloping, so the same codec serves every partner and their idiosyncrasies live on the partner record.

**PartnerOverlay**

**element\_overrides** `ElementOverride[]`

Force an element's value on the first matching segment of an outbound transaction (optionally scoped to a set) — e.g. a fixed qualifier.

**ElementOverride**

**element** `integer` *required*

1-based element position (element 1 is the first after the segment tag). Minimum: `0`.

**segment** `string` *required*

**transaction\_set** `string,null`

**value** `string` *required*

**extra\_segments** `OverlaySegment[]`

Extra segments appended to outbound transactions (optionally scoped to a transaction set) — e.g. a partner-required `REF`/`N9`/`DTM`.

**OverlaySegment**

**elements** `string[]`

**tag** `string` *required*

**transaction\_set** `string,null`

Restrict to one transaction set (e.g. `856`); `None` applies to all.

**packing\_slip** `PackingSlipProfile,null`

Per-partner packing-slip presentation. Defaults are sensible for a generic slip; a partner overlay overrides the fields its companion guide mandates.

**PackingSlipProfile**

**footer\_note** `string,null`

Optional footer note (return policy, compliance marks, partner-required statements).

**logo\_text** `string,null`

Optional logo / brand line printed above the seller name.

**seller\_name** `string` *required*

Seller / shipper name printed in the header (the 'from' identity).

**show\_sscc** `boolean`

When true, render each carton's SSCC alongside its contents — required by retailers that scan the slip against the carton label.

**partner\_gs\_id** `string,null`

GS application codes; default to the ISA IDs when omitted.

**partner\_isa\_id** `string` *required*

**partner\_isa\_qualifier** `string` *required*

The partner's ISA qualifier/ID (they are the receiver on our outbound).

**require\_asn\_ack\_before\_invoice** `boolean`

Require accepted functional acknowledgments for every recorded ASN before accepting invoice documents/events. Set from the agreed guide.

**require\_retail\_v1** `boolean`

Require explicit retail-v1 source facts for new ERP events. Previously accepted requests still replay their original receipt after enabling it.

**retail\_closure\_policy** `RetailClosurePolicy`

Opt-in review of fully rejected or cancelled orders with no fulfillment. Does not assert financial settlement or retailer business acceptance. Allowed values: `'standard'`, `'unfulfilled_terminal_review'`.

**retailer\_profile** `string,null`

Built-in retailer profile key (e.g. `walmart`, `qvc-rithum`) whose outbound rules the pre-send compliance check also enforces.

**tenant\_id** `string`

Owning tenant. Every partner belongs to exactly one tenant; an API key issued for the partner therefore implies its tenant. Defaults to `default` so single-tenant deployments and pre-tenancy records work unchanged.

**usage** `string`

ISA15 usage indicator: `P` production, `T` test.

**validation** `PartnerValidation`

Optional inbound validation rules — a subset of a partner's EDI implementation guide, enforced before translation.

**PartnerValidation**

**accepted\_inbound** `string[]`

If non-empty, inbound transaction sets not in this list are rejected (e.g. `['850', '860']` for a partner that only sends orders).

**accepted\_versions** `string[]`

If non-empty, an inbound functional group whose GS08 version is not in this list is rejected (SNIP level 2). Empty accepts any supported version — e.g. `['005010']` pins a partner certified only on 5010.

**conditional\_rules** `ConditionalRule[]`

If-then rules, e.g. 'when BEG02 is SA, a DTM segment is required'.

**ConditionalRule**

**equals** `string[]`

Trigger values. Empty means 'when the element is present (non-empty)'.

**require\_element** `ElementRef,null`

A (segment tag, 1-based element position) pair.

**require\_segment** `string,null`

Then this segment must be present somewhere in the transaction.

**when\_element** `integer` *required*

Minimum: `0`.

**when\_segment** `string` *required*

Trigger: segment tag + 1-based element position.

**count\_checks** `object`

Count-balancing rules per inbound transaction set — `CTT01` must equal the number of `PO1` segments and friends. Checked only when the counter segment is present (pair with `required_segments` to mandate it). Additional keys map to values of type `CountRule[]`.

**element\_constraints** `ElementConstraint[]`

Element-level constraints applied to matching segments anywhere in an inbound document — e.g. pin PO1-03 (unit of measure) to an allowed set.

**ElementConstraint**

**allowed** `string[]`

If non-empty, the element must be one of these values.

**component** `integer,null`

1-based component within an EDIFACT composite element, e.g. `2` for the reference value in `RFF+ON:&lt;value>` (element 1). Unset checks the element itself: an X12 element, or an EDIFACT element's first component. X12 elements have only component 1. Minimum: `0`.

**element** `integer` *required*

1-based element position, e.g. `3` for the PO1 unit of measure. Minimum: `0`.

**format** `ElementFormat,null`

X12 data-type formats an element can be pinned to. Deliberately the high-value subset: numeric identifiers, decimal amounts, and the CCYYMMDD / HHMM(SS) date-time shapes that reject the malformed values retailers charge back over. Anything not listed validates as free text. Allowed values: `'numeric'`, `'decimal'`, `'date'`, `'time'`.

**max\_len** `integer,null`

Maximum length (in characters) when the element is present. Minimum: `0`.

**min\_len** `integer,null`

Minimum length (in characters) when the element is present. Minimum: `0`.

**qualifier\_element** `integer,null`

With `qualifier_value`: apply only to occurrences whose element at this position equals the qualifier (e.g. REF where REF01 = `DP`). Minimum: `0`.

**qualifier\_value** `string,null`

**required** `boolean`

If true, the element must be present (non-empty).

**segment** `string` *required*

Segment tag, e.g. `PO1`.

**sets** `string[]`

Transaction sets the rule applies to (e.g. `['850']`); empty = every set containing the segment. Shared segments (REF, N1, DTM) mean different things in different sets.

**enforce\_x12\_envelope\_identity** `boolean`

Require inbound X12 ISA sender/receiver qualifiers and IDs, plus ISA15, to match this partner even when the caller supplies an explicit partner ID.

**enforce\_x12\_group\_identity** `boolean`

Require every inbound X12 GS02/GS03 to match the configured application sender/receiver IDs (falling back to ISA IDs when GS IDs are unset).

**outbound\_rules** `OutboundRule[]`

Sourced checks for generated 855/856/810 wire, evaluated after overlays. Stored with guide snapshots and included in readiness fingerprints.

**OutboundRule**

**kind** `string` *required*

Allowed values: `'required_segment'`.

**qualifier** `string,null`

**segment** `string` *required*

**set** `string` *required*

The outbound transaction set the rule applies to (`856`, `810`).

**source** `string` *required*

Where the requirement comes from (document + section, or code site).

**required\_qualified** `object`

Qualified-segment requirements per inbound transaction set — the guide staple `required_references` can't reach beyond REF: 'a DTM\*002 (delivery date) must be present', 'an N1 loop with N101=ST'. The `'*'` key applies to every set. Additional keys map to values of type `QualifiedSegmentRule[]`.

**required\_references** `object`

REF qualifiers that must be present per inbound transaction set, e.g. `&#123;'850': ['DP']&#125;` to require a department-number reference on every PO. Additional keys map to values of type `string[]`.

**required\_segments** `object`

Segment tags that must be present per inbound transaction set, e.g. `&#123;'850': ['DTM', 'REF']&#125;` to require a date and reference on every PO. The `'*'` key applies to every inbound set. Additional keys map to values of type `string[]`.

**segment\_cardinality** `object`

Occurrence bounds per inbound transaction set, e.g. `&#123;'850': [&#123;'segment': 'BEG', 'min': 1, 'max': 1&#125;]&#125;` for 'exactly one BEG' or a guide's 'max 200 PO1 lines'. The `'*'` key applies to every set; a set-specific rule for the same segment takes precedence. Additional keys map to values of type `CardinalityRule[]`.

**warning\_codes** `string[]`

Validation issue codes (e.g. `too_long`, `value_not_allowed`) that are advisory for this partner: matching issues are reported on the accepted document and acknowledged `E` (accepted with errors) in the 997/999 instead of rejecting the transaction. For EDIFACT, a parsed, mapped message is accepted with findings in the report and ledger; CONTRL reports acceptance without inventing a syntax-error code. Unlisted guide codes and parser failures still reject.

**van** `VanConfig,null`

**VanConfig**

**mailbox** `string` *required*

Mailbox slug under the provider.

**provider** `string`

`stateset-network` for our native managed network, or an interconnect key such as `sps-commerce` when a bridge is configured.

**version** `string`

GS08 version, e.g. `004010`.

### Status codes

| Code | Meaning |
| - | - |
| `200` | All trading partners (key hashes redacted) |
| `403` | Admin credential required |

### Using this contract

Read the [source OpenAPI document](https://docs.stateset.com/spec/edi.json) for declared schemas and alternatives.
This page also includes documented corrections from the [spec overlays](https://github.com/stateset/docs/tree/main/spec/overlays).
Example IDs and values are illustrative; replace them with records from your workspace.

```bash cURL theme={null}
curl --silent --show-error --fail-with-body --request GET \
  --url 'https://api.edi.stateset.com/v1/partners' \
  --header "Authorization: Bearer $EDI_API_TOKEN"
```

```json 200 theme={null}
[
  {
    "ack_sla_hours": 1,
    "ack_type": "string",
    "api_key_hash": "YOUR_API_KEY",
    "as1": {
      "partner_email": "string"
    },
    "as2": {
      "compress_outbound": true,
      "encrypt_outbound": true,
      "mdn_mode": "none",
      "mic_algorithm": "sha256",
      "our_as2_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "partner_as2_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "partner_cert_pem": "string",
      "partner_receipt_delivery_url": "string",
      "partner_url": "string",
      "receipt_delivery_url": "string",
      "request_signed_mdn": true,
      "require_encrypted_inbound": true,
      "require_signed_inbound": true,
      "sign_outbound": true
    },
    "auto_ack_855": "off",
    "delimiters": {
      "component": ">",
      "element": "*",
      "repetition": "string",
      "segment": "~"
    },
    "enforce_business_po_identity": true,
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "label": {
      "darkness": 1,
      "height_dots": 1,
      "partner_mark": "string",
      "width_dots": 1
    },
    "name": "Two-Person Tent",
    "our_gs_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "our_isa_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "our_isa_qualifier": "string",
    "outbound_compliance": "off",
    "overlay": {
      "element_overrides": [
        {
          "element": 1,
          "segment": "string",
          "transaction_set": "string",
          "value": "49.00"
        }
      ],
      "extra_segments": [
        {
          "elements": [
            "string"
          ],
          "tag": "priority",
          "transaction_set": "string"
        }
      ]
    },
    "packing_slip": {
      "footer_note": "string",
      "logo_text": "https://cdn.example.com/products/tent-2p.jpg",
      "seller_name": "string",
      "show_sscc": true
    },
    "partner_gs_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "partner_isa_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "partner_isa_qualifier": "string",
    "require_asn_ack_before_invoice": true,
    "require_retail_v1": true,
    "retail_closure_policy": "standard",
    "retailer_profile": "string",
    "tenant_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "usage": "string",
    "validation": {
      "accepted_inbound": [
        "string"
      ],
      "accepted_versions": [
        "string"
      ],
      "conditional_rules": [
        {
          "equals": [
            "string"
          ],
          "require_element": {
            "element": 1,
            "segment": "string"
          },
          "require_segment": "string",
          "when_element": 1,
          "when_segment": "string"
        }
      ],
      "count_checks": {},
      "element_constraints": [
        {
          "allowed": [
            "string"
          ],
          "component": 1,
          "element": 1,
          "format": "numeric",
          "max_len": 1,
          "min_len": 1,
          "qualifier_element": 1,
          "qualifier_value": "49.00",
          "required": true,
          "segment": "string",
          "sets": [
            "string"
          ]
        }
      ],
      "enforce_x12_envelope_identity": true,
      "enforce_x12_group_identity": true,
      "outbound_rules": [
        {
          "kind": "required_segment",
          "qualifier": "string",
          "segment": "string",
          "set": "string",
          "source": "string"
        }
      ],
      "required_qualified": {},
      "required_references": {},
      "required_segments": {},
      "segment_cardinality": {},
      "warning_codes": [
        "string"
      ]
    },
    "van": {
      "mailbox": "string",
      "provider": "string"
    },
    "version": "2026-08-01"
  }
]
```


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