Metadata

Metadata lets you annotate many of the API’s entities with your own personalized data.

This allows for great flexibility, and can be used for everything from attaching purchase order numbers to tasks and maintaining inventory counts, to keeping track of additional driver attributes and much more.

As an initial example, say you want to keep track of your workers by the neighborhood in which they start their shifts. Instead of introducing complexity by creating teams for each of your city’s neighborhoods and managing those memberships for each worker (or using hubs), you can simply create or update a worker and include a neighborhood metadata property.

Here’s a worker for whom the neighborhood metadata property has been set:

{
    "id": "2Fwp6wS5wLNjDn36r1LJPscA",
    "name": "Marco Emery",
    "teams": [
        "0pgyktD5f3RpV3gfGZn9HPIt"
    ],
		// ...
    "metadata": [
        {
            "name": "neighborhood",
            "type": "string",
            "value": "SoMa",
            "visibility": [
                "api"
            ]
        }
    ]
}

Once metadata has been added to the target workers, finding workers by neighborhood is easily done through Querying metadata. You could also fetch all of your organization’s workers and group them in your application logic based on the value of the neighborhood metadata properties in the response.

metadata is always a top-level array property on the entity where each member of the array represents a single metadata entry. The order of the metadata entries does not matter as the array is simply a set containing zero or more entries. At the moment, permissions for entity metadata are such that these can only be accessed via API.

Whether you are implementing custom, on-demand inventory workflows or simply want a quick way to retrieve entities that share a certain custom property, metadata makes it easy to take existing API functionality and adapt it to the specific needs of your application.