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.