Operations Center - Work Plans

Click here for more information on how to get started.

Overview

Work Plan integration automates setup and removes operator guess work in the field. Use this integration to help our customers:

Plan work from anywhere, with any software
Prepare work to be transferred to equipment via Work Planner within Operations Center
Setup the Generation 4 display (4200, 4240, 4600, or 4640) with one touch.
Analyze completed work in Operations Center or from any software solution

Work Plans API Offering

Enable collaboration between trusted advisors, save time in the field, and ensure high quality precision Ag Data by integrating with the Work Plans API offering. The Work Plans API offering allows a Connected Software Company to send field specific recommendations to the John Deere Operations Center for wireless data flow to the Generation 4 displays (4200, 4240, 4600, or 4640), removing operator guess work and enabling one touch setup as the operator approaches the field.

If you are looking to enable work order planning and logistics for Ag Retailer custom application services, check out the AgLogic API offering.

What makes up a Work Plan?

A work plan can be made up of the data elements below.

Fields
Boundaries
Guidance Lines
Products
Prescription File
Machines
Implements
Operators

Where do Work Plans appear?

Work Plans are available in the Work Planner in both Operations Center web and mobile. Work Plans can be sent wirelessly to Generation 4 displays (4200, 4240, 4600, or 4640) for execution.

Work Planner - Operations Center Web

Work Planner - Operations Center mobile

Work Plan - Generation 4 display (4200, 4240, 4600, or 4640)

Getting Started

Operations Center is a digital representation of the farm, it is increasingly important to keep the digital farm synchronized software solutions used by the farmer. Setup components are critical to get in place and keep up to date to enable faster execution in the cab and make full use of work plan transfers, automation, autonomy, monitoring and insights. We recommend mapping customer’s Operations Center master data to records within your software solution by storing the John Deere IDs.

Use this guide to create your first work plan to be viewable in Work Planner in Operations Center. Follow the steps below for the best work plan integration.

Retrieve the necessary master data from your customer's Operations Center organization. You need the John Deere ID later to create the Work Plan. Retrieving the data allows you to discover what data the customer has in Operations Center so you don't create multiple records for the customer. It is only necessary to retrieve the data your system uses when creating work for the grower.

Retrieve Fields
Retrieve Field Boundaries

Accurate boundaries in Operations Center are important for machine execution and enables the operator to be notified of an associated work plan when they approach the field.

Retrieve Products

Accurate inputs drive quality data associated with completed work and reduce data editing for customers after execution.

Retrieve Machines
Retrieve Implements
Retrieve Operators
Retrieve Guidance Lines

If you were unable to map your record to existing master data in the customer’s organization, you can create the data for them. You need the John Deere ID later to create the Work Plan.

Upload a prescription file
Create a Work Plan

After you create the Work plan customers view it within Work Planner in the Operations Center. From Work Planner customers can add additional setup data like guidance lines, equipment and more, then wirelessly transfer Work Plans to machines.

Retrieve Field Operations

Check out the Data Subscription Service for Field Operations Events. Subscribe to Field Operations per organization and we will tell you when there are new Field Operations for an organization. The Field Operations API response will include a link to the work plan associated to the field operation.

Endpoints

Create a Work Plan

POST

/organizations/{orgId}/workPlans

This endpoint can be used to create work plans within the target organization. In order to do this, the authenticated user must have following permissions within the organization.

Work: access level 2
Locations: access level 1
Equipment: access level 1
Organization Management: access level 1

Note: All work plans created using this api will have PLANNED status by default.

OAuth Scope Required: work2

Request URI

POST https://sandboxapi.deere.com/platform/organizations/{orgId}/workPlans

Accept: application/vnd.deere.axiom.v3+json

Content-Type: application/vnd.deere.axiom.v3+json

Parameters

Parameter	Type	Description & Example	In
orgId Required	string	Organization Example: 1234	path

Status Codes

Code	Message	Description
201	Created	Work Plan successfully created
400	Bad Request	Request is rejected due to invalid request body. Response body will contain more details on reason of failure
403	Forbidden	Authenticated user does not have required permission in target organization to create work plan
409	Conflict	Erid provided in request body already exists in target organization

Response Details

Field	Type	Description & Example
year	integer	--- Example: 2021

Sample Request [JSON]: Create Tillage work plan [Minimum request payload]

{
  "location": {
    "fieldUri": "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/fields/{FieldId}"
  },
  "workType": {
    "representationDomainId": "dtOperationClass",
    "instanceDomainId": "dtiTillage"
  },
  "year": 2021,
  "operations": [
    {
      "operationType": {
        "representationDomainId": "dtOperationClass",
        "instanceDomainId": "dtiTillage"
      },
      "operationInputs": []
    }
  ],
  "workPlanAssignments": [],
  "guidanceUris": [],
  "workOrder": "",
  "instructions": ""
}

Sample Request [JSON]: Create Tillage work plan

{
  "location": {
    "fieldUri": "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/fields/{FieldId}"
  },
  "workType": {
    "representationDomainId": "dtOperationClass",
    "instanceDomainId": "dtiTillage"
  },
  "year": 2021,
  "operations": [
    {
      "operationType": {
        "representationDomainId": "dtOperationClass",
        "instanceDomainId": "dtiTillage"
      },
      "operationInputs": [
        {
          "operationPrescription": {
            "fixedRate": {
              "valueAsDouble": 10,
              "unit": "cm",
              "vrDomainId": "vrTillageDepthTarget"
            }
          }
        }
      ]
    }
  ],
  "workPlanAssignments": [
    {
      "machineUri": "https://sandboxapi.deere.com/platform/machines/{MachineId}",
      "operatorUri": "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/operators/{OperatorId}",
      "implementUris": [
        "https://sandboxapi.deere.com/platform/implements/{ImplementId1}",
        "https://sandboxapi.deere.com/platform/implements/{ImplementId2}"
      ]
    }
  ],
  "guidanceUris": [
    "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/fields/{FieldId}/guidanceLines/{GuidanceId1}",
    "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/fields/{FieldId}/guidanceLines/{GuidanceId2}"
  ],
  "workOrder": "Sample work order",
  "instructions": "Sample work instructions"
}

Sample Request [JSON]: Create Seeding work plan [Minimum request payload]

{
  "location": {
    "fieldUri": "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/fields/{FieldId}"
  },
  "workType": {
    "representationDomainId": "dtOperationClass",
    "instanceDomainId": "dtiSeeding"
  },
  "year": 2021,
  "operations": [
    {
      "operationType": {
        "representationDomainId": "dtOperationClass",
        "instanceDomainId": "dtiSeeding"
      },
      "operationInputs": [
        {
          "operationProduct": {
            "inputUri": "https://sandboxapi.deere.com/platform/cropTypes/{CropName}",
            "inputType": "CROP"
          }
        }
      ]
    }
  ],
  "workPlanAssignments": [],
  "guidanceUris": [],
  "workOrder": "",
  "instructions": ""
}

Sample Request [JSON]: Create Seeding + Application work plan [Minimum request payload]

{
  "location": {
    "fieldUri": "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/fields/{FieldId}"
  },
  "workType": {
    "representationDomainId": "dtOperationClass",
    "instanceDomainId": "dtiSeeding"
  },
  "year": 2021,
  "operations": [
    {
      "operationType": {
        "representationDomainId": "dtOperationClass",
        "instanceDomainId": "dtiSeeding"
      },
      "operationInputs": [
        {
          "operationProduct": {
            "inputUri": "https://sandboxapi.deere.com/platform/cropTypes/{CropName}",
            "inputType": "CROP"
          }
        }
      ]
    },
    {
      "operationType": {
        "representationDomainId": "dtOperationClass",
        "instanceDomainId": "dtiApplication"
      },
      "operationInputs": []
    }
  ],
  "workPlanAssignments": [],
  "guidanceUris": [],
  "workOrder": "",
  "instructions": ""
}

Sample Request [JSON]: Create Seeding work plan

{
  "location": {
    "fieldUri": "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/fields/{FieldId}"
  },
  "workType": {
    "representationDomainId": "dtOperationClass",
    "instanceDomainId": "dtiSeeding"
  },
  "year": 2021,
  "operations": [
    {
      "operationType": {
        "representationDomainId": "dtOperationClass",
        "instanceDomainId": "dtiSeeding"
      },
      "operationInputs": [
        {
          "operationProduct": {
            "inputUri": "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/varieties/{VarietyId1}",
            "inputType": "VARIETY"
          },
          "operationPrescription": {
            "fixedRate": {
              "valueAsDouble": 15000,
              "unit": "seeds1ha-1",
              "vrDomainId": "vrSeedRateSeedsTarget"
            }
          }
        },
        {
          "operationProduct": {
            "inputUri": "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/varieties/{VarietyId2}",
            "inputType": "VARIETY"
          },
          "operationPrescription": {
            "prescriptionUse": {
              "fileUri": "https://sandboxapi.deere.com/platform/files/{FileId1}",
              "unit": "seeds1ha-1",
              "vrDomainId": "vrSeedRateSeedsTarget"
            }
          }
        },
        {
          "operationProduct": {
            "inputUri": "https://sandboxapi.deere.com/platform/cropTypes/{CropName}",
            "inputType": "CROP"
          }
        }
      ]
    }
  ],
  "workPlanAssignments": [
    {
      "machineUri": "https://sandboxapi.deere.com/platform/machines/{MachineId1}",
      "operatorUri": "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/operators/{OperatorId1}",
      "implementUris": [
        "https://sandboxapi.deere.com/platform/implements/{ImplementId1}"
      ]
    },
    {
      "machineUri": "https://sandboxapi.deere.com/platform/machines/{MachineId2}",
      "operatorUri": "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/operators/{OperatorId2}",
      "implementUris": [
        "https://sandboxapi.deere.com/platform/implements/{ImplementId2}",
        "https://sandboxapi.deere.com/platform/implements/{ImplementId3}"
      ]
    }
  ],
  "guidanceUris": [
    "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/fields/{FieldId}/guidanceLines/{GuidanceId1}",
    "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/fields/{FieldId}/guidanceLines/{GuidanceId2}"
  ],
  "workOrder": "Sample work order",
  "instructions": "Sample work instructions"
}

Sample Request [JSON]: Create Seeding + Application work plan

{
  "location": {
    "fieldUri": "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/fields/{FieldId}"
  },
  "workType": {
    "representationDomainId": "dtOperationClass",
    "instanceDomainId": "dtiSeeding"
  },
  "year": 2021,
  "operations": [
    {
      "operationType": {
        "representationDomainId": "dtOperationClass",
        "instanceDomainId": "dtiSeeding"
      },
      "operationInputs": [
        {
          "operationProduct": {
            "inputUri": "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/varieties/{VarietyId1}",
            "inputType": "VARIETY"
          },
          "operationPrescription": {
            "fixedRate": {
              "valueAsDouble": 15000,
              "unit": "seeds1ha-1",
              "vrDomainId": "vrSeedRateSeedsTarget"
            }
          }
        },
        {
          "operationProduct": {
            "inputUri": "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/varieties/{VarietyId2}",
            "inputType": "VARIETY"
          },
          "operationPrescription": {
            "prescriptionUse": {
              "fileUri": "https://sandboxapi.deere.com/platform/files/{FileId1}",
              "unit": "seeds1ha-1",
              "vrDomainId": "vrSeedRateSeedsTarget"
            }
          }
        },
        {
          "operationProducts": {
            "inputUri": "https://sandboxapi.deere.com/platform/cropTypes/{CropName}",
            "inputType": "CROP"
          }
        }
      ]
    },
    {
      "operationType": {
        "representationDomainId": "dtOperationClass",
        "instanceDomainId": "dtiApplication"
      },
      "operationInputs": [
        {
          "operationProduct": {
            "inputUri": "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/chemicals/{ChemicalId1}",
            "inputType": "CHEMICAL"
          },
          "operationPrescription": {
            "fixedRate": {
              "valueAsDouble": 60,
              "unit": "l1ha-1",
              "vrDomainId": "vrAppRateVolumeTarget"
            }
          }
        },
        {
          "operationProduct": {
            "inputUri": "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/fertilizers/{FertilizerId1}",
            "inputType": "FERTILIZER"
          },
          "operationPrescription": {
            "prescriptionUse": {
              "fileUri": "https://sandboxapi.deere.com/platform/files/{FileId2}",
              "unit": "kg1ha-1",
              "vrDomainId": "vrAppRateMassTarget"
            }
          }
        }
      ]
    }
  ],
  "workPlanAssignments": [
    {
      "machineUri": "https://sandboxapi.deere.com/platform/machines/{MachineId1}",
      "operatorUri": "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/operators/{OperatorId1}",
      "implementUris": [
        "https://sandboxapi.deere.com/platform/implements/{ImplementId1}"
      ]
    },
    {
      "machineUri": "https://sandboxapi.deere.com/platform/machines/{MachineId2}",
      "operatorUri": "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/operators/{OperatorId2}",
      "implementUris": [
        "https://sandboxapi.deere.com/platform/implements/{ImplementId1}",
        "https://sandboxapi.deere.com/platform/implements/{ImplementId2}"
      ]
    }
  ],
  "guidanceUris": [
    "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/fields/{FieldId}/guidanceLines/{GuidanceId1}",
    "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/fields/{FieldId}/guidanceLines/{GuidanceId2}"
  ],
  "workOrder": "Sample work order",
  "instructions": "Sample work instructions"
}

Sample Request [JSON]: Create Application work plan [Minimum request payload]

{
  "location": {
    "fieldUri": "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/fields/{FieldId}"
  },
  "workType": {
    "representationDomainId": "dtOperationClass",
    "instanceDomainId": "dtiApplication"
  },
  "year": 2021,
  "operations": [
    {
      "operationType": {
        "representationDomainId": "dtOperationClass",
        "instanceDomainId": "dtiApplication"
      },
      "operationInputs": []
    }
  ],
  "workPlanAssignments": [],
  "guidanceUris": [],
  "workOrder": "",
  "instructions": ""
}

Sample Request [JSON]: Create Application work plan

{
  "location": {
    "fieldUri": "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/fields/{FieldId}"
  },
  "workType": {
    "representationDomainId": "dtOperationClass",
    "instanceDomainId": "dtiApplication"
  },
  "year": 2021,
  "operations": [
    {
      "operationType": {
        "representationDomainId": "dtOperationClass",
        "instanceDomainId": "dtiApplication"
      },
      "operationInputs": [
        {
          "operationProduct": {
            "inputUri": "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/chemicals/{ChemicalId1}",
            "inputType": "CHEMICAL"
          },
          "operationPrescription": {
            "fixedRate": {
              "valueAsDouble": 60,
              "unit": "l1ha-1",
              "vrDomainId": "vrAppRateVolumeTarget"
            }
          }
        },
        {
          "operationProduct": {
            "inputUri": "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/fertilizers/{FertilizerId1}",
            "inputType": "FERTILIZER"
          },
          "operationPrescription": {
            "prescriptionUse": {
              "fileUri": "https://sandboxapi.deere.com/platform/files/{FileId2}",
              "unit": "kg1ha-1",
              "vrDomainId": "vrAppRateMassTarget"
            }
          }
        },
        {
          "operationProduct": {
            "inputUri": "https://api.deere.com/platform/organizations/294130/tankMixes/bf6b0bf0-8f5b-442d-963a-e6629fc8a390",
            "inputType": "TANK_MIX",
            "operationPrescription": {
              "fixedRate": {
                "valueAsDouble": 120,
                "unit": "gal1ac-1",
                "vrDomainId": "vrSolutionRateLiquid"
              }
            }
          }
        },
        {
          "operationProduct": {
            "inputUri": "https://api.deere.com/platform/organizations/294130/dryBlends/e2dc48f1-dd37-4dcb-ba87-8ec06955d5b5",
            "inputType": "DRY_BLEND",
            "operationPrescription": {
              "fixedRate": {
                "valueAsDouble": 920.22,
                "unit": "kg1ha-1",
                "vrDomainId": "vrSolutionRateMass"
              }
            }
          }
        }
      ]
    }
  ],
  "workPlanAssignments": [
    {
      "machineUri": "https://sandboxapi.deere.com/platform/machines/{MachineId1}",
      "operatorUri": "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/operators/{OperatorId1}",
      "implementUris": [
        "https://sandboxapi.deere.com/platform/implements/{ImplementId1}"
      ]
    }
  ],
  "guidanceUris": [
    "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/fields/{FieldId}/guidanceLines/{GuidanceId1}",
    "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/fields/{FieldId}/guidanceLines/{GuidanceId2}"
  ],
  "workOrder": "Sample work order",
  "instructions": "Sample work instructions"
}

Sample Request [JSON]: Create Harvest work plan [Minimum request payload]

{
  "location": {
    "fieldUri": "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/fields/{FieldId}"
  },
  "workType": {
    "representationDomainId": "dtOperationClass",
    "instanceDomainId": "dtiHarvest"
  },
  "year": 2021,
  "operations": [
    {
      "operationType": {
        "representationDomainId": "dtOperationClass",
        "instanceDomainId": "dtiHarvest"
      },
      "operationInputs": [
        {
          "operationProduct": {
            "inputUri": "https://sandboxapi.deere.com/platform/cropTypes/{CropName}",
            "inputType": "CROP"
          }
        }
      ]
    }
  ],
  "workPlanAssignments": [],
  "guidanceUris": [],
  "workOrder": "",
  "instructions": ""
}

Sample Request [JSON]: Create Harvest work plan

{
  "location": {
    "fieldUri": "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/fields/{FieldId}"
  },
  "workType": {
    "representationDomainId": "dtOperationClass",
    "instanceDomainId": "dtiHarvest"
  },
  "year": 2021,
  "operations": [
    {
      "operationType": {
        "representationDomainId": "dtOperationClass",
        "instanceDomainId": "dtiHarvest"
      },
      "operationInputs": [
        {
          "operationProduct": {
            "inputUri": "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/varieties/{VarietyId1}",
            "inputType": "VARIETY"
          }
        },
        {
          "operationProduct": {
            "inputUri": "https://sandboxapi.deere.com/platform/cropTypes/{CropName}",
            "inputType": "CROP"
          }
        }
      ]
    }
  ],
  "workPlanAssignments": [
    {
      "machineUri": "https://sandboxapi.deere.com/platform/machines/{MachineId1}",
      "operatorUri": "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/operators/{OperatorId1}",
      "implementUris": [
        "https://sandboxapi.deere.com/platform/implements/{ImplementId1}"
      ]
    }
  ],
  "guidanceUris": [
    "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/fields/{FieldId}/guidanceLines/{GuidanceId1}",
    "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/fields/{FieldId}/guidanceLines/{GuidanceId2}"
  ],
  "workOrder": "Sample work order",
  "instructions": "Sample work instructions"
}

Sample Response [JSON]

201 Created
Location:https://sandboxapi.deere.com/platform//organizations/{OrganizationId}/workPlans/{WorkPlanId}

{
  "links": {
    "rel": "self",
    "uri": "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/workPlans/{WorkPlanId}"
  },
  "erid": "{WorkPlanId}",
  "location": {
    "fieldUri": "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/fields/{FieldId}"
  },
  "workType": {
    "representationDomainId": "dtOperationClass",
    "instanceDomainId": "dtiSeeding"
  },
  "year": 2021,
  "operations": [
    {
      "operationType": {
        "representationDomainId": "dtOperationClass",
        "instanceDomainId": "dtiSeeding"
      },
      "operationInputs": [
        {
          "operationProduct": {
            "inputUri": "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/varieties/{VarietyId1}",
            "inputType": "VARIETY"
          },
          "operationPrescription": {
            "fixedRate": {
              "valueAsDouble": 15000,
              "unit": "seeds1ha-1",
              "vrDomainId": "vrSeedRateSeedsTarget"
            }
          }
        },
        {
          "operationProduct": {
            "inputUri": "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/varieties/{VarietyId2}",
            "inputType": "VARIETY"
          },
          "operationPrescription": {
            "prescriptionUse": {
              "fileUri": "https://sandboxapi.deere.com/platform/files/{FileId1}",
              "unit": "seeds1ha-1",
              "vrDomainId": "vrSeedRateSeedsTarget"
            }
          }
        },
        {
          "operationProduct": {
            "inputUri": "https://sandboxapi.deere.com/platform/cropTypes/{CropName}",
            "inputType": "CROP"
          }
        }
      ]
    },
    {
      "operationType": {
        "representationDomainId": "dtOperationClass",
        "instanceDomainId": "dtiApplication"
      },
      "operationInputs": [
        {
          "operationProduct": {
            "inputUri": "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/chemicals/{ChemicalId}",
            "inputType": "CHEMICAL"
          },
          "operationPrescription": {
            "fixedRate": {
              "valueAsDouble": 60,
              "unit": "l1ha-1",
              "vrDomainId": "vrAppRateVolumeTarget"
            }
          }
        },
        {
          "operationProduct": {
            "inputUri": "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/chemicals/{FertilizerId}",
            "inputType": "FERTILIZER"
          },
          "operationPrescription": {
            "prescriptionUse": {
              "fileUri": "https://sandboxapi.deere.com/platform/files/{FileId2}",
              "unit": "kg1ha-1",
              "vrDomainId": "vrAppRateMassTarget"
            }
          }
        }
      ]
    }
  ],
  "workPlanAssignments": [
    {
      "machineUri": "https://sandboxapi.deere.com/platform/machines/{MachineId1}",
      "operatorUri": "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/operators/{OperatorId1}",
      "implementUris": [
        "https://sandboxapi.deere.com/platform/implements/{ImplementId1}"
      ]
    },
    {
      "machineUri": "https://sandboxapi.deere.com/platform/machines/{MachineId2}",
      "operatorUri": "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/operators/{OperatorId2}",
      "implementUris": [
        "https://sandboxapi.deere.com/platform/implements/{ImplementId2}",
        "https://sandboxapi.deere.com/platform/implements/{ImplementId3}"
      ]
    }
  ],
  "guidanceUris": [
    "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/fields/{FieldId}/guidanceLines/{GuidanceId1}",
    "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/fields/{FieldId}/guidanceLines/{GuidanceId2}"
  ],
  "workStatus": "PLANNED",
  "workOrder": "Sample work order",
  "instructions": "Sample work instructions",
  "sequenceNumber": 1500
}

Sample Response [JSON]: Error

400 Bad Request
Location:https://sandboxapi.deere.com/platform//organizations/{OrganizationId}/workPlans/{WorkPlanId}

{
  "total": 4,
  "errors": [
    {
      "guid": "6d7c5648-a87a-4360-aa7d-fc063291389f",
      "message": "size must be between 1 and 2",
      "field": "operations",
      "@type": "Error"
    },
    {
      "guid": "b18e8f42-20fe-41d4-8164-f1a30fa221cb",
      "message": "must not be null",
      "field": "year",
      "@type": "Error"
    },
    {
      "guid": "f2ad44b7-c41d-4c1d-9377-8d3ebcb33ac8",
      "message": "must not be null",
      "field": "location",
      "@type": "Error"
    },
    {
      "guid": "fe094b6c-9c16-41c5-99c7-e0075146acd3",
      "message": "must not be null",
      "field": "workType",
      "@type": "Error"
    }
  ],
  "@type": "Errors"
}

List Work Plans

GET

/organizations/{orgId}/workPlans

This endpoint returns a list of work plans for the target organization. In order to do this, the authenticated user must have following permissions within the organization. By default only work plans in PLANNED status will be returned and the response will be paginated with a default page size of 10. The Response will also contain next and previous page links, which can be used to fetch the complete set for the organization.

Work: access level 1
Locations: access level 1
Equipment: access level 1
Organization Management: access level 1

OAuth Scope Required: work1

Request URI

GET https://sandboxapi.deere.com/platform/organizations/{orgId}/workPlans

Accept: application/vnd.deere.axiom.v3+json

Parameters

Parameter	Type	Description & Example	In
orgId Required	string	Owning Organization ID Example: 1234	path
year	string	Filter by year Example: 2021	query
workType	string	Filter by work type. Accepted values are, dtiTillage, dtiSeeding, dtiApplication, dtiHarvest Example: dtiTillage Allowed Values: dtiTillage,dtiSeeding,dtiApplication,dtiHarvest	query
workStatus	string	Filter by work status. Accepted values are, PLANNED, IN_PROGRESS, COMPLETED, ALL Example: PLANNED Allowed Values: PLANNED,IN_PROGRESS,COMPLETED,ALL	query
startDate	datetime	Filter results by date range specified by using startDate and endDate. Result will include work plans created or modified in date range. Example: 2021-01-01T10:15:00.000Z	query
endDate	datetime	Filter results by date range specified by using startDate and endDate. Result will include work plans created or modified in date range. Example: 2022-01-01T10:15:00.000Z	query
embed	string	Request to include additional information in response. Currently supported embed is showRecordMetadata Example: showRecordMetadata	query
start	integer	Pagination parameter. This should be used with the count parameter to paginate the response. Example: 0	path(matrix parameter)
count	integer	Pagination parameter. This should be used with the start parameter to paginate the response. Example: 10	path(matrix parameter)
workPlanErids	array	Parameter to only retrieve workplans from a given list of erids Example: 43b12553-c5ca-42f7-ac5b-a44612e24cca, 53b12553-c5ca-42f7-ac5b-a44612e24cca	query
fieldIds	array	Parameter to only retrieve workplans from a given list of erids Example: 43b12553-c5ca-42f7-ac5b-a44612e24cca, 53b12553-c5ca-42f7-ac5b-a44612e24cca	query

Status Codes

Code	Message	Description
200	OK	The request succeeded. List of work plans are included in values attribute of response body. Total attribute indicates complete set of work plans available at server for given request
400	Bad Request	Request is rejected due to invalid request parameter values. Response body will contain more details on reason of failure
403	Forbidden	Authenticated user does not have required permission in target organization to get work plans

Response Details

Field	Type	Description & Example
erid	GUID	Id of work plan unique within organization Example: 9c28ef53-da68-4a85-916e-74c1a5b4491d
location	string	Indicates location where work will be executed Example: See sample response
location.fieldUri	uri	Reference of field where work will be executed Example: https://sandboxapi.deere.com/platform/organizations/1234/fields/5cb79090-e850-11ea-adc1-0242ac120005
workType	DefinedType	Type of work planned Example: See sample response
workType.representationDomainId	string	Domain id for defined type which represents different operations supported Example: dtOperationClass
workType.instanceDomainId	string	Value for defined type which represents different operations supported. Accepted values are dtiTillage, dtiSeeding, dtiApplication, dtiHarvest Example: dtiTillage
year	integer	calendar year Example: 2021
operations	[OperationSetup]	Array of OperationSetups to plan single pass on work location. Apart from individual work types specified above, API also supports planning Seeding and Application operation in one work plan. No other combination is supported. Example: See sample Response MaxLength: 2 MinLength: 1
operations.operationType	DefinedType	Type of work planned Example: See sample response
operations.operationInputs	OperationInput	Array of operation Inputs. Accepted operation inputs will vary based on operation Type. Please refer payload samples added for POST Example: See sample response below
operations.operationInputs.operationProduct	OperationProduct	Operation Product can be used to add details of crop or product being used in operation Example: See sample response
operations.operationInputs.operationProduct.inputType	string	Indicates type of Input. Accepted values are, CHEMICAL, CROP, TANK_MIX, VARIETY Example: CHEMICAL
operations.operationInputs.operationProduct.inputUri	uri	Uri of Input Example: https://sandboxapi.deere.com/platform/organizations/1234/chemicals/e1095e88-e921-11ea-adc1-0242ac12000
operations.operationInputs.operationPrescription	OperationPrescription	Operation Prescription can be used to specify fixed rate or prescription file reference Example: See sample response
operations.operationInputs.operationPrescription.fixedRate	MeasurementAsDouble	Operation Prescription can be used to specify fixed rate or prescription file reference Example: See sample response
operations.operationInputs.operationPrescription.fixedRate.valueAsDouble²	number	Numeric value for fixed rate Example: 50.5
operations.operationInputs.operationPrescription.fixedRate.unit²	string	Unit of fixed rate Example: kg
operations.operationInputs.operationPrescription.fixedRate.vrDomainId¹	string	Domain Id of representation system used to validate value and unit of fixed rate Example: vrAppRateMassTarget
operations.operationInputs.operationPrescription.prescriptionUse	MeasurementAsDouble	PrescriptionUse can be used to specify prescription file and unit details Example: See sample response
operations.operationInputs.operationPrescription.prescriptionUse.fileUri	uri	Uri of prescription file Example: https://sandboxapi.deere.com/platform/files/1111
operations.operationInputs.operationPrescription.prescriptionUse.unit²	string	Unit for rates included in prescription file Example: gal1ac-1
operations.operationInputs.operationPrescription.prescriptionUse.vrDomainId¹	string	Domain Id of representation system used to validate unit of prescription rate Example: vrAppRateMassTarget
workPlanAssignments	[WorkPlanAssignment]	Array of WorkPlanAssignment to plan work with multiple machines. Each WorkPlanAssignment object can hold information about one machine, one operator and multiple implements that will attached to specified machine Example: See sample response
workPlanAssignment.machineUri	uri	Uri of machine Example: https://sandboxapi.deere.com/platform/machines/2222
workPlanAssignment.operatorUri	uri	Uri of operator Example: https://sandboxapi.deere.com/platform/organizations/1234/operators/6708408a-e918-11ea-adc1-0242ac120002
workPlanAssignment.implementUris	[uri]	Array of implement uris Example: [https://sandboxapi.deere.com/platform/implements/3333]
guidanceUris	[uri]	Array of guidance uris Example: [https://sandboxapi.deere.com/platform/organizations/1234/fields/5cb79090-e850-11ea-adc1-0242ac120005/guidanceLines/58e37f70-e86d-11ea-adc1-0242ac120002]
workOrder	string	This attribute can be used to group related work on multiple fields. Max length possible is 255 characters Example: sample work order
instructions	string	This attribute can be used to provide instructions to operator executing work. Max length possible is 255 characters Example: sample work instructions
workStatus	string	Indicates status of work plan. This is read only field. Possible values are, PLANNED, IN_PROGRESS, COMPLETED Example: PLANNED
sequenceNumber	number	Indicates priority of work plan. This is read only field. Sequence number will be calculated by POST API. Lower sequence number indicates higher priority. Newly created work plan will have higher priority than old work plans within the context of the same work type and year Example: 10

Sample Response [JSON]

200 Success

{
  "links": [
    {
      "rel": "self",
      "uri": "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/workPlans"
    }
  ],
  "total": 1,
  "values": [
    {
      "links": [
        {
          "rel": "self",
          "uri": "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/workPlans/{WorkPlanId}"
        }
      ],
      "erid": "{WorkPlanId}",
      "location": {
        "fieldUri": "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/fields/{FieldId}"
      },
      "workType": {
        "representationDomainId": "dtOperationClass",
        "instanceDomainId": "dtiSeeding"
      },
      "year": 2021,
      "operations": [
        {
          "operationType": {
            "representationDomainId": "dtOperationClass",
            "instanceDomainId": "dtiSeeding"
          },
          "operationInputs": [
            {
              "operationProduct": {
                "inputUri": "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/varieties/{VarietyId1}",
                "inputType": "VARIETY"
              },
              "operationPrescription": {
                "fixedRate": {
                  "valueAsDouble": 15000,
                  "unit": "seeds1ha-1",
                  "vrDomainId": "vrSeedRateSeedsTarget"
                }
              }
            },
            {
              "operationProduct": {
                "inputUri": "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/varieties/{VarietyId2}",
                "inputType": "VARIETY"
              },
              "operationPrescription": {
                "prescriptionUse": {
                  "fileUri": "https://sandboxapi.deere.com/platform/files/{FileId1}",
                  "unit": "seeds1ha-1",
                  "vrDomainId": "vrSeedRateSeedsTarget"
                }
              }
            },
            {
              "operationProduct": {
                "inputUri": "https://sandboxapi.deere.com/platform/cropTypes/{CropName}",
                "inputType": "CROP"
              }
            }
          ]
        },
        {
          "operationType": {
            "representationDomainId": "dtOperationClass",
            "instanceDomainId": "dtiApplication"
          },
          "operationInputs": [
            {
              "operationProduct": {
                "inputUri": "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/chemicals/{ChemicalId}",
                "inputType": "CHEMICAL"
              },
              "operationPrescription": {
                "fixedRate": {
                  "valueAsDouble": 60,
                  "unit": "l1ha-1",
                  "vrDomainId": "vrAppRateVolumeTarget"
                }
              }
            },
            {
              "operationProduct": {
                "inputUri": "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/chemicals/{FertilizerId}",
                "inputType": "FERTILIZER"
              },
              "operationPrescription": {
                "prescriptionUse": {
                  "fileUri": "https://sandboxapi.deere.com/platform/files/{FileId2}",
                  "unit": "kg1ha-1",
                  "vrDomainId": "vrAppRateMassTarget"
                }
              }
            }
          ]
        }
      ],
      "workPlanAssignments": [
        {
          "machineUri": "https://sandboxapi.deere.com/platform/machines/{MachineId1}",
          "operatorUri": "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/operators/{OperatorId1}",
          "implementUris": [
            "https://sandboxapi.deere.com/platform/implements/{ImplementId1}"
          ]
        },
        {
          "machineUri": "https://sandboxapi.deere.com/platform/machines/{MachineId2}",
          "operatorUri": "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/operators/{OperatorId2}",
          "implementUris": [
            "https://sandboxapi.deere.com/platform/implements/{ImplementId2}",
            "https://sandboxapi.deere.com/platform/implements/{ImplementId3}"
          ]
        }
      ],
      "guidanceUris": [
        "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/fields/{FieldId}/guidanceLines/{GuidanceId1}",
        "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/fields/{FieldId}/guidanceLines/{GuidanceId2}"
      ],
      "workStatus": "PLANNED",
      "workOrder": "Sample work order",
      "instructions": "Sample work instructions",
      "sequenceNumber": 1500
    }
  ]
}

Sample Response [JSON]: Paginated

200 Success

{
  "links": [
    {
      "rel": "self",
      "uri": "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/workPlans;start=2;count=2"
    },
    {
      "rel": "nextPage",
      "uri": "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/workPlans;start=4;count=2"
    },
    {
      "rel": "previousPage",
      "uri": "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/workPlans;start=0;count=2"
    }
  ],
  "total": 10,
  "values": [
    {
      "links": [
        {
          "rel": "self",
          "uri": "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/workPlans/{WorkPlanId}"
        }
      ],
      "erid": "{WorkPlanId}",
      "location": {
        "fieldUri": "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/fields/{FieldId}"
      },
      "workType": {
        "representationDomainId": "dtOperationClass",
        "instanceDomainId": "dtiSeeding"
      },
      "year": 2021,
      "operations": [
        {
          "operationType": {
            "representationDomainId": "dtOperationClass",
            "instanceDomainId": "dtiSeeding"
          },
          "operationInputs": [
            {
              "operationProduct": {
                "inputUri": "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/varieties/{VarietyId1}",
                "inputType": "VARIETY"
              },
              "operationPrescription": {
                "fixedRate": {
                  "valueAsDouble": 15000,
                  "unit": "seeds1ha-1",
                  "vrDomainId": "vrSeedRateSeedsTarget"
                }
              }
            },
            {
              "operationProduct": {
                "inputUri": "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/varieties/{VarietyId2}",
                "inputType": "VARIETY"
              },
              "operationPrescription": {
                "prescriptionUse": {
                  "fileUri": "https://sandboxapi.deere.com/platform/files/{FileId1}",
                  "unit": "seeds1ha-1",
                  "vrDomainId": "vrSeedRateSeedsTarget"
                }
              }
            },
            {
              "operationProduct": {
                "inputUri": "https://sandboxapi.deere.com/platform/cropTypes/{CropName}",
                "inputType": "CROP"
              }
            }
          ]
        },
        {
          "operationType": {
            "representationDomainId": "dtOperationClass",
            "instanceDomainId": "dtiApplication"
          },
          "operationInputs": [
            {
              "operationProduct": {
                "inputUri": "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/chemicals/{ChemicalId}",
                "inputType": "CHEMICAL"
              },
              "operationPrescription": {
                "fixedRate": {
                  "valueAsDouble": 60,
                  "unit": "l1ha-1",
                  "vrDomainId": "vrAppRateVolumeTarget"
                }
              }
            },
            {
              "operationProduct": {
                "inputUri": "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/chemicals/{FertilizerId}",
                "inputType": "FERTILIZER"
              },
              "operationPrescription": {
                "prescriptionUse": {
                  "fileUri": "https://sandboxapi.deere.com/platform/files/{FileId2}",
                  "unit": "kg1ha-1",
                  "vrDomainId": "vrAppRateMassTarget"
                }
              }
            }
          ]
        }
      ],
      "workPlanAssignments": [
        {
          "machineUri": "https://sandboxapi.deere.com/platform/machines/{MachineId1}",
          "operatorUri": "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/operators/{OperatorId1}",
          "implementUris": [
            "https://sandboxapi.deere.com/platform/implements/{ImplementId1}"
          ]
        },
        {
          "machineUri": "https://sandboxapi.deere.com/platform/machines/{MachineId2}",
          "operatorUri": "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/operators/{OperatorId2}",
          "implementUris": [
            "https://sandboxapi.deere.com/platform/implements/{ImplementId2}",
            "https://sandboxapi.deere.com/platform/implements/{ImplementId3}"
          ]
        }
      ],
      "guidanceUris": [
        "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/fields/{FieldId}/guidanceLines/{GuidanceId1}",
        "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/fields/{FieldId}/guidanceLines/{GuidanceId2}"
      ],
      "workStatus": "PLANNED",
      "workOrder": "Sample work order",
      "instructions": "Sample work instructions",
      "sequenceNumber": 1500
    },
    {
      "links": [
        {
          "rel": "self",
          "uri": "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/workPlans/{WorkPlanId2}"
        }
      ],
      "erid": "{WorkPlanId2}",
      "location": {
        "fieldUri": "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/fields/{FieldId2}"
      },
      "workType": {
        "representationDomainId": "dtOperationClass",
        "instanceDomainId": "dtiApplication"
      },
      "year": 2021,
      "operations": [
        {
          "operationType": {
            "representationDomainId": "dtOperationClass",
            "instanceDomainId": "dtiApplication"
          },
          "operationInputs": [
            {
              "operationProduct": {
                "inputUri": "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/chemicals/{ChemicalId}",
                "inputType": "CHEMICAL"
              },
              "operationPrescription": {
                "fixedRate": {
                  "valueAsDouble": 60,
                  "unit": "l1ha-1",
                  "vrDomainId": "vrAppRateVolumeTarget"
                }
              }
            },
            {
              "operationProduct": {
                "inputUri": "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/chemicals/{FertilizerId}",
                "inputType": "FERTILIZER"
              },
              "operationPrescription": {
                "prescriptionUse": {
                  "fileUri": "https://sandboxapi.deere.com/platform/files/{FileId2}",
                  "unit": "kg1ha-1",
                  "vrDomainId": "vrAppRateMassTarget"
                }
              }
            }
          ]
        }
      ],
      "workPlanAssignments": [
        {
          "machineUri": "https://sandboxapi.deere.com/platform/machines/{MachineId1}",
          "operatorUri": "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/operators/{OperatorId1}",
          "implementUris": [
            "https://sandboxapi.deere.com/platform/implements/{ImplementId1}"
          ]
        },
        {
          "machineUri": "https://sandboxapi.deere.com/platform/machines/{MachineId2}",
          "operatorUri": "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/operators/{OperatorId2}",
          "implementUris": [
            "https://sandboxapi.deere.com/platform/implements/{ImplementId2}",
            "https://sandboxapi.deere.com/platform/implements/{ImplementId3}"
          ]
        }
      ],
      "guidanceUris": [
        "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/fields/{FieldId}/guidanceLines/{GuidanceId1}",
        "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/fields/{FieldId}/guidanceLines/{GuidanceId2}"
      ],
      "workStatus": "PLANNED",
      "workOrder": "Sample work order",
      "instructions": "Sample work instructions",
      "sequenceNumber": 1510
    }
  ]
}

Get a Work Plan

GET

/organizations/{orgId}/workPlans/{erid}

Get a single work plan by erid in the target organization. In order to do this, the authenticated user must have following permissions within the organization.

Work: access level 1
Locations: access level 1
Equipment: access level 1
Organization Management: access level 1

OAuth Scope Required: work1

Request URI

GET https://sandboxapi.deere.com/platform/organizations/{orgId}/workPlans/{erid}

Accept: application/vnd.deere.axiom.v3+json

Parameters

Parameter	Type	Description & Example	In
orgId Required	string	Owning Organization ID Example: 1234	path
erid Required	GUID	id of a work plan unique within target organization Example: 43b12553-c5ca-42f7-ac5b-a44612e24cca	path
embed	array	Request to include additional information in response. Currently supported embed is showRecordMetadata Example: showRecordMetadata	query

Status Codes

Code	Message	Description
200	Ok	The request succeeded. Work plan is returned in response body
400	Bad Request	Request is rejected due to invalid request parameter values. Response body will contain more details on reason of failure
403	Forbidden	Authenticated user does not have required permission in target organization to get work plan
404	Not Found	Server can not find requested work plan

Response Details

Field	Type	Description & Example
total	integer	--- Example: 1

Sample Response [JSON]

200 Success

{
  "links": [
    {
      "rel": "self",
      "uri": "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/workPlans/{WorkPlanId}"
    }
  ],
  "erid": "{WorkPlanId}",
  "location": {
    "fieldUri": "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/fields/{FieldId}"
  },
  "workType": {
    "representationDomainId": "dtOperationClass",
    "instanceDomainId": "dtiSeeding"
  },
  "year": 2021,
  "operations": [
    {
      "operationType": {
        "representationDomainId": "dtOperationClass",
        "instanceDomainId": "dtiSeeding"
      },
      "operationInputs": [
        {
          "operationProduct": {
            "inputUri": "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/varieties/{VarietyId1}",
            "inputType": "VARIETY"
          },
          "operationPrescription": {
            "fixedRate": {
              "valueAsDouble": 15000,
              "unit": "seeds1ha-1",
              "vrDomainId": "vrSeedRateSeedsTarget"
            }
          }
        },
        {
          "operationProduct": {
            "inputUri": "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/varieties/{VarietyId2}",
            "inputType": "VARIETY"
          },
          "operationPrescription": {
            "prescriptionUse": {
              "fileUri": "https://sandboxapi.deere.com/platform/files/{FileId1}",
              "unit": "seeds1ha-1",
              "vrDomainId": "vrSeedRateSeedsTarget"
            }
          }
        },
        {
          "operationProduct": {
            "inputUri": "https://sandboxapi.deere.com/platform/cropTypes/{CropName}",
            "inputType": "CROP"
          }
        }
      ]
    },
    {
      "operationType": {
        "representationDomainId": "dtOperationClass",
        "instanceDomainId": "dtiApplication"
      },
      "operationInputs": [
        {
          "operationProduct": {
            "inputUri": "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/chemicals/{ChemicalId}",
            "inputType": "CHEMICAL"
          },
          "operationPrescription": {
            "fixedRate": {
              "valueAsDouble": 60,
              "unit": "l1ha-1",
              "vrDomainId": "vrAppRateVolumeTarget"
            }
          }
        },
        {
          "operationProduct": {
            "inputUri": "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/chemicals/{FertilizerId}",
            "inputType": "FERTILIZER"
          },
          "operationPrescription": {
            "prescriptionUse": {
              "fileUri": "https://sandboxapi.deere.com/platform/files/{FileId2}",
              "unit": "kg1ha-1",
              "vrDomainId": "vrAppRateMassTarget"
            }
          }
        }
      ]
    }
  ],
  "workPlanAssignments": [
    {
      "machineUri": "https://sandboxapi.deere.com/platform/machines/{MachineId1}",
      "operatorUri": "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/operators/{OperatorId1}",
      "implementUris": [
        "https://sandboxapi.deere.com/platform/implements/{ImplementId1}"
      ]
    },
    {
      "machineUri": "https://sandboxapi.deere.com/platform/machines/{MachineId2}",
      "operatorUri": "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/operators/{OperatorId2}",
      "implementUris": [
        "https://sandboxapi.deere.com/platform/implements/{ImplementId2}",
        "https://sandboxapi.deere.com/platform/implements/{ImplementId3}"
      ]
    }
  ],
  "guidanceUris": [
    "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/fields/{FieldId}/guidanceLines/{GuidanceId1}",
    "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/fields/{FieldId}/guidanceLines/{GuidanceId2}"
  ],
  "workStatus": "PLANNED",
  "workOrder": "Sample work order",
  "instructions": "Sample work instructions",
  "sequenceNumber": 1500
}

Update a Work Plan

PUT

/organizations/{orgId}/workPlans/{erid}

This endpoint will update an existing work plan within the target organization. In order to do this, the authenticated user must have following permissions within the organization.

Work: access level 2
Locations: access level 1
Equipment: access level 1
Organization Management: access level 1

Following attributes of work plan can not be updated.

erid
location
workType
year
sequenceNumber
workStatus

OAuth Scope Required: work2

Request URI

PUT https://sandboxapi.deere.com/platform/organizations/{orgId}/workPlans/{erid}

Accept: application/vnd.deere.axiom.v3+json

Content-Type: application/vnd.deere.axiom.v3+json

Parameters

Parameter	Type	Description & Example	In
orgId Required	string	Owning Organization ID Example: 1234	path
erid Required	GUID	id of a work plan unique within target organization Example: 43b12553-c5ca-42f7-ac5b-a44612e24cca	path

Status Codes

Code	Message	Description
203	No Content	The request succeeded. Work plan is updated
400	Bad Request	Request is rejected due to invalid request body. Response body will contain more details on reason of failure
403	Forbidden	Authenticated user does not have required permission in target organization to update work plan
404	Not Found	Server can not find requested work plan

Response Details

Field	Type	Description & Example

Sample Request [JSON]: Update tillage work plan

{
  "erid": "{WorkPlanId}",
  "location": {
    "fieldUri": "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/fields/{FieldId}"
  },
  "workType": {
    "representationDomainId": "dtOperationClass",
    "instanceDomainId": "dtiTillage"
  },
  "year": 2021,
  "operations": [
    {
      "operationType": {
        "representationDomainId": "dtOperationClass",
        "instanceDomainId": "dtiTillage"
      },
      "operationInputs": [
        {
          "operationPrescription": {
            "fixedRate": {
              "valueAsDouble": 10,
              "unit": "cm",
              "vrDomainId": "vrTillageDepthTarget"
            }
          }
        }
      ]
    }
  ],
  "workPlanAssignments": [
    {
      "machineUri": "https://sandboxapi.deere.com/platform/machines/{MachineId}",
      "operatorUri": "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/operators/{OperatorId}",
      "implementUris": [
        "https://sandboxapi.deere.com/platform/implements/{ImplementId1}",
        "https://sandboxapi.deere.com/platform/implements/{ImplementId2}"
      ]
    }
  ],
  "guidanceUris": [
    "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/fields/{FieldId}/guidanceLines/{GuidanceId1}",
    "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/fields/{FieldId}/guidanceLines/{GuidanceId2}"
  ],
  "workOrder": "Sample work order",
  "instructions": "Sample work instructions"
}

Sample Request [JSON]: Update seeding work plan

{
  "erid": "{WorkPlanId}",
  "location": {
    "fieldUri": "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/fields/{FieldId}"
  },
  "workType": {
    "representationDomainId": "dtOperationClass",
    "instanceDomainId": "dtiSeeding"
  },
  "year": 2021,
  "operations": [
    {
      "operationType": {
        "representationDomainId": "dtOperationClass",
        "instanceDomainId": "dtiSeeding"
      },
      "operationInputs": [
        {
          "operationProduct": {
            "inputUri": "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/varieties/{VarietyId1}",
            "inputType": "VARIETY"
          },
          "operationPrescription": {
            "fixedRate": {
              "valueAsDouble": 15000,
              "unit": "seeds1ha-1",
              "vrDomainId": "vrSeedRateSeedsTarget"
            }
          }
        },
        {
          "operationProduct": {
            "inputUri": "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/varieties/{VarietyId2}",
            "inputType": "VARIETY"
          },
          "operationPrescription": {
            "prescriptionUse": {
              "fileUri": "https://sandboxapi.deere.com/platform/files/{FileId1}",
              "unit": "seeds1ha-1",
              "vrDomainId": "vrSeedRateSeedsTarget"
            }
          }
        },
        {
          "operationProduct": {
            "inputUri": "https://sandboxapi.deere.com/platform/cropTypes/{CropName}",
            "inputType": "CROP"
          }
        }
      ]
    }
  ],
  "workPlanAssignments": [
    {
      "machineUri": "https://sandboxapi.deere.com/platform/machines/{MachineId1}",
      "operatorUri": "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/operators/{OperatorId1}",
      "implementUris": [
        "https://sandboxapi.deere.com/platform/implements/{ImplementId1}"
      ]
    },
    {
      "machineUri": "https://sandboxapi.deere.com/platform/machines/{MachineId2}",
      "operatorUri": "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/operators/{OperatorId2}",
      "implementUris": [
        "https://sandboxapi.deere.com/platform/implements/{ImplementId2}",
        "https://sandboxapi.deere.com/platform/implements/{ImplementId3}"
      ]
    }
  ],
  "guidanceUris": [
    "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/fields/{FieldId}/guidanceLines/{GuidanceId1}",
    "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/fields/{FieldId}/guidanceLines/{GuidanceId2}"
  ],
  "workOrder": "Sample work order",
  "instructions": "Sample work instructions"
}

Sample Request [JSON]: Update Seeding + Application work plan

{
  "location": {
    "fieldUri": "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/fields/{FieldId}"
  },
  "workType": {
    "representationDomainId": "dtOperationClass",
    "instanceDomainId": "dtiSeeding"
  },
  "year": 2021,
  "operations": [
    {
      "operationType": {
        "representationDomainId": "dtOperationClass",
        "instanceDomainId": "dtiSeeding"
      },
      "operationInputs": [
        {
          "operationProduct": {
            "inputUri": "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/varieties/{VarietyId1}",
            "inputType": "VARIETY"
          },
          "operationPrescription": {
            "fixedRate": {
              "valueAsDouble": 15000,
              "unit": "seeds1ha-1",
              "vrDomainId": "vrSeedRateSeedsTarget"
            }
          }
        },
        {
          "operationProduct": {
            "inputUri": "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/varieties/{VarietyId2}",
            "inputType": "VARIETY"
          },
          "operationPrescription": {
            "prescriptionUse": {
              "fileUri": "https://sandboxapi.deere.com/platform/files/{FileId1}",
              "unit": "seeds1ha-1",
              "vrDomainId": "vrSeedRateSeedsTarget"
            }
          }
        },
        {
          "operationProduct": {
            "inputUri": "https://sandboxapi.deere.com/platform/cropTypes/{CropName}",
            "inputType": "CROP"
          }
        }
      ]
    },
    {
      "operationType": {
        "representationDomainId": "dtOperationClass",
        "instanceDomainId": "dtiApplication"
      },
      "operationInputs": [
        {
          "operationProduct": {
            "inputUri": "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/chemicals/{ChemicalId1}",
            "inputType": "CHEMICAL"
          },
          "operationPrescription": {
            "fixedRate": {
              "valueAsDouble": 60,
              "unit": "l1ha-1",
              "vrDomainId": "vrAppRateVolumeTarget"
            }
          }
        },
        {
          "operationProduct": {
            "inputUri": "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/fertilizers/{FertilizerId1}",
            "inputType": "FERTILIZER"
          },
          "operationPrescription": {
            "prescriptionUse": {
              "fileUri": "https://sandboxapi.deere.com/platform/files/{FileId2}",
              "unit": "kg1ha-1",
              "vrDomainId": "vrAppRateMassTarget"
            }
          }
        }
      ]
    }
  ],
  "workPlanAssignments": [
    {
      "machineUri": "https://sandboxapi.deere.com/platform/machines/{MachineId1}",
      "operatorUri": "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/operators/{OperatorId1}",
      "implementUris": [
        "https://sandboxapi.deere.com/platform/implements/{ImplementId1}"
      ]
    },
    {
      "machineUri": "https://sandboxapi.deere.com/platform/machines/{MachineId2}",
      "operatorUri": "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/operators/{OperatorId2}",
      "implementUris": [
        "https://sandboxapi.deere.com/platform/implements/{ImplementId2}",
        "https://sandboxapi.deere.com/platform/implements/{ImplementId3}"
      ]
    }
  ],
  "guidanceUris": [
    "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/fields/{FieldId}/guidanceLines/{GuidanceId1}",
    "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/fields/{FieldId}/guidanceLines/{GuidanceId2}"
  ],
  "workOrder": "Sample work order",
  "instructions": "Sample work instructions"
}

Sample Request [JSON]: Update Application work plan

{
  "erid": "{WorkPlanId}",
  "location": {
    "fieldUri": "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/fields/{FieldId}"
  },
  "workType": {
    "representationDomainId": "dtOperationClass",
    "instanceDomainId": "dtiApplication"
  },
  "year": 2021,
  "operations": [
    {
      "operationType": {
        "representationDomainId": "dtOperationClass",
        "instanceDomainId": "dtiApplication"
      },
      "operationInputs": [
        {
          "operationProduct": {
            "inputUri": "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/chemicals/{ChemicalId1}",
            "inputType": "CHEMICAL"
          },
          "operationPrescription": {
            "fixedRate": {
              "valueAsDouble": 60,
              "unit": "l1ha-1",
              "vrDomainId": "vrAppRateVolumeTarget"
            }
          }
        },
        {
          "operationProduct": {
            "inputUri": "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/fertilizers/{FertilizerId1}",
            "inputType": "FERTILIZER"
          },
          "operationPrescription": {
            "prescriptionUse": {
              "fileUri": "https://sandboxapi.deere.com/platform/files/{FileId2}",
              "unit": "kg1ha-1",
              "vrDomainId": "vrAppRateMassTarget"
            }
          }
        }
      ]
    }
  ],
  "workPlanAssignments": [
    {
      "machineUri": "https://sandboxapi.deere.com/platform/machines/{MachineId1}",
      "operatorUri": "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/operators/{OperatorId1}",
      "implementUris": [
        "https://sandboxapi.deere.com/platform/implements/{ImplementId1}"
      ]
    }
  ],
  "guidanceUris": [
    "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/fields/{FieldId}/guidanceLines/{GuidanceId1}",
    "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/fields/{FieldId}/guidanceLines/{GuidanceId2}"
  ],
  "workOrder": "Sample work order",
  "instructions": "Sample work instructions"
}

Sample Request [JSON]: Update Harvest work plan

{
  "erid": "{WorkPlanId}",
  "location": {
    "fieldUri": "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/fields/{FieldId}"
  },
  "workType": {
    "representationDomainId": "dtOperationClass",
    "instanceDomainId": "dtiHarvest"
  },
  "year": 2021,
  "operations": [
    {
      "operationType": {
        "representationDomainId": "dtOperationClass",
        "instanceDomainId": "dtiHarvest"
      },
      "operationInputs": [
        {
          "operationProduct": {
            "inputUri": "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/varieties/{VarietyId1}",
            "inputType": "VARIETY"
          }
        },
        {
          "operationProduct": {
            "inputUri": "https://sandboxapi.deere.com/platform/cropTypes/{CropName}",
            "inputType": "CROP"
          }
        }
      ]
    }
  ],
  "workPlanAssignments": [
    {
      "machineUri": "https://sandboxapi.deere.com/platform/machines/{MachineId1}",
      "operatorUri": "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/operators/{OperatorId1}",
      "implementUris": [
        "https://sandboxapi.deere.com/platform/implements/{ImplementId1}"
      ]
    }
  ],
  "guidanceUris": [
    "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/fields/{FieldId}/guidanceLines/{GuidanceId1}",
    "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/fields/{FieldId}/guidanceLines/{GuidanceId2}"
  ],
  "workOrder": "Sample work order",
  "instructions": "Sample work instructions"
}

Sample Response [JSON]

204 No Content

Delete a Work Plan

DELETE

/organizations/{orgId}/workPlans/{erid}

This endpoint will delete a single work plan based on its erid in the target organization. In order to do this, the authenticated user must have following permission within the organization.

Work: access level 2

OAuth Scope Required: work2

Request URI

DELETE https://sandboxapi.deere.com/platform/organizations/{orgId}/workPlans/{erid}

Accept: application/vnd.deere.axiom.v3+json

Parameters

Parameter	Type	Description & Example	In
orgId Required	string	Owning Organization ID Example: 1234	path
erid Required	GUID	id of a work plan unique within target organization Example: 43b12553-c5ca-42f7-ac5b-a44612e24cca	path

Status Codes

Code	Message	Description
204	No Content	The request succeeded. Work plan is deleted
403	Forbidden	Authenticated user does not have required permission in target organization to delete work plan
404	Not Found	Server can not find requested work plan

Response Details

Field	Type	Description & Example

Sample Response [JSON]

204 No Content

Prioritize a Work Plan

PUT

/organizations/{orgId}/workPlans/{erid}/workPlanSequence

This endpoint will update the sequence number of a work plan with reference to other work plans within the target organization. In order to do this, the authenticated user must have following permission within the organization.

Work: access level 2

The Priority of a work plan can only be updated in the context of same the year and work type. To update priority, the client needs to send the uri of the previous work plan after which the current work plan should be executed. In order to put the current work plan on top (highest priority within the same year and work type) send the self uri in the payload.

OAuth Scope Required: work2

Request URI

PUT https://sandboxapi.deere.com/platform/organizations/{orgId}/workPlans/{erid}/workPlanSequence

Accept: application/vnd.deere.axiom.v3+json

Content-Type: application/vnd.deere.axiom.v3+json

Parameters

Parameter	Type	Description & Example	In
orgId Required	string	Owning Organization ID Example: 1234	path
erid Required	GUID	id of a work plan unique within target organization Example: 43b12553-c5ca-42f7-ac5b-a44612e24cca	path

Status Codes

Code	Message	Description
204	No Content	The request succeeded. Work plan sequence is updated
400	Bad Request	Request is rejected due to invalid request body. Response body will contain more details on reason of failure
403	Forbidden	Authenticated user do not have required permission in target organization to update work plan sequence
404	Not Found	Server can not find requested work plan

Response Details

Field	Type	Description & Example

Sample Request [JSON]

{
  "previousWorkPlanUri": "https://sandboxapi.deere.com/platform/organizations/{OrganizationId}/workPlans/{WorkPlanId}"
}

Sample Response [JSON]

204 No Content

vrTillageDepthTarget

This representation defines units allowed to specify target tillage depth for tillage operation

Units

Unit Of Measure	Digits	Decimal	Min Value	Max Value	Measurement System
in	3	1	-100.0	100.0	English
cm	3	1	-254.0	254.0	Metric
in	3	1	-100.0	100.0	Mixed

vrSeedRateMassTarget

This representation defines units allowed to specify target seed mass per area for seeding operation

Units

Unit Of Measure	Digits	Decimal	Max Value	Measurement System
lb1ac-1	5	1	99999.9	English
ton1ac-1	5	1	99999.9	English
lb1[ft2]-1	5	1	99999.9	English
kg1ha-1	5	1	99999.9	Metric
t1ha-1	5	1	99999.9	Metric
kg1[m2]-1	5	1	99999.9	Metric
lb1ac-1	5	1	99999.9	Mixed
kg1[ft2]-1	5	1	99999.9	Mixed
kg1ac-1	5	1	99999.9	Mixed

vrSeedRateSeedsTarget

This representation defines units allowed to specify seeds per area for seeding operation

Units

Unit Of Measure	Digits	Decimal	Min Value	Max Value	Measurement System
seeds1ac-1	8	0	0	99999999	English
thndSeeds1ac-1	6	1	0.0	100000.0	English
seeds1[ft2]-1	4	1	0.0	9999.9	English
seeds1ha-1	8	0	0	99999999	Metric
thndSeeds1ha-1	6	1	0.0	100000.0	Metric
seeds1[m2]-1	4	1	0.0	9999.9	Metric
seeds1ac-1	8	0	0	99999999	Mixed
seeds1[ft2]-1	4	1	0.0	9999.9	Mixed

vrAppRateMassTarget

This representation defines units allowed to specify average target application mass rate per area

Units

Unit Of Measure	Digits	Decimal	Min Value	Max Value	Measurement System
lb1ac-1	5	2	0.00	99999.99	English
ton1ac-1	5	2	0.00	99999.99	English
ozm1ac-1	5	2	0.00	99999.99	English
ozm1[ft2]-1	4	2	0.00	9999.99	English
kg1ha-1	5	2	0.00	99999.99	Metric
t1ha-1	5	2	0.00	99999.99	Metric
g1ha-1	5	2	0.00	99999.99	Metric
mg1ha-1	5	2	0.00	99999.99	Metric
dg1ha-1	5	2	0.00	99999.99	Metric
dg1[mm2]-1	5	1	0.0	99999.9	Metric
mg1[m2]-1	4	0	0	9999	Metric
g1[m2]-1	4	0	0	9999	Metric
kg1[m2]-1	5	2	0.00	99999.99	Metric
lb1ac-1	5	2	0.00	99999.99	Mixed
kg1ac-1	5	2	0.00	99999.99	Mixed
ton1ac-1	5	2	0.00	99999.99	Mixed
ozm1ac-1	5	2	0.00	99999.99	Mixed
t1ac-1	5	2	0.00	99999.99	Mixed
g1ac-1	5	2	0.00	99999.99	Mixed
mg1ac-1	5	2	0.00	99999.99	Mixed
dg1ac-1	5	2	0.00	99999.99	Mixed

vrAppRateVolumeTarget

This representation defines units allowed to specify average target application volume rate per area

Units

Unit Of Measure	Digits	Decimal	Max Value	Measurement System
gal1ac-1	5	2	99999.99	English
qt1ac-1	5	2	99999.99	English
pt1ac-1	5	2	99999.99	English
floz1ac-1	5	2	99999.99	English
l1ha-1	6	2	935395.53	Metric
ml1ha-1	5	2	99999.99	Metric
kl1ha-1	5	2	99999.99	Metric
ul1ha-1	5	2	99999.99	Metric
dl1ha-1	5	2	99999.99	Metric
[m3]1ha-1	5	2	99999.99	Metric
gal1ac-1	5	2	99999.99	Mixed
kl1ac-1	5	2	99999.99	Mixed
qt1ac-1	5	2	99999.99	Mixed
pt1ac-1	5	2	99999.99	Mixed
floz1ac-1	5	2	99999.99	Mixed
ul1ac-1	5	2	99999.99	Mixed
ml1ac-1	5	2	99999.99	Mixed
l1ac-1	5	2	99999.99	Mixed
dl1ac-1	5	2	99999.99	Mixed

vrSolutionRateLiquid

This representation defines units allowed to specify liquid solution rate per area

Units

Unit Of Measure	Digits	Decimal	Min Value	Max Value	Measurement System
gal1ac-1	5	3	0.000	99999.999	English
qt1ac-1	5	2	0.00	99999.99	English
pt1ac-1	5	2	0.00	99999.99	English
floz1ac-1	5	2	0.00	99999.99	English
l1ha-1	5	3	0.000	99999.999	Metric
ml1ha-1	5	2	0.00	99999.99	Metric
kl1ha-1	5	2	0.00	99999.99	Metric
ul1ha-1	5	2	0.00	99999.99	Metric
dl1ha-1	5	2	0.00	99999.99	Metric
[m3]1ha-1	5	2	0.00	99999.99	Metric
gal1ac-1	5	3	0.000	99999.999	Mixed
kl1ac-1	5	2	0.00	99999.99	Mixed
qt1ac-1	5	2	0.00	99999.99	Mixed
pt1ac-1	5	2	0.00	99999.99	Mixed
floz1ac-1	5	2	0.00	99999.99	Mixed
ul1ac-1	5	2	0.00	99999.99	Mixed
ml1ac-1	5	2	0.00	99999.99	Mixed
l1ac-1	5	2	0.00	99999.99	Mixed
dl1ac-1	5	2	0.00	99999.99	Mixed

dtProjectionType

This type defines the allowed values used to specify coordinate system for a guidance line

Values

Defined type value	Calculation Method
dtiProjectionDeere	Deere
dtiNonJohnDeere1	BeeLine
dtiNonJohnDeere2	Trimble

dtSignalType

This type defines allowed values to specify signal type used for boundary data

Values

dtiSignalTypeUnknown

dtiSignalTypeDigitized

dtiSignalTypeNoDiff

dtiSignalTypeUnknownDiff

dtiSignalTypeWAAS

dtiSignalTypeSF1

dtiSignalTypeSF2

dtiSignalTypeRTKX

dtiSignalTypeRTK

dtiSignalTypeSF3

dtiSignalTypeSFRTK

dtiSignalTypeNonJdDiff

dtiSignalTypeJdDiff

Additional Information

VrDomainId values allowed for Operation Types:

Operation Type	VrDomainIds
Tillage	vrTillageDepthTarget
Seeding	vrSeedRateMassTarget, vrSeedRateSeedsTarget
Application	vrAppRateMassTarget, vrAppRateVolumeTarget, vrSolutionRateLiquid

Value & Units: Please refer Representation System to know possible units and their respective value ranges for provided VrDomainId

Work Plan Event

Work Plan events are triggered whenever an addition, modification, or deletion is made to a Work Plan. For example, if new Work Plan data is available or if Work Plan data has been edited, then an event will be sent. The client must specify an orgId filter while creating a subscription. Other filters are optional. The values for each filter are arrays, so multiple orgIds, workPlanErid may be requested in a single subscription.

These events are provided through Data Subscription Service. Learn how to subscribe to events on the Getting Started page.

Work Plan subscriptions are best created for a single orgId rather than multiple since:

You cannot change the list of orgIds in a subscription after it has been created, and
Subscriptions are terminated if the user loses access to any of the orgIds in the subscription.

Work Plan Event Statuses

Status	Description
PLANNED	This indicates whether Work Plan is planned.
IN_PROGRESS	This indicates whether Work Plan operation is in progress.
COMPLETED	This indicates whether Work Plan is in completed state.

Work Plan Event Actions

Action	Description
CREATED
This event gets triggered on Work Plan Creation.
DELETED
This event gets triggered on Work Plan Deletion.
MODIFIED
This event gets triggered on Work Plan meta data update, Work Plan sequence change, changes in Work Plan.

Work Plan Event Filters

MetaDataFilter	Required	Example:	Description
orgId	Yes	"123456"	The ID of the organization that the Work Plan is associated with.
operationType	No	"dtiTillage"	The operation type of the Work Plan.
status	No	"PLANNED"	The status of the Work Plan.
action	No	"CREATED"	The action that was just performed for the Work Plan.

Sample Response [JSON]

{
  "clientKey": "johndeere-123456789",
  "eventTypeId": "workPlan",
  "targetResource": "https://sandboxapi.deere.com/organizations/123456/workPlans/f0e68d2e-4564-4cb9-85f7-11a64ea043b2",
  "metadata": [
    {
      "key": "orgId",
      "value": "123456"
    },
    {
      "key": "action",
      "value": "CREATE"
    },
    {
      "key": "operationType",
      "value": "dtiTillage"
    },
    {
      "key": "status",
      "value": "PLANNED"
    },
    {
      "key": "workPlanErid",
      "value": "f0e68d2e-4564-4cb9-85f7-11a64ea043b2"
    }
  ],
  "links": [
    {
      "rel": "subscription",
      "uri": "https://sandboxapi.deere.com/platform/eventSubscriptions/719e63d9-bd98-4505-b981-2500d9d276ba"
    },
    {
      "rel": "user",
      "uri": "https://sandboxapi.deere.com/platform/users/{username}"
    }
  ]
}

Authentication (OAuth 2)

The John Deere Precision Tech API endpoints use OAuth 2.0 for authentication. OAuth is an open protocol, and these APIs currently only support the authorization code grant type for external applications.

You can also see our sample code for examples of navigating our OAuth 2 authentication code flow.

Create an Application on Developer.Deere.com
You must be a validated John Deere user to create an application on developer.deere.com. If you do not have a John Deere username and password, you can create one using the Create an Account option on our digital tools home page here: https://www.deere.com/en/digital-tools/. You must be able to sign into the developer.deere.com to use the Create Application option in the My Applications section of the website. Please follow the steps of the Create Application workflow on the website before proceeding to the next steps.
Once your application is created, the Security section of the application Details will provide you with the Application ID and Secret necessary for the next steps to sign your API token requests.
A note on Redirect URIs (Callback URLs):
During the creation of the application (or found after creation in the application Details/Security section) you will need to define one or any number of Redirect URIs (Callback URLs). These are required for the OAuth 2 authentication flow. If you do not have this when creating the application, there is an example given in that section when creating the application that you may use for now which is http://localhost:9090/callback
If Redirect URIs are not added to your application properly or used in the authentication process in a different format than listed in the application details (for example encoded vs non-encoded), your users will experience a 400 Bad Redirect error during authentication.
Call the OAuth 2 well-known URL
With your application client or a web browser window, make a GET request to https://signin.johndeere.com/oauth2/aus78tnlaysMraFhC1t7/.well-known/oauth-authorization-server. This URL contains the authorization and token endpoints, as well as the available scopes mentioned in the steps below.
Sample Response [JSON]
{ "issuer": "https://signin.johndeere.com/oauth2/aus78tnlaysMraFhC1t7", "authorization_endpoint": "https://signin.johndeere.com/oauth2/aus78tnlaysMraFhC1t7/v1/authorize", "token_endpoint": "https://signin.johndeere.com/oauth2/aus78tnlaysMraFhC1t7/v1/token", "registration_endpoint": "https://signin.johndeere.com/oauth2/v1/clients", "jwks_uri": "https://signin.johndeere.com/oauth2/aus78tnlaysMraFhC1t7/v1/keys", "response_types_supported": [ "code", "token", "id_token", "code id_token", "code token", "id_token token", "code id_token token" ], "response_modes_supported": [ "query", "fragment", "form_post", "okta_post_message" ], "grant_types_supported": [ "authorization_code", "implicit", "refresh_token", "password", "client_credentials", "urn:ietf:params:oauth:grant-type:device_code" ], "subject_types_supported": [ "public" ], "scopes_supported": [ "ag1", "ag2", "ag3", "eq1", "eq2", "files", "finance1", "finance2", "org1", "org2", "work1", "work2", "openid", "profile", "email", "address", "phone", "offline_access", "device_sso" ], "token_endpoint_auth_methods_supported": [ "client_secret_basic", "client_secret_post", "client_secret_jwt", "private_key_jwt", "none" ], "claims_supported": [ "ver", "jti", "iss", "aud", "iat", "exp", "cid", "uid", "scp", "sub" ], "code_challenge_methods_supported": [ "S256" ], "introspection_endpoint": "https://signin.johndeere.com/oauth2/aus78tnlaysMraFhC1t7/v1/introspect", "introspection_endpoint_auth_methods_supported": [ "client_secret_basic", "client_secret_post", "client_secret_jwt", "private_key_jwt", "none" ], "revocation_endpoint": "https://signin.johndeere.com/oauth2/aus78tnlaysMraFhC1t7/v1/revoke", "revocation_endpoint_auth_methods_supported": [ "client_secret_basic", "client_secret_post", "client_secret_jwt", "private_key_jwt", "none" ], "end_session_endpoint": "https://signin.johndeere.com/oauth2/aus78tnlaysMraFhC1t7/v1/logout", "request_parameter_supported": true, "request_object_signing_alg_values_supported": [ "HS256", "HS384", "HS512", "RS256", "RS384", "RS512", "ES256", "ES384", "ES512" ], "device_authorization_endpoint": "https://signin.johndeere.com/oauth2/aus78tnlaysMraFhC1t7/v1/device/authorize", "dpop_signing_alg_values_supported": [ "RS256", "RS384", "RS512", "ES256", "ES384", "ES512" ] }

Acquire an authorization code

The authorization code is obtained by using the authorization server as an intermediary between the client and resource owner. The client directs the resource owner to an authorization server, and once authorized the server redirects the resource owner back to the client with the authorization code. Along with the GET request to the authorization server URL, you will need to send a response type code parameter, along with OAuth scopes, client ID, state, and redirect URI.

The authorization URL for the user to follow (in a web browser) should look like this:

GET

'https://signin.johndeere.com/oauth2/aus78tnlaysMraFhC1t7/v1/authorize?response_type=code&scope={scopes}&client_id={clientId}&state={state}&redirect_uri={redirect_uri}

A note on OAuth Scopes and Data Permissions:

In the Dev Docs API sections, the required OAuth scopes will be referenced for each method and endpoint. For the OAuth access token, you must request the required scopes for each endpoint your application will be using. DO NOT request all scopes available on our authorization server as not all are required for your application, and your users should be prompted to only accept scopes (permissions) necessary for the API calls you will be making.

The OAuth scopes your application requests initially for a user access token will directly relate to the permissions granted when the user makes the organization connection to your application. Please refer to the scopes table below. These scopes directly relate to user, partner, and Connected Software Company data access permissions referenced in Team Manager.

Note: If the user has less permissions in their own organization(s) or their partner organization(s) than the scopes you are requesting initially, only the user’s permission set will be assumed in the connection from the selected organization to your application. We will not grant more permissions to your application than the connecting user has.

Once the connection from the user’s organization is made to your application, you may request a higher-level scope or new scopes for the user access token, however, the connection permissions must also be adjusted by the user in https://connections.deere.com for the requesting application. Before adjusting those permission levels in the Connections website, the user must have obtained those permissions in their own organization or must be shared by the partner organizations that are currently connected.

Scope	User/Connection Permission	Description
org1	Organization Management Access Level 1	View Staff, Operators, and Partners
org2	Organization Management Access Level 1 Organization Management Access Level 2	View Staff, Operators, and Partners Modify Staff, Operators, and Partners
eq1	Equipment Access Level 1 RDA Setup & WDT	View Equipment Remote Display Access Setup File Creator, Products, and Wireless Data Transfer
eq2	Equipment Access Level 1 Equipment Access Level 2 Equipment Access Level 3 RDA Setup & WDT	View Equipment Edit Equipment (also View Detailed Machine Measurements) Manage Equipment Remote Display Access Setup File Creator, Products, and Wireless Data Transfer
ag1	Locations Access Level 1	View Locations (Clients, Farms, Fields and Associated Data)
ag2	Locations Access Level 1 Locations Access Level 2	View Locations (Clients, Farms, Fields and Associated Data) Analyze Production Data (Website Access Only)
ag3	Locations Access Level 1 Locations Access Level 2 Locations Access Level 3	View Locations (Clients, Farms, Fields and Associated Data) Analyze Production Data (Website Access Only) Manage Locations & Production Data (Website and API Access)
files	Files API Access Equipment Access Level 3 Setup & WDT	Files API Access (ag3 scope also required for most file types) Manage Equipment Setup File Creator, Products, and Wireless Data Transfer
finance1	Financial Access Level 1	View Financials
finance2	Financial Access Level 1 Financial Access Level 2	View Financials Manage Financials
work1	Work and Crop Plans Access Level 1	View Work and Crop Plans
work2	Work and Crop Plans Access Level 1 Work and Crop Plans Access Level 2	View Work and Crop Plans View Work and Crop Plans
offline_access	API Authentication Only	Request a Refresh Token

To summarize the Authorization Code steps:

The customer initiates a request for data from a client application, and the client sends an OAuth request to the authorization server with the proper headers.
The customer is redirected to the John Deere sign-in page.
The customer signs into John Deere, and the request is redirected back to the authorization server.
The customer is then presented with the scope allowance screen. (During first token request, or with modified scopes)
Scope acceptance is sent back to the OAuth server, and the customer is then redirected back to the client application with the authorization code.

Acquire an Access Token
Once the application has the authorization code, the client then requests an access token from the token server by sending a grant type authorization_code parameter, along with the authorization code, a redirect URI, and the client credentials. The authorization server authenticates the client and issues an access token and a refresh token (only if offline_access scope was requested in the previous step). The access token will expire after 12 hours after which it must be refreshed (see the last step).
POST
https://signin.johndeere.com/oauth2/aus78tnlaysMraFhC1t7/v1/token
Content-Type: application/x-www-form-urlencoded
- grant_type=authorization_code
- code={auth_code_from_authorize_call_response}
- redirect_uri={redirect_uri}
- client_id={client_id}
- client_secret={client_secret}
Post authorization redirect to enable organization access
Once the client obtains a valid access token, there is an additional step required to enable organization data access for your client application. If this step is skipped, the client will receive a 403 Forbidden response when trying the access data for any organization to which the user has access
1. Make a call to GET /organizations. If you see a ‘connections’ link in the response, your client has not granted access to that organization.
  Note: A user may have access to multiple organizations but may not enable access to all of them. A ‘connections’ may always be returned for an organization the user chooses not to allow your application access to.
  Example Response:
```
[
  {
    "@type": "Organization",
    "name": "Spahn Ranch",
    "type": "customer",
    "member": true,
    "internal": false,
    "id": "283480",
    "links": [
      {
        "@type": "Link",
        "rel": "self",
        "uri": "https://apiqa.tal.deere.com/platform/organizations/283480"
      },
      {
        "@type": "Link",
        "rel": "connections",
        "uri": "https://connections.deere.com/connections/deere-sld8shg8ee0o8ns8nhdh88hn/select-organizations"
      }
    ]
  }
]
```
2. Redirect the user to Operations Center (in a web browser) using the URI provided in the ‘connections’ link. You can also provide a redirect_uri query parameter so the user will be redirected back to your application after the organization selection process is completed. The redirect_uri that is provided must match one of the Redirect URIs listed in your application profile. The redirect_uri must also be URL encoded (i.e. “https://example.client.com/callback” should be passed as “https%3A%2F%2Fexample.client.com%2Fcallback”).
  Example URI: https://connections.deere.com/connections/{clientId}/select-organizations?redirect_uri={redirectUri}
3. The user selects the organization(s) to which your client can have access.
4. Once the organization selection is complete, the user will be redirected back to your application based on the redirect_uri query parameter that was provided. If the redirect_uri query parameter is not provided or is invalid, then the user will remain on the Connections application in Operations Center.
  Additionally, the GET /organizations endpoint will no longer include the ‘connections’ link and instead will include a ‘manage_connections’ link. This will link into the management modal in Connections for the application in the organization. Having the ‘manage_connections’ link implies that a connection between an application and organization is fully established.
  Example Response:
```
[
  {
    "@type": "Organization",
    "name": "Spahn Ranch",
    "type": "customer",
    "member": true,
    "internal": false,
    "id": "283480",
    "links": [
      {
        "@type": "Link",
        "rel": "self",
        "uri": "https://apiqa.tal.deere.com/platform/organizations/283480"
      },
      {
        "@type": "Link",
        "rel": "manage_connections",
        "uri": "https://connections-qual.deere.com/connections/deere-sld8shg8ee0o8ns8nhdh88hn/connections-dialog?orgId=283480"
      }
    ]
  }
]
```
5. Avoid getting into a redirect loop and only perform the connections redirect one time per user session. There are a few scenarios in Operations Center when a user either decides not to or is unable to complete the organization selection step. If your application does not have access to an organization after completing the connections redirect, we suggest that you inform the user that the connection was not completed and they may need to login to Operations Center to modify the Connection manually.
Use the access token to call API resource
Once the client obtains the valid access token and the user has enabled organization access for the client, they can use this token to call the appropriate resource server (API) to obtain the data needed.
For API call structure, parameters, and headers, refer to the Dev Docs section.
All your API calls should include an Authorization: Bearer {token} utilizing the obtained token.
Setup Token Refresh Process
The client application will need to pass a refresh token to the authorization (token) server to obtain a new access token before the access token expires (12 hours). For this you will pass through a refresh_token grant type parameter, along with the refresh_token to the token server.
Even if the customer did not request a resource call, the client would need to initiate a periodic refresh of this token to keep it 'hot'. The refresh token will expire after 365 days if it is not used. If the refresh token expires, the customer will need to re-authenticate. As long as you continue to refresh the access token with this refresh token, it will remain active indefinitely (unless the customer removes all organization connections on https://connections.deere.com to your application).
POST
https://signin.johndeere.com/oauth2/aus78tnlaysMraFhC1t7/v1/token
Accept: application/json
Content-Type: application/x-www-form-urlencoded
- grant_type=refresh_token
- refresh_token={refresh_token}
- redirect_uri={redirect_uri}
- scope={scopes}
- client_id={client_id}
- client_secret={client_secret}

Using Postman to call the MyJohnDeere API (OAuth 2)

Postman is a third-party API client, which you can use to test your John Deere API calls. You may use the Postman website or the desktop application for calling APIs while in Sandbox to see and follow REST API responses. Other API test clients may work for this as well. The below instructions will provide the initial setup steps to get Postman configured and obtain an OAuth 2 token.

Download and install Postman on your computer (link above), or you may use the web version.
Open Postman, click on Settings at the top, and in General settings turn off all of the Headers options.
In the top nav section of the Postman client application, you can hit the + sign to add a new request to your console.
In the Auth section of that new request tab, there is a dropdown to select the type of authorization you’ll be using. Select the OAuth2 option.
The screen will change, and you will see Type is set as OAuth 2.0.
Add auth data to should be set as Request Headers.
Header Prefix should be set as Bearer.
Within the Configure New Token section, you will need to add values to each of the fields or configure the options before selecting the Get New Access Token button (or it will error out).

Add a Token Name (can be anything).
Leave the Grant Type as Authorization Code.
The Callback URL for redirecting the authorization code back to Postman is https://www.getpostman.com/oauth2/callback. The Callback URL can be set to anything in this example. Remember that if you will be using this Postman callback URL, it (and any other Callback URL you use) will need to be synced with your OAuth client. See step 2 in this document for help in syncing this Callback URL with your application.
The Auth URL and Access Token URL can be found with opening a new Postman request window and doing a GET on this URL https://signin.johndeere.com/oauth2/aus78tnlaysMraFhC1t7/.well-known/oauth-authorization-server. No Auth is needed for this GET request. You can also open this URL in any internet browser window.
For the Client ID and Client Secret Developer.Deere.com, login, and access your application profile in the "My Applications" section.

In the Details window, under the Security section, you will find this information. What Postman calls the Client ID is called "Application Id" in this window. What Postman calls the Client Secret is called "Secret" in this window. Copy the necessary information into the Postman token section.

The Scope box should be populated with only the scopes require for the API calls you are making (space delimited). The scopes required for your API calls can be found in the Dev Docs section of every API under each endpoint’s documentation.
State is an opaque value to prevent cross-site forgery. Enter any unique string in this box (ex. 12345).
For Client Authentication, this option should be set to Send client credentials in body for this example. (not selecting this option will result in an error)

Once the steps above are complete, press the Get New Access Token button to proceed to the John Deere sign in page where a valid Operations Center user can sign in. If this is the first time the user is obtaining an API token for your application, they will be presented with the scopes acceptance screen, to which they must choose Allow Access (Don’t Allow will result in a token with no assigned scopes).

In the Details window, the first two pieces of information that OAuth requires are found in the Application Details section (illustration below). What Postman calls the Client ID is called "Application Id" in this window. What Postman calls the Client Secret is called "Secret" in this window. Copy the necessary information into the Postman token section.

Once the token is obtained and shown in the Postman screen, select the Use Token button to apply the token to your current API call. (you do not need to configure Authorization headers on the API call, as Postman will do this for you)
The next step is to enter the URL of the API call and configure an Accept header. To test, please configure the API URL to be GET https://sandboxapi.deere.com/platform/organizations. In the Headers section, please configure an Accept header with a value of application/vnd.deere.axiom.v3+json. (you may leave the default Postman headers in the request, if applicable)
Only once all the steps above are completed, can you hit the Send button in the API request to make the API call and receive a 200 OK response and response body.
If you can’t complete this process or have any questions, please feel free to use the Support button in the top navigation of the page to contact us.

Paging

When a Precision Tech API returns a collection of objects, it wraps the response in a CollectionPage object. This wrapper object has three properties:

Integer total: An integer value that represents the number of available values.
List<Link> links: A collection of links. If the response was paginated, this will contain 'nextPage' and 'previousPage' links.
List<T> values: The actual object values returned by the API.

By default, collections are paginated. Each page of data contains 10 values. The response will contain nextPage and previousPage links, which can be followed to view the entire response. The last page of data will not have a nextPage link. Please note that not all responses from each API are paginated or accept the page size parameters below.

Page Item Limit

You can control the page size by adding an itemLimit parameter to your request url. The value for this parameter should be in multiples of 10 up to 100 (max limit). You can set this by appending ?itemLimit=100 to the end of the request url.

Page Offset

You can control what page the response begins with by adding a pageOffset parameter to your request url. You can set this by appending ?pageOffset=0 to the end of the request url. The value used for this parameter should be in line with the item limit you are requesting. By default the page size is 10, so when not using the itemLimit parameter, this value should be in multiples of 10 (10,20,30, etc.). If you are using an itemLimit of 100, the value should be in multiples of 100 (100,200,300, etc.)

Disabling Paging

If you prefer, you can disable pagination entirely. The API response will still wrap responses in a CollectionPage object, but you would receive the entire collection at once. To disable pagination, add a request header named x-deere-no-paging and set its value to true. If you will be repeatedly polling an endpoint for updated data, consider using eTags instead of disabling pagination.

eTags

If your client will be making frequent/regular calls to some API to check for updates, you can use Deere's eTag implementation to limit the response to newly modified data. This feature is available for most APIs that return a list through MyJohnDeere API. To use this function:

Include x-deere-signature as a request header.
The response header will include a String Token. Send the request again with this String Token as the value for the x-deere-signature header
If there are no changes to the list, then the resource will return 304 Not Modified. If there are changes to the list, it will return only the changed data, along with a new String Token. You must use this new String Token in your next request.
While using eTags,pagination is skipped and the complete response, which include all the changes since last API call, is returned.

String Tokens should be stored as string data types.

eTags are retained by John Deere for forty-five days. If an eTag is no longer retained, the response will include the whole list. The same will occur if the signature used is not found.

Sample Request with eTag Header

GET https://sandboxapi.deere.com/platform/organizations/1234/files

Accept: application / vnd.deere.axiom.v3 + json
x - deere - signature: 
Authorization: Bearer {token}

Sample Response Header with String Token

200 OK

pragma: no - cache
date: Tue, 05 May 2015 19:37:58 GMT
server: Apache - Coyote / 1.1
x - deere - handling - server: ldxctc1
x - deere - elapsed - ms: 225
x - frame - options: SAMEORIGIN
x - deere - signature: 520122365ebb4870a344784570d202c7
content - language: en - US
cache - control: no - cache, no-store, max-age=0
transfer - encoding: chunked
connection: Keep - Alive
content - type: application / vnd.deere.axiom.v3 + json;charset=UTF-8
keep - alive: timeout = 5, max=100
expires: Thu, 01 Jan 1970 00:00:00 GMT

Sample Request with eTag & String Token

GET https://sandboxapi.deere.com/platform/organizations/1234/files

Accept: application / vnd.deere.axiom.v3 + json
x - deere - signature: 520122365ebb4870a344784570d202c7
Authorization: Bearer {token}

Sample Response: No Changes

304 Not Modified

date: Tue, 05 May 2015 19:53:00 GMT
cache - control: no - cache, no-store, max-age=0
server: Apache - Coyote / 1.1
connection: Keep - Alive
keep - alive: timeout = 5, max=100
expires: Thu, 01 Jan 1970 00:00:00 GMT

Links

Links is John Deere’s implementation of HATEOS. They are handy for discovering additional actions and endpoints. Please note that we do not show or hide returned links in a response based on client API access granted, but we do make efforts to return only those links that a user or application has access to based on data permissions. In summary, not all returned links will be accessible to your application as some APIs are not public facing and you may not have access to that endpoint, and not all returned links will allow every action (GET, PUT, POST, DELETE).

Due to our large number of API's, the number of links can become overwhelming. For some base resources, links can account for the majority of the response payload. You can optionally disable links by specifying a showLinks=none query parameter on any API call. You can also request specific links. For example, showLinks=field,clients will only show links if they have a 'rel' value of 'fields', or 'clients'.

Some Examples:

"links": [
  {
    "rel": "self",
    "uri": "https://sandboxapi.deere.com/platform/organizations/1234/farms/14e69520-34b2-4e67-b5f1-fffaf49531de"
  },
  {
    "rel": "fields",
    "uri": "https://sandboxapi.deere.com/platform/organizations/1234/farms/14e69520-34b2-4e67-b5f1-fffaf49531de/fields"
  },
  {
    "rel": "clients",
    "uri": "https://sandboxapi.deere.com/platform/organizations/1234/farms/14e69520-34b2-4e67-b5f1-fffaf49531de/clients"
  },
  {
    "rel": "owningOrganization",
    "uri": "https://sandboxapi.deere.com/platform/organizations/1234"
  }
]

How are these links helpful?

Links help to identify and discover additional API's and actions.
If you do not have access to a link, it will return a 403 response to your application.
Only those returned links that relate to the public APIs visible in https://developer.deere.com are accessible to external applications.

Common Error Codes

When a client application is making requests to John Deere APIs, it will encounter HTTP response errors that should be handled appropriately. Below you will find most of these errors and instructions on handling them.

400 Bad Request

HTTP Code: 400
Response code: Bad Request

This error means that either the POST/PUT body used in the request is incorrect, or if this error is seen in the OAuth 2 POST /token request, it means the refresh token is invalid. Before contacting API Support, please attempt to update the request body or get a valid token for the user. Please see the OAuth 2 documentation here.

401 Unauthorized

HTTP Code: 401
Response code: Server Authorization Failed

This error means that either the application does not have a license for the endpoint, or the user token is expired. Before contacting API Support, please attempt to get a valid token for the user, or use the refresh token process to get a new access token. Please see the OAuth 2 documentation here. Information about what APIs a client application can call by default are listed here, and all other APIs listed on the website are only accessible via a given license.

403 Forbidden

HTTP Code: 403
Response code: Access Denied

This error pertains to the user not having access to this resource. You should only request resources found while navigating the REST endpoints for the user. If the client calls for a resource the user does not have access to, the request will be denied. You can prevent this error by beginning your calls with /platform, and following the returned links to discover resource IDs available to the user (most are found under the /organizations link).

HTTP Code: 403
Response: The client does not have a proper access for this API

This error relates to missing OAuth 2 scopes for the user token. Along with this error code, you will see the client ID, license needed, and read/write/delete scopes needed for that license to make the corresponding requests.

HTTP Code: 403
Response: Requested org is in a restricted state

This error relates to our updates Orgs Terms & Conditions process. We have a guide for handling these requests here.

404 Not Found

HTTP Code: 404
Response code: The requested resource was not found

This error means that the resource ID requested is not valid. All resource IDs should be parsed from API responses immediately before requesting access to it. If IDs are stored for long periods of time, user access to that resource could change or be removed.

429 Too Many Requests

HTTP Code: 429
Response code: HTTP_TOO_MANY_REQUESTS

When the John Deere Servers are overwhelmed by requests, clients may receive a HTTP 429 response. That response may include a "Retry-After" header with a numeric value indicating the number of seconds the client should wait before trying again. When you receive a 429 response with that header, you have to wait at least for the specified time before retrying the request. If a customer is actively waiting for the result, you may need to return an error instead of waiting. If your application is fully asynchronous, always wait the Retry-After amount.

503 Service Unavailable

HTTP Code: 503
Response code: : HTTP_SERVICE_UNAVAILABLE

When John Deere Servers have a backend or server problem, they MAY return a corresponding Retry-After header along with a 503 response. If a 503 is returned without a Retry-After header then John Deere Servers cannot estimate a reasonable recovery time. Your application should enter an exponential back-off loop or return an error in this case. If a Retry-After header is returned, wait the number of seconds given and try again

For all other possible status codes, please refer to this resource that is publicly available (provided by Wikipedia).

Markdown

Markdown is a simple and easy-to-use markup language with broad industry adoption. There are readily available tutorials and reference materials if you’d like an introduction.

We do not support everything Markdown offers. The supported Markdown is listed below.

Supported Markdown

List- supports ordered list and unordered list (bullets will not render on UI)
Paragraph
Strong
Italic
Line Break
Horizontal Rule
Links

Map Layer Summary POST

Markdown is supported on the text field of Map Layer Summaries. View Map Layer Summary POST documentation

Sample text with Markdown

A *description* of a **Map Layer Summary** showing Markdown support.
***
an ordered list:
1. first item 
2. second item 
3. third item 
***
an unordered list:
- first item 
- second item 
- third item 
More examples can be found at this [link](https://en.wikipedia.org/wiki/Markdown).

Asset Location POST

AssetLocation has a property named measurementData, which supports Markdown on its name attribute. Please note that only links are supported here; no other Markdown will be rendered. View Asset Location POST documentation

Sample measurementData with Markdown

"measurementData" : [
    {
        "@type" : "BasicMeasurement",
        <span class="spanText">"name" : "[Leaf Wetness](https://www.example.com)",</span>
        "value" : "1.3",
        "unit" : "u1"
    }
]

Required Customer Action (RCA) Events

A Required Customer Action (RCA) event is a change or addition to the customer‘s organization flow that requires the user to take action before further account activity is allowed. This includes API calls on behalf of a customer.

Example: User must accept new terms and conditions to verify their account information.

What does it look like?

The client’s API calls will result in a 403 Forbidden response.
X-Deere-Warning header will indicate a more specific error message.

Example: "Requested Org is in a restricted state."

X-Deere-Terms-Location header will include a redirect URL where the user can take action.

Example: "https://teammanager.deere.com/organizations/{OrgId}/terms."

The response payload will indicate a short description of required user action.

Sample Response [JSON]

{
  "@type": "Errors",
  "errors": [
    {
      "@type": "Error",
      "guid": "19f7b283-d383-4990-9e14-1b3ee0f7b63d",
      "message": "Requested Org is in a restricted state."
    }
  ],
  "otherAttributes": {}
}

How should your app handle these RCAs?

If possible, navigate the user to the URL supplied in the 403 response X-Deere-Terms-Location header.
Implement a way to notify the customer that action is required. Supply a 403 response message and X-Deere-Terms-Location URL as instructions to resolve.

Consider RCA Event handling as a best practice moving forward. Your application should take steps to handle these events now.