> ## 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: Partner Profile Validation Rules

> Express a trading partner's companion-guide requirements as ordered, optionally conditional validation rules on a partner profile.

## Overview

Validation rules capture the requirements a trading partner states in its companion guide: which fields are required, which values are allowed, and what format a field must match. A rule can also carry a condition, so a requirement applies only to the records the guide says it applies to. Rules live on a [partner profile](https://www.integrate.io/docs/etl/trading-partners-account-level.md) and target the profile's `grain_fields`, which are flattened field names such as `member_id` or `benefit_status`, never X12 segment positions.

Use validation rules when a partner's guide states checks that go beyond simple element requirements, for example:

* A field that is required only when another field holds a given value.
* A field that must never carry one of a set of values the partner rejects.
* A date that must fall on or after another date in the same record.

> [!NOTE]
>
> Rules are configuration today. They are stored on the profile and returned by the API, but Integrate.io does not yet evaluate them when a job runs. Enforcement, where a blocking finding holds a file before it reaches the partner, is enabled per account separately once an account's rules have been reviewed.

## Rule anatomy

Every rule has:

| Field | Description |
| :- | :- |
| `name` | Required. Up to 255 characters. |
| `rule_type` | Required. One of `required`, `prohibited`, `length`, `pattern`, `code_list`, `blacklist`, `compare`. |
| `target_field` | Required. A field from the profile's grain. |
| `params` | Object of settings for the rule type. See below. |
| `condition` | Optional. `{field, operator, value}`. When set, the rule only applies to records where the condition holds. |
| `severity` | Required. `block` or `warn`. A `block` finding marks the file as held; a `warn` finding is recorded and delivery proceeds. |
| `message` | Optional override, up to 1000 characters. Shown instead of the generated sentence when a finding fires. |
| `position` | Evaluation order. Rules created without one land at the end. |

Every rule type becomes conditional by attaching a `condition`. `required` plus a condition is a conditional requirement; `prohibited` plus a condition is a conditional prohibition.

### Rule types and params

| Rule type | Checks | `params` |
| :- | :- | :- |
| `required` | The field is present and not blank. | None. |
| `prohibited` | The field is absent or blank. | None. |
| `length` | Character length of a present value. | `min`, `max`, or both. Whole numbers. |
| `pattern` | A present value matches a regular expression. | `pattern`. Up to 200 characters. Anchored at both ends at match time. |
| `code_list` | A present value is one of an allowed list. | `values`: flat list of allowed codes, up to 1000. |
| `blacklist` | A present value is not one of a denied list. | `values`: flat list of denied codes, up to 1000. |
| `compare` | A present value compares against another field in the same record. | `other`: the other grain field. `operator`: one of `after`, `before`, `on_or_after`, `on_or_before`, `eq`, `ne`. The date operators parse `CCYYMMDD` and ISO dates. |

`length`, `pattern`, `code_list`, `blacklist`, and `compare` stay quiet on a blank value. Presence is a `required` rule's job, so one missing field does not produce two findings.

### Conditions

A condition is `{"field": ..., "operator": ..., "value": ...}`:

| Operator | Meaning | `value` |
| :- | :- | :- |
| `eq`, `ne` | Field equals, or does not equal, the value. | Required. |
| `in`, `not_in` | Field is, or is not, in a list. | Non-empty list, up to 1000 entries. |
| `present`, `blank` | Field is present, or blank. | Not used. |

The condition's `field`, like `target_field` and a compare rule's `other`, must be one of the profile's grain fields. A rule naming an unknown field is rejected at save time, with the grain listed in the error. A profile likewise refuses to drop a grain field while a rule still uses it.

### Readable summaries

Each rule is returned with a generated `summary` sentence, for example `cobra_qualifier is required when benefit_status is C`. Set `message` to replace the generated wording in findings.

## Rules on overlays

A profile that overlays a base is governed by both rule sets: the base's rules run first, then the overlay's own. Rules on platform-scoped profiles are readable by every account and read-only through the API; writes return `403`.

## API

All rule endpoints require the same permissions as the profile they belong to: viewing connections to read, creating connections to write.

| Method | Path | Purpose |
| :- | :- | :- |
| `GET` | `/{account_id}/api/partner_profiles/{profile_id}/rules` | List the profile's rules in evaluation order. |
| `GET` | `/{account_id}/api/partner_profiles/{profile_id}/rules/{id}` | Show one rule. |
| `POST` | `/{account_id}/api/partner_profiles/{profile_id}/rules` | Create a rule. |
| `PUT` | `/{account_id}/api/partner_profiles/{profile_id}/rules/{id}` | Update a rule. |
| `DELETE` | `/{account_id}/api/partner_profiles/{profile_id}/rules/{id}` | Delete a rule. |
| `PUT` | `/{account_id}/api/partner_profiles/{profile_id}/rules/reorder` | Reorder all rules in one call. |

### Create a conditional requirement

```bash theme={null}
curl -X POST "https://api.integrate.io/{account_id}/api/partner_profiles/{profile_id}/rules" \
  -u "{api_key}:" \
  -H "Content-Type: application/json" \
  -d '{
    "profile_rule": {
      "name": "COBRA qualifier required for COBRA members",
      "rule_type": "required",
      "target_field": "cobra_qualifier",
      "condition": {"field": "benefit_status", "operator": "eq", "value": "C"},
      "severity": "block"
    }
  }'
```

### Create a code list rule

```bash theme={null}
curl -X POST "https://api.integrate.io/{account_id}/api/partner_profiles/{profile_id}/rules" \
  -u "{api_key}:" \
  -H "Content-Type: application/json" \
  -d '{
    "profile_rule": {
      "name": "Relationship code",
      "rule_type": "code_list",
      "target_field": "relationship_code",
      "params": {"values": ["18", "01", "19"]},
      "severity": "warn",
      "message": "Relationship code must be 18 (self), 01 (spouse) or 19 (child)."
    }
  }'
```

### Reorder rules

```bash theme={null}
curl -X PUT "https://api.integrate.io/{account_id}/api/partner_profiles/{profile_id}/rules/reorder" \
  -u "{api_key}:" \
  -H "Content-Type: application/json" \
  -d '{"rule_ids": [12, 10, 11]}'
```

`rule_ids` must list every rule on the profile, in the order they should be evaluated. A partial or mismatched list is refused with the profile's actual rule ids in the error.

## Limits

* Patterns are capped at 200 characters, anchored at both ends, and run under a timeout per match. A pattern that exceeds the timeout on a value fails validation of the file rather than skipping the rule.
* Values longer than 4096 characters are not pattern-matched and are reported as findings instead.
* `values` lists and `in`/`not_in` condition lists are capped at 1000 entries.
* Findings never quote more than 10 values from a list.

## FAQ

**Q: Why was my rule rejected at save time?**

The most common causes are a `target_field`, condition field, or compare `other` that is not in the profile's grain, an invalid or too-long pattern, an empty `values` list, or a `min` greater than `max`. The error names the field and lists the profile's grain fields.

**Q: What is the difference between `block` and `warn`?**

`block` marks the finding as one that holds the file so it does not reach the partner. `warn` records the finding and lets delivery proceed. Until enforcement is enabled for your account, both are recorded only.

**Q: Can I edit the rules on a platform profile?**

No. They are curated centrally. Overlay the platform profile with an account profile and add your own rules on the overlay; the base's rules still apply, followed by yours.

## Related

> **[ETL: Trading Partners](https://www.integrate.io/docs/etl/trading-partners-account-level.md)**

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


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