Create Audit Trail

This endpoint is asynchronous. It returns 202 Accepted with a dds_record_task envelope (and a Location header) — not the record(s). A worker resolves the filter, groups the resolved plots by (country_code, commodity, supplier), runs assessments per group, and inserts one dds_record + version 1 atomically per group. The record(s) exist only once the task reaches completed.

None at the URL — the route is top-level under /regulations/eudr/audit-trail. Plot visibility is enforced server-side: only plots visible to the caller's organization are eligible. The new record is owned by the caller's active org; its plot set may span any number of asset tasks the caller can see.

Only filter (which resolves the plot set) is meaningful as a required input; every other block is optional:

• operator — optional. When omitted, the acting organisation's stored operator defaults are used (see PATCH /organizations/me); if neither the body nor the org defaults provide a complete operator, the POST returns 400 naming the missing fields. When supplied it must be complete and valid — there is no per-field merge with the org defaults.
• commodity — optional. You can create a record before the product/HS-code details are known. When omitted, the version's commodity columns are left NULL; you populate them later via Update DDS Record. Filing is then blocked until they're set — Submit DDS returns 422 with a commodity_missing pre-submission blocker. NOTE: when a call auto-splits into multiple records (across commodity, country, or supplier), a single supplied commodity block — whose quantity can't be apportioned across the split — is not applied; every split record stores NULL commodity and you set each via PATCH before submit.
• separate_by — accepted by the schema (["facility" | "tag"]) but not yet supported: records are auto-split by (country_code, commodity, supplier) only for now, so a non-empty separate_by returns 400. Finer separation (one record per facility / per tag) is a planned follow-up.

operator and commodity are editable via Update DDS Record while no version has been submitted, and are visible on the GET response.

Submission metadata (TRACES activity type, internal reference number, etc.) is not an input to create. The handler stamps placeholder values on v1; operators supply the real values before the version is filed with TRACES — that input moves to a dedicated update / submit-time payload.

Filter keys use the dot-notation convention shared with /locations/* (see schemas/locations.ts). assets.* keys live in the same namespace whether the request is a querystring or JSON body.

{
  "data": {
    "type": "dds_record",
    "attributes": {
      "name": "Q2 2026 cocoa shipment",   // optional, max 255 chars
      "filter": {
        "plot_id":          { "in":  ["uuid", ...] },          // or { "eq": "uuid" }; up to 1000 ids
        "country_code":     { "eq":  "GH" },
        "commodity":        { "eq":  "cocoa" },
        "area_ha":          { "gte": 0.5, "lte": 1000 },
        "tag":              { "in":  ["pilot-2026"] },         // or { "eq": "name" }; tag NAMES
        "facility_id":      { "in":  ["fac_123", ...] },       // or { "eq" }; facility.id (tile_ids on /locations)
        "facility_name":    { "contains": "mill" },            // string-condition; facility's NORMALIZED name
        "supplier_id":      { "eq":  "uuid" },                  // or { "in": ["uuid", ...] }; global supplier id
        "supplier_external_id": { "in": ["CV-001"] },          // or { "eq" }; your per-org `supplierid`
        "supplier_name":    { "contains": "verde" },           // string-condition
        "supplier_country": { "eq":  "BR" },                   // string-condition; same for supplier_city, supplier_region, supplier_postcode, supplier_address_line1, supplier_address_line2, supplier_statement
        "assets.task_id":   { "eq":  "uuid" },                  // or { "in": ["uuid", ...] }; ≤ 100 ids
        "assets.filename":  { "contains": "shipment" },        // string-condition
        "assets.data.Company": { "eq":  "Acme" },              // string-condition
        "assets.data.Region":  { "in":  ["west", "central"] }  // ≤ 10 assets.data.* keys
      }
    }
  }
}

{ "eq":         "exact value" }
| { "in":       ["v1", "v2"] }   // ≤ 50 entries
| { "contains": "substr" }       // case-insensitive ILIKE %substr%
| { "startsWith": "prefix" }     // case-insensitive ILIKE prefix%

reuse_assessments_within_days controls how aggressively the worker reuses previously-computed assessments when resolving v1's plot assessments:

Pass false after a methodology bump (or any time the operator wants a guaranteed-fresh signal); pass a smaller number (e.g. 7) to require recent assessments without bypassing the cache entirely.

Three blocks travel together on a DDS submission and they are often confused — be explicit which entity each one refers to:

• operator — the legal entity actually placing the product on the EU market (or the trader handling it). This is the party EUDR Article 9 names as accountable for the DDS; their name, address, EORI/VAT, and contact details end up on the TRACES envelope. For REPRESENTATIVE_OPERATOR filings this same entity becomes the wire representedOperator (Epoch files on its behalf); for OPERATOR filings the submitter identity is the authenticated TRACES account and no represented operator is sent. Falls back to the acting org's operator defaults when omitted.

• commodity — the goods this DDS covers, not an entity. Carries the product identification fields TRACES expects on the submission envelope: HS code, product type, free-text description, quantity in kilograms, and species names (mandatory for timber and timber-derived products, optional otherwise). Snapshotted on the record's current version at create time; editable via Update DDS Record until the version has a submit-lifecycle event in the audit log.

• Deforestation metric selection — for each plot the server picks the latest deforestation-detection job where:

  1. monitoring_start = '2020-12-31' (EUDR Article 2 cutoff), then
  2. used_ccdc = true (CCDC/enhanced) wins over used_ccdc = false, then
  3. tiebreaker is most recent ingestion_date.

  Plots with no EUDR-valid metric are stamped plot_for_job_id = null and surface in completeness.missing_deforestation_metric.

• Assessment selection — for each plot, every assessment attached to its location is pinned into the version's snapshot. Missing assessment types stay null.

• Methodology versions are aggregated per assessment type by picking the modal methodology_version value across the pinned assessments; null when absent.

Returns a dds_record_task envelope — not the record(s). Poll it via Get Audit Trail Task.

On completed, result carries:

Synchronous (returned on this POST):

Asynchronous (surface on the task, see Get Audit Trail Task):

A mixed commodity/country plot set is not an error — it auto-splits into one record per group (see above).

Required scope: eudr:write