Skip to main content
Programmatic equivalent of two dashboard pages under Compliance: the traceability plan’s Contact and lot codes form and the Retention policy form. Each page and its API route write through the same service and the same validation, so a setting saved on one reads back on the other, and a value one refuses the other refuses too.
  • The designated contact is the person the FDA reaches for traceability records within 24 hours. FSMA 204 requires one on every traceability plan; each new plan version copies the contact saved here when it is generated, and earlier versions keep the contact they had.
  • The TLC prefix and pattern build the Traceability Lot Codes the organization assigns when it receives Food Traceability List food from an exempt supplier that sent none.
  • The retention policy sets how many years each kind of traceability record is kept before it may be deleted. FSMA 204 requires at least 2.

​
When to use

  • The organization has no designated contact yet, or the contact changed.
  • The organization wants its assigned lot codes to follow its own format.
  • A customer contract asks for records to be kept longer than 2 years.

​
Auth

X-API-Key header or OAuth token. Reading needs any member of the organization (or any API key of it). Writing needs an OWNER, MANAGER or EDITOR (or an API key with the EDITOR role or above): a read-only key gets 403. An organization the caller does not belong to is 404.

​
Flow

  • GET .../fsma-settings — designated_contact_name, designated_contact_email, designated_contact_phone, tlc_prefix and tlc_pattern. An empty text field is not set.
  • PATCH .../fsma-settings — send only the fields you are changing; an empty string clears a contact field. tlc_prefix is up to 16 characters, and empty means the organization’s GLN is used instead. tlc_pattern may use only {prefix}, {date} (YYYYMMDD), {sequence} and {gtin}, with format specs such as {sequence:04d}, and must contain {sequence}; empty restores {prefix}-{date}-{sequence:04d}.
  • GET .../retention-policy — the minimum whole years for cte_min_years (Critical Tracking Events), epcis_event_min_years (EPCIS events and the reference documents they name), product_lot_min_years, bulk_export_job_min_years and audit_event_min_years. An organization that never changed its policy reads 2 for each.
  • PATCH .../retention-policy — send only the minimums you are changing, each a whole number from 0 to 32767. Lowering a minimum never deletes a record; it only lets one be deleted sooner.
null is 422 on both PATCH routes. A value the dashboard would refuse — an invalid email address, a pattern with an unknown token or without {sequence}, a negative number of years — is 422, with one details row per field, such as ["body", "data", "tlc_pattern"].

​
Verify

  1. GET each resource you changed and confirm it reads back with the values you intended.
  2. Confirm no setting you did not mean to touch changed.