Skip to main content
POST
/
api
/
v1
/
process-field
Process Field
curl --request POST \
  --url https://esa.acreblitz.com/api/v1/process-field \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "provider_id": "<string>",
  "provider_field_id": "<string>",
  "account_id": "<string>",
  "field_name": "<string>",
  "field_boundary": {},
  "year": 123,
  "include_mitigation_options": true
}
'
{
  "success": true,
  "field_id": "<string>",
  "provider_field_id": "<string>",
  "soil_data": {},
  "counties": [
    {}
  ],
  "pulas": [
    {}
  ],
  "mitigations_applied": [
    {}
  ],
  "mitigation_options": [
    {}
  ],
  "steps": {},
  "summary": {}
}

Documentation Index

Fetch the complete documentation index at: https://docs.acreblitz.com/llms.txt

Use this file to discover all available pages before exploring further.

Submit a field boundary to run the full ESA runoff pipeline. The endpoint:
  1. Resolves or creates the field by (provider_field_id, provider_id).
  2. Persists the boundary and runs county/state intersection.
  3. Detects intersecting PULAs.
  4. Retrieves USDA SSURGO soil data (dominant hydrologic group, average slope).
  5. Auto-applies field-level epa_runoff mitigation measures based on slope, county relief points, and soil hydrologic group.
  6. Optionally returns the full epa_runoff mitigation options tree with selection state for the field/year.
This endpoint is idempotent on (provider_field_id, provider_id) — resubmitting the same field updates the existing record rather than creating a duplicate, and previously-applied mitigation measures are not re-inserted.

​
Request Body

​
Required Fields

​
provider_id
string
required
Your internal provider identifier, assigned by AcreBlitz.
​
provider_field_id
string
required
Your internal field identifier. The (provider_field_id, provider_id) pair uniquely identifies a field across calls.
​
account_id
string
required
Your customer account identifier. Stored on the field record for downstream reporting.
​
field_name
string
required
Name of the field. Stored on the field record and displayed in compliance reports.
​
field_boundary
object
required
GeoJSON Feature with Polygon or MultiPolygon geometry in EPSG:4326 (WGS84).
Example
{
  "type": "Feature",
  "geometry": {
    "type": "Polygon",
    "coordinates": [[
      [-95.284265, 42.263233],
      [-95.284470, 42.254180],
      [-95.267536, 42.254063],
      [-95.267341, 42.263116],
      [-95.284265, 42.263233]
    ]]
  }
}

​
Optional Fields

​
year
integer
Year for the annual mitigation record. Defaults to the current calendar year.
​
include_mitigation_options
boolean
default:"false"
When true, the response includes the full epa_runoff mitigation options tree (categories → options → sub-options) with a selected flag on each sub-option indicating whether it is currently applied to the field for the given year, plus a total_points tally.

​
Response

​
success
boolean
required
Whether the pipeline completed end-to-end.
​
field_id
string
required
Internal AcreBlitz field UUID resolved from provider_field_id.
​
provider_field_id
string
required
Echo of the provider’s field identifier from the request.
​
soil_data
object
Soil analysis from USDA SSURGO. null if the soil step failed (the rest of the pipeline still runs).
FieldTypeDescription
dominant_hydgrpdcdstring | nullDominant hydrologic soil group (A, B, C, D, or compound like B/D)
weighted_avg_slopegradwtanumber | nullArea-weighted average slope (percent)
hydgrpdcd_analysisobjectPer-HSG breakdown with area_sqm and percentage
musym_analysisobjectPer-map-unit breakdown with muname, area_sqm, and percentage
​
counties
array
Counties intersecting the field. Each entry contains:
FieldTypeDescription
geo_idstringCounty GEOID (e.g. "0500000US19153")
state_fipsstringState FIPS code
county_fipsstringCounty FIPS code
county_namestringCounty name
mitigation_pointsintegerEPA county-relief mitigation points (0, 2, 3, or 6)
​
pulas
array
required
PULA IDs intersecting the field boundary.
​
mitigations_applied
array
required
Sorted list of epa_runoff sub_option_ids currently applied to the field for the given year. Includes any auto-applied measures from this call as well as any pre-existing measures.
​
mitigation_options
array
Full epa_runoff mitigation tree (only present when include_mitigation_options=true). An array of categories, each with nested options and sub-options.Each category contains:
FieldTypeDescription
idintegerCategory ID
codestringCategory code
labelstringDisplay label
descriptionstring | nullOptional description
max_selectinteger | nullMaximum sub-options selectable in this category
sort_orderintegerDisplay order
optionsarrayNested options
Each option contains:
FieldTypeDescription
idintegerOption ID
codestringOption code
labelstringDisplay label
descriptionstring | nullOptional description
has_sub_optionsbooleanWhether this option has selectable sub-options
max_selectinteger | nullMaximum sub-options selectable in this option
helper_textstring | nullUX helper text
helper_linkstring | nullUX helper URL
sub_optionsarrayNested sub-options
Each sub-option contains:
FieldTypeDescription
idintegerSub-option ID (matches entries in mitigations_applied)
codestring | nullSub-option code
labelstringDisplay label
pointsinteger | nullMitigation points awarded if selected
hydrologic_soil_groupstring | nullHSG filter (A_B, C_D, or null for all)
helper_textstring | nullUX helper text
helper_linkstring | nullUX helper URL
selectedbooleanWhether this sub-option is currently applied to the field for the given year
implementation_datestring | nullDate the measure was applied (only when selected=true)
notesstring | nullNotes recorded with the measure (only when selected=true)
​
steps
object
required
Per-step status for the pipeline. Keys: county_state, pula_detection, soil_data, auto_mitigations, and (when requested) mitigation_options. Each value contains:
FieldTypeDescription
successbooleanWhether this step succeeded
errorstring | nullError message if the step failed
dataobject | nullStep-specific result payload
​
summary
object
required
Roll-up counters for the call.
FieldTypeDescription
pula_countintegerNumber of PULAs intersecting the field
soil_availablebooleanWhether soil data was retrieved successfully
mitigations_applied_countintegerNumber of currently-applied epa_runoff sub-options
total_pointsintegerSum of points across selected sub-options (only computed when include_mitigation_options=true)

​
Examples

cURL
curl -X POST https://esa.acreblitz.com/api/v1/process-field \
  -H "X-API-Key: $ACREBLITZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider_id": "your_provider_id",
    "provider_field_id": "field-001",
    "account_id": "acct-98765",
    "field_name": "North 40",
    "field_boundary": {
      "type": "Feature",
      "geometry": {
        "type": "Polygon",
        "coordinates": [[
          [-95.284265, 42.263233],
          [-95.284470, 42.254180],
          [-95.267536, 42.254063],
          [-95.267341, 42.263116],
          [-95.284265, 42.263233]
        ]]
      }
    }
  }'

{
  "success": true,
  "field_id": "a3393468-8c3a-45a3-9fce-9d71bdb58489",
  "provider_field_id": "test_field_001",
  "soil_data": {
    "dominant_hydgrpdcd": "C",
    "weighted_avg_slopegradwta": 9.1,
    "hydgrpdcd_analysis": {
      "C": { "area_sqm": 471285.35, "percentage": 50.83 },
      "D": { "area_sqm": 249185.38, "percentage": 26.87 },
      "B/D": { "area_sqm": 130124.66, "percentage": 14.03 }
    },
    "musym_analysis": {
      "M162B": {
        "muname": "Downs silt loam, till plain, 2 to 5 percent slopes",
        "area_sqm": 231573.23,
        "percentage": 24.97
      }
    }
  },
  "counties": [
    {
      "geo_id": "0500000US19153",
      "state_fips": "19",
      "county_fips": "153",
      "county_name": "Polk",
      "mitigation_points": 2
    },
    {
      "geo_id": "0500000US19181",
      "state_fips": "19",
      "county_fips": "181",
      "county_name": "Warren",
      "mitigation_points": 0
    }
  ],
  "pulas": [87],
  "mitigations_applied": [12, 24],
  "mitigation_options": null,
  "steps": {
    "county_state": { "success": true, "error": null, "data": {} },
    "pula_detection": { "success": true, "error": null, "data": { "pula_count": 1 } },
    "soil_data": { "success": true, "error": null, "data": { "dominant_hydgrpdcd": "C", "weighted_avg_slopegradwta": 9.1 } },
    "auto_mitigations": { "success": true, "error": null, "data": { "mitigations_applied": [12, 24] } }
  },
  "summary": {
    "pula_count": 1,
    "soil_available": true,
    "mitigations_applied_count": 2,
    "total_points": 0
  }
}
The mitigation_options array contains the full epa_runoff tree (6 categories, ~30 options, ~50+ sub-options). Each sub-option carries a selected flag — true if its id appears in mitigations_applied. The slice below shows just the County-based mitigation relief option to illustrate the structure; your response will include all categories.
{
  "id": 2,
  "code": "field_characteristics",
  "label": "Field Characteristics",
  "description": "Natural characteristics of the field that reduce runoff",
  "max_select": null,
  "sort_order": 2,
  "options": [
    {
      "id": 13,
      "code": "county_based_mitigation_relief",
      "label": "County-based mitigation relief",
      "description": "Pesticide runoff value based off of the runoff vulnerability map and County List",
      "has_sub_options": true,
      "max_select": 1,
      "helper_text": "EPA analyzed the runoff vulnerability of counties...",
      "helper_link": "https://www.epa.gov/pesticides/mitigation-menu-measure-descriptions#pesticide-runoff",
      "sort_order": 1,
      "sub_options": [
        {
          "id": 12,
          "label": "Pesticide runoff vulnerability - high",
          "points": 0,
          "hydrologic_soil_group": null,
          "selected": true,
          "implementation_date": "2026-04-29",
          "notes": "Using available county points from Warren - 0 points."
        },
        {
          "id": 11,
          "label": "Pesticide runoff vulnerability - low",
          "points": 3,
          "hydrologic_soil_group": null,
          "selected": false,
          "implementation_date": null,
          "notes": null
        }
        // ... additional sub-options (id 9, 10) omitted
      ]
    }
    // ... additional options in this category omitted
  ]
}
// ... 5 more categories omitted (Application Parameters, In-Field Mitigation Measures,
// Edge-of-Field Mitigation Measures, Adjacent-to-Field Mitigation Measures, Other)
When total_points in summary is computed (only when include_mitigation_options=true), it is the sum of points across every sub-option where selected=true.

​
Auto-Applied Mitigation Logic

The auto_mitigations step inspects the field’s soil, slope, and county data and inserts EPA-approved field-level credits into the annual runoff mitigation record:
TriggerSub-option IDDescription
Always applied24Digital tracking credit
Slope < 3%17Naturally low slope or flat fields
County mitigation_points = 012Pesticide runoff vulnerability — high
County mitigation_points = 210Pesticide runoff vulnerability — medium
County mitigation_points = 311Pesticide runoff vulnerability — low
County mitigation_points = 69Pesticide runoff vulnerability — very low
Soil HSG = A27Predominantly sandy soils (HSG A)
Soil HSG = B or A/B28Moderately sandy soils (HSG B)
When a county has multiple mitigation_points values, the lowest value is used. Existing measures are never duplicated — re-running the endpoint on the same field is safe.

​
Notes

Idempotency: The (provider_field_id, provider_id) pair makes the endpoint idempotent. Resubmitting the same field updates the existing record and replaces its boundary, but previously-applied mitigation measures are preserved.
Fail-forward soil step: If USDA SSURGO is unreachable, soil_data is null and the soil_data step is marked failed, but the rest of the pipeline still runs. Soil-dependent auto-credits (sub-options 17, 27, 28) are simply skipped in that case.
Selection state: Use mitigations_applied for a flat list of currently-applied sub-option IDs, or include_mitigation_options=true to see the full tree with each sub-option’s selected flag. The selection set is the same in both views.
GeoJSON Format: The field_boundary must be a GeoJSON Feature with a Polygon or MultiPolygon geometry in EPSG:4326 (WGS84). MultiPolygon is supported for fields with excluded areas or multiple sections.