Global FieldID UIMy AccountSupportRoadmap
Guides

Deleting a field

GFID system allows deletion of fields.

Suggest Edits

The DELETE /fields/{id} endpoint allows client applications to delete fields.

Prerequisites

Please note: write access to the API is available on request. Creating and updating fields is intended only for client applications with end users, who are able to confirm the validity and suitability of input data as a canonical field boundary. Before granting access we will discuss with you how to ensure your users understand the implications of updating the Global FieldID map of fields. We will also assign you a unique source name to be used in input to the write endpoints.

Input

The id of the field to delete.

Output

The output payload is the same as for the GET /fields/{id} endpoint, i.e. a JSON object representing the field that got deleted.

How the deletion of fields works

The deletion of fields works differently depending on if the field is a past, an active or a future field.

  • If the field is a past field i.e. its effective_to date expired in the past, the field can’t be subject to any update and any attempt to delete the field will error out;

  • if the field is an active field i.e. its time interval of validity includes the current timestamp, then deletion results on the deprecation of the active boundary of the field i.e. the effectiveto date of the field (and its active boundary) is set to _now. Indeed, the deletion of an active field is never a "hard deletion" and it will always be possible to query the system and obtain data for a field that got deleted while it was active. So, how a deleted field will look like when retrieved?

Please see below the response of the GET /fields/68M7.H137 where 68M7.H137 is the id of an active field:

{
     "active_boundary_id": "018d12b7-d2df-7279-8528-327bf0b95cd5",
     "boundaries": [
        {
           "boundary_id": "018d12b7-d2df-7279-8528-327bf0b95cd5",
           "effective_from": "2024-01-16T14:40:53.272751+00:00",
           "effective_to": "9999-12-31T00:00:00+00:00"
        }
     ],
     "created_at": "2024-01-16T14:40:53.489138+00:00",
     "effective_from": "2024-01-16T14:40:53.272751+00:00",
     "effective_to": "9999-12-31T00:00:00+00:00",
     "field_id": "68M7.H137"
}

Now let’s delete this active field by sending request DELETE /fields/68M7.H137 and then retrieve again the field from the system by GET /fields/68M7.H137 to see how it looks like:

{
     "active_boundary_id": null,
     "boundaries": [
        {
          "boundary_id": "018d12b7-d2df-7279-8528-327bf0b95cd5",
          "effective_from": "2024-01-16T14:40:53.272751+00:00",
          "effective_to": "2024-01-24T13:57:15.915811+00:00"
        }
     ],
     "created_at": "2024-01-16T14:40:53.489138+00:00",
     "effective_from": "2024-01-16T14:40:53.272751+00:00",
     "effective_to": "2024-01-24T13:57:15.915811+00:00",
     "field_id": "68M7.H137"
}

As you can see the activeboundary_id is now _null because the field is no longer active, and the effectiveto of both the previously active boundary and the field itself have been updated to _now.

Also, if an active field has boundaries set to become active in the future, all these “future“ boundaries will no longer be linked with the field (but will keep existing in the system).

Please see below the response of the GET /fields/6CQ2.QV71 where 6CQ2.QV71 is the id of an active field which has a current active boundary “018d3bd7-…“ that will be replaced by boundary “018c1439-…“ on the 2026-12-31. 

{
     "active_boundary_id": "018d3bd7-2196-7538-a340-1d7aad82b151",
     "boundaries": [
        {
          "boundary_id": "018c1439-14f4-7c1f-ab63-93e50777a03e",
          "effective_from": "2026-12-31T00:00:00+00:00",
          "effective_to": "9999-12-31T00:00:00+00:00"
        },
        {
          "boundary_id": "018d3bd7-2196-7538-a340-1d7aad82b151",
          "effective_from": "2024-01-24T14:19:31.075162+00:00",
          "effective_to": "2026-12-31T00:00:00+00:00"
        }
     ],
     "created_at": "2024-01-24T14:19:31.119654+00:00",
     "effective_from": "2024-01-24T14:19:31.075162+00:00",
     "effective_to": "9999-12-31T00:00:00+00:00",
     "field_id": "6CQ2.QV71"
}

Now let’s delete this active field by sending request DELETE /fields/6CQ2.QV71 and then retrieve again the field from the system by GET /fields/6CQ2.QV71 to see how it looks like:

{
     "active_boundary_id": null,
     "boundaries": [
        {
          "boundary_id": "018d3bd7-2196-7538-a340-1d7aad82b151",
          "effective_from": "2024-01-24T14:19:31.075162+00:00",
          "effective_to": "2024-01-24T14:46:39.937866+00:00"
        }
     ],
     "created_at": "2024-01-24T14:19:31.119654+00:00",
     "effective_from": "2024-01-24T14:19:31.075162+00:00",
     "effective_to": "2024-01-24T14:46:39.937866+00:00",
     "field_id": "6CQ2.QV71"
}

As you can see the activeboundary_id is now _null because the field is no longer active, and the effectiveto of both the previously active boundary and the field itself have been updated to _now. Also, the “future“ boundary “018c1439-…“ does no longer appear among the list of boundaries of the field.

  • If the field is a future field i.e. its time range of validity starts in the future, then the field is invalidated and all the linked boundaries will non longer be linked to it.

Please see below the response of the GET /fields/6CQ2.QGVY where 6CQ2.QGVY is the id of a future field. The response is showing that the field does not have an active boundary and the first boundary of the field will become active on the 2026-11-15.

{
     "active_boundary_id": null,
     "boundaries": [
        {
          "boundary_id": "018c1439-14f4-7c1f-ab63-93e50777a03e",
          "effective_from": "2026-11-15T00:00:00+00:00",
          "effective_to": "9999-12-31T00:00:00+00:00"
        }
     ],
     "created_at": "2024-01-24T14:52:59.237497+00:00",
     "effective_from": "2026-11-15T00:00:00+00:00",
     "effective_to": "9999-12-31T00:00:00+00:00",
     "field_id": "6CQ2.QGVY"
}

Now let’s delete this future field by sending request DELETE /fields/6CQ2.QGVY and then retrieve again the field from the system by GET /fields/6CQ2.QGVY to see how it looks like:

{
     "active_boundary_id": null,
     "boundaries": [],
     "created_at": "2024-01-24T14:52:59.237497+00:00",
     "effective_from": null,
     "effective_to": null,
     "field_id": "6CQ2.QGVY"
}

Please note that the boundary that was meant to become the boundary of the field, will always be available in the system. So, if you execute GET/boundaries/018c1439-14f4-7c1f-ab63-93e50777a03e the system will return the boundary data.

Updated about 1 month ago