Working with metadata

The metadata object

Every entry in the metadata array must adhere to the following structure:

Name	Type	Description
name	string	The name of the property.
type	string	The type of the property. Must be one of `[ "boolean", "number", "string", "object", "array" ]`.
subtype	string	Required only for entries of type `array`, used for future visualization purposes. Must be one of `[ "boolean", "number", "string", "object" ]`.
visibility	array of strings	Whether the metadata object should be visible to the `api`, the `dashboard`, and/or `worker`. Defaults to `[ "api" ]`.
value		The value of the property. The JSON type must match the type (and subtype) provided for the entry.

Examples

👍
Valid Metadata Examples
These valid metadata entries show the different types available:

{
    "name": "isOnfleetTrained",
    "type": "boolean",
    "value": true
}

{
    "name": "hourlyRate",
    "type": "number",
    "value": 27.33
}

{
    "name": "hometown",
    "type": "string",
    "value": "Tiburon, CA"
}

{
    "name": "load",
    "type": "object",
    "value": {
	      "ambient": {
		        "artichokes": 18,
            "strawberries": 23
        },
	      "cold": {
		        "strawberries": 52
	      },
	      "hot": {
            "apple-pie": 5
    	  }
    }
}

{
    "name": "paymentOptions",
    "type": "array",
    "subtype": "string",
    "value": [
        "visa",
        "mc",
        "amex",
        "btc"
    ]
}

❗️
Invalid Metadata Examples
The following metadata entries are invalid.

{
    "name": "lifetimeValue",
    "type": "number",
    "value": "3827.4"
}

Reason: value is expected as a number, however a string was provided.

{
    "name": "preferredDropoffLocations",
    "type": "array",
    "subtype": "string",
    "value": [
        "-122.42271423339842,37.7897092979573",
        "-122.46803283691405,37.76040136229719",
        -122.41550445556639,
        37.76420119453823
    ]
}

Reason: string subtype expects all array members to be of type string, however both string and number members were provided.

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 "<your_api_key>:" \
     -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"
           ]
         }
       ]
     }'

$ curl -X POST "https://onfleet.com/api/v2/tasks" \
  -u "YOUR_API_KEY:" \
  -d '{
    "destination": {
      "address": {
        "unparsed": "543 Howard St, SF, CA, USA"
      }
    },
    "recipients": [],
    "metadata": [
      {
        "name": "order_id",
        "type": "string",
        "value": "ORD-88291",
        "visibility": ["api", "dashboard"]
      },
      {
        "name": "age_verified",
        "type": "boolean",
        "value": true,
        "visibility": ["api"]
      },
      {
        "name": "item_count",
        "type": "number",
        "value": 4,
        "visibility": ["api", "dashboard"]
      }
    ]
  }'

{
  "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"
      ]
    }
  ]
}

{
    "id": "D~TU2BtWMzLWJlY2Q7Ge4zIx",
     // ...
    "metadata": [
        {
            "type": "string",
            "visibility": [
                "api",
                "dashboard"
            ],
            "value": "ORD-88291",
            "name": "order_id"
        },
        {
            "type": "boolean",
            "visibility": [
                "api"
            ],
            "value": true,
            "name": "age_verified"
        },
        {
            "type": "number",
            "visibility": [
                "api",
                "dashboard"
            ],
            "value": 4,
            "name": "item_count"
        }
    ],
      // ...
}

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 "<your_api_key>:" \
     -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 "<your_api_key>:" \
     -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"
      ]
    }
  ]
}

The example below adds a new delivery_preferences field to a task while retaining all existing entries.

curl -X PUT "https://onfleet.com/api/v2/tasks/l6AA3a7COZvLs316QIsqMfWe" \
  -u "YOUR_API_KEY:" \
  -d '{
    "metadata": [
  {
    "name": "order_id",
    "type": "string",
    "value": "ORD-88291",
    "visibility": ["api", "dashboard"]
  },
  {
    "name": "age_verified",
    "type": "boolean",
    "value": true,
    "visibility": ["api"]
  },
  {
    "name": "item_count",
    "type": "number",
    "value": 4,
    "visibility": ["api", "dashboard"]
  },
  {
    "name": "delivery_preferences",
    "type": "object",
    "value": {
      "leave_at_door": true,
      "contact_on_arrival": false
    },
    "visibility": ["api"]
  }
]
}'

Response

{
    "id": "l6AA3a7COZvLs316QIsqMfWe",
  // ...
    "metadata": [
        {
            "type": "string",
            "visibility": [
                "api",
                "dashboard"
            ],
            "value": "ORD-88291",
            "name": "order_id"
        },
        {
            "type": "boolean",
            "visibility": [
                "api"
            ],
            "value": true,
            "name": "age_verified"
        },
        {
            "type": "number",
            "visibility": [
                "api",
                "dashboard"
            ],
            "value": 4,
            "name": "item_count"
        },
        {
            "type": "object",
            "visibility": [
                "api"
            ],
            "value": {
                "contact_on_arrival": false,
                "leave_at_door": true
            },
            "name": "delivery_preferences"
        }
    ],
    // ...
}

The example below adds a new New_Location field to a team.

curl -X PUT "https://onfleet.com/api/v2/teams/9PVeSqj*RxI46~aD*M812DkY" \
  -u "YOUR_API_KEY:" \
  -d ' {
    "metadata": {
        "$set":[
            {
                "name":"New_Location",
                "type":"boolean",
                "value":true
            }
        ]
    }
}'

Response

{
    "id": "9PVeSqj*RxI46~aD*M812DkY",
    "timeCreated": 1740590327000,
    "timeLastModified": 1774189583099,
    "name": "Team Kitchener",
    "workers": [
        "mQpa~QD~LYcG89bPdig8sREj",
        "sLB6mGxkXylco27jnJ0Ca2CF",
        "mM*PRrLDRSCzC~V6xNHiYS3~"
    ],
    "managers": [],
    "metadata": [
        {
            "type": "boolean",
            "visibility": [
                "api"
            ],
            "value": true,
            "name": "New_Location"
        }
    ],
    "hub": "NqP2A0*flulajomC~If3bnxD",
    "enableSelfAssignment": true
}

$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 "<your_api_key>:" \
     -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.

To remove a field, fetch the entity, filter out the entry, and PUT the remaining array back. The example below removes delivery_preferences from a task.

Example

curl -X PUT "https://onfleet.com/api/v2/tasks/kc5SA4k8YkMYMQMQMkMQM" \
  -u "YOUR_API_KEY:" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": [
      {
        "name": "order_id",
        "type": "string",
        "value": "ORD-88291",
        "visibility": ["api", "dashboard"]
      },
      {
        "name": "age_verified",
        "type": "boolean",
        "value": true,
        "visibility": ["api"]
      },
      {
        "name": "item_count",
        "type": "number",
        "value": 4,
        "visibility": ["api", "dashboard"]
      }
    ]
  }'

const auth = "Basic " + btoa("YOUR_API_KEY:");
const taskId = "kc5SA4k8YkMYMQMQMkMQM";

// Step 1: Fetch existing task
const getRes = await fetch(`https://onfleet.com/api/v2/tasks/${taskId}`, {
  headers: { "Authorization": auth }
});
const task = await getRes.json();

// Step 2: Filter out the field to remove
const filtered = task.metadata.filter(e => e.name !== "synced_to_crm");

// Step 3: PUT the remaining array back
const putRes = await fetch(`https://onfleet.com/api/v2/tasks/${taskId}`, {
  method: "PUT",
  headers: { "Authorization": auth, "Content-Type": "application/json" },
  body: JSON.stringify({ metadata: filtered })
});
const data = await putRes.json();
console.log(data);

import requests, base64, json

credentials = base64.b64encode(b"YOUR_API_KEY:").decode("utf-8")
headers = {"Authorization": f"Basic {credentials}", "Content-Type": "application/json"}
task_id = "kc5SA4k8YkMYMQMQMkMQM"

# Step 1: Fetch existing task
task = requests.get(
    f"https://onfleet.com/api/v2/tasks/{task_id}",
    headers=headers
).json()

# Step 2: Filter out the field to remove
filtered = [e for e in task["metadata"] if e["name"] != "synced_to_crm"]

# Step 3: PUT the remaining array back
response = requests.put(
    f"https://onfleet.com/api/v2/tasks/{task_id}",
    headers=headers,
    data=json.dumps({"metadata": filtered})
)
print(response.json())

<?php
$taskId = "kc5SA4k8YkMYMQMQMkMQM";
$auth = "YOUR_API_KEY:";

// Step 1: Fetch existing task
$ch = curl_init("https://onfleet.com/api/v2/tasks/{$taskId}");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_USERPWD, $auth);
$task = json_decode(curl_exec($ch), true);
curl_close($ch);

// Step 2: Filter out the field to remove
$filtered = array_values(array_filter(
    $task["metadata"],
    fn($e) => $e["name"] !== "synced_to_crm"
));

// Step 3: PUT the remaining array back
$payload = json_encode(["metadata" => $filtered]);
$ch = curl_init("https://onfleet.com/api/v2/tasks/{$taskId}");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "PUT");
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
curl_setopt($ch, CURLOPT_USERPWD, $auth);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["Content-Type: application/json"]);

$response = curl_exec($ch);
curl_close($ch);
echo $response;
?>

Response

{
  "id": "kc5SA4k8YkMYMQMQMkMQM",
  "shortId": "8f983639",
  "metadata": [
    {
      "name": "order_id",
      "type": "string",
      "value": "ORD-88291",
      "visibility": ["api", "dashboard"]
    },
    {
      "name": "age_verified",
      "type": "boolean",
      "value": true,
      "visibility": ["api"]
    },
    {
      "name": "item_count",
      "type": "number",
      "value": 4,
      "visibility": ["api", "dashboard"]
    }
  ]
}

ℹ️
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.

The metadata object

Examples

Valid Metadata Examples

Invalid Metadata Examples

Working with metadata

Creating metadata

Updating metadata

$set

$pop

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

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