{"openapi":"3.0.0","info":{"version":"1.0.0","title":"DTN Farm Intelligence API","description":"The Farm Intelligence API provides programmatic access to DTN's agricultural data — producer records,\nland metadata, crop history, and related datasets. It is organized into three surfaces plus shared utilities:\n\n- **Producer API** — Producer discovery, details, and relationship data\n- **Land API** — Land search, metadata, crop history, soil, and geospatial data\n- **Linked Data API** — Segments, portfolios, and batch operations\n- **Shared Utilities** — Crop codes, geographic areas (unmetered)\n\n## Authentication\n\nAll endpoints require OAuth 2.0 client credentials authentication. Obtain a token from the DTN DAIS gateway\nwith your client_id, client_secret, and the Farm Intelligence audience.\n\n## Credit Metering\n\nEndpoints are classified as:\n- **Metered (1 credit per record)** — Producer and Land data endpoints\n- **Unmetered (discovery class)** — Search, codes, geographic areas\n\nResponse headers include credit usage information:\n- `X-Credit-Cost` — Credits consumed by this request\n- `X-Credits-Remaining` — Remaining balance\n- `X-Credit-Pool-Reset` — Contract reset date","contact":{"name":"DTN Agriculture Intelligence Team","email":"agintel@dtn.com"},"x-logo":{"url":"https://www.dtn.com/wp-content/uploads/2019/03/dtn-logo-tag.png","altText":"DTN"}},"servers":[{"description":"Development","url":"https://api-farm-intelligence.dev.ag.zones.dtn.com"},{"description":"Staging","url":"https://api-farm-intelligence.stg.ag.zones.dtn.com"},{"description":"Production","url":"https://api-farm-intelligence.prd.ag.zones.dtn.com"}],"security":[{"clientCredentials":[]}],"paths":{"/api/v1/producer/search/radius":{"get":{"operationId":"searchProducersByRadius","summary":"Search producers by radius","description":"Find producers whose registered address falls within a radius of a geographic point.\nReturns the full producer record for each match. Results are sorted by proximity.\n\n**Billing:** Metered — 1 credit per producer returned.\n","tags":["Producer Search"],"parameters":[{"in":"query","name":"lat","required":true,"schema":{"type":"number","format":"float","example":41.6},"description":"Latitude of the center point (decimal degrees, WGS84)."},{"in":"query","name":"lon","required":true,"schema":{"type":"number","format":"float","example":-93.6},"description":"Longitude of the center point (decimal degrees, WGS84)."},{"in":"query","name":"radius","required":true,"schema":{"type":"number","example":16000},"description":"Search radius in meters. Maximum approximately 16,093m (10 miles)."},{"in":"query","name":"limit","required":false,"schema":{"type":"integer","default":10,"minimum":1,"maximum":500},"description":"Maximum number of results to return."},{"in":"query","name":"offset","required":false,"schema":{"type":"integer","default":0,"minimum":0},"description":"Number of results to skip (for pagination)."}],"responses":{"200":{"description":"Producers found within the radius.","headers":{"X-Credit-Cost":{"schema":{"type":"integer"},"description":"Number of credits consumed by this request."},"X-Credits-Remaining":{"schema":{"type":"integer"},"description":"Credits remaining in your account."},"X-Credit-Pool-Reset":{"schema":{"type":"string","format":"date-time"},"description":"Contract reset date."}},"content":{"application/json":{"schema":{"type":"object","properties":{"producers":{"type":"array","items":{"$ref":"#/components/schemas/Producer"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}},"example":{"producers":[{"producerId":5091294,"firstName":"John","lastName":"Smith","companyName":"Smith Farms LLC","address":"123 Farm Rd","city":"Des Moines","state":"IA","postalCode":"50316-2921","fipsCode":"19153","county":"Polk","lat":41.601,"lon":-93.609,"locationAccuracy":"Address was DPV confirmed for the primary number only, and secondary number information was missing.","role":"operator","status":"customer","externalID":"CRM-12345","phones":["515-555-0100"],"emails":["john@smithfarms.com"]},{"producerId":8890647,"firstName":"Jane","lastName":"Doe","companyName":null,"address":"456 County Line Rd","city":"Des Moines","state":"IA","postalCode":"50316-3413","fipsCode":"19153","county":"Polk","lat":41.598,"lon":-93.612,"locationAccuracy":"Address was DPV confirmed for the primary number only, and secondary number information was missing.","role":"owner-operator","status":"prospect","externalID":null,"phones":[],"emails":[]}],"pagination":{"total":15,"hasMore":true}}}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"bad-request","title":"Invalid Request","status":400,"detail":"Validation failed.","instance":"urn:dtn:farm-intel-external-api:/api/v1/producer/search/radius:requestId:abc123","errors":[{"message":"Required query parameter lat is invalid or missing.","parameter":"lat"}]}}}},"401":{"description":"Missing or invalid authentication token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"unauthorized","title":"Error while authenticating the user","status":401,"detail":"Bearer Token is malformed.","instance":"urn:dtn:farm-intel-external-api:requestId:example-id"}}}},"429":{"description":"Insufficient credits remaining.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"insufficient-credits","title":"Insufficient Credits","status":429,"detail":"This request requires 15 producer credits, but only 10 remain."}}}}}}},"/api/v1/producers/{partyId}":{"get":{"operationId":"getProducerById","summary":"Get producer details","description":"Retrieve the full detail record for a single producer by their party ID.\nReturns contact information, address, role, status, and external identifiers.\n\n**Billing:** Metered — 1 credit per request.\n","tags":["Producer Details"],"parameters":[{"in":"path","name":"partyId","required":true,"schema":{"type":"integer","example":5091294},"description":"Unique producer identifier."}],"responses":{"200":{"description":"Producer details.","headers":{"X-Credit-Cost":{"schema":{"type":"integer"},"description":"Number of credits consumed by this request."},"X-Credits-Remaining":{"schema":{"type":"integer"},"description":"Credits remaining in your account."},"X-Credit-Pool-Reset":{"schema":{"type":"string","format":"date-time"},"description":"Contract reset date."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProducerDetail"},"example":{"partyId":5091294,"firstName":"John","lastName":"Smith","companyName":"Smith Farms LLC","address":"123 Farm Rd","city":"Des Moines","state":"IA","postalCode":"50316-2921","county":"Polk","email":"john@smithfarms.com","phone":"515-555-0100","externalId":"CRM-12345"}}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"bad-request","title":"Invalid Request","status":400,"detail":"Validation failed.","instance":"urn:dtn:farm-intel-external-api:/api/v1/producers/abc:requestId:abc123","errors":[{"message":"Path parameter partyId must be a valid integer.","parameter":"partyId"}]}}}},"401":{"description":"Missing or invalid authentication token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"unauthorized","title":"Error while authenticating the user","status":401,"detail":"Bearer Token is malformed.","instance":"urn:dtn:farm-intel-external-api:requestId:example-id"}}}},"404":{"description":"Producer not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"not-found","title":"Not Found","status":404,"detail":"Resource not found","instance":"urn:dtn:farm-intel-external-api:/api/v1/producers/999999:requestId:abc123"}}}},"429":{"description":"Insufficient credits remaining.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"insufficient-credits","title":"Insufficient Credits","status":429,"detail":"This request requires 1 producer credit, but only 0 remain."}}}}}}},"/api/v1/producers/{partyId}/land":{"get":{"operationId":"getProducerLand","summary":"Get land linked to a producer","description":"Retrieve the land parcel IDs linked to a producer. Returns a list of land-party\nassociations. Use /land/{landId} to get full metadata for each parcel.\n\n**Billing:** Unmetered (discovery class).\n","tags":["Producer Relationships"],"parameters":[{"in":"path","name":"partyId","required":true,"schema":{"type":"integer","example":5091294},"description":"Unique producer identifier."}],"responses":{"200":{"description":"Land parcels linked to the producer.","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"partyId":{"type":"integer","description":"Producer identifier.","example":5091294},"landId":{"type":"integer","description":"Land parcel identifier.","example":3456789}}}},"example":[{"partyId":5091294,"landId":3456789},{"partyId":5091294,"landId":3456790},{"partyId":5091294,"landId":3456791}]}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"bad-request","title":"Invalid Request","status":400,"detail":"Validation failed.","instance":"urn:dtn:farm-intel-external-api:/api/v1/producers/abc/land:requestId:abc123","errors":[{"message":"Path parameter partyId must be a valid integer.","parameter":"partyId"}]}}}},"401":{"description":"Missing or invalid authentication token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"unauthorized","title":"Error while authenticating the user","status":401,"detail":"Bearer Token is malformed.","instance":"urn:dtn:farm-intel-external-api:requestId:example-id"}}}}}}},"/api/v1/producers/{partyId}/grainbin":{"get":{"operationId":"getProducerGrainBins","summary":"Get grain bins for a producer","description":"Retrieve grain bin IDs associated with a producer.\n\n**Billing:** Metered — 1 credit per record (linked data scope).\n","tags":["Producer Relationships"],"parameters":[{"in":"path","name":"partyId","required":true,"schema":{"type":"integer","example":5091294},"description":"Unique producer identifier."}],"responses":{"200":{"description":"Grain bins for the producer.","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"partyId":{"type":"integer","description":"Producer identifier.","example":5091294},"binId":{"type":"integer","description":"Unique grain bin identifier.","example":88001}}}},"example":[{"partyId":5091294,"binId":88001},{"partyId":5091294,"binId":88002}]}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"bad-request","title":"Invalid Request","status":400,"detail":"Validation failed.","instance":"urn:dtn:farm-intel-external-api:/api/v1/producers/abc/grainbin:requestId:abc123","errors":[{"message":"Path parameter partyId must be a valid integer.","parameter":"partyId"}]}}}},"401":{"description":"Missing or invalid authentication token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"unauthorized","title":"Error while authenticating the user","status":401,"detail":"Bearer Token is malformed.","instance":"urn:dtn:farm-intel-external-api:requestId:example-id"}}}}}}},"/api/v1/producers/{partyId}/consumer":{"get":{"operationId":"getProducerConsumer","summary":"Get consumer details for a producer","description":"Retrieve consumer/demographic details for a producer, including age, household\ncomposition, income, education, occupation, and predictive persona classification.\n\n**Billing:** Metered — 1 credit per request.\n","tags":["Producer Details"],"parameters":[{"in":"path","name":"partyId","required":true,"schema":{"type":"integer","example":5091294},"description":"Unique producer identifier."}],"responses":{"200":{"description":"Consumer details for the producer.","headers":{"X-Credit-Cost":{"schema":{"type":"integer"},"description":"Number of credits consumed by this request."},"X-Credits-Remaining":{"schema":{"type":"integer"},"description":"Credits remaining in your account."},"X-Credit-Pool-Reset":{"schema":{"type":"string","format":"date-time"},"description":"Contract reset date."}},"content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"partyId":{"type":"integer","description":"Producer identifier.","example":5091294},"exactAge":{"type":"integer","nullable":true,"description":"Exact age of the producer.","example":54},"birthMonth":{"type":"integer","nullable":true,"description":"Birth month (1-12).","example":3},"birthDay":{"type":"integer","nullable":true,"description":"Birth day of month (1-31).","example":15},"birthYear":{"type":"integer","nullable":true,"description":"Birth year.","example":1972},"numberOfChildren":{"type":"integer","nullable":true,"description":"Number of children in the household.","example":2},"medianHouseholdIncome":{"type":"number","nullable":true,"description":"Estimated median household income.","example":85000},"numberOfAdults":{"type":"integer","nullable":true,"description":"Number of adults in the household.","example":2},"generationsInHouseHold":{"type":"integer","nullable":true,"description":"Number of generations living in the household.","example":2},"inferredAge":{"type":"integer","nullable":true,"description":"Inferred age when exact age is unavailable.","example":null},"matchType":{"type":"string","nullable":true,"description":"Type of record match used for this data enrichment.","example":"Individual"},"maritalStatus":{"type":"string","nullable":true,"description":"Marital status.","example":"Married"},"education":{"type":"string","nullable":true,"description":"Highest education level attained.","example":"Completed College"},"occupation":{"type":"string","nullable":true,"description":"Occupation category.","example":"Farmer/Agriculture"},"gender":{"type":"string","nullable":true,"description":"Gender of the producer.","example":"Male"},"persona":{"type":"string","nullable":true,"description":"Predictive persona classification for the current year.","example":"Tech-Savvy Operator"}}}},"example":[{"partyId":5091294,"exactAge":54,"birthMonth":3,"birthDay":15,"birthYear":1972,"numberOfChildren":2,"medianHouseholdIncome":85000,"numberOfAdults":2,"generationsInHouseHold":2,"inferredAge":null,"matchType":"Individual","maritalStatus":"Married","education":"Completed College","occupation":"Farmer/Agriculture","gender":"Male","persona":"Tech-Savvy Operator"}]}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"bad-request","title":"Invalid Request","status":400,"detail":"Validation failed.","instance":"urn:dtn:farm-intel-external-api:/api/v1/producers/abc/consumer:requestId:abc123","errors":[{"message":"Path parameter partyId must be a valid integer.","parameter":"partyId"}]}}}},"401":{"description":"Missing or invalid authentication token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"unauthorized","title":"Error while authenticating the user","status":401,"detail":"Bearer Token is malformed.","instance":"urn:dtn:farm-intel-external-api:requestId:example-id"}}}},"429":{"description":"Insufficient credits remaining.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"insufficient-credits","title":"Insufficient Credits","status":429,"detail":"This request requires 1 producer credit, but only 0 remain."}}}}}}},"/api/v1/producers/{partyId}/related":{"get":{"operationId":"getProducerRelated","summary":"Get related parties for a producer","description":"Retrieve parties related to a producer (e.g., household members, business partners,\nlandlords). Returns relationship type descriptions mapped from internal codes.\n\n**Billing:** Unmetered (discovery class).\n","tags":["Producer Relationships"],"parameters":[{"in":"path","name":"partyId","required":true,"schema":{"type":"integer","example":5091294},"description":"Unique producer identifier."}],"responses":{"200":{"description":"Related parties for the producer.","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"partyId":{"type":"integer","description":"The source producer identifier.","example":5091294},"relatedPartyId":{"type":"integer","description":"The related party identifier.","example":5091300},"linkType":{"type":"string","description":"Description of the relationship type (e.g., \"Land\", \"Household Member\", \"Business Partner\").","example":"Land"}}}},"example":[{"partyId":5091294,"relatedPartyId":5091300,"linkType":"Land"},{"partyId":5091294,"relatedPartyId":6200145,"linkType":"Land"}]}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"bad-request","title":"Invalid Request","status":400,"detail":"Validation failed.","instance":"urn:dtn:farm-intel-external-api:/api/v1/producers/abc/related:requestId:abc123","errors":[{"message":"Path parameter partyId must be a valid integer.","parameter":"partyId"}]}}}},"401":{"description":"Missing or invalid authentication token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"unauthorized","title":"Error while authenticating the user","status":401,"detail":"Bearer Token is malformed.","instance":"urn:dtn:farm-intel-external-api:requestId:example-id"}}}}}}},"/api/v1/producers/grainbin/search":{"get":{"operationId":"searchGrainBinsByPartyIds","summary":"Batch grain bin search by party IDs","description":"Search grain bins for multiple producers in a single request. Accepts a comma-separated\nlist of party IDs and returns all bins associated with those producers.\n\n**Billing:** Metered — 1 credit per record (linked data scope).\n","tags":["Producer Relationships"],"parameters":[{"in":"query","name":"party-id","required":true,"schema":{"type":"string","example":"5091294,5091300,6200145"},"description":"Comma-separated list of producer party IDs."}],"responses":{"200":{"description":"Grain bins for the requested producers.","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"partyId":{"type":"integer","description":"Producer who owns this bin.","example":5091294},"binId":{"type":"integer","description":"Unique grain bin identifier.","example":88001}}}},"example":[{"partyId":5091294,"binId":88001},{"partyId":5091294,"binId":88002},{"partyId":5091300,"binId":88015}]}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"bad-request","title":"Invalid Request","status":400,"detail":"Validation failed.","instance":"urn:dtn:farm-intel-external-api:/api/v1/producers/grainbin/search:requestId:abc123","errors":[{"message":"Required query parameter party-id is missing.","parameter":"party-id"}]}}}},"401":{"description":"Missing or invalid authentication token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"unauthorized","title":"Error while authenticating the user","status":401,"detail":"Bearer Token is malformed.","instance":"urn:dtn:farm-intel-external-api:requestId:example-id"}}}}}}},"/api/v1/producers/channels":{"post":{"operationId":"searchProducersByPolygon","summary":"Find producers within a GeoJSON polygon","description":"Find producers whose registered address falls within a GeoJSON polygon boundary.\nAccepts a GeoJSON Polygon geometry in the request body and returns matching producers.\n\n**Billing:** Metered — 1 credit per producer returned.\n","tags":["Producer Search"],"parameters":[{"in":"query","name":"limit","required":false,"schema":{"type":"integer","default":10,"minimum":1,"maximum":500},"description":"Maximum number of results to return."},{"in":"query","name":"offset","required":false,"schema":{"type":"integer","default":0,"minimum":0},"description":"Number of results to skip (for pagination)."}],"requestBody":{"required":true,"description":"GeoJSON Polygon geometry defining the search area.","content":{"application/json":{"schema":{"type":"object","required":["type","coordinates"],"properties":{"type":{"type":"string","enum":["Polygon"],"description":"Must be \"Polygon\".","example":"Polygon"},"coordinates":{"type":"array","items":{"type":"array","items":{"type":"array","items":{"type":"number"},"minItems":2,"maxItems":2}},"description":"Array of linear rings. The first ring is the exterior boundary.\nEach position is [longitude, latitude] in WGS84.\n"}}},"example":{"type":"Polygon","coordinates":[[[-93.7,41.5],[-93.5,41.5],[-93.5,41.7],[-93.7,41.7],[-93.7,41.5]]]}}}},"responses":{"200":{"description":"Producers found within the polygon.","headers":{"X-Credit-Cost":{"schema":{"type":"integer"},"description":"Number of credits consumed by this request."},"X-Credits-Remaining":{"schema":{"type":"integer"},"description":"Credits remaining in your account."},"X-Credit-Pool-Reset":{"schema":{"type":"string","format":"date-time"},"description":"Contract reset date."}},"content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"partyId":{"type":"integer","example":5091294},"firstName":{"type":"string","nullable":true,"example":"JOHN"},"middleName":{"type":"string","nullable":true},"lastName":{"type":"string","nullable":true,"example":"SMITH"},"companyName":{"type":"string","nullable":true,"example":"SMITH FARMS LLC"},"addressLine":{"type":"string","nullable":true,"example":"123 FARM RD"},"city":{"type":"string","nullable":true,"example":"DES MOINES"},"stateCode":{"type":"string","nullable":true,"example":"IA"},"postalCode":{"type":"string","nullable":true,"example":"50316"},"fipsCode":{"type":"string","nullable":true,"example":"19153"},"countyName":{"type":"string","nullable":true,"example":"POLK"},"lat":{"type":"number","nullable":true,"example":41.601},"lon":{"type":"number","nullable":true,"example":-93.609},"email":{"type":"string","nullable":true},"phoneNumber":{"type":"string","nullable":true},"mobileNumber":{"type":"string","nullable":true},"producerCode":{"type":"string","nullable":true},"linkType":{"type":"string","nullable":true},"personaDescription":{"type":"string","nullable":true}}}},"links":{"type":"object","properties":{"next":{"type":"string","nullable":true},"previous":{"type":"string","nullable":true}}},"count":{"type":"integer","example":15}}},"example":{"results":[{"partyId":5091294,"firstName":"JOHN","lastName":"SMITH","companyName":"SMITH FARMS LLC","addressLine":"123 FARM RD","city":"DES MOINES","stateCode":"IA","postalCode":"50316","fipsCode":"19153","countyName":"POLK","lat":41.601,"lon":-93.609,"email":null,"phoneNumber":"5155550100","mobileNumber":null,"producerCode":"1","linkType":"O"}],"links":{"next":"/api/v1/party/channels?limit=10&offset=10","previous":null},"count":15}}}},"400":{"description":"Invalid request body or parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"bad-request","title":"Invalid Request","status":400,"detail":"Validation failed.","instance":"urn:dtn:farm-intel-external-api:/api/v1/producers/channels:requestId:abc123","errors":[{"message":"Request body must be a valid GeoJSON Polygon.","parameter":"body"}]}}}},"401":{"description":"Missing or invalid authentication token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"unauthorized","title":"Error while authenticating the user","status":401,"detail":"Bearer Token is malformed.","instance":"urn:dtn:farm-intel-external-api:requestId:example-id"}}}},"429":{"description":"Insufficient credits remaining.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"insufficient-credits","title":"Insufficient Credits","status":429,"detail":"This request requires 25 producer credits, but only 10 remain."}}}}}}},"/api/v1/producers/match":{"post":{"operationId":"matchProducer","summary":"Match a producer by name/address/contact","description":"Match a producer record by providing partial identifying information (name, address,\nphone, or email). Returns the best-matching producer record if found. Useful for\ndeduplication and CRM integration workflows.\n\n**Billing:** Metered — 1 credit per successful match.\n","tags":["Producer Search"],"requestBody":{"required":true,"description":"Match criteria. Either `firstName` or `companyName` (or both) must be provided.\nAdditional fields improve match accuracy.\n","content":{"application/json":{"schema":{"type":"object","anyOf":[{"required":["firstName"]},{"required":["companyName"]}],"properties":{"companyName":{"type":"string","nullable":true,"description":"Company or farm name to match.","example":"Smith Farms LLC"},"fullName":{"type":"string","nullable":true,"description":"Full name (alternative to firstName/lastName split).","example":"John Smith"},"firstName":{"type":"string","nullable":true,"description":"First name.","example":"John"},"middleInitial":{"type":"string","nullable":true,"description":"Middle initial.","example":"A"},"lastName":{"type":"string","nullable":true,"description":"Last name.","example":"Smith"},"nameSuffix":{"type":"string","nullable":true,"description":"Name suffix (Jr., Sr., III, etc.).","example":"Jr."},"address":{"type":"string","nullable":true,"description":"Street address line 1.","example":"123 Farm Rd"},"address2":{"type":"string","nullable":true,"description":"Street address line 2.","example":null},"city":{"type":"string","nullable":true,"description":"City name.","example":"Des Moines"},"stateCode":{"type":"string","nullable":true,"description":"Two-letter state code.","example":"IA"},"zipCode":{"type":"string","nullable":true,"description":"ZIP code.","example":"50316"},"phone":{"type":"string","nullable":true,"description":"Phone number.","example":"515-555-0100"},"email":{"type":"string","nullable":true,"description":"Email address.","example":"john@smithfarms.com"}}},"example":{"firstName":"John","lastName":"Smith","stateCode":"IA","zipCode":"50316"}}}},"responses":{"200":{"description":"Best matching producer found.","headers":{"X-Credit-Cost":{"schema":{"type":"integer"},"description":"Number of credits consumed by this request."},"X-Credits-Remaining":{"schema":{"type":"integer"},"description":"Credits remaining in your account."},"X-Credit-Pool-Reset":{"schema":{"type":"string","format":"date-time"},"description":"Contract reset date."}},"content":{"application/json":{"schema":{"type":"object","properties":{"partyId":{"type":"integer","description":"Matched producer identifier.","example":5091294},"primaryContact":{"type":"boolean","description":"Whether this is the primary contact for the party.","example":true},"companyName":{"type":"string","nullable":true,"example":"Smith Farms LLC"},"firstName":{"type":"string","nullable":true,"example":"John"},"middleInitial":{"type":"string","nullable":true,"example":"A"},"lastName":{"type":"string","nullable":true,"example":"Smith"},"suffix":{"type":"string","nullable":true,"example":"Jr."},"role":{"type":"string","nullable":true,"description":"Human-readable role description.","example":"operator"}}},"example":{"partyId":5091294,"primaryContact":true,"companyName":"Smith Farms LLC","firstName":"John","middleInitial":"A","lastName":"Smith","suffix":null,"role":"operator"}}}},"400":{"description":"Invalid request body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"bad-request","title":"Invalid Request","status":400,"detail":"Validation failed.","instance":"urn:dtn:farm-intel-external-api:/api/v1/producers/match:requestId:abc123","errors":[{"message":"Either firstName or companyName must be provided.","parameter":"body"}]}}}},"401":{"description":"Missing or invalid authentication token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"unauthorized","title":"Error while authenticating the user","status":401,"detail":"Bearer Token is malformed.","instance":"urn:dtn:farm-intel-external-api:requestId:example-id"}}}},"429":{"description":"Insufficient credits remaining.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"insufficient-credits","title":"Insufficient Credits","status":429,"detail":"This request requires 1 producer credit, but only 0 remain."}}}}}}},"/api/v1/segments":{"get":{"operationId":"listSegments","summary":"List all segments","description":"List all segments (saved producer audiences) for the authenticated customer account.\nReturns segment metadata including creator name and producer count.\n\n**Billing:** Unmetered (discovery class).\n","tags":["Segments"],"responses":{"200":{"description":"List of segments.","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/Segment"}},"warnings":{"type":"array","items":{"type":"string"},"description":"Optional warnings (e.g., if some creator names could not be resolved)."}}},"example":{"results":[{"segmentId":4521,"segmentName":"Iowa Corn Operators 500+ Acres","numberOfProducers":312,"dateCreated":"2025-03-15T14:30:00Z","creator":"Jane Doe"},{"segmentId":4522,"segmentName":"Illinois Soybean Growers","numberOfProducers":189,"dateCreated":"2025-02-20T10:00:00Z","creator":"John Smith"}],"warnings":[]}}}},"401":{"description":"Missing or invalid authentication token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"unauthorized","title":"Error while authenticating the user","status":401,"detail":"Bearer Token is malformed.","instance":"urn:dtn:farm-intel-external-api:requestId:example-id"}}}}}}},"/api/v1/segments/{segmentId}/producers":{"get":{"operationId":"getSegmentProducers","summary":"Get producers in a segment","description":"Retrieve producers belonging to a specific segment. Supports pagination and optional\nfilters for role, status, contact availability, and geographic location.\n\n**Billing:** Metered — 1 credit per producer returned.\n","tags":["Segments"],"parameters":[{"in":"path","name":"segmentId","required":true,"schema":{"type":"integer","example":4521},"description":"Unique segment identifier."},{"in":"query","name":"limit","required":false,"schema":{"type":"integer","default":10,"minimum":1,"maximum":500},"description":"Maximum number of results to return."},{"in":"query","name":"offset","required":false,"schema":{"type":"integer","default":0,"minimum":0},"description":"Number of results to skip (for pagination)."},{"in":"query","name":"role","required":false,"schema":{"type":"string","enum":["operator","owner-operator","owner","other"]},"description":"Filter by producer role."},{"in":"query","name":"status","required":false,"schema":{"type":"string","enum":["lead","prospect","customer","former-customer","other","none"]},"description":"Filter by relationship status."},{"in":"query","name":"has-email","required":false,"schema":{"type":"boolean"},"description":"Filter to producers with (true) or without (false) email addresses."},{"in":"query","name":"has-phone","required":false,"schema":{"type":"boolean"},"description":"Filter to producers with (true) or without (false) phone numbers."},{"in":"query","name":"has-external-id","required":false,"schema":{"type":"boolean"},"description":"Filter to producers with (true) or without (false) external CRM identifiers."},{"in":"query","name":"fips-code","required":false,"schema":{"type":"string","example":"19153"},"description":"Filter to producers in a specific county (5-digit FIPS code)."}],"responses":{"200":{"description":"Producers in the segment.","headers":{"X-Credit-Cost":{"schema":{"type":"integer"},"description":"Number of credits consumed by this request."},"X-Credits-Remaining":{"schema":{"type":"integer"},"description":"Credits remaining in your account."},"X-Credit-Pool-Reset":{"schema":{"type":"string","format":"date-time"},"description":"Contract reset date."}},"content":{"application/json":{"schema":{"type":"object","properties":{"producers":{"type":"array","items":{"$ref":"#/components/schemas/Producer"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}},"example":{"producers":[{"producerId":5091294,"firstName":"John","lastName":"Smith","companyName":"Smith Farms LLC","address":"123 Farm Rd","city":"Des Moines","state":"IA","postalCode":"50316-2921","fipsCode":"19153","county":"Polk","lat":41.601,"lon":-93.609,"locationAccuracy":"Address was DPV confirmed for the primary number only, and secondary number information was missing.","role":"operator","status":"customer","externalID":"CRM-12345","phones":["515-555-0100"],"emails":["john@smithfarms.com"]}],"pagination":{"total":312,"hasMore":true}}}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"bad-request","title":"Invalid Request","status":400,"detail":"Validation failed.","instance":"urn:dtn:farm-intel-external-api:/api/v1/segments/abc/producers:requestId:abc123","errors":[{"message":"Path parameter segmentId must be a valid integer.","parameter":"segmentId"}]}}}},"401":{"description":"Missing or invalid authentication token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"unauthorized","title":"Error while authenticating the user","status":401,"detail":"Bearer Token is malformed.","instance":"urn:dtn:farm-intel-external-api:requestId:example-id"}}}},"429":{"description":"Insufficient credits remaining.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"insufficient-credits","title":"Insufficient Credits","status":429,"detail":"This request requires 10 producer credits, but only 5 remain."}}}}}}},"/api/v1/portfolios":{"get":{"operationId":"listPortfolios","summary":"List all portfolios","description":"List all portfolios (curated producer lists) for the authenticated customer account.\nReturns portfolio metadata including creator name and producer count.\n\n**Billing:** Unmetered (discovery class).\n","tags":["Portfolios"],"responses":{"200":{"description":"List of portfolios.","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/Portfolio"}},"warnings":{"type":"array","items":{"type":"string"},"description":"Optional warnings (e.g., if some creator names could not be resolved)."}}},"example":{"results":[{"portfolioId":782,"portfolioName":"2025 Spring Prospects","numberOfProducers":45,"dateCreated":"2025-01-10T09:15:00Z","creator":"John Smith"},{"portfolioId":783,"portfolioName":"Key Accounts - Midwest","numberOfProducers":120,"dateCreated":"2025-02-01T08:00:00Z","creator":"Jane Doe"}],"warnings":[]}}}},"401":{"description":"Missing or invalid authentication token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"unauthorized","title":"Error while authenticating the user","status":401,"detail":"Bearer Token is malformed.","instance":"urn:dtn:farm-intel-external-api:requestId:example-id"}}}}}}},"/api/v1/portfolios/{portfolioId}/producers":{"get":{"operationId":"getPortfolioProducers","summary":"Get producers in a portfolio","description":"Retrieve producers belonging to a specific portfolio. Supports pagination and optional\nfilters for role, status, contact availability, and geographic location.\n\n**Billing:** Metered — 1 credit per producer returned.\n","tags":["Portfolios"],"parameters":[{"in":"path","name":"portfolioId","required":true,"schema":{"type":"integer","example":782},"description":"Unique portfolio identifier."},{"in":"query","name":"limit","required":false,"schema":{"type":"integer","default":10,"minimum":1,"maximum":500},"description":"Maximum number of results to return."},{"in":"query","name":"offset","required":false,"schema":{"type":"integer","default":0,"minimum":0},"description":"Number of results to skip (for pagination)."},{"in":"query","name":"role","required":false,"schema":{"type":"string","enum":["operator","owner-operator","owner","other"]},"description":"Filter by producer role."},{"in":"query","name":"status","required":false,"schema":{"type":"string","enum":["lead","prospect","customer","former-customer","other","none"]},"description":"Filter by relationship status."},{"in":"query","name":"has-email","required":false,"schema":{"type":"boolean"},"description":"Filter to producers with (true) or without (false) email addresses."},{"in":"query","name":"has-phone","required":false,"schema":{"type":"boolean"},"description":"Filter to producers with (true) or without (false) phone numbers."},{"in":"query","name":"has-external-id","required":false,"schema":{"type":"boolean"},"description":"Filter to producers with (true) or without (false) external CRM identifiers."},{"in":"query","name":"fips-code","required":false,"schema":{"type":"string","example":"19153"},"description":"Filter to producers in a specific county (5-digit FIPS code)."}],"responses":{"200":{"description":"Producers in the portfolio.","headers":{"X-Credit-Cost":{"schema":{"type":"integer"},"description":"Number of credits consumed by this request."},"X-Credits-Remaining":{"schema":{"type":"integer"},"description":"Credits remaining in your account."},"X-Credit-Pool-Reset":{"schema":{"type":"string","format":"date-time"},"description":"Contract reset date."}},"content":{"application/json":{"schema":{"type":"object","properties":{"producers":{"type":"array","items":{"$ref":"#/components/schemas/Producer"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}},"example":{"producers":[{"producerId":8890647,"firstName":"Jane","lastName":"Doe","companyName":null,"address":"456 County Line Rd","city":"Des Moines","state":"IA","postalCode":"50316-3413","fipsCode":"19153","county":"Polk","lat":41.598,"lon":-93.612,"locationAccuracy":"Address was DPV confirmed for the primary number only, and secondary number information was missing.","role":"owner-operator","status":"prospect","externalID":null,"phones":[],"emails":[]}],"pagination":{"total":45,"hasMore":true}}}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"bad-request","title":"Invalid Request","status":400,"detail":"Validation failed.","instance":"urn:dtn:farm-intel-external-api:/api/v1/portfolios/abc/producers:requestId:abc123","errors":[{"message":"Path parameter portfolioId must be a valid integer.","parameter":"portfolioId"}]}}}},"401":{"description":"Missing or invalid authentication token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"unauthorized","title":"Error while authenticating the user","status":401,"detail":"Bearer Token is malformed.","instance":"urn:dtn:farm-intel-external-api:requestId:example-id"}}}},"429":{"description":"Insufficient credits remaining.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"insufficient-credits","title":"Insufficient Credits","status":429,"detail":"This request requires 10 producer credits, but only 5 remain."}}}}}}},"/api/v1/land/search":{"get":{"operationId":"searchLand","summary":"Search land parcels","description":"Search land parcels by geographic criteria. Supports two mutually exclusive modes:\n\n1. **Radius mode** — Provide `lat`, `lon`, and `radius` to find parcels within a circle.\n2. **FIPS code mode** — Provide `fips-code` to find all parcels in a county.\n\nYou must provide either (lat + lon + radius) OR fips-code, not both.\n\n**Billing:** Unmetered (discovery class).\n","tags":["Land Search"],"parameters":[{"in":"query","name":"lat","required":false,"schema":{"type":"number","format":"float","example":41.6},"description":"Latitude of the center point (required for radius mode)."},{"in":"query","name":"lon","required":false,"schema":{"type":"number","format":"float","example":-93.6},"description":"Longitude of the center point (required for radius mode)."},{"in":"query","name":"radius","required":false,"schema":{"type":"number","example":16000},"description":"Search radius in meters (required for radius mode)."},{"in":"query","name":"fips-code","required":false,"schema":{"type":"string","example":"19153"},"description":"5-digit county FIPS code (required for FIPS code mode)."},{"in":"query","name":"limit","required":false,"schema":{"type":"integer","default":50,"minimum":1,"maximum":1000},"description":"Maximum number of results to return."},{"in":"query","name":"offset","required":false,"schema":{"type":"integer","default":0,"minimum":0},"description":"Number of results to skip (for pagination)."}],"responses":{"200":{"description":"Land parcels matching the search criteria.","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/LandSearchResult"}},"links":{"type":"object","properties":{"next":{"type":"string","nullable":true,"description":"Relative URL for the next page of results (null if no more pages).","example":"/land?fips=19153&limit=50&offset=50"},"previous":{"type":"string","nullable":true,"description":"Relative URL for the previous page of results (null if on first page).","example":null}}},"count":{"type":"integer","description":"Total number of matching land parcels.","example":13128}}},"example":{"results":[{"landId":3456789,"lat":41.732,"lon":-93.458,"acres":152.4,"fipsCode":"19153","zipCode":"50316","mtrs":"4-080N-024W-14"},{"landId":3456790,"lat":41.715,"lon":-93.47,"acres":80,"fipsCode":"19153","zipCode":"50316","mtrs":"4-080N-024W-15"}],"links":{"next":"/land?fips=19153&limit=50&offset=50","previous":null},"count":13128}}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"bad-request","title":"Invalid Request","status":400,"detail":"Validation failed.","instance":"urn:dtn:farm-intel-external-api:/api/v1/land/search:requestId:abc123","errors":[{"message":"Provide either (lat, lon, radius) or fips-code, not both.","parameter":"query"}]}}}},"401":{"description":"Missing or invalid authentication token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"unauthorized","title":"Error while authenticating the user","status":401,"detail":"Bearer Token is malformed.","instance":"urn:dtn:farm-intel-external-api:requestId:example-id"}}}}}}},"/api/v1/land/list":{"get":{"operationId":"getLandByIds","summary":"Batch land metadata by IDs","description":"Retrieve metadata for multiple land parcels in a single request. Accepts a\ncomma-separated list of land IDs.\n\n**Billing:** Unmetered (discovery class).\n","tags":["Land Search"],"parameters":[{"in":"query","name":"land-id","required":true,"schema":{"type":"string","example":"3456789,3456790,3456791"},"description":"Comma-separated list of land parcel IDs."}],"responses":{"200":{"description":"Land parcel metadata.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/LandSearchResult"}},"example":[{"landId":3456789,"lat":41.732,"lon":-93.458,"acres":152.4,"fipsCode":"19153","zipCode":"50316","mtrs":"4-080N-024W-14"},{"landId":3456790,"lat":41.715,"lon":-93.47,"acres":80,"fipsCode":"19153","zipCode":"50316","mtrs":"4-080N-024W-15"},{"landId":3456791,"lat":41.698,"lon":-93.485,"acres":160,"fipsCode":"19153","zipCode":"50317","mtrs":"4-080N-024W-22"}]}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"bad-request","title":"Invalid Request","status":400,"detail":"Validation failed.","instance":"urn:dtn:farm-intel-external-api:/api/v1/land/list:requestId:abc123","errors":[{"message":"Required query parameter land-id is missing.","parameter":"land-id"}]}}}},"401":{"description":"Missing or invalid authentication token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"unauthorized","title":"Error while authenticating the user","status":401,"detail":"Bearer Token is malformed.","instance":"urn:dtn:farm-intel-external-api:requestId:example-id"}}}}}}},"/api/v1/land/{landId}":{"get":{"operationId":"getLandById","summary":"Get land metadata by ID","description":"Retrieve detailed metadata for a single land parcel, including acreage, coordinates,\nand county name (enriched as \"County, ST\" format with state abbreviation).\n\n**Billing:** Unmetered (discovery class).\n","tags":["Land Details"],"parameters":[{"in":"path","name":"landId","required":true,"schema":{"type":"integer","example":3456789},"description":"Unique land parcel identifier."}],"responses":{"200":{"description":"Land parcel metadata.","content":{"application/json":{"schema":{"type":"object","properties":{"landId":{"type":"integer","description":"Unique land parcel identifier.","example":1000},"acres":{"type":"number","format":"float","description":"Total acreage of the land parcel.","example":12.61},"lat":{"type":"number","format":"float","description":"Latitude of the land centroid (decimal degrees, WGS84).","example":31.534},"lon":{"type":"number","format":"float","description":"Longitude of the land centroid (decimal degrees, WGS84).","example":-84.965},"zipCode":{"type":"string","nullable":true,"description":"ZIP code for the land parcel.","example":"39851"},"mtrs":{"type":"string","nullable":true,"description":"Meridian-Township-Range-Section identifier.","example":"IA05T0780N0220W017"},"nameStatus":{"type":"string","description":"Whether the land has operator name data.","example":"Y"},"cropStatus":{"type":"string","description":"Whether the land has crop data.","example":"Y"},"irrigationAcres":{"type":"number","format":"float","nullable":true,"description":"Irrigated acres on this parcel.","example":12.61},"countyName":{"type":"string","description":"County and state abbreviation in \"County, ST\" format.","example":"Clay, GA"}}},"example":{"landId":1000,"lat":31.534,"lon":-84.965,"acres":12.61,"zipCode":"39851","mtrs":"IA05T0780N0220W017","nameStatus":"Y","cropStatus":"Y","irrigationAcres":12.61,"countyName":"Clay, GA"}}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"bad-request","title":"Invalid Request","status":400,"detail":"Validation failed.","instance":"urn:dtn:farm-intel-external-api:/api/v1/land/abc:requestId:abc123","errors":[{"message":"Path parameter landId must be a valid integer.","parameter":"landId"}]}}}},"401":{"description":"Missing or invalid authentication token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"unauthorized","title":"Error while authenticating the user","status":401,"detail":"Bearer Token is malformed.","instance":"urn:dtn:farm-intel-external-api:requestId:example-id"}}}}}}},"/api/v1/land/{landId}/crop":{"get":{"operationId":"getLandCropHistory","summary":"Get crop history for a land parcel","description":"Retrieve crop planting and harvest history for a specific land parcel. Optionally\nfilter by year. Results are paginated.\n\n**Billing:** Metered — 1 credit per crop-year record returned.\n","tags":["Land Crop"],"parameters":[{"in":"path","name":"landId","required":true,"schema":{"type":"integer","example":3456789},"description":"Unique land parcel identifier."},{"in":"query","name":"year","required":false,"schema":{"type":"integer","example":2025},"description":"Filter to a specific crop year."},{"in":"query","name":"limit","required":false,"schema":{"type":"integer","default":10,"minimum":1,"maximum":100},"description":"Maximum number of results to return."},{"in":"query","name":"offset","required":false,"schema":{"type":"integer","default":0,"minimum":0},"description":"Number of results to skip (for pagination)."}],"responses":{"200":{"description":"Crop history for the land parcel.","headers":{"X-Credit-Cost":{"schema":{"type":"integer"},"description":"Number of credits consumed by this request."},"X-Credits-Remaining":{"schema":{"type":"integer"},"description":"Credits remaining in your account."},"X-Credit-Pool-Reset":{"schema":{"type":"string","format":"date-time"},"description":"Contract reset date."}},"content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/LandCrop"}},"links":{"type":"object","properties":{"next":{"type":"string","nullable":true,"description":"Relative URL for the next page of results.","example":"/api/v1/land/1000/crop?limit=10&offset=10"},"previous":{"type":"string","nullable":true,"description":"URL for the previous page of results.","example":null}}},"count":{"type":"integer","description":"Total number of crop-year records for this land.","example":29}}},"example":{"results":[{"landId":3456789,"cropYear":2025,"acres":148.2,"lciId":1,"planted":null,"harvested":null},{"landId":3456789,"cropYear":2024,"acres":150,"lciId":5,"planted":null,"harvested":null},{"landId":3456789,"cropYear":2023,"acres":148.5,"lciId":1,"planted":null,"harvested":null}],"links":{"next":"/api/v1/land/3456789/crop?limit=10&offset=10","previous":null},"count":29}}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"bad-request","title":"Invalid Request","status":400,"detail":"Validation failed.","instance":"urn:dtn:farm-intel-external-api:/api/v1/land/abc/crop:requestId:abc123","errors":[{"message":"Path parameter landId must be a valid integer.","parameter":"landId"}]}}}},"401":{"description":"Missing or invalid authentication token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"unauthorized","title":"Error while authenticating the user","status":401,"detail":"Bearer Token is malformed.","instance":"urn:dtn:farm-intel-external-api:requestId:example-id"}}}},"429":{"description":"Insufficient credits remaining.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"insufficient-credits","title":"Insufficient Credits","status":429,"detail":"This request requires 8 land credits, but only 5 remain."}}}}}}},"/api/v1/land/{landId}/producers":{"get":{"operationId":"getLandProducers","summary":"Get producers linked to a land parcel","description":"Retrieve all producers (operators, owners) associated with a specific land parcel.\nReturns producer details including role, crop year, and geographic information.\n\n**Billing:** Unmetered (discovery class).\n","tags":["Land Details"],"parameters":[{"in":"path","name":"landId","required":true,"schema":{"type":"integer","example":3456789},"description":"Unique land parcel identifier."}],"responses":{"200":{"description":"Producers linked to the land parcel.","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"landId":{"type":"integer","description":"Land parcel identifier.","example":3456789},"partyId":{"type":"integer","description":"Producer identifier.","example":5091294},"primaryFlag":{"type":"boolean","description":"Whether this is the primary operator for the land.","example":true},"roleId":{"type":"integer","description":"Internal role identifier.","example":1},"cropYear":{"type":"integer","description":"Most recent crop year for this association.","example":2025},"roleDescription":{"type":"string","description":"Human-readable role description.","example":"Operator"},"firstName":{"type":"string","nullable":true,"example":"John"},"lastName":{"type":"string","nullable":true,"example":"Smith"},"companyName":{"type":"string","nullable":true,"example":"Smith Farms LLC"},"stateCode":{"type":"string","nullable":true,"example":"IA"},"fipsCode":{"type":"string","nullable":true,"example":"19153"},"countyName":{"type":"string","nullable":true,"example":"Polk"}}}},"example":[{"landId":3456789,"partyId":5091294,"primaryFlag":true,"roleId":1,"cropYear":2025,"roleDescription":"Operator","firstName":"John","lastName":"Smith","companyName":"Smith Farms LLC","stateCode":"IA","fipsCode":"19153","countyName":"Polk"},{"landId":3456789,"partyId":6200145,"primaryFlag":false,"roleId":2,"cropYear":2025,"roleDescription":"Owner","firstName":"Robert","lastName":"Johnson","companyName":null,"stateCode":"IA","fipsCode":"19153","countyName":"Polk"}]}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"bad-request","title":"Invalid Request","status":400,"detail":"Validation failed.","instance":"urn:dtn:farm-intel-external-api:/api/v1/land/abc/producers:requestId:abc123","errors":[{"message":"Path parameter landId must be a valid integer.","parameter":"landId"}]}}}},"401":{"description":"Missing or invalid authentication token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"unauthorized","title":"Error while authenticating the user","status":401,"detail":"Bearer Token is malformed.","instance":"urn:dtn:farm-intel-external-api:requestId:example-id"}}}}}}},"/api/v1/land/{landId}/grainbin":{"get":{"operationId":"getLandGrainBins","summary":"Get grain bins on a land parcel","description":"Retrieve grain storage bins located on a specific land parcel. Returns bin\nlocation, capacity, and the year the data was recorded.\n\n**Billing:** Unmetered (discovery class).\n","tags":["Land Details"],"parameters":[{"in":"path","name":"landId","required":true,"schema":{"type":"integer","example":3456789},"description":"Unique land parcel identifier."}],"responses":{"200":{"description":"Grain bins on the land parcel.","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"binId":{"type":"integer","description":"Unique grain bin identifier.","example":88001},"lat":{"type":"number","format":"float","description":"Latitude of the bin location.","example":41.732},"lon":{"type":"number","format":"float","description":"Longitude of the bin location.","example":-93.458},"bushels":{"type":"number","format":"float","description":"Estimated storage capacity in bushels.","example":25000},"landId":{"type":"integer","description":"Land parcel identifier.","example":3456789},"cropYear":{"type":"integer","description":"Year the bin data was recorded.","example":2025}}}},"example":[{"binId":88001,"lat":41.732,"lon":-93.458,"bushels":25000,"landId":3456789,"cropYear":2025},{"binId":88002,"lat":41.733,"lon":-93.459,"bushels":18000,"landId":3456789,"cropYear":2025}]}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"bad-request","title":"Invalid Request","status":400,"detail":"Validation failed.","instance":"urn:dtn:farm-intel-external-api:/api/v1/land/abc/grainbin:requestId:abc123","errors":[{"message":"Path parameter landId must be a valid integer.","parameter":"landId"}]}}}},"401":{"description":"Missing or invalid authentication token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"unauthorized","title":"Error while authenticating the user","status":401,"detail":"Bearer Token is malformed.","instance":"urn:dtn:farm-intel-external-api:requestId:example-id"}}}}}}},"/api/v1/land/{landId}/soil":{"get":{"operationId":"getLandSoil","summary":"Get soil types for a land parcel","description":"Retrieve soil type classification data for a specific land parcel. Returns\nsoil series, map unit information, and coverage area within the parcel.\n\n**Billing:** Unmetered (discovery class).\n","tags":["Land Details"],"parameters":[{"in":"path","name":"landId","required":true,"schema":{"type":"integer","example":3456789},"description":"Unique land parcel identifier."}],"responses":{"200":{"description":"Soil types for the land parcel.","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"landId":{"type":"integer","description":"Land parcel identifier.","example":1000},"soilId":{"type":"integer","description":"Unique soil type identifier.","example":198526},"soilName":{"type":"string","nullable":true,"description":"Soil type name/symbol.","example":"138B"},"soilDescription":{"type":"string","nullable":true,"description":"Full soil description.","example":"Clarion loam, 2 to 5 percent slopes"},"acres":{"type":"number","format":"float","nullable":true,"description":"Acres of this soil type within the parcel.","example":45.2}}}},"example":[{"landId":1000,"soilId":198526,"soilName":"138B","soilDescription":"Clarion loam, 2 to 5 percent slopes","acres":45.2},{"landId":1000,"soilId":198530,"soilName":"55","soilDescription":"Nicollet clay loam, 0 to 2 percent slopes","acres":62.8},{"landId":1000,"soilId":198545,"soilName":"507","soilDescription":"Webster clay loam, 0 to 2 percent slopes","acres":44.4}]}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"bad-request","title":"Invalid Request","status":400,"detail":"Validation failed.","instance":"urn:dtn:farm-intel-external-api:/api/v1/land/abc/soil:requestId:abc123","errors":[{"message":"Path parameter landId must be a valid integer.","parameter":"landId"}]}}}},"401":{"description":"Missing or invalid authentication token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"unauthorized","title":"Error while authenticating the user","status":401,"detail":"Bearer Token is malformed.","instance":"urn:dtn:farm-intel-external-api:requestId:example-id"}}}}}}},"/api/v1/land/{landId}/soil/intersection":{"get":{"operationId":"getLandSoilIntersection","summary":"Get soil intersection data for a land parcel","description":"Retrieve detailed soil intersection data for a land parcel. Returns the geometric\nintersection of soil map units with the land boundary, providing precise soil\ncoverage information including NCCPI productivity ratings and drainage characteristics.\n\n**Billing:** Unmetered (discovery class).\n","tags":["Land Details"],"parameters":[{"in":"path","name":"landId","required":true,"schema":{"type":"integer","example":3456789},"description":"Unique land parcel identifier."}],"responses":{"200":{"description":"Soil intersection data for the land parcel.","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"landId":{"type":"integer","description":"Land parcel identifier.","example":3456789},"mapUnitKey":{"type":"string","description":"SSURGO Map Unit Key.","example":"198526"},"totalAcres":{"type":"number","format":"float","description":"Total acres of this soil map unit.","example":45.2},"affectedAcres":{"type":"number","format":"float","description":"Acres of this soil type intersecting the land parcel boundary.","example":43.8},"percentageCovered":{"type":"number","format":"float","description":"Percentage of the land parcel covered by this soil type.","example":28.7},"description":{"type":"string","nullable":true,"description":"Soil map unit description/name.","example":"Clarion loam, 2 to 5 percent slopes"},"kind":{"type":"string","nullable":true,"description":"Soil map unit kind (e.g., Consociation, Complex).","example":"Consociation"},"floodCondition":{"type":"string","nullable":true,"description":"Flood frequency classification.","example":"None"},"drainingClass":{"type":"string","nullable":true,"description":"Soil drainage class.","example":"Well drained"},"nccpi3Corn":{"type":"number","format":"float","nullable":true,"description":"NCCPI v3 productivity index for corn (0-1 scale).","example":0.72},"nccpi3Soy":{"type":"number","format":"float","nullable":true,"description":"NCCPI v3 productivity index for soybeans (0-1 scale).","example":0.68},"nccpi3Cotton":{"type":"number","format":"float","nullable":true,"description":"NCCPI v3 productivity index for cotton (0-1 scale).","example":null},"nccpi3SmallGrains":{"type":"number","format":"float","nullable":true,"description":"NCCPI v3 productivity index for small grains (0-1 scale).","example":0.55},"nccpi3All":{"type":"number","format":"float","nullable":true,"description":"NCCPI v3 overall productivity index (0-1 scale).","example":0.7},"landSoilGeom":{"type":"object","nullable":true,"description":"GeoJSON geometry of the soil-land intersection polygon.","properties":{"crs":{"type":"object","nullable":true,"description":"Coordinate reference system metadata."},"type":{"type":"string","description":"GeoJSON geometry type.","example":"Polygon"},"coordinates":{"type":"array","description":"GeoJSON coordinate array."}}}}}},"example":[{"landId":3456789,"mapUnitKey":"198526","totalAcres":45.2,"affectedAcres":43.8,"percentageCovered":28.7,"description":"Clarion loam, 2 to 5 percent slopes","kind":"Consociation","floodCondition":"None","drainingClass":"Well drained","nccpi3Corn":0.72,"nccpi3Soy":0.68,"nccpi3Cotton":null,"nccpi3SmallGrains":0.55,"nccpi3All":0.7,"landSoilGeom":{"crs":null,"type":"Polygon","coordinates":[[[-93.46,41.73],[-93.455,41.73],[-93.455,41.735],[-93.46,41.735],[-93.46,41.73]]]}},{"landId":3456789,"mapUnitKey":"198530","totalAcres":65,"affectedAcres":61.2,"percentageCovered":40.2,"description":"Nicollet clay loam, 0 to 2 percent slopes","kind":"Consociation","floodCondition":"None","drainingClass":"Somewhat poorly drained","nccpi3Corn":0.85,"nccpi3Soy":0.8,"nccpi3Cotton":null,"nccpi3SmallGrains":0.65,"nccpi3All":0.82,"landSoilGeom":{"crs":null,"type":"Polygon","coordinates":[[[-93.458,41.731],[-93.453,41.731],[-93.453,41.736],[-93.458,41.736],[-93.458,41.731]]]}}]}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"bad-request","title":"Invalid Request","status":400,"detail":"Validation failed.","instance":"urn:dtn:farm-intel-external-api:/api/v1/land/abc/soil/intersection:requestId:abc123","errors":[{"message":"Path parameter landId must be a valid integer.","parameter":"landId"}]}}}},"401":{"description":"Missing or invalid authentication token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"unauthorized","title":"Error while authenticating the user","status":401,"detail":"Bearer Token is malformed.","instance":"urn:dtn:farm-intel-external-api:requestId:example-id"}}}}}}},"/api/v1/geospatial/land/{landId}":{"get":{"operationId":"getGeospatialLand","summary":"Get GeoJSON polygon for a land parcel","description":"Retrieve the GeoJSON FeatureCollection representing the boundary polygon(s) for a\nland parcel. Properties include land metadata such as acreage, FIPS code, and\ncrop/name status flags.\n\n**Billing:** Unmetered (discovery class).\n","tags":["Land Geospatial"],"parameters":[{"in":"path","name":"landId","required":true,"schema":{"type":"integer","example":3456789},"description":"Unique land parcel identifier."}],"responses":{"200":{"description":"GeoJSON FeatureCollection with the land boundary.","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","enum":["FeatureCollection"],"example":"FeatureCollection"},"features":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["Feature"],"example":"Feature"},"geometry":{"type":"object","properties":{"type":{"type":"string","enum":["Polygon","MultiPolygon"],"example":"MultiPolygon"},"coordinates":{"type":"array","description":"GeoJSON coordinate array (structure depends on geometry type)."}}},"properties":{"type":"object","properties":{"landId":{"type":"integer","example":3456789},"zipCode":{"type":"string","nullable":true,"example":"50316"},"fipsCode":{"type":"string","nullable":true,"example":"19153"},"mtrs":{"type":"string","nullable":true,"example":"4-080N-024W-14"},"acres":{"type":"number","format":"float","example":152.4},"lat":{"type":"number","format":"float","example":41.732},"lon":{"type":"number","format":"float","example":-93.458},"nameStatus":{"type":"string","nullable":true,"description":"Name attribution status for this land.","example":"confirmed"},"cropStatus":{"type":"string","nullable":true,"description":"Crop data availability status.","example":"current"}}}}}}}},"example":{"type":"FeatureCollection","features":[{"type":"Feature","geometry":{"type":"MultiPolygon","coordinates":[[[[-93.46,41.73],[-93.455,41.73],[-93.455,41.735],[-93.46,41.735],[-93.46,41.73]]]]},"properties":{"landId":3456789,"zipCode":"50316","fipsCode":"19153","mtrs":"4-080N-024W-14","acres":152.4,"lat":41.732,"lon":-93.458,"nameStatus":"confirmed","cropStatus":"current"}}]}}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"bad-request","title":"Invalid Request","status":400,"detail":"Validation failed.","instance":"urn:dtn:farm-intel-external-api:/api/v1/geospatial/land/abc:requestId:abc123","errors":[{"message":"Path parameter landId must be a valid integer.","parameter":"landId"}]}}}},"401":{"description":"Missing or invalid authentication token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"unauthorized","title":"Error while authenticating the user","status":401,"detail":"Bearer Token is malformed.","instance":"urn:dtn:farm-intel-external-api:requestId:example-id"}}}}}}},"/api/v1/geospatial/producers/{partyId}":{"get":{"operationId":"getGeospatialProducer","summary":"Get GeoJSON polygons for a producer's lands","description":"Retrieve a GeoJSON FeatureCollection containing boundary polygons for all land\nparcels linked to a producer. Properties include the land-party relationship details\nsuch as role, crop type, and acreage.\n\n**Billing:** Unmetered (discovery class).\n","tags":["Land Geospatial"],"parameters":[{"in":"path","name":"partyId","required":true,"schema":{"type":"integer","example":5091294},"description":"Unique producer identifier."}],"responses":{"200":{"description":"GeoJSON FeatureCollection with all land boundaries for the producer.","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","enum":["FeatureCollection"],"example":"FeatureCollection"},"features":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["Feature"],"example":"Feature"},"geometry":{"type":"object","properties":{"type":{"type":"string","enum":["Polygon","MultiPolygon"],"example":"Polygon"},"coordinates":{"type":"array","description":"GeoJSON coordinate array."}}},"properties":{"type":"object","properties":{"landId":{"type":"integer","example":3456789},"partyId":{"type":"integer","example":5091294},"zipCode":{"type":"string","nullable":true,"example":"50316"},"primary":{"type":"boolean","description":"Whether this is the primary land-party association.","example":true},"producerCode":{"type":"string","nullable":true,"description":"Producer role code.","example":"O"},"acres":{"type":"number","format":"float","example":152.4},"crop":{"type":"string","nullable":true,"description":"Most recent crop planted on this land.","example":"Corn"},"fipsCode":{"type":"string","nullable":true,"example":"19153"},"county":{"type":"string","nullable":true,"example":"Polk"},"lat":{"type":"number","format":"float","example":41.732},"lon":{"type":"number","format":"float","example":-93.458}}}}}}}},"example":{"type":"FeatureCollection","features":[{"type":"Feature","geometry":{"type":"Polygon","coordinates":[[[-93.46,41.73],[-93.455,41.73],[-93.455,41.735],[-93.46,41.735],[-93.46,41.73]]]},"properties":{"landId":3456789,"partyId":5091294,"zipCode":"50316","primary":true,"producerCode":"O","acres":152.4,"crop":"Corn","fipsCode":"19153","county":"Polk","lat":41.732,"lon":-93.458}},{"type":"Feature","geometry":{"type":"Polygon","coordinates":[[[-93.475,41.712],[-93.468,41.712],[-93.468,41.718],[-93.475,41.718],[-93.475,41.712]]]},"properties":{"landId":3456790,"partyId":5091294,"zipCode":"50316","primary":true,"producerCode":"O","acres":80,"crop":"Soybeans","fipsCode":"19153","county":"Polk","lat":41.715,"lon":-93.47}}]}}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"bad-request","title":"Invalid Request","status":400,"detail":"Validation failed.","instance":"urn:dtn:farm-intel-external-api:/api/v1/geospatial/producers/abc:requestId:abc123","errors":[{"message":"Path parameter partyId must be a valid integer.","parameter":"partyId"}]}}}},"401":{"description":"Missing or invalid authentication token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"unauthorized","title":"Error while authenticating the user","status":401,"detail":"Bearer Token is malformed.","instance":"urn:dtn:farm-intel-external-api:requestId:example-id"}}}}}}},"/api/v1/codes/crops":{"get":{"operationId":"listCrops","summary":"List all crop codes","description":"Retrieve the full list of crop codes from the Land Cover Index (LCI). Use the\n`cropId` (LCI ID) when filtering other endpoints by crop type.\n\n**Billing:** Unmetered.\n","tags":["Codes"],"responses":{"200":{"description":"List of crop codes.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Crop"}},"example":[{"cropId":1,"cropName":"Field Corn"},{"cropId":5,"cropName":"Soybeans"},{"cropId":24,"cropName":"Winter Wheat"},{"cropId":36,"cropName":"Alfalfa"},{"cropId":61,"cropName":"Fallow/Idle Cropland"},{"cropId":176,"cropName":"Grass/Pasture"}]}}},"401":{"description":"Missing or invalid authentication token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"unauthorized","title":"Error while authenticating the user","status":401,"detail":"Bearer Token is malformed.","instance":"urn:dtn:farm-intel-external-api:requestId:example-id"}}}}}}},"/api/v1/codes/crops/{lciId}":{"get":{"operationId":"getCropById","summary":"Get a single crop code","description":"Retrieve a single crop code by its LCI ID. Returns the crop name and identifier.\n\n**Billing:** Unmetered.\n","tags":["Codes"],"parameters":[{"in":"path","name":"lciId","required":true,"schema":{"type":"integer","example":1},"description":"Land Cover Index (crop type) identifier."}],"responses":{"200":{"description":"Crop code details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Crop"},"example":{"cropId":1,"cropName":"Field Corn"}}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"bad-request","title":"Invalid Request","status":400,"detail":"Validation failed.","instance":"urn:dtn:farm-intel-external-api:/api/v1/codes/crops/abc:requestId:abc123","errors":[{"message":"Path parameter lciId must be a valid identifier.","parameter":"lciId"}]}}}},"401":{"description":"Missing or invalid authentication token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"unauthorized","title":"Error while authenticating the user","status":401,"detail":"Bearer Token is malformed.","instance":"urn:dtn:farm-intel-external-api:requestId:example-id"}}}}}}},"/api/v1/geographic-areas/counties":{"get":{"operationId":"listCounties","summary":"List all US counties","description":"Retrieve the full list of US counties with their FIPS codes and state associations.\nUse `fipsCode` values when filtering producer endpoints by county.\n\n**Billing:** Unmetered.\n","tags":["Geographic Areas"],"responses":{"200":{"description":"List of US counties.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/County"}},"example":[{"fipsCode":"19001","countyName":"Adair","stateCode":"IA"},{"fipsCode":"19003","countyName":"Adams","stateCode":"IA"},{"fipsCode":"19005","countyName":"Allamakee","stateCode":"IA"},{"fipsCode":"19153","countyName":"Polk","stateCode":"IA"},{"fipsCode":"17001","countyName":"Adams","stateCode":"IL"}]}}},"401":{"description":"Missing or invalid authentication token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"unauthorized","title":"Error while authenticating the user","status":401,"detail":"Bearer Token is malformed.","instance":"urn:dtn:farm-intel-external-api:requestId:example-id"}}}}}}},"/api/v1/geographic-areas/states":{"get":{"operationId":"listStates","summary":"List all US states","description":"Retrieve the full list of US states with their two-letter codes.\n\n**Billing:** Unmetered.\n","tags":["Geographic Areas"],"responses":{"200":{"description":"List of US states.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/State"}},"example":[{"stateCode":"AL","stateName":"Alabama"},{"stateCode":"AK","stateName":"Alaska"},{"stateCode":"AZ","stateName":"Arizona"},{"stateCode":"IA","stateName":"Iowa"},{"stateCode":"IL","stateName":"Illinois"},{"stateCode":"IN","stateName":"Indiana"}]}}},"401":{"description":"Missing or invalid authentication token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"unauthorized","title":"Error while authenticating the user","status":401,"detail":"Bearer Token is malformed.","instance":"urn:dtn:farm-intel-external-api:requestId:example-id"}}}}}}},"/api/v1/credits":{"get":{"operationId":"getCreditStatus","summary":"Get credit balance","description":"Retrieve the current credit balance and contract end date for the authenticated customer.\nShows the quota pool limit, remaining credits, and when the contract period ends.\n\n**Billing:** Unmetered.\n","tags":["Codes"],"responses":{"200":{"description":"Current credit status.","content":{"application/json":{"schema":{"type":"object","properties":{"quotaPool":{"type":"object","properties":{"limit":{"type":"integer","description":"Total credits allocated for the contract period.","example":100000},"remaining":{"type":"integer","description":"Credits remaining in the quota pool.","example":99945}}},"contractEndDate":{"type":"string","format":"date-time","description":"Contract expiration date (ISO 8601). API requests are rejected after this date.","example":"2028-01-01T05:59:59.000Z"}}},"example":{"quotaPool":{"limit":100000,"remaining":99945},"contractEndDate":"2028-01-01T05:59:59.000Z"}}}},"401":{"description":"Missing or invalid authentication token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"unauthorized","title":"Error while authenticating the user","status":401,"detail":"Bearer Token is malformed.","instance":"urn:dtn:farm-intel-external-api:requestId:example-id"}}}},"403":{"description":"Contract expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"contract-expired","title":"Contract Expired","status":403,"detail":"Your credit quota expired on 2025-12-31T23:59:59.000Z"}}}}}}}},"components":{"securitySchemes":{"clientCredentials":{"type":"oauth2","x-receive-token-in":"request-body","flows":{"clientCredentials":{"tokenUrl":"https://api.auth.dtn.com/v1/tokens/authorize"}},"description":"# Using DAIS for M2M/API Auth\nYou have been given a Client ID and a Client Secret, which are used to request a DTN Access Token. DTN Access Tokens are required when making calls to each and every DTN API endpoint. The following information provides additional details on these tokens and how they are generated.\n## What is an Access Token and how is it different from an API Key?\nAn API Key is a random string of characters that an API uses to authorize whether or not a calling client has approved access to an endpoint. These keys are a non-standard approach to API authorization and are generally issued on a per-API basis.\n\nAn Access Token is also a string of characters but is a base-64 encoded JavaScript Object Notation Web Token, or JWT. JWTs are a widely accepted standard that use OAuth concepts and approaches. \n\nBoth API Keys and Access Tokens are used in an Authorization Request Header as a Bearer, meaning there is no difference in where you put this string of characters when you make calls to DTN APIs.\n## How to generate an Access Token?\nWhen requested, an Access Token is generated for your specific Client (ID/Secret) and for a specific API. The DTN Auth and Identity Service (DAIS) generates new Access Tokens for your client. The DAIS endpoint is `POST https://api.auth.dtn.com/v1/tokens/authorize`.\n\nThis endpoint takes two Header parameters:\n  * `Content-Type: application/json`\n  * `Accept: application/json`\n\nThis endpoint takes four parameters in the Request Body:\n  * `grant_type`: this should always be client_credentials for generating machine-to-machine tokens.\n  * `client_id`: this is the Client ID or Application ID using the token and is given to you by DTN's Identity Team. This ID will never change for your client/application.\n  * `client_secret`: this is the Client Secret that is associated with the Application ID and is given to you by DTN's Identity Team. This key is subject to rotation for security purposes but always with the client's knowledge.\n  * `audience`: this is the API for which this Access Token will be used. For the Farm Intel API, you need to use the following audience: https://api-farm-intelligence.dev.ag.zones.dtn.com\n\nYou can use this CURL command template as a reference for obtaining an access token:\n  ```\n  curl --location --request POST 'https://api.auth.dtn.com/v1/tokens/authorize' \\\n--header 'Accept: application/json' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n\"grant_type\": \"client_credentials\",\n\"client_id\": \"insert your client id here\",\n\"client_secret\": \"insert your client secret here\",\n\"audience\": \"insert your audience here\"\n}' \n  ```\n\n*This document, for demonstration purposes, supplies a client_id and client_secret in all code examples. This client/application is for a fictitious API and cannot be used in practice to gain unauthorized access to any other DTN API.*\nUpon generating a new Access Token, you should receive an HTTP Response from DAIS similar to this:\n  ```\n  {\n    \"data\": {\n          \"access_token\": \"eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6InpfX21pZW13NGhoTmdvQWQxR3N6ciJ9.eyJodHRwczovL2F1dGguZHRuLmNvbS9jdXN0b21lcklkIjoiMTIzNDU2Nzg5MERlbW8iLCJodHRwczovL2F1dGguZHRuLmNvbS9wcm9kdWN0Q29kZSI6IkRlbW9BcGlQIiwiaHR0cHM6Ly9hdXRoLmR0bi5jb20vcmVxdWVzdGVySXAiOiIxOC4yMTMuMTc0LjI3IiwiaHR0cHM6Ly9hdXRoLmR0bi5jb20vcnBzIjoiMTAwIiwiaHR0cHM6Ly9hdXRoLmR0bi5jb20vdGllciI6IkJhc2ljIiwiaHR0cHM6Ly9hdXRoLmR0bi5jb20vcXVvdGEiOiI5OTk5OTkiLCJpc3MiOiJodHRwczovL2lkLmF1dGguZHRuLmNvbS8iLCJzdWIiOiJuZnlPM0tpS1BSOE4wREtSNUNMOGpTOUdGQkNEZXlGTUBjbGllbnRzIiwiYXVkIjoiaHR0cHM6Ly9kZW1vLWFwaS5hdXRoLmR0bi5jb20vIiwiaWF0IjoxNjU2MDk5MDY4LCJleHAiOjE2NTYwOTkxNTgsImF6cCI6Im5meU8zS2lLUFI4TjBES1I1Q0w4alM5R0ZCQ0RleUZNIiwic2NvcGUiOiJyZWFkOmRlbW8gY3JlYXRlOmRlbW8gdXBkYXRlOmRlbW8iLCJndHkiOiJjbGllbnQtY3JlZGVudGlhbHMiLCJwZXJtaXNzaW9ucyI6WyJyZWFkOmRlbW8iLCJjcmVhdGU6ZGVtbyIsInVwZGF0ZTpkZW1vIl19.0VHdyp1w9PPFVI0FPheAwuKZwb5C25rwP-LPMXcSNoRmouvga1DZtNLA67ZzE_sAlc_VpaDRr6daLKr_Alw4347mw9sdjP8wKR27kCZa9JZK5PGQMmXHscATbzBEJYpCPklfyGaajgymqTBGnedcv8F0UvlRzQPsFeRPnVoX7BWOSXpMbyToGiXWkQLBQT7r96KAmLZOPJFZspPtjw-wH2mSL2WNa_nkB4j5vMGhGxlKiNRsKb30TH_WAel2hsxNlcPK3XHCmrMTYsNnu7HNqOTMn2i0__0rvBrhSWEw-_grqQDmWFJuWd7Qhi1q81AaJcdqgoSa_efz93QFclJUNw\",\n          \"scope\": \"read:demo create:demo update:demo\",\n          \"expires_in\": 90,\n          \"token_type\": \"Bearer\"\n      },\n      \"meta\": {\n          \"date_time\": \"2022-06-24T19:09:42.963Z\",\n          \"name\": \"v1.tokens.authorize\",\n          \"uuid\": \"ee6f9feb-dcf8-4421-a6fd-efd6beabdaa9\",\n          \"start_timestamp\": 1656097782509,\n          \"end_timestamp\": 1656097782963,\n          \"execution_time\": 454\n      }\n  }\n  ```\nLooking at this Response, you will see:\n  * `access_token`: contains the JWT Access Token string you will use as your Bearer token.\n  * `scope`: contains the scopes that this Access Token gives you permissions to access.\n  * `expires_in`: contains the length of time before this Access Token will expire, in seconds.\n  * `token_type`: verifies that this Access Token should be used as a Bearer token.\n\n## How to use an Access Token after one is generated?\nOnce a new Access Token is obtained, it is used in each call to a DTN API endpoint as a Bearer token in an Authorization Request Header. For example:\n  ```\n  Header: 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6InpfX21pZW13NGhoTmdvQWQxR3N6ciJ9.eyJodHRwczovL2F1dGguZHRuLmNvbS9jdXN0b21lcklkIjoiMTIzNDU2Nzg5MERlbW8iLCJodHRwczovL2F1dGguZHRuLmNvbS9wcm9kdWN0Q29kZSI6IkRlbW9BcGlQIiwiaHR0cHM6Ly9hdXRoLmR0bi5jb20vcmVxdWVzdGVySXAiOiIxOC4yMTMuMTc0LjI3IiwiaHR0cHM6Ly9hdXRoLmR0bi5jb20vcnBzIjoiMTAwIiwiaHR0cHM6Ly9hdXRoLmR0bi5jb20vdGllciI6IkJhc2ljIiwiaHR0cHM6Ly9hdXRoLmR0bi5jb20vcXVvdGEiOiI5OTk5OTkiLCJpc3MiOiJodHRwczovL2lkLmF1dGguZHRuLmNvbS8iLCJzdWIiOiJuZnlPM0tpS1BSOE4wREtSNUNMOGpTOUdGQkNEZXlGTUBjbGllbnRzIiwiYXVkIjoiaHR0cHM6Ly9kZW1vLWFwaS5hdXRoLmR0bi5jb20vIiwiaWF0IjoxNjU2MDk5MDY4LCJleHAiOjE2NTYwOTkxNTgsImF6cCI6Im5meU8zS2lLUFI4TjBES1I1Q0w4alM5R0ZCQ0RleUZNIiwic2NvcGUiOiJyZWFkOmRlbW8gY3JlYXRlOmRlbW8gdXBkYXRlOmRlbW8iLCJndHkiOiJjbGllbnQtY3JlZGVudGlhbHMiLCJwZXJtaXNzaW9ucyI6WyJyZWFkOmRlbW8iLCJjcmVhdGU6ZGVtbyIsInVwZGF0ZTpkZW1vIl19.0VHdyp1w9PPFVI0FPheAwuKZwb5C25rwP-LPMXcSNoRmouvga1DZtNLA67ZzE_sAlc_VpaDRr6daLKr_Alw4347mw9sdjP8wKR27kCZa9JZK5PGQMmXHscATbzBEJYpCPklfyGaajgymqTBGnedcv8F0UvlRzQPsFeRPnVoX7BWOSXpMbyToGiXWkQLBQT7r96KAmLZOPJFZspPtjw-wH2mSL2WNa_nkB4j5vMGhGxlKiNRsKb30TH_WAel2hsxNlcPK3XHCmrMTYsNnu7HNqOTMn2i0__0rvBrhSWEw-_grqQDmWFJuWd7Qhi1q81AaJcdqgoSa_efz93QFclJUNw'\n  ```\n\n## Deconstructing the Access Token\nA DTN Access Token carries information within its JWT Body that is available on every API call. By deconstructing the JWT token, our Access Tokens will resemble:\n  ```\n  {\n    \"https://auth.dtn.com/customerId\": \"1234567890Demo\",\n    \"https://auth.dtn.com/productCode\": \"DemoApiP\",\n    \"https://auth.dtn.com/requesterIp\": \"18.213.174.27\",\n    \"https://auth.dtn.com/rps\": \"100\",\n    \"https://auth.dtn.com/tier\": \"Basic\",\n    \"https://auth.dtn.com/quota\": \"999999\",\n    \"iss\": \"https://id.auth.dtn.com/\",\n    \"sub\": \"nfyO3KiKPR8N0DKR5CL8jS9GFBCDeyFM@clients\",\n    \"aud\": \"https://demo-api.auth.dtn.com/\",\n    \"iat\": 1656099068,\n    \"exp\": 1656099158,\n    \"azp\": \"nfyO3KiKPR8N0DKR5CL8jS9GFBCDeyFM\",\n    \"scope\": \"read:demo create:demo update:demo\",\n    \"gty\": \"client-credentials\",\n    \"permissions\": [\n      \"read:demo\",\n      \"create:demo\",\n      \"update:demo\"\n    ]\n  }\n  ```\n### Description of Claims\n\n  | Claim                              | Type                                        | Description                                                                                                                                                                                                                |\n  | -----------------------------------| --------------------------------------------| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n  | `https://auth.dtn.com/customerId`  | String                                      | Custom DTN claim containing the Customer ID found in the DTN Order Management/Salesforce system associated with this token.                                                                                                |\n  | `https://auth.dtn.com/productCode` | String                                      | Custom DTN claim containing the Identity product code associated with this token.                                                                                                                                          |\n  | `https://auth.dtn.com/requesterIp` | String                                      | Custom DTN claim containing the IP address of the requesting client.                                                                                                                                                       |\n  | `https://auth.dtn.com/rps`         | String                                      | Custom DTN claim containing the maximum rate per second this customer is authorized to utilize.                                                                                                                            |\n  | `https://auth.dtn.com/tier`        | String                                      | Custom DTN claim containing the data tier the customer purchased for the requested access.                                                                                                                                 |\n  | `https://auth.dtn.com/quota`       | String                                      | Custom DTN claim containing the maximum yearly quota the customer purchased for calling DTN endpoints for the specific product.                                                                                            |\n  | `iss`                              | String (URI)                                | The Security Token Service (STS) that issues and returns the token. If this value is not from `https://id.auth.dtn.com/`, the token should not be considered trusted.                                                      |\n  | `sub`                              | String (URI)                                | The principle about which the token asserts information (the User ID or Client ID within the Identity Provider). A User ID will start with a prefix of `auth0\\|`, while the Client ID will end with the suffix `@clients`. |\n  | `aud`                              | String \\| Array (Strings) (URI \\| [URI, …]) | Identifies the intended recipient(s) of the token – its audience. The token should be rejected if the audience does not contain values expected by the calling application.                                                |\n  | `iat`                              | Number (Timestamp)                          | “Issued At” indicates when the authentication for this token occurred.                                                                                                                                                     |\n  | `exp`                              | Number (Timestamp)                          | The “expiration time” on or after which the JWT must not be accepted for processing.                                                                                                                                       |\n  | `azp`                              | String                                      | The application/client ID of the client using the token. The application can cat as itself or on behalf of a user.                                                                                                         |\n  | `gty`                              | String (Space-delimited)                    | The grant type that was used to request the token – not an RFC 7519 registered claim (Auth0-specific).                                                                                                                     |\n  | `permissions`                      | Array (Strings)                             | The grant type that was used to request the token – not an RFC 7519 registered claim (Auth0-specific).                                                                                                                     |\n\n  "}},"schemas":{"Producer":{"type":"object","description":"A producer record representing an agricultural entity (farmer, company, cooperative).","properties":{"producerId":{"type":"integer","description":"Unique identifier for the producer.","example":5091294},"firstName":{"type":"string","nullable":true,"description":"Producer's first name (null for company-only records).","example":"John"},"lastName":{"type":"string","nullable":true,"description":"Producer's last name (null for company-only records).","example":"Smith"},"companyName":{"type":"string","nullable":true,"description":"Company or farm name (null for individual-only records).","example":"Smith Farms LLC"},"address":{"type":"string","nullable":true,"description":"Street address line.","example":"123 Farm Rd"},"city":{"type":"string","nullable":true,"description":"City name.","example":"Des Moines"},"state":{"type":"string","nullable":true,"description":"Two-letter state code.","example":"IA"},"postalCode":{"type":"string","nullable":true,"description":"ZIP code, optionally with +4 extension (e.g., \"50316-2921\").","example":"50316-2921"},"fipsCode":{"type":"string","nullable":true,"description":"5-digit county FIPS code. Use /geographic-areas/counties to look up county names.","example":"19153"},"county":{"type":"string","nullable":true,"description":"County name.","example":"Polk"},"lat":{"type":"number","format":"float","nullable":true,"description":"Latitude of the producer's address (decimal degrees, WGS84).","example":41.601},"lon":{"type":"number","format":"float","nullable":true,"description":"Longitude of the producer's address (decimal degrees, WGS84).","example":-93.609},"locationAccuracy":{"type":"string","nullable":true,"description":"Human-readable description of the geocoding accuracy for the lat/lon coordinates.\nValues include: \"Address was DPV confirmed...\", \"PO Box\", \"Zip 5 Centroid\",\n\"Zip 7 Centroid\", \"Zip 9 Centroid\", \"Approximate\", \"Range Interpolation\",\n\"Geometric Center\", \"Intersection\", \"Failure\".\n","example":"Address was DPV confirmed for the primary number only, and secondary number information was missing."},"role":{"type":"string","nullable":true,"description":"Producer's role/relationship to the land.\nValues: \"operator\", \"owner-operator\", \"owner\", \"other\"\n","enum":["operator","owner-operator","owner","other"],"example":"operator"},"status":{"type":"string","nullable":true,"description":"Customer relationship status (if tracked).\nValues: \"lead\", \"prospect\", \"customer\", \"former-customer\", \"other\"\n","enum":["lead","prospect","customer","former-customer","other"],"example":"customer"},"externalID":{"type":"string","nullable":true,"description":"Customer's external CRM/ERP identifier for this producer (if synced).","example":"CRM-12345"},"phones":{"type":"array","items":{"type":"string"},"description":"Up to 3 phone numbers, ordered by priority. Empty array if do-not-contact is flagged\nor no phone numbers are available.\n","example":["515-555-0100","515-555-0101"]},"emails":{"type":"array","items":{"type":"string"},"description":"Up to 3 email addresses, ordered by priority. Empty array if do-not-contact is flagged\nor no emails are available.\n","example":["john@smithfarms.com"]}}},"ProducerDetail":{"type":"object","description":"Detailed producer record returned by the single-producer lookup endpoint.\nNote: This shape differs from the list endpoint producer record (which uses producerId, phones[], emails[]).\nThis endpoint returns the CPDA detail format with singular email/phone fields.\n","properties":{"partyId":{"type":"integer","description":"Unique producer identifier.","example":5091294},"firstName":{"type":"string","nullable":true,"example":"John"},"lastName":{"type":"string","nullable":true,"example":"Smith"},"companyName":{"type":"string","nullable":true,"example":"Smith Farms LLC"},"address":{"type":"string","nullable":true,"example":"123 Farm Rd"},"city":{"type":"string","nullable":true,"example":"Des Moines"},"state":{"type":"string","nullable":true,"example":"IA"},"postalCode":{"type":"string","nullable":true,"example":"50316-2921"},"county":{"type":"string","nullable":true,"example":"Polk"},"email":{"type":"string","nullable":true,"description":"Primary email address.","example":"john@smithfarms.com"},"phone":{"type":"string","nullable":true,"description":"Primary phone number.","example":"515-555-0100"},"externalId":{"type":"string","nullable":true,"description":"Customer's external CRM/ERP identifier.","example":"CRM-12345"}}},"Pagination":{"type":"object","description":"Pagination metadata for list responses.","properties":{"total":{"type":"integer","description":"Total number of records matching the query (across all pages).","example":150},"hasMore":{"type":"boolean","description":"Whether there are more results beyond the current page.","example":true}}},"Error":{"type":"object","description":"RFC 7807 Problem Detail error response.","properties":{"type":{"type":"string","description":"Error type identifier.","example":"bad-request"},"title":{"type":"string","description":"Human-readable error title.","example":"Invalid Request"},"status":{"type":"integer","description":"HTTP status code.","example":400},"detail":{"type":"string","description":"Human-readable error description.","example":"Validation failed."},"instance":{"type":"string","description":"URI identifying the specific request that failed (includes request ID for tracing).","example":"urn:dtn:farm-intel-external-api:/api/v1/producer/search/radius:requestId:abc123"},"errors":{"type":"array","description":"Detailed validation errors (present for 400 responses).","items":{"type":"object","properties":{"message":{"type":"string","description":"Description of what's wrong.","example":"Required query parameter lat is invalid or missing."},"parameter":{"type":"string","description":"The parameter that failed validation.","example":"lat"}}}}}},"LandSearchResult":{"type":"object","description":"A land parcel record returned from search or list endpoints.","properties":{"landId":{"type":"integer","description":"Unique identifier for the land parcel.","example":3456789},"lat":{"type":"number","format":"float","description":"Latitude of the land centroid (decimal degrees, WGS84).","example":41.732},"lon":{"type":"number","format":"float","description":"Longitude of the land centroid (decimal degrees, WGS84).","example":-93.458},"acres":{"type":"number","format":"float","description":"Total acreage of the land parcel.","example":152.4},"fipsCode":{"type":"string","description":"5-digit county FIPS code where the land is located.","example":"19153"},"zipCode":{"type":"string","nullable":true,"description":"ZIP code of the land parcel.","example":"50316"},"mtrs":{"type":"string","nullable":true,"description":"Meridian-Township-Range-Section legal description.","example":"4-080N-024W-14"}}},"LandCrop":{"type":"object","description":"A crop history record for a land parcel.","properties":{"landId":{"type":"integer","description":"Land parcel identifier.","example":3456789},"cropYear":{"type":"integer","description":"Year the crop was planted/harvested.","example":2025},"acres":{"type":"number","format":"float","description":"Acres planted with this crop in the given year.","example":148.2},"lciId":{"type":"integer","description":"Land Cover Index (crop type) identifier. Use /codes/crops to look up crop names.","example":1},"planted":{"type":"string","format":"date-time","nullable":true,"description":"Date the crop was planted (ISO 8601 timestamp), or null if unknown.","example":"2025-04-15T00:00:00Z"},"harvested":{"type":"string","format":"date-time","nullable":true,"description":"Date the crop was harvested (ISO 8601 timestamp), or null if unknown.","example":"2025-10-20T00:00:00Z"}}},"Segment":{"type":"object","description":"A customer-defined segment (saved audience of producers).","properties":{"segmentId":{"type":"integer","description":"Unique identifier for the segment.","example":4521},"segmentName":{"type":"string","description":"Human-readable name of the segment.","example":"Iowa Corn Operators 500+ Acres"},"numberOfProducers":{"type":"integer","description":"Number of producers currently in the segment.","example":312},"dateCreated":{"type":"string","format":"date-time","description":"ISO 8601 timestamp when the segment was created.","example":"2025-03-15T14:30:00Z"},"creator":{"type":"string","nullable":true,"description":"Name of the user who created the segment.","example":"Jane Doe"}}},"Portfolio":{"type":"object","description":"A customer-defined portfolio (curated list of producers).","properties":{"portfolioId":{"type":"integer","description":"Unique identifier for the portfolio.","example":782},"portfolioName":{"type":"string","description":"Human-readable name of the portfolio.","example":"2025 Spring Prospects"},"numberOfProducers":{"type":"integer","description":"Number of producers currently in the portfolio.","example":45},"dateCreated":{"type":"string","format":"date-time","description":"ISO 8601 timestamp when the portfolio was created.","example":"2025-01-10T09:15:00Z"},"creator":{"type":"string","nullable":true,"description":"Name of the user who created the portfolio.","example":"John Smith"}}},"Crop":{"type":"object","description":"A crop code entry from the Land Cover Index.","properties":{"cropId":{"type":"integer","description":"Unique crop identifier (LCI ID).","example":1},"cropName":{"type":"string","description":"Human-readable crop name.","example":"Field Corn"}}},"County":{"type":"object","description":"A US county with its FIPS code.","properties":{"fipsCode":{"type":"string","description":"5-digit county FIPS code.","example":"19153"},"countyName":{"type":"string","description":"County name.","example":"Polk"},"stateCode":{"type":"string","description":"Two-letter state code.","example":"IA"}}},"State":{"type":"object","description":"A US state.","properties":{"stateCode":{"type":"string","description":"Two-letter state code.","example":"IA"},"stateName":{"type":"string","description":"Full state name.","example":"Iowa"}}}}},"x-tagGroups":[{"name":"Producer API","tags":["Producer Search","Producer Details","Producer Relationships"]},{"name":"Land API","tags":["Land Search","Land Details","Land Crop","Land Geospatial"]},{"name":"Linked Data API","tags":["Segments","Portfolios"]},{"name":"Shared Utilities","tags":["Codes","Geographic Areas"]}]}