Retrieve Farmers for Trade

GET /api/v1/trades/{tradeId}/farmers

Description

Retrieves a list of farmers involved in a specific trade, allowing for detailed analysis based on registration dates, specific farmer identifiers, and sorting preferences. This endpoint supports extensive filtering and sorting to provide tailored insights into the agricultural workforce involved in trades.

URL Parameters:

• tradeId (required): The unique identifier of the trade whose farmers are to be retrieved. This must be included in the URL path.

Headers:

• tenantId (required): The tenant ID under which the trade is registered. This header identifies the specific tenant environment and should be included.
• userId (required): The user ID of the individual requesting the farmer information. This should also be included as a header.
• countryCode (required): The country code where the trade and farmer registration is taking place. This should be included as a header.

Query Parameters:

• tradeFarmerDateRange (optional): Filters the farmers by a specific date range associated with their registration or activity within the trade. Format: start_date,end_date (e.g., 2020-11-12,2022-11-15).
• farmerByFarmerIds (optional): Filters the list by specific farmer IDs.
• farmerByTradeFarmerIds (optional): Filters the list by specific trade-farmer relationship IDs.
• order (optional): Specifies the order of the results. Available values: ASC, DESC.
• page (optional): Specifies the pagination page.
• limit (optional): Specifies the number of results per page.

Example Request:

curl -G "http://[base_url]/api/v1/trades/{tradeId}/farmers" \
     -H "Authorization: Bearer [access_token]" \
     -H "tenantId: TEN123" \
     -H "userId: USR456" \
     -H "countryCode: US" \
     -d "tradeFarmerDateRange=2020-11-12,2022-11-15" \
     -d "farmerByFarmerIds=101,102" \
     -d "farmerByTradeFarmerIds=201,202" \
     -d "order=ASC" \
     -d "page=1" \
     -d "limit=10"

Responses:

• 200 OK: Successfully retrieved the list of farmers associated with the trade. The response includes detailed information about each farmer that matches the specified criteria.

Example Response:

{
  "farmers": [
    {
      "farmerId": "101",
      "firstName": "John",
      "lastName": "Doe",
      "tradeId": "12345",
      "registrationDate": "2020-12-01"
    },
    {
      "farmerId": "102",
      "firstName": "Jane",
      "lastName": "Smith",
      "tradeId": "12345",
      "registrationDate": "2020-12-02"
    }
  ],
  "totalItems": 50,
  "totalPages": 5,
  "currentPage": 1
}

Error Responses:

• 400 Bad Request: Incorrect or incomplete query parameters.
• 404 Not Found: No farmers found based on the provided criteria.
• 403 Forbidden: The user does not have permission to view the farmer details.