curl --silent --show-error --fail-with-body --request PUT \
--url 'https://api.edi.stateset.com/v1/partners/{id}/guide' \
--header "Authorization: Bearer $EDI_API_TOKEN" \
--header 'Content-Type: application/json' \
--data '{
"expected_revision": "string",
"note": "Two-person tent, green — replacement for damaged pole set.",
"overlay": {
"element_overrides": [
{
"element": 1,
"segment": "string",
"transaction_set": "string",
"value": "49.00"
}
],
"extra_segments": [
{
"elements": [
"string"
],
"tag": "priority",
"transaction_set": "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"
]
}
}'
{
"data": {
"guide": {
"overlay": {
"element_overrides": [
{
"element": 1,
"segment": "string",
"transaction_set": "string",
"value": "49.00"
}
],
"extra_segments": [
{
"elements": [],
"tag": "priority",
"transaction_set": "string"
}
]
},
"publishing_available": true,
"revision": "string",
"validation": {
"accepted_inbound": [
"string"
],
"accepted_versions": [
"string"
],
"conditional_rules": [
{
"equals": [],
"require_element": {
"element": null,
"segment": null
},
"require_segment": "string",
"when_element": 1,
"when_segment": "string"
}
],
"count_checks": {},
"element_constraints": [
{
"allowed": [],
"component": 1,
"element": 1,
"format": "numeric",
"max_len": 1,
"min_len": 1,
"qualifier_element": 1,
"qualifier_value": "49.00",
"required": true,
"segment": "string",
"sets": []
}
],
"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"
]
}
},
"snapshot": {
"author": "string",
"created_at": "2026-08-31T14:22:05Z",
"note": "Two-person tent, green — replacement for damaged pole set.",
"overlay": {
"element_overrides": [
{
"element": 1,
"segment": "string",
"transaction_set": "string",
"value": "49.00"
}
],
"extra_segments": [
{
"elements": [],
"tag": "priority",
"transaction_set": "string"
}
]
},
"partner_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"tenant_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"validation": {
"accepted_inbound": [
"string"
],
"accepted_versions": [
"string"
],
"conditional_rules": [
{
"equals": [],
"require_element": {
"element": null,
"segment": null
},
"require_segment": "string",
"when_element": 1,
"when_segment": "string"
}
],
"count_checks": {},
"element_constraints": [
{
"allowed": [],
"component": 1,
"element": 1,
"format": "numeric",
"max_len": 1,
"min_len": 1,
"qualifier_element": 1,
"qualifier_value": "49.00",
"required": true,
"segment": "string",
"sets": []
}
],
"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"
]
},
"version": 1
},
"warnings": [
{
"field": "string",
"message": "Two-person tent, green — replacement for damaged pole set.",
"severity": "string"
}
]
},
"success": true
}
Publish partner guide
Guide, immutable snapshot and audit committed together
PUT
/
v1
/
partners
/
{id}
/
guide
curl --silent --show-error --fail-with-body --request PUT \
--url 'https://api.edi.stateset.com/v1/partners/{id}/guide' \
--header "Authorization: Bearer $EDI_API_TOKEN" \
--header 'Content-Type: application/json' \
--data '{
"expected_revision": "string",
"note": "Two-person tent, green — replacement for damaged pole set.",
"overlay": {
"element_overrides": [
{
"element": 1,
"segment": "string",
"transaction_set": "string",
"value": "49.00"
}
],
"extra_segments": [
{
"elements": [
"string"
],
"tag": "priority",
"transaction_set": "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"
]
}
}'
{
"data": {
"guide": {
"overlay": {
"element_overrides": [
{
"element": 1,
"segment": "string",
"transaction_set": "string",
"value": "49.00"
}
],
"extra_segments": [
{
"elements": [],
"tag": "priority",
"transaction_set": "string"
}
]
},
"publishing_available": true,
"revision": "string",
"validation": {
"accepted_inbound": [
"string"
],
"accepted_versions": [
"string"
],
"conditional_rules": [
{
"equals": [],
"require_element": {
"element": null,
"segment": null
},
"require_segment": "string",
"when_element": 1,
"when_segment": "string"
}
],
"count_checks": {},
"element_constraints": [
{
"allowed": [],
"component": 1,
"element": 1,
"format": "numeric",
"max_len": 1,
"min_len": 1,
"qualifier_element": 1,
"qualifier_value": "49.00",
"required": true,
"segment": "string",
"sets": []
}
],
"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"
]
}
},
"snapshot": {
"author": "string",
"created_at": "2026-08-31T14:22:05Z",
"note": "Two-person tent, green — replacement for damaged pole set.",
"overlay": {
"element_overrides": [
{
"element": 1,
"segment": "string",
"transaction_set": "string",
"value": "49.00"
}
],
"extra_segments": [
{
"elements": [],
"tag": "priority",
"transaction_set": "string"
}
]
},
"partner_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"tenant_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"validation": {
"accepted_inbound": [
"string"
],
"accepted_versions": [
"string"
],
"conditional_rules": [
{
"equals": [],
"require_element": {
"element": null,
"segment": null
},
"require_segment": "string",
"when_element": 1,
"when_segment": "string"
}
],
"count_checks": {},
"element_constraints": [
{
"allowed": [],
"component": 1,
"element": 1,
"format": "numeric",
"max_len": 1,
"min_len": 1,
"qualifier_element": 1,
"qualifier_value": "49.00",
"required": true,
"segment": "string",
"sets": []
}
],
"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"
]
},
"version": 1
},
"warnings": [
{
"field": "string",
"message": "Two-person tent, green — replacement for damaged pole set.",
"severity": "string"
}
]
},
"success": true
}
Path parameters
string
required
Tenant-owned partner
Request body
GuideUpdate
string
required
string,null
PartnerOverlay,null
required
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.
Show PartnerOverlay
Show PartnerOverlay
ElementOverride[]
PartnerValidation
required
Per-partner inbound validation. Empty rules accept everything (the default), so existing partners are unaffected.
Show PartnerValidation
Show PartnerValidation
string[]
If non-empty, inbound transaction sets not in this list are rejected (e.g.
['850', '860'] for a partner that only sends orders).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.ConditionalRule[]
If-then rules, e.g. ‘when BEG02 is SA, a DTM segment is required’.
Show ConditionalRule
Show ConditionalRule
string[]
Trigger values. Empty means ‘when the element is present (non-empty)’.
ElementRef,null
A (segment tag, 1-based element position) pair.
string,null
Then this segment must be present somewhere in the transaction.
integer
required
Minimum:
0.string
required
Trigger: segment tag + 1-based element position.
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[].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.
Show ElementConstraint
Show ElementConstraint
string[]
If non-empty, the element must be one of these values.
integer,null
1-based component within an EDIFACT composite element, e.g.
2 for the reference value in RFF+ON:<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.integer
required
1-based element position, e.g.
3 for the PO1 unit of measure. Minimum: 0.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'.integer,null
Maximum length (in characters) when the element is present. Minimum:
0.integer,null
Minimum length (in characters) when the element is present. Minimum:
0.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.string,null
boolean
If true, the element must be present (non-empty).
string
required
Segment tag, e.g.
PO1.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.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.
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).
OutboundRule[]
Sourced checks for generated 855/856/810 wire, evaluated after overlays. Stored with guide snapshots and included in readiness fingerprints.
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[].object
REF qualifiers that must be present per inbound transaction set, e.g.
{'850': ['DP']} to require a department-number reference on every PO. Additional keys map to values of type string[].object
Segment tags that must be present per inbound transaction set, e.g.
{'850': ['DTM', 'REF']} to require a date and reference on every PO. The '*' key applies to every inbound set. Additional keys map to values of type string[].object
Occurrence bounds per inbound transaction set, e.g.
{'850': [{'segment': 'BEG', 'min': 1, 'max': 1}]} 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[].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.Response
GuideResponse_GuidePublication
object
required
Show data
Show data
GuideDraft
required
Show GuideDraft
Show GuideDraft
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.
boolean
required
Atomic guide publication is available on PostgreSQL deployments.
string
required
Opaque revision of the partner settings, including its environment.
PartnerValidation
required
Per-partner inbound validation. Empty rules accept everything (the default), so existing partners are unaffected.
GuideSnapshot
required
An immutable snapshot of a partner’s guide at a point in time.
Show GuideSnapshot
Show GuideSnapshot
string
required
Who captured it (
admin, partner:{id}).string (date-time)
required
string,null
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.
string
required
string
required
PartnerValidation
required
Per-partner inbound validation. Empty rules accept everything (the default), so existing partners are unaffected.
integer (int32)
required
Monotonic version, starting at 1. Minimum:
0.boolean
required
Status codes
| Code | Meaning |
|---|---|
200 | Guide, immutable snapshot and audit committed together |
404 | Unknown partner |
409 | Guide or partner settings changed; reload before publishing |
422 | Invalid guide or durable guide publishing unavailable |
Using this contract
Read the source OpenAPI document for declared schemas and alternatives. This page also includes documented corrections from the spec overlays. Example IDs and values are illustrative; replace them with records from your workspace.curl --silent --show-error --fail-with-body --request PUT \
--url 'https://api.edi.stateset.com/v1/partners/{id}/guide' \
--header "Authorization: Bearer $EDI_API_TOKEN" \
--header 'Content-Type: application/json' \
--data '{
"expected_revision": "string",
"note": "Two-person tent, green — replacement for damaged pole set.",
"overlay": {
"element_overrides": [
{
"element": 1,
"segment": "string",
"transaction_set": "string",
"value": "49.00"
}
],
"extra_segments": [
{
"elements": [
"string"
],
"tag": "priority",
"transaction_set": "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"
]
}
}'
{
"data": {
"guide": {
"overlay": {
"element_overrides": [
{
"element": 1,
"segment": "string",
"transaction_set": "string",
"value": "49.00"
}
],
"extra_segments": [
{
"elements": [],
"tag": "priority",
"transaction_set": "string"
}
]
},
"publishing_available": true,
"revision": "string",
"validation": {
"accepted_inbound": [
"string"
],
"accepted_versions": [
"string"
],
"conditional_rules": [
{
"equals": [],
"require_element": {
"element": null,
"segment": null
},
"require_segment": "string",
"when_element": 1,
"when_segment": "string"
}
],
"count_checks": {},
"element_constraints": [
{
"allowed": [],
"component": 1,
"element": 1,
"format": "numeric",
"max_len": 1,
"min_len": 1,
"qualifier_element": 1,
"qualifier_value": "49.00",
"required": true,
"segment": "string",
"sets": []
}
],
"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"
]
}
},
"snapshot": {
"author": "string",
"created_at": "2026-08-31T14:22:05Z",
"note": "Two-person tent, green — replacement for damaged pole set.",
"overlay": {
"element_overrides": [
{
"element": 1,
"segment": "string",
"transaction_set": "string",
"value": "49.00"
}
],
"extra_segments": [
{
"elements": [],
"tag": "priority",
"transaction_set": "string"
}
]
},
"partner_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"tenant_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"validation": {
"accepted_inbound": [
"string"
],
"accepted_versions": [
"string"
],
"conditional_rules": [
{
"equals": [],
"require_element": {
"element": null,
"segment": null
},
"require_segment": "string",
"when_element": 1,
"when_segment": "string"
}
],
"count_checks": {},
"element_constraints": [
{
"allowed": [],
"component": 1,
"element": 1,
"format": "numeric",
"max_len": 1,
"min_len": 1,
"qualifier_element": 1,
"qualifier_value": "49.00",
"required": true,
"segment": "string",
"sets": []
}
],
"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"
]
},
"version": 1
},
"warnings": [
{
"field": "string",
"message": "Two-person tent, green — replacement for damaged pole set.",
"severity": "string"
}
]
},
"success": true
}
Last modified on October 20, 2026