# Use integration action contracts

> Turn discovered actions into workflow nodes using exact handlers, configured connections, explicit output paths, and recovery rules.

Source: [https://genhealth.ai/docs/workflows/action-contracts](https://genhealth.ai/docs/workflows/action-contracts)

## Discover, then load the exact contract

```bash
curl --fail-with-body "$GENHEALTH_API_BASE/developer/v1/actions?group=Brightree&query=patient&limit=100" \
  -H "Authorization: Bearer $GENHEALTH_API_KEY"
curl --fail-with-body "$GENHEALTH_API_BASE/developer/v1/actions/brightree_create_patient_from_document" \
  -H "Authorization: Bearer $GENHEALTH_API_KEY"
curl --fail-with-body "$GENHEALTH_API_BASE/developer/v1/integration-connections" \
  -H "Authorization: Bearer $GENHEALTH_API_KEY"
```

Follow next_offset while has_more is true. Search terms are filters, not an instruction to invent an action. Copy integration_node_config from the live contract, then fill its params. An advertised action does not imply that your organization has credentials, strategy support, payer coverage, or permission to perform the requested business operation. Connection discovery reports configured, validated, and coarse status values without revealing credentials.

## Resolve inputs and identifiers

Use input_schema and fields together. A non-required field may have a runtime prerequisite or a relationship with other fields; read the reviewed description. Retrieve dynamic choices from /developer/v1/actions/{handler}/fields/{field}/options. Do not substitute labels for IDs. GenHealth document IDs, local patient IDs, Brightree patient keys, and vendor order IDs are different identifiers.

## Wire the handler payload under default

```json
{
  "expression": "{{create_patient.default.patient_key}}",
  "business_success": "{{create_patient.default.success}}"
}
```

Integration nodes wrap the handler payload under outputs.default. Use {{node_id.default.field}} in downstream expressions. Node completion and HTTP success are not business success. A handler can return success=false. Branch on the declared success field before dependent writes. A branchable_error flag by itself does not override the node error strategy. A hard failure may prevent default edges from running; do not assume an if node handles every failure. Use deployed capabilities for error_strategy and supported error ports.

| Contract signal | Agent behavior |
| --- | --- |
| output_schema_completeness=unknown | Do not invent fields or infer a successful write. Obtain a reviewed contract or validate in an isolated configured environment before wiring a write. |
| best_effort_declared | Names are known; types and optionality may be incomplete. Check business prerequisites and observed authorized test results. |
| reviewed_partial | Public descriptions and selected output types were reviewed against source. Additional keys and failure variants can exist; this is not runtime certification. |
| safety.retry_safe=false | An uncertain outcome needs reconciliation. A new run key can repeat the business operation. |
| safety.dry_run_supported=false | Do not add a fictional dry_run flag. Use synthetic data and a configured test connection. |

## Brightree patient creation

Use brightree_create_patient_from_document after demographics extraction. It requires document_id, a document belonging to the authenticated organization, extracted first and last names and birth date, a Brightree connection, and organization strategy support. It checks for an existing patient before creation. Branch on success; created=false can mean successful reuse of an existing patient. patient_id is local, while patient_key identifies Brightree. On an ambiguous write, reconcile in Brightree before retrying. The legacy brightree_create_patient handler is excluded from the public Developer API because its executor path is not implemented; do not use its cached catalog entry.

- [Brightree actions](https://genhealth.ai/docs/workflows/integrations/brightree.md): Inspect the latest published catalog and compare it with authenticated discovery.
- [Patient intake recipe](https://genhealth.ai/docs/workflows/recipes/patient-intake.md): An importable patient match/create segment.