{"_id":"59778bba32f043002002f5e7","category":{"_id":"59778bb932f043002002f5d4","version":"59778bb932f043002002f5d3","project":"5425e663ffd4411c319a65b4","__v":0,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2014-09-26T23:22:58.179Z","from_sync":false,"order":0,"slug":"getting-started","title":"Getting Started"},"project":"5425e663ffd4411c319a65b4","user":"5425e31affd4411c319a65b1","version":{"_id":"59778bb932f043002002f5d3","project":"5425e663ffd4411c319a65b4","__v":1,"createdAt":"2017-07-25T18:19:37.272Z","releaseDate":"2017-07-25T18:19:37.272Z","categories":["59778bb932f043002002f5d4","59778bb932f043002002f5d5"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"2.5.0","version":"2.5"},"__v":0,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2015-04-16T17:44:54.886Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":6,"body":"[Metadata](https://en.wikipedia.org/wiki/Metadata) lets you annotate many of the API’s entities with your own personalized data. \n\nThis 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. \n\nAs 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.\n\nHere’s a worker for whom the neighborhood metadata property has been set:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"id\\\": \\\"2Fwp6wS5wLNjDn36r1LJPscA\\\",\\n    \\\"name\\\": \\\"Marco Emery\\\",\\n    \\\"teams\\\": [\\n        \\\"0pgyktD5f3RpV3gfGZn9HPIt\\\"\\n    ],\\n\\t\\t// ...\\n    \\\"metadata\\\": [\\n        {\\n            \\\"name\\\": \\\"neighborhood\\\",\\n            \\\"type\\\": \\\"string\\\",\\n            \\\"value\\\": \\\"SoMa\\\",\\n            \\\"visibility\\\": [\\n                \\\"api\\\"\\n            ]\\n        }\\n    ]\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nOnce metadata has been added to the target workers, finding workers by neighborhood is easily done through a [find by metadata request](doc:metadata#querying-by-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.\n\n```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.\n\nWhether 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.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Supported Entities\"\n}\n[/block]\nMetadata can be set on the following entities:\n\n- Administrators\n- Workers\n- Destinations\n- Tasks\n- Recipients\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Limitations\"\n}\n[/block]\nThe following limitations must be considered when using metadata:\n\n- The number of metadata properties, that is, the length of the ```metadata``` array, cannot exceed **32 per entity**.\n- Binary or binary-to-text encoded values, such as Base64, are not allowed. You should always provide external references should this type of data need to be associated with an entity.\n- Array nesting is not permitted, therefore a metadata entry of type `array` cannot contain another array inside of it.\n- The `object` type must always include a value that is JSON-serializable, as with all other objects in the API.\n- The length of the `value` field, when stringified, cannot exceed 1,024 characters. If this is a problem, you should consider breaking up the data into separate metadata entries.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"The metadata object\"\n}\n[/block]\nEvery entry in the `metadata` array must adhere to the following structure:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Name\",\n    \"h-1\": \"Type\",\n    \"h-2\": \"Description\",\n    \"0-0\": \"name\",\n    \"0-1\": \"string\",\n    \"0-2\": \"The name of the property.\",\n    \"1-0\": \"type\",\n    \"1-1\": \"string\",\n    \"1-2\": \"The type of the property. Must be one of `[ ‘boolean’, ‘number’, ‘string’, ‘object’, ‘array’ ]`.\",\n    \"2-0\": \"subtype\",\n    \"2-1\": \"string\",\n    \"2-2\": \"Required only for entries of type ```array```, used for future visualization purposes. Must be one of `[ ‘boolean’, ‘number’, ‘string’, ‘object’ ]`.\",\n    \"3-0\": \"visibility\",\n    \"3-1\": \"string array\",\n    \"3-2\": \"Reserved for future use. Defaults to `[ ‘api’ ]`.\",\n    \"4-0\": \"value\",\n    \"4-1\": \"*\",\n    \"4-2\": \"The value of the property. The JSON type must match the type (and subtype) provided for the entry.\"\n  },\n  \"cols\": 3,\n  \"rows\": 5\n}\n[/block]\n###Examples\n\nThese valid metadata entries show the different types available.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"name\\\": \\\"isOnfleetTrained\\\",\\n    \\\"type\\\": \\\"boolean\\\",\\n    \\\"value\\\": true\\n}\",\n      \"language\": \"json\",\n      \"name\": \"\"\n    }\n  ]\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"name\\\": \\\"hourlyRate\\\",\\n    \\\"type\\\": \\\"number\\\",\\n    \\\"value\\\": 27.33\\n}\",\n      \"language\": \"json\",\n      \"name\": null\n    }\n  ]\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"name\\\": \\\"hometown\\\",\\n    \\\"type\\\": \\\"string\\\",\\n    \\\"value\\\": \\\"Tiburon, CA\\\"\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"name\\\": \\\"load\\\",\\n    \\\"type\\\": \\\"object\\\",\\n    \\\"value\\\": {\\n\\t      \\\"ambient\\\": {\\n\\t\\t        \\\"artichokes\\\": 18,\\n            \\\"strawberries\\\": 23\\n        },\\n\\t      \\\"cold\\\": {\\n\\t\\t        \\\"strawberries\\\": 52\\n\\t      },\\n\\t      \\\"hot\\\": {\\n            \\\"apple-pie\\\": 5\\n    \\t  }\\n    }\\n}\\n\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"name\\\": \\\"paymentOptions\\\",\\n    \\\"type\\\": \\\"array\\\",\\n    \\\"subtype\\\": \\\"string\\\",\\n    \\\"value\\\": [\\n        \\\"visa\\\",\\n        \\\"mc\\\",\\n        \\\"amex\\\",\\n        \\\"btc\\\"\\n    ]\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nThe following metadata entries, however, are invalid. \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"name\\\": \\\"lifetimeValue\\\",\\n    \\\"type\\\": \\\"number\\\",\\n    \\\"value\\\": \\\"3827.4\\\"\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nReason: value is expected as a number, however a string was provided.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"name\\\": \\\"preferredDropoffLocations\\\",\\n    \\\"type\\\": \\\"array\\\",\\n    \\\"subtype\\\": \\\"string\\\",\\n    \\\"value\\\": [\\n        \\\"-122.42271423339842,37.7897092979573\\\",\\n        \\\"-122.46803283691405,37.76040136229719\\\",\\n        -122.41550445556639,\\n        37.76420119453823\\n    ]\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nReason: string subtype expects all array members to be of type string, however both string and number members were provided.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Working with metadata\"\n}\n[/block]\nThe following entity operations are available.\n\n###Creating metadata\n\nYou can add metadata to a new entity by providing it at creation.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"$ curl -X POST \\\"https://onfleet.com/api/v2/recipients\\\" \\\\\\n       -u \\\"cd3b3de84cc1ee040bf06512d233719c:\\\" \\\\\\n       -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\\\"]}]}'\",\n      \"language\": \"shell\"\n    }\n  ]\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"id\\\": \\\"KepP1xpV5Lmxkm2P3PYVddcz\\\",\\n  // ...\\n  \\\"metadata\\\": [\\n    {\\n      \\\"name\\\": \\\"isHighNetWorth\\\",\\n      \\\"type\\\": \\\"boolean\\\",\\n      \\\"value\\\": false,\\n      \\\"visibility\\\": [\\n        \\\"api\\\"\\n      ]\\n    },\\n    {\\n      \\\"name\\\": \\\"otherCustomerConnections\\\",\\n      \\\"type\\\": \\\"array\\\",\\n      \\\"subtype\\\": \\\"string\\\",\\n      \\\"value\\\": [\\n        \\\"walt-4864619e\\\",\\n        \\\"tuco-b7ec089b\\\",\\n        \\\"mike-6df58fee\\\"\\n      ],\\n      \\\"visibility\\\": [\\n        \\\"api\\\"\\n      ]\\n    }\\n  ]\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nYou can also add metadata to an existing entity by updating it directly. This replaces any metadata previously set on the entity.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"$ curl -X PUT \\\"https://onfleet.com/api/v2/workers/h*wSb*apKlDkUFnuLTtjPke7\\\" \\\\\\n       -u \\\"cd3b3de84cc1ee040bf06512d233719c:\\\" \\\\\\n       -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}}]}'\",\n      \"language\": \"shell\"\n    }\n  ]\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"id\\\": \\\"h*wSb*apKlDkUFnuLTtjPke7\\\",\\n  // ...\\n  \\\"metadata\\\": [\\n    {\\n      \\\"name\\\": \\\"nickname\\\",\\n      \\\"type\\\": \\\"string\\\",\\n      \\\"value\\\": \\\"Puffy\\\",\\n      \\\"visibility\\\": [\\n        \\\"api\\\"\\n      ]\\n    },\\n    {\\n      \\\"name\\\": \\\"otherDetails\\\",\\n      \\\"type\\\": \\\"object\\\",\\n      \\\"value\\\": {\\n        \\\"availability\\\": {\\n          \\\"mon\\\": \\\"10:00\\\",\\n          \\\"sat\\\": \\\"16:20\\\",\\n          \\\"wed\\\": \\\"13:30\\\"\\n        },\\n        \\\"premiumInsurance\\\": false,\\n        \\\"trunkSize\\\": 9.5\\n      },\\n      \\\"visibility\\\": [\\n        \\\"api\\\"\\n      ]\\n    }\\n  ],\\n  // ...\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n###Updating metadata\n\nYou can update existing metadata for entities by using the `$set` and `$pop` commands.\n\n####$set\n\nThe upsert-like `$set` command updates existing metadata properties (based on an exact, case-sensitive `name` match) if they exist or creates them otherwise.\n\nHere is an example of an administrator entity before a `$set` request:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"id\\\": \\\"EJmsbJgHiRLPjNVE7GEIPs7*\\\",\\n  // ...\\n  \\\"metadata\\\": [\\n    {\\n      \\\"name\\\": \\\"supportRequestsHandled\\\",\\n      \\\"type\\\": \\\"number\\\",\\n      \\\"value\\\": 281,\\n      \\\"visibility\\\": [\\n        \\\"api\\\"\\n      ]\\n    },\\n    {\\n      \\\"name\\\": \\\"languages\\\",\\n      \\\"type\\\": \\\"array\\\",\\n      \\\"subtype\\\": \\\"string\\\",\\n      \\\"value\\\": [\\n        \\\"en\\\",\\n        \\\"ar\\\",\\n        \\\"ru\\\"\\n      ],\\n      \\\"visibility\\\": [\\n        \\\"api\\\"\\n      ]\\n    }\\n  ]\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nRequest\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"$ curl -X PUT \\\"https://onfleet.com/api/v2/admins/EJmsbJgHiRLPjNVE7GEIPs7*\\\" \\\\\\n       -u \\\"cd3b3de84cc1ee040bf06512d233719c:\\\" \\\\\\n       -d '{\\\"metadata\\\":{\\\"$set\\\":[{\\\"name\\\":\\\"supportRequestsHandled\\\",\\\"type\\\":\\\"number\\\",\\\"value\\\":331},{\\\"name\\\":\\\"isHighPerformer\\\",\\\"type\\\":\\\"boolean\\\",\\\"value\\\":true}]}}'\",\n      \"language\": \"shell\"\n    }\n  ]\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \" {\\n  \\\"id\\\": \\\"EJmsbJgHiRLPjNVE7GEIPs7*\\\",\\n  // ...\\n  \\\"metadata\\\": [\\n    {\\n      \\\"name\\\": \\\"supportRequestsHandled\\\",\\n      \\\"type\\\": \\\"number\\\",\\n      \\\"value\\\": 331,\\n      \\\"visibility\\\": [\\n        \\\"api\\\"\\n      ]\\n    },\\n    {\\n      \\\"name\\\": \\\"languages\\\",\\n      \\\"type\\\": \\\"array\\\",\\n      \\\"subtype\\\": \\\"string\\\",\\n      \\\"value\\\": [\\n        \\\"en\\\",\\n        \\\"ar\\\",\\n        \\\"ru\\\"\\n      ],\\n      \\\"visibility\\\": [\\n        \\\"api\\\"\\n      ]\\n    },\\n    {\\n      \\\"name\\\": \\\"isHighPerformer\\\",\\n      \\\"type\\\": \\\"boolean\\\",\\n      \\\"value\\\": true,\\n      \\\"visibility\\\": [\\n        \\\"api\\\"\\n      ]\\n    }\\n  ]\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n####$pop\n\nThe `$pop` command allows for the removal of one or more metadata entries for a given entity. \n\nHere is an example of a task entity before a `$pop` request:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"id\\\": \\\"LDJXqd2HEoGVhgmjxOawxgjF\\\",\\n  // ...\\n  \\\"metadata\\\": [\\n    {\\n      \\\"name\\\": \\\"customerId\\\",\\n      \\\"type\\\": \\\"string\\\",\\n      \\\"value\\\": \\\"4ef29b3e84eba9f2\\\",\\n      \\\"visibility\\\": [\\n        \\\"api\\\"\\n      ]\\n    },\\n    {\\n      \\\"name\\\": \\\"isDisenfranchised\\\",\\n      \\\"type\\\": \\\"boolean\\\",\\n      \\\"value\\\": true,\\n      \\\"visibility\\\": [\\n        \\\"api\\\"\\n      ]\\n    }\\n  ]\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nRequest\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"$ curl -X PUT \\\"https://onfleet.com/api/v2/tasks/LDJXqd2HEoGVhgmjxOawxgjF\\\" \\\\\\n       -u \\\"cd3b3de84cc1ee040bf06512d233719c:\\\" \\\\\\n       -d '{\\\"metadata\\\":{\\\"$pop\\\":[{\\\"name\\\":\\\"isDisenfranchised\\\"}]}}'\",\n      \"language\": \"shell\"\n    }\n  ]\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \" {\\n  \\\"id\\\": \\\"LDJXqd2HEoGVhgmjxOawxgjF\\\",\\n  // ...\\n  \\\"metadata\\\": [\\n    {\\n      \\\"name\\\": \\\"customerId\\\",\\n      \\\"type\\\": \\\"string\\\",\\n      \\\"value\\\": \\\"4ef29b3e84eba9f2\\\",\\n      \\\"visibility\\\": [\\n        \\\"api\\\"\\n      ]\\n    }\\n  ]\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nIf you wish to fully remove an entity’s metadata, you may update the entity via PUT and simply provide an empty `metadata` array.\n[block:api-header]\n{\n  \"type\": \"post\",\n  \"title\": \"Querying by metadata\"\n}\n[/block]\nAll supported entities have a `/entityNamePluralized/metadata` POST endpoint which you can use to retrieve a collection of entities that match one or more query metadata.\n\nHere is an example of a destination metadata query request.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"$ curl -X POST \\\"https://onfleet.com/api/v2/destinations/metadata\\\" \\\\\\n       -u \\\"cd3b3de84cc1ee040bf06512d233719c:\\\" \\\\\\n       -d '[{\\\"name\\\":\\\"hasDog\\\",\\\"type\\\":\\\"boolean\\\",\\\"value\\\":true}]'\",\n      \"language\": \"shell\"\n    }\n  ]\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \" [\\n  {\\n    \\\"id\\\": \\\"aCbtgPsM*w7lAf61t4YqQODO\\\",\\n    // ...\\n    \\\"metadata\\\": [\\n      {\\n        \\\"name\\\": \\\"hasDog\\\",\\n        \\\"type\\\": \\\"boolean\\\",\\n        \\\"value\\\": true,\\n        \\\"visibility\\\": [\\n          \\\"api\\\"\\n        ]\\n      }\\n    ]\\n  },\\n  {\\n    \\\"id\\\": \\\"YI**76lT7nu053HRWHPVLhKW\\\",\\n    // ...\\n    \\\"tasks\\\": [],\\n    \\\"metadata\\\": [\\n      {\\n        \\\"name\\\": \\\"hasDog\\\",\\n        \\\"type\\\": \\\"boolean\\\",\\n        \\\"value\\\": true,\\n        \\\"visibility\\\": [\\n          \\\"api\\\"\\n        ]\\n      }\\n    ]\\n  }\\n]\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nThe order of the `metadata` query array members is not taken into account and the API will apply the **AND** logical operator to these, nevertheless, it is important that complex types like `object` be properly specified, as an exact match is strictly required for an entity to be included in the query result set. This implies that, while key order does not matter in metadata entries of type `object`, it does matter with those of type `array`; further, the object values must adhere to the exact JSON type which was originally provided.","excerpt":"","slug":"metadata","type":"basic","title":"Metadata"}
[Metadata](https://en.wikipedia.org/wiki/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: [block:code] { "codes": [ { "code": "{\n \"id\": \"2Fwp6wS5wLNjDn36r1LJPscA\",\n \"name\": \"Marco Emery\",\n \"teams\": [\n \"0pgyktD5f3RpV3gfGZn9HPIt\"\n ],\n\t\t// ...\n \"metadata\": [\n {\n \"name\": \"neighborhood\",\n \"type\": \"string\",\n \"value\": \"SoMa\",\n \"visibility\": [\n \"api\"\n ]\n }\n ]\n}", "language": "json" } ] } [/block] Once metadata has been added to the target workers, finding workers by neighborhood is easily done through a [find by metadata request](doc:metadata#querying-by-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. [block:api-header] { "type": "basic", "title": "Supported Entities" } [/block] Metadata can be set on the following entities: - Administrators - Workers - Destinations - Tasks - Recipients [block:api-header] { "type": "basic", "title": "Limitations" } [/block] The following limitations must be considered when using metadata: - The number of metadata properties, that is, the length of the ```metadata``` array, cannot exceed **32 per entity**. - Binary or binary-to-text encoded values, such as Base64, are not allowed. You should always provide external references should this type of data need to be associated with an entity. - Array nesting is not permitted, therefore a metadata entry of type `array` cannot contain another array inside of it. - The `object` type must always include a value that is JSON-serializable, as with all other objects in the API. - The length of the `value` field, when stringified, cannot exceed 1,024 characters. If this is a problem, you should consider breaking up the data into separate metadata entries. [block:api-header] { "type": "basic", "title": "The metadata object" } [/block] Every entry in the `metadata` array must adhere to the following structure: [block:parameters] { "data": { "h-0": "Name", "h-1": "Type", "h-2": "Description", "0-0": "name", "0-1": "string", "0-2": "The name of the property.", "1-0": "type", "1-1": "string", "1-2": "The type of the property. Must be one of `[ ‘boolean’, ‘number’, ‘string’, ‘object’, ‘array’ ]`.", "2-0": "subtype", "2-1": "string", "2-2": "Required only for entries of type ```array```, used for future visualization purposes. Must be one of `[ ‘boolean’, ‘number’, ‘string’, ‘object’ ]`.", "3-0": "visibility", "3-1": "string array", "3-2": "Reserved for future use. Defaults to `[ ‘api’ ]`.", "4-0": "value", "4-1": "*", "4-2": "The value of the property. The JSON type must match the type (and subtype) provided for the entry." }, "cols": 3, "rows": 5 } [/block] ###Examples These valid metadata entries show the different types available. [block:code] { "codes": [ { "code": "{\n \"name\": \"isOnfleetTrained\",\n \"type\": \"boolean\",\n \"value\": true\n}", "language": "json", "name": "" } ] } [/block] [block:code] { "codes": [ { "code": "{\n \"name\": \"hourlyRate\",\n \"type\": \"number\",\n \"value\": 27.33\n}", "language": "json", "name": null } ] } [/block] [block:code] { "codes": [ { "code": "{\n \"name\": \"hometown\",\n \"type\": \"string\",\n \"value\": \"Tiburon, CA\"\n}", "language": "json" } ] } [/block] [block:code] { "codes": [ { "code": "{\n \"name\": \"load\",\n \"type\": \"object\",\n \"value\": {\n\t \"ambient\": {\n\t\t \"artichokes\": 18,\n \"strawberries\": 23\n },\n\t \"cold\": {\n\t\t \"strawberries\": 52\n\t },\n\t \"hot\": {\n \"apple-pie\": 5\n \t }\n }\n}\n", "language": "json" } ] } [/block] [block:code] { "codes": [ { "code": "{\n \"name\": \"paymentOptions\",\n \"type\": \"array\",\n \"subtype\": \"string\",\n \"value\": [\n \"visa\",\n \"mc\",\n \"amex\",\n \"btc\"\n ]\n}", "language": "json" } ] } [/block] The following metadata entries, however, are invalid. [block:code] { "codes": [ { "code": "{\n \"name\": \"lifetimeValue\",\n \"type\": \"number\",\n \"value\": \"3827.4\"\n}", "language": "json" } ] } [/block] Reason: value is expected as a number, however a string was provided. [block:code] { "codes": [ { "code": "{\n \"name\": \"preferredDropoffLocations\",\n \"type\": \"array\",\n \"subtype\": \"string\",\n \"value\": [\n \"-122.42271423339842,37.7897092979573\",\n \"-122.46803283691405,37.76040136229719\",\n -122.41550445556639,\n 37.76420119453823\n ]\n}", "language": "json" } ] } [/block] Reason: string subtype expects all array members to be of type string, however both string and number members were provided. [block:api-header] { "type": "basic", "title": "Working with metadata" } [/block] The following entity operations are available. ###Creating metadata You can add metadata to a new entity by providing it at creation. [block:code] { "codes": [ { "code": "$ curl -X POST \"https://onfleet.com/api/v2/recipients\" \\\n -u \"cd3b3de84cc1ee040bf06512d233719c:\" \\\n -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\"]}]}'", "language": "shell" } ] } [/block] [block:code] { "codes": [ { "code": "{\n \"id\": \"KepP1xpV5Lmxkm2P3PYVddcz\",\n // ...\n \"metadata\": [\n {\n \"name\": \"isHighNetWorth\",\n \"type\": \"boolean\",\n \"value\": false,\n \"visibility\": [\n \"api\"\n ]\n },\n {\n \"name\": \"otherCustomerConnections\",\n \"type\": \"array\",\n \"subtype\": \"string\",\n \"value\": [\n \"walt-4864619e\",\n \"tuco-b7ec089b\",\n \"mike-6df58fee\"\n ],\n \"visibility\": [\n \"api\"\n ]\n }\n ]\n}", "language": "json" } ] } [/block] You can also add metadata to an existing entity by updating it directly. This replaces any metadata previously set on the entity. [block:code] { "codes": [ { "code": "$ curl -X PUT \"https://onfleet.com/api/v2/workers/h*wSb*apKlDkUFnuLTtjPke7\" \\\n -u \"cd3b3de84cc1ee040bf06512d233719c:\" \\\n -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}}]}'", "language": "shell" } ] } [/block] [block:code] { "codes": [ { "code": "{\n \"id\": \"h*wSb*apKlDkUFnuLTtjPke7\",\n // ...\n \"metadata\": [\n {\n \"name\": \"nickname\",\n \"type\": \"string\",\n \"value\": \"Puffy\",\n \"visibility\": [\n \"api\"\n ]\n },\n {\n \"name\": \"otherDetails\",\n \"type\": \"object\",\n \"value\": {\n \"availability\": {\n \"mon\": \"10:00\",\n \"sat\": \"16:20\",\n \"wed\": \"13:30\"\n },\n \"premiumInsurance\": false,\n \"trunkSize\": 9.5\n },\n \"visibility\": [\n \"api\"\n ]\n }\n ],\n // ...\n}", "language": "json" } ] } [/block] ###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: [block:code] { "codes": [ { "code": "{\n \"id\": \"EJmsbJgHiRLPjNVE7GEIPs7*\",\n // ...\n \"metadata\": [\n {\n \"name\": \"supportRequestsHandled\",\n \"type\": \"number\",\n \"value\": 281,\n \"visibility\": [\n \"api\"\n ]\n },\n {\n \"name\": \"languages\",\n \"type\": \"array\",\n \"subtype\": \"string\",\n \"value\": [\n \"en\",\n \"ar\",\n \"ru\"\n ],\n \"visibility\": [\n \"api\"\n ]\n }\n ]\n}", "language": "json" } ] } [/block] Request [block:code] { "codes": [ { "code": "$ curl -X PUT \"https://onfleet.com/api/v2/admins/EJmsbJgHiRLPjNVE7GEIPs7*\" \\\n -u \"cd3b3de84cc1ee040bf06512d233719c:\" \\\n -d '{\"metadata\":{\"$set\":[{\"name\":\"supportRequestsHandled\",\"type\":\"number\",\"value\":331},{\"name\":\"isHighPerformer\",\"type\":\"boolean\",\"value\":true}]}}'", "language": "shell" } ] } [/block] [block:code] { "codes": [ { "code": " {\n \"id\": \"EJmsbJgHiRLPjNVE7GEIPs7*\",\n // ...\n \"metadata\": [\n {\n \"name\": \"supportRequestsHandled\",\n \"type\": \"number\",\n \"value\": 331,\n \"visibility\": [\n \"api\"\n ]\n },\n {\n \"name\": \"languages\",\n \"type\": \"array\",\n \"subtype\": \"string\",\n \"value\": [\n \"en\",\n \"ar\",\n \"ru\"\n ],\n \"visibility\": [\n \"api\"\n ]\n },\n {\n \"name\": \"isHighPerformer\",\n \"type\": \"boolean\",\n \"value\": true,\n \"visibility\": [\n \"api\"\n ]\n }\n ]\n}", "language": "json" } ] } [/block] ####$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: [block:code] { "codes": [ { "code": "{\n \"id\": \"LDJXqd2HEoGVhgmjxOawxgjF\",\n // ...\n \"metadata\": [\n {\n \"name\": \"customerId\",\n \"type\": \"string\",\n \"value\": \"4ef29b3e84eba9f2\",\n \"visibility\": [\n \"api\"\n ]\n },\n {\n \"name\": \"isDisenfranchised\",\n \"type\": \"boolean\",\n \"value\": true,\n \"visibility\": [\n \"api\"\n ]\n }\n ]\n}", "language": "json" } ] } [/block] Request [block:code] { "codes": [ { "code": "$ curl -X PUT \"https://onfleet.com/api/v2/tasks/LDJXqd2HEoGVhgmjxOawxgjF\" \\\n -u \"cd3b3de84cc1ee040bf06512d233719c:\" \\\n -d '{\"metadata\":{\"$pop\":[{\"name\":\"isDisenfranchised\"}]}}'", "language": "shell" } ] } [/block] [block:code] { "codes": [ { "code": " {\n \"id\": \"LDJXqd2HEoGVhgmjxOawxgjF\",\n // ...\n \"metadata\": [\n {\n \"name\": \"customerId\",\n \"type\": \"string\",\n \"value\": \"4ef29b3e84eba9f2\",\n \"visibility\": [\n \"api\"\n ]\n }\n ]\n}", "language": "json" } ] } [/block] If you wish to fully remove an entity’s metadata, you may update the entity via PUT and simply provide an empty `metadata` array. [block:api-header] { "type": "post", "title": "Querying by metadata" } [/block] All supported entities have a `/entityNamePluralized/metadata` POST endpoint which you can use to retrieve a collection of entities that match one or more query metadata. Here is an example of a destination metadata query request. [block:code] { "codes": [ { "code": "$ curl -X POST \"https://onfleet.com/api/v2/destinations/metadata\" \\\n -u \"cd3b3de84cc1ee040bf06512d233719c:\" \\\n -d '[{\"name\":\"hasDog\",\"type\":\"boolean\",\"value\":true}]'", "language": "shell" } ] } [/block] [block:code] { "codes": [ { "code": " [\n {\n \"id\": \"aCbtgPsM*w7lAf61t4YqQODO\",\n // ...\n \"metadata\": [\n {\n \"name\": \"hasDog\",\n \"type\": \"boolean\",\n \"value\": true,\n \"visibility\": [\n \"api\"\n ]\n }\n ]\n },\n {\n \"id\": \"YI**76lT7nu053HRWHPVLhKW\",\n // ...\n \"tasks\": [],\n \"metadata\": [\n {\n \"name\": \"hasDog\",\n \"type\": \"boolean\",\n \"value\": true,\n \"visibility\": [\n \"api\"\n ]\n }\n ]\n }\n]", "language": "json" } ] } [/block] The order of the `metadata` query array members is not taken into account and the API will apply the **AND** logical operator to these, nevertheless, it is important that complex types like `object` be properly specified, as an exact match is strictly required for an entity to be included in the query result set. This implies that, while key order does not matter in metadata entries of type `object`, it does matter with those of type `array`; further, the object values must adhere to the exact JSON type which was originally provided.