OnfleetSupportAPI StatusEngineering Blog

Working with metadata

Working with metadata

The following entity operations are available.

Creating metadata

You can add metadata to a new entity by providing it at creation.

$ curl -X POST "https://onfleet.com/api/v2/recipients" \
       -u "cd3b3de84cc1ee040bf06512d233719c:" \
       -d '{"name":"Saul Goodman","phone":"505-374-2733","notes":"Change for $100 always required.","metadata":[{"name":"isHighNetWorth","type":"boolean","value":false},{"name":"otherCustomerConnections","type":"array","subtype":"string","value":["walt-4864619e","tuco-b7ec089b","mike-6df58fee"]}]}'

{
  "id": "KepP1xpV5Lmxkm2P3PYVddcz",
  // ...
  "metadata": [
    {
      "name": "isHighNetWorth",
      "type": "boolean",
      "value": false,
      "visibility": [
        "api"
      ]
    },
    {
      "name": "otherCustomerConnections",
      "type": "array",
      "subtype": "string",
      "value": [
        "walt-4864619e",
        "tuco-b7ec089b",
        "mike-6df58fee"
      ],
      "visibility": [
        "api"
      ]
    }
  ]
}

You can also add metadata to an existing entity by updating it directly. This replaces any metadata previously set on the entity.

$ curl -X PUT "https://onfleet.com/api/v2/workers/h*wSb*apKlDkUFnuLTtjPke7" \
       -u "cd3b3de84cc1ee040bf06512d233719c:" \
       -d '{"metadata":[{"name":"nickname","type":"string","value":"Puffy"},{"name":"otherDetails","type":"object","value":{"availability":{"mon":"10:00","wed":"13:30","sat":"16:20"},"trunkSize":9.5,"premiumInsurance":false}}]}'

{
  "id": "h*wSb*apKlDkUFnuLTtjPke7",
  // ...
  "metadata": [
    {
      "name": "nickname",
      "type": "string",
      "value": "Puffy",
      "visibility": [
        "api"
      ]
    },
    {
      "name": "otherDetails",
      "type": "object",
      "value": {
        "availability": {
          "mon": "10:00",
          "sat": "16:20",
          "wed": "13:30"
        },
        "premiumInsurance": false,
        "trunkSize": 9.5
      },
      "visibility": [
        "api"
      ]
    }
  ],
  // ...
}

Updating metadata

You can update existing metadata for entities by using the $set and $pop commands.

$set

The upsert-like $set command updates existing metadata properties (based on an exact, case-sensitive name match) if they exist or creates them otherwise.

Here is an example of an administrator entity before a $set request:

{
  "id": "EJmsbJgHiRLPjNVE7GEIPs7*",
  // ...
  "metadata": [
    {
      "name": "supportRequestsHandled",
      "type": "number",
      "value": 281,
      "visibility": [
        "api"
      ]
    },
    {
      "name": "languages",
      "type": "array",
      "subtype": "string",
      "value": [
        "en",
        "ar",
        "ru"
      ],
      "visibility": [
        "api"
      ]
    }
  ]
}

Request

$ curl -X PUT "https://onfleet.com/api/v2/admins/EJmsbJgHiRLPjNVE7GEIPs7*" \
       -u "cd3b3de84cc1ee040bf06512d233719c:" \
       -d '{"metadata":{"$set":[{"name":"supportRequestsHandled","type":"number","value":331},{"name":"isHighPerformer","type":"boolean","value":true}]}}'

{
  "id": "EJmsbJgHiRLPjNVE7GEIPs7*",
  // ...
  "metadata": [
    {
      "name": "supportRequestsHandled",
      "type": "number",
      "value": 331,
      "visibility": [
        "api"
      ]
    },
    {
      "name": "languages",
      "type": "array",
      "subtype": "string",
      "value": [
        "en",
        "ar",
        "ru"
      ],
      "visibility": [
        "api"
      ]
    },
    {
      "name": "isHighPerformer",
      "type": "boolean",
      "value": true,
      "visibility": [
        "api"
      ]
    }
  ]
}

$pop

The $pop command allows for the removal of one or more metadata entries for a given entity.

Here is an example of a task entity before a $pop request:

{
  "id": "LDJXqd2HEoGVhgmjxOawxgjF",
  // ...
  "metadata": [
    {
      "name": "customerId",
      "type": "string",
      "value": "4ef29b3e84eba9f2",
      "visibility": [
        "api"
      ]
    },
    {
      "name": "isDisenfranchised",
      "type": "boolean",
      "value": true,
      "visibility": [
        "api"
      ]
    }
  ]
}
Request
$ curl -X PUT "https://onfleet.com/api/v2/tasks/LDJXqd2HEoGVhgmjxOawxgjF" \
       -u "cd3b3de84cc1ee040bf06512d233719c:" \
       -d '{"metadata":{"$pop":[{"name":"isDisenfranchised"}]}}'

{
  "id": "LDJXqd2HEoGVhgmjxOawxgjF",
  // ...
  "metadata": [
    {
      "name": "customerId",
      "type": "string",
      "value": "4ef29b3e84eba9f2",
      "visibility": [
        "api"
      ]
    }
  ]
}

If you wish to fully remove an entity’s metadata, you may update the entity via PUT and simply provide an empty metadata array.

📘

Updating metadata

Note that metadata can also be updated via the Update endpoint for each supported Entity.

While metadata can be updated during any state of a Task, we strongly recommend keeping a record of the response when executing that API request.