DTN corporate logo
API docs by Redocly

DTN AgCore Client Applications API (1.0.0)

Download OpenAPI specification:

DTN Agriculture Intelligence Team: agintel@dtn.com

Introduction

This set of endpoints are custom built for DTN web application products such as Farmers for Soil Health (FSH) and the Grain Intelligence Hub.

Authentication

Users must be authenticated through the DTN Identity Management Tool. Credentials are passed as bearer tokens from the web application.

/api/v1/health-check

Get a message to prove the API is responding.

Returns a message to indicate the API is up and running.

Responses

Response samples

Content type
application/json
{
  • "message": "works"
}

/api/v1/usda/crops

Get all crop data from a table.

Returns a list of all crop data from the Land, Income, and Crop object data tables.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

/api/v1/usda/{landId}/cover-crop

Cover crop data by year and landID

Returns a list of cover crop and crop type data.

Authorizations:
bearerAuth
path Parameters
landId
required
integer

Numeric ID of the land to get

query Parameters
limit
number

The maximum response amount desired, if no limit all matching results will be returned.

offset
number

The offset of the last previously returned pagination results. To be used with limit for pagination.

crop-year
number

When passed, returns all data for a matching crop-year. Multiple occurrences are allowed.

Responses

Response samples

Content type
application/json
{}

/api/v1/usda/cover-crops

Cover crop data by year and landID

Returns a list of cover crop and crop type data.

Authorizations:
bearerAuth
query Parameters
year
number >= 1

The crop year associated with the requested data. This parameter is optional.

Request Body schema: application/json
required

List of primary keys for land objects.

landIds
required
Array of numbers[ items >= 1 ]

Responses

Request samples

Content type
application/json
{
  • "landIds": [
    ]
}

Response samples

Content type
application/json
[
  • {
    }
]

/api/v1/usda/party/search

Get party data by name and postal code.

Returns a list of a party's information based on a name and postal code search.

Authorizations:
bearerAuth
query Parameters
name
required
string
Example: name=smith

This will search for any party with last names starting with the inputted characters and search for any companies that include the specified characters.

postal-code
required
string (postalCode)
Example: postal-code=28320

A postal code search.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

/api/v1/usda/search-radius

Land data by latitude, longitude and radius.

Returns a list of land data excluding a party (if party id is passed) or all for a given point radius.

Authorizations:
bearerAuth
query Parameters
lat
required
number (latitude) [ -90 .. 90 ]
Example: lat=39.9191954099076

latitude

lon
required
number (longitude) [ -180 .. 180 ]
Example: lon=-73.899739925533

longitude

radius
required
number (radius) [ 1 .. 50000 ]

The search radius in meters.

party-id
number

Optional, if no party id all parties land is searched. If party id is present that parties land is excluded from the search.

Responses

Response samples

Content type
application/json
[
  • [
    ]
]

Land data by latitude, longitude and radius.

Returns a list of land data for a given point radius while excluding a party if party argument is passed.

Authorizations:
bearerAuth
query Parameters
lat
required
number (latitude) [ -90 .. 90 ]
Example: lat=39.9191954099076

latitude

lon
required
number (longitude) [ -180 .. 180 ]
Example: lon=-73.899739925533

longitude

radius
required
number (radius) [ 1 .. 50000 ]

The search radius in meters.

party-id
number

If no party id all parties land is searched. If party id is present that parties land is excluded from the search.

Request Body schema: application/json

List of land to exclude from search results (land has already been enrolled).

excludeLandIds
Array of numbers[ items >= 1 ]
includeStates
Array of strings[ items >= 1 ]

Responses

Request samples

Content type
application/json
{
  • "excludeLandIds": [
    ],
  • "includeStates": [
    ]
}

Response samples

Content type
application/json
[
  • [
    ]
]

/api/v1/usda/party/{partyId}/land

Returns a list land linked to a party id

Returns a list land linked to a party id either all or filtered by participating states.

Authorizations:
bearerAuth
path Parameters
partyId
required
integer

Numeric ID of the party

Request Body schema: application/json

List of participating states and or land ids to exclude.

includeStates
Array of strings[ items >= 1 ]
excludeLandIds
Array of numbers[ items >= 1 ]

Responses

Request samples

Content type
application/json
{
  • "includeStates": [
    ],
  • "excludeLandIds": [
    ]
}

Response samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]

Returns a list land linked to a party id

Returns a list land linked to a party id.

Authorizations:
bearerAuth
path Parameters
partyId
required
integer

Numeric ID of the party

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]

/app-views/grower-profile/address/{addressId}/related

Related address data by addressId.

Returns a list of related parties by address id.

Authorizations:
bearerAuth
path Parameters
addressId
required
integer

Numeric ID of the address.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

/app-views/grower-profile/party/{partyId}/land

Land and Crop data by partyId.

Returns a list of results containing land attributes and 7 years of crop data.

Authorizations:
bearerAuth
path Parameters
partyId
required
integer

Numeric ID of the party whose land we are getting.

Responses

Response samples

Content type
application/json
{
  • "result": [
    ]
}

/app-views/grower-profile/party/{partyId}/land-grids

Land grids data by partyId.

Returns a list of land grids.

Authorizations:
bearerAuth
path Parameters
partyId
required
integer

Numeric ID of the party whose land we are getting.

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

/app-views/grower-profile/party/{partyId}/grainbin

Grainbin data by partyId.

Returns a list of results containing a parties grainbins and their attributes.

Authorizations:
bearerAuth
path Parameters
partyId
required
integer

Numeric ID of the party whose land we are getting.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

/app-views/grower-profile/grower-names

Grower names by partyIds.

Returns a list of grower names by partyIds.

Authorizations:
bearerAuth
query Parameters
party-id
required
Array of numbers

Comma separated list of Party IDs.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

/app-views/grower-profile/grower-relationships

Land and Acres data for main and related growers.

Returns individual and shared data between main and related growers.

Authorizations:
bearerAuth
query Parameters
party-id
required
number

Party ID for the main grower

related-party-id
required
number

Party ID for the related grower

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    }
]

/api/v1/app-views/sustainable-practices/lands

Get inventories of all lands enrolled in sustainable practice programs

Get detailed inventory of all lands enrolled in sustainable practice programs

Authorizations:
bearerAuth
query Parameters
land-practice-id
Array of strings <uuid> [ items <uuid > ]

when passed, returns all land practices with a matching land-practice-id. Multiple occurrences are allowed.

practice-id
Array of integers <int64> [ items <int64 > ]

when passed, returns all sustainable practices with a matching practice-id. Multiple occurrences are allowed. If none passed, only active sustainable practices are returned

state-code
Array of strings (participatingStates)
Items Enum: "DE" "IL" "IN" "IA" "KS" "KY" "MD" "MI" "MN" "MO" "NE" "NY" "NC" "ND" "OH" "PA" "SD" "TN" "VA" "WI"
Example: state-code=IA

when passed, returns all lands with a matching state-code. Multiple occurrences are allowed. If none passed, lands in all participating states are returned

fsh-verified
boolean

when TRUE, returns all lands in sustainable programs that have been verified by FSH. Otherwise, all lands are returned

crop-year
Array of integers <int64> [ items <int64 > ]

when passed, returns all sustainable practice programs with a matching crop-year. Multiple occurrences are allowed

land-id
Array of integers <int64> [ items <int64 > ]

when passed, returns all sustainable practices with a matching land-id. Multiple occurrences are allowed.

lat
number (latitude) [ -90 .. 90 ]
Example: lat=39.9191954099076

latitude. Rerquired if lon and/or radius are passed.

lon
number (longitude) [ -180 .. 180 ]
Example: lon=-73.899739925533

longitude. Rerquired if lon and/or radius are passed.

radius
number (radius) [ 1 .. 50000 ]

The search radius in meters. Rerquired if lat and/or lon are passed.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

/api/v1/app-views/sustainable-practices/lands/check-available

Checks which given landIds have been already enrolled in a sustainable practice program

Checks which given landIds have been already enrolled in a sustainable practice program by a different customerId

Authorizations:
bearerAuth
query Parameters
land-id
required
Array of numbers

Required. AgCore Land identifier to be checked within the land practices. Multiple occurrences are allowed.

Responses

Response samples

Content type
application/json
[
  • 0
]

/api/v1/app-views/sustainable-practices/lands/inventories

Get user inventories of lands enrolled in sustainable practice programs

Get detailed inventory of user's lands enrolled in sustainable practice programs

Authorizations:
bearerAuth
query Parameters
land-practice-id
Array of strings <uuid> [ items <uuid > ]

when passed, returns all land practices with a matching land-practice-id. Multiple occurrences are allowed.

practice-id
Array of integers <int64> [ items <int64 > ]

when passed, returns all sustainable practices with a matching practice-id. Multiple occurrences are allowed. If none passed, only active sustainable practices are returned

starts-after
string <date>
Example: starts-after=2024-03-01

when passed, only land in sustainable programs that start on or after the given date are returned

ends-before
string <date>
Example: ends-before=2025-03-01

when passed, only land in sustainable programs that end on or before the given date are returned

state-code
Array of strings (participatingStates)
Items Enum: "DE" "IL" "IN" "IA" "KS" "KY" "MD" "MI" "MN" "MO" "NE" "NY" "NC" "ND" "OH" "PA" "SD" "TN" "VA" "WI"
Example: state-code=IA

when passed, returns all lands with a matching state-code. Multiple occurrences are allowed. If none passed, lands in all participating states are returned

fsh-verified
boolean

when TRUE, returns all lands in sustainable programs that have been verified by FSH. Otherwise, all lands are returned

crop-year
Array of integers <int64> [ items <int64 > ]

when passed, returns all sustainable practice programs with a matching crop-year. Multiple occurrences are allowed

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Update inventories of lands enrolled in sustainable practice programs

Update inventories of lands enrolled in sustainable practice programs through transactions

Authorizations:
bearerAuth
Request Body schema: application/json
required

List of objects containing details of a transaction request to update the land practice inventory.

Array
landPracticeId
required
string <uuid>
originator
required
string
Value: "SusMarketplace"
originatorReference
required
string
executionStatus
required
string
Enum: "accepted" "adjusted_up" "adjusted_down" "withdrawn"
lastQuantity
required
number
executedAt
required
string <date-time>

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
[
  • {
    }
]

/api/v1/app-views/sustainable-practices/lands/verifications

Get land identifiers of unverified land practices by practice and crop year

Get list of land identifiers enrolled with a given sustainable practice that have not been verified yet in a given crop year

Authorizations:
bearerAuth
query Parameters
crop-year
required
integer <int64>

Required. Filters all land practices enrolled in a sustainable practice programs with a matching crop-year.

practice-id
required
integer <int64>

Required. filters all lands enrolled in a sustainable practice with a matching practice-id. Currently, only practiceId=1 (Cover crop) is allowed.

land-id
Array of numbers

Optional. AgCore Land identifier to be checked within the land practices. Multiple occurrences are allowed.

Responses

Response samples

Content type
application/json
[
  • 0
]

Update land practice verification status

Update verfication status of lands enrolled in sustainable practice programs

Authorizations:
bearerAuth
Request Body schema: application/json
required

List of objects containing details of a land verified.

Array
agCoreLandId
required
number

Uniquely identifies the land in agcore

practiceId
required
integer <int64>
verifiedAt
required
string <date-time>
cropYear
required
integer <int64>
coverCrop
boolean

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
[
  • {
    }
]

/api/v1/app-views/sustainable-practices/practices

Get sustainable practices catalog

By passing in the appropriate options, you can search in the sustainable practice catalog the practices that meet the given criteria

Authorizations:
bearerAuth
query Parameters
practice-id
Array of integers <int64> [ items <int64 > ]

when passed, returns all sustainable practices with a matching practice-id. Multiple occurrences are allowed. If none passed, only active sustainable practices are returned

show-all
boolean

when TRUE, returns all active and inactive sustainable practices. Otherwise, only active ones are returned

Responses

Response samples

Content type
application/json
[
  • {
    }
]

/api/v1/app-views/sustainable-practices/programs

Get sustainable practice programs catalog

By passing in the appropriate options, you can search in the sustainable practice programs catalog the programs that meet the given criteria

Authorizations:
bearerAuth
query Parameters
program-id
Array of integers <int64> [ items <int64 > ]

when passed, returns all sustainable practice programs with a matching program-id. Multiple occurrences are allowed

practice-id
Array of integers <int64> [ items <int64 > ]

when passed, returns all sustainable practices with a matching practice-id. Multiple occurrences are allowed. If none passed, only active sustainable practices are returned

show-all
boolean

when TRUE, returns all active and inactive sustainable programs. Otherwise, only active ones are returned

status
Array of strings
Items Enum: "open" "closed" "restricted"

when passed, returns all sustainable programs with a matching status. Multiple occurrences are allowed. If none passed, only sustainable programs with an "open" status are returned

starts-after
string <date>
Example: starts-after=2024-03-01

when passed, only sustainable programs that start on or after the given date are returned

ends-before
string <date>
Example: ends-before=2025-03-01

when passed, only sustainable programs that end on or before the given date are returned

crop-year
Array of integers <int64> [ items <int64 > ]

when passed, returns all sustainable practice programs with a matching crop-year. Multiple occurrences are allowed

Responses

Response samples

Content type
application/json
[
  • {
    }
]

/api/v1/app-views/sustainable-practices/programs/{programId}

Get details of a given sustainable practice program

By passing in the appropriate options, you can get details of a given sustainable practice program, including specific practices associated with it

Authorizations:
bearerAuth
path Parameters
programId
required
integer <int64>

sustainable practice program identifier

query Parameters
practice-id
Array of integers <int64> [ items <int64 > ]

when passed, returns all sustainable practices with a matching practice-id. Multiple occurrences are allowed. If none passed, only active sustainable practices are returned

Responses

Response samples

Content type
application/json
{
  • "programId": "1",
  • "name": "string",
  • "description": "string",
  • "status": "open",
  • "active": "true",
  • "startsAt": "2023-03-01T05:00:00.000Z",
  • "endsAt": "2024-03-01T05:00:00.000Z",
  • "cropYear": 2024,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "practices": [
    ]
}

/api/v1/app-views/sustainable-practices/programs/{programId}/enrollments

Save sustainable practices enrollment for a specific program.

Allows users to save a sustainable practices enrollment for a specific program. Users can specify the parties, lands, and practices they want to enroll in the program. The service processes the given enrollment object and performs actions like adding, updating, or deleting the land practice data accordingly.

Authorizations:
bearerAuth
path Parameters
programId
required
integer

The identifier for the sustainable practice program.

Request Body schema: application/json
required

Object containing details for sustainable practices enrollment.

Array of objects
required
Array of objects

Responses

Request samples

Content type
application/json
{
  • "parties": [
    ],
  • "enrolledLands": [
    ]
}

Response samples

Content type
application/json
{
  • "dtnCustomerId": "string",
  • "enrolledLands": [
    ],
  • "parties": [
    ]
}

Returns the sustainable practices enrollments and associated parties.

Returns the sustainable practices enrollments and associated parties.

Authorizations:
bearerAuth
path Parameters
programId
required
integer

The identifier for the sustainable practice program.

Responses

Response samples

Content type
application/json
{
  • "dtnCustomerId": "string",
  • "enrolledLands": [
    ],
  • "parties": [
    ]
}

/api/v1/app-views/sustainable-practices/land-outcomes/inventories

Get Inventories

Authorizations:
bearerAuth
query Parameters
verified
boolean
fips-codes
string
Example: fips-codes=100010,470321
crop-years
string
Example: crop-years=2024,2023
land-outcome-ids
string
Example: land-outcome-ids=1,2
outcome-type-ids
string
Example: outcome-type-ids=1,2
unit-of-measurements
string
Example: unit-of-measurements=1,2
state-codes
string
Example: state-codes=CO,MO
outcomes
string
Example: outcomes=Cover Crop
active
boolean
limit
number
offset
number
header Parameters
x-requested-customer-id
string

Required if the requesting user has multiple customer ids or using an M2M token.

Responses

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "links": {},
  • "count": 0
}

Create inventories for land outcomes

Authorizations:
bearerAuth
Request Body schema: application/json
required
agcoreLandId
required
integer
dtnCustomerId
string
required
Array of objects

Responses

Request samples

Content type
application/json
{
  • "agcoreLandId": 10,
  • "dtnCustomerId": "4c6966d49d0a4bcea2a024b7cf505b19",
  • "outcomes": [
    ]
}

Response samples

Content type
application/json
{
  • "sustainableLandId": 102,
  • "agcoreLandId": 10,
  • "dtnCustomerId": "string",
  • "createdAt": "2025-03-04T04:12:52.138Z",
  • "updatedAt": "2025-03-04T04:12:52.138Z",
  • "deletedAt": null,
  • "land": {
    },
  • "outcomes": [
    ]
}

/api/v1/app-views/sustainable-practices/land-outcomes/inventories/{landOutcomeId}

Get inventory

Authorizations:
bearerAuth
path Parameters
landOutcomeId
number
header Parameters
x-requested-customer-id
string

Required if the requesting user has multiple customer ids or using an M2M token.

Responses

Response samples

Content type
application/json
{
  • "landOutcomeId": 0,
  • "sustainableLandId": 0,
  • "outcomeId": 0,
  • "cropYear": 0,
  • "quantity": 0,
  • "baseUomId": [
    ],
  • "verifiedAt": "2019-08-24T14:15:22Z",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "createdBy": "string",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "updatedBy": "string",
  • "outcome": {
    },
  • "sustainableLand": {
    }
}

Delete inventory

Authorizations:
bearerAuth
path Parameters
landOutcomeId
number
header Parameters
x-requested-customer-id
string

Required if the requesting user has multiple customer ids or using an M2M token.

Responses

Response samples

Content type
application/json
{
  • "type": "bad-request",
  • "title": "Invalid Request",
  • "status": 400,
  • "detail": "Request contains unexpected request parameters",
  • "instance": "urn:dtn:/api/v1/participating-states?k=r:requestId:959babbe-81ca-4667-a880-a9447bf05dc6",
  • "error": "Request body is invalid, please use array of fips codes. example: {'fipsCodes': [1,2,3]}",
  • "errors": [
    ]
}