Developer Guide
Build your FSMA 204 traceability program on RegEngine's Food Safety APIs
The FDA Food Safety Modernization Act Section 204 (FSMA 204) requires companies handling foods on the Food Traceability List (FTL) [FDA] to maintain standardized traceability records [FDA]. In a recall, you must provide the FDA with a sortable spreadsheet within 24 hours [FDA].
Enforcement Delayed
FDA has proposed a 30-month extension and Congress directed FDA not to enforce before July 20, 2028. RegEngine tracks FDA timing changes so your team isn't relying on stale dates.
Critical Tracking Events (CTEs) are the building blocks of FSMA 204 compliance. Here's how to record a receiving event. RegEngine issues the API key and signing secret on request; the Quickstart explains the signature, the idempotency key and the test workspace, and the API reference lists the required KDEs for every event type.
export REGENGINE_API_KEY="rge_live_..." # from RegEngine
export REGENGINE_SIGNING_SECRET="..." # from RegEngineNOW=$(date -u +%Y-%m-%dT%H:%M:%SZ)
TODAY=$(date -u +%Y-%m-%d)
BODY=$(cat <<EOF
{
"source": "<your source system id>",
"events": [
{
"cte_type": "receiving",
"traceability_lot_code": "<the lot code you assigned>",
"product_description": "<product name>",
"quantity": "<number greater than 0>",
"unit_of_measure": "<cases | lbs | kg | pallets | each>",
"location_name": "<your facility name>",
"timestamp": "$NOW",
"kdes": {
"receive_date": "$TODAY",
"receiving_location": "<where the lot arrived>",
"immediate_previous_source": "<who sent it to you>",
"reference_document": "<your ASN or receipt id>",
"tlc_source_reference": "<the lot reference your supplier gave you>"
}
}
]
}
EOF
)
# Sign the exact bytes you send: sha256= plus the HMAC-SHA256 hex digest.
SIGNATURE="sha256=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$REGENGINE_SIGNING_SECRET" -hex | sed 's/^.* //')"
curl -X POST https://regengine.co/api/v1/webhooks/ingest \
-H "X-RegEngine-API-Key: $REGENGINE_API_KEY" \
-H "X-Webhook-Signature: $SIGNATURE" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
--data-binary "$BODY"{
"accepted": 1,
"rejected": 0,
"total": 1,
"events": [
{
"traceability_lot_code": "<the lot code you sent>",
"cte_type": "receiving",
"status": "accepted",
"event_id": "<event UUID>",
"sha256_hash": "<event hash>",
"chain_hash": "<chain hash>",
"errors": []
}
],
"ingestion_timestamp": "<server time, ISO 8601>",
"ingestion_run_id": null
}FSMA 204 defines specific events that must be recorded at each point in the supply chain:
| CTE | event_type | Required KDEs |
|---|---|---|
| Harvesting | harvesting | Location, Harvest Date, Lot Code, Product |
| Cooling | cooling | Location, Cooling Date, Lot Code, Product |
| Initial Packing | initial_packing | Location, Pack Date, TLC, Quantity |
| First Land-Based Receiving | first_land_based_receiving | Location, Landing Date, TLC, Quantity, Vessel Source |
| Shipping | shipping | Ship From/To, TLC, Carrier, Date |
| Receiving | receiving | Location, TLC, Source, Quantity, Date |
| Transformation | transformation | Input TLCs, Output TLC, Date, Location |
When the FDA requests traceability data during a recall, you have 24 hours [FDA] to provide an electronic sortable spreadsheet per 21 CFR 1.1455(c). RegEngine generates this with one API call (the fda.export scope and an active subscription are required):
curl -G https://regengine.co/api/v1/fda/export/recall \
-H "X-RegEngine-API-Key: $REGENGINE_API_KEY" \
-d "tenant_id=YOUR_WORKSPACE_ID" \
-d "tlc=<the lot code under recall>" \
-o fda_response.csvThe export includes traceability fields such as the following; FDA does not mandate this particular column layout:
Traceability Lot Code, Event Type (CTE), Product Description, Quantity, Unit of Measure, Location Description, Location Identifier (GLN), Date, Time, Reference Document Type, Reference Document NumberRegEngine performs graph-based tracing over your event data to trace products forward and backward through your supply chain:
curl -G https://regengine.co/api/v1/fda/trace/<the-lot-code> \
-H "X-RegEngine-API-Key: $REGENGINE_API_KEY" \
-d "tenant_id=YOUR_WORKSPACE_ID"Ingested events are SHA-256 hashed and chain-linked, and export bundles ship with a timestamped manifest. You can verify a downloaded bundle out-of-band via /verify.
POST /api/v1/webhooks/ingestCreate compliance eventsGET /api/v1/fda/export/recallGenerate §1.1455-formatted sortable spreadsheetGET /api/v1/fda/trace/{tlc}Upstream sources and downstream products for a lotGET /api/v1/recordsList stored events for your workspace