{"metadata":{"image":[],"title":"","description":""},"api":{"url":"","auth":"required","settings":"","results":{"codes":[]},"params":[]},"next":{"description":"","pages":[]},"title":"Custom Fields","type":"basic","slug":"custom-fields-overview","excerpt":"","body":"Fleetio provides many pre-defined program fields to store details for various data records. You may wish to track additional information, and Custom Fields give you a place to store and report these values.\n\nAn unlimited number of Custom Fields are available for Contacts, Expense Entries, Fuel Entries, Issues, Parts, Purchase Details, Purchase Orders, Service Entries, Vehicles, Vehicle Assignments, Vehicle Renewal Reminders, Vendors, and Work Orders.\n\nCustom Fields consist of two parts - a `Label` to name the field, and a `Data Type` that determines what sort of data this field supports. Available `Data Types` are:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Data Type\",\n    \"0-0\": \"Text\",\n    \"1-0\": \"Drop-down\",\n    \"2-0\": \"Checkbox\",\n    \"3-0\": \"Date\",\n    \"0-1\": \"Any text value is acceptable. Can be words, numbers, etc. as long as they are in String format. Examples: `\\\"Excellent\\\"`, `\\\"9\\\"`, or `\\\"1.5\\\"`.\",\n    \"1-1\": \"The same as Text, except this is constrained to a pre-defined set of text values. Examples: `\\\"Excellent\\\"`, `\\\"9\\\"`, or `\\\"1.5\\\"`\",\n    \"2-1\": \"Boolean. Examples: `true` or `false`.\",\n    \"3-1\": \"Date value. Example: `\\\"2018-08-09 12:00:00 -0600\\\"`\",\n    \"h-1\": \"Value\"\n  },\n  \"cols\": 2,\n  \"rows\": 4\n}\n[/block]\nTo illustrate how Custom Fields work, let's say we want to store the T-shirt size for our Contacts in Fleetio so we can buy them a swaggy company shirt every now and then. Fleetio doesn't have a way to store this information by default for Contacts - there isn't a field for \"Shirt Size\" for Contacts. So we would create a Custom Field for Contacts, with a label called \"Shirt Size\". In this case, we also want to define the possible values it can have - (Small, Medium, Large, Extra Large, etc.). We wouldn't want anyone saying their T-shirt size was \"Eleventeen\", now would we? So we will choose the `Drop-down` data type to constrain the possible answers to our list of values.\n\nIn order to create or update Custom Fields, we'll have to use the Fleetio UI. Full documentation available [here](https://help.fleetio.com/hc/en-us/articles/360019527331-Custom-Fields-Overview#add). For example:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/ebdcaef-2020-08-03_15.54.44.gif\",\n        \"2020-08-03 15.54.44.gif\",\n        3840,\n        2008,\n        \"#ebeeef\"\n      ]\n    }\n  ]\n}\n[/block]\nOnce we've created the Custom Fields for a given entity via the Fleetio UI, we can then utilize those custom fields in our API requests to pull or push information in and out of Fleetio. One important thing to note is that spaces get converted into `_`'s, and all uppercase letters are downcased. So `Shirt Size` as the Label in the UI will become `shirt_size` in API requests / responses.\n\nFor example, let's say we have a Contact with the ID of `1234`, and we want to give them a `shirt_size` of `Medium`, we could do this using cURL like so:\n\n```\ncurl \\\n  --request PATCH \\\n  --header \"Authorization: Token abcdefghijklmnopqrstuvwxyz\" \\\n  --header \"Account-Token: 9876543210\" \\\n  --header \"Content-Type: application/json\" \\\n  --data '{\"custom_fields\": { \"shirt_size\": \"Medium\"}}' \\\n  \"https://secure.fleetio.com/api/v1/contacts/1234\"\n```\n\nNow, you can see this value in the Fleetio web UI for this user:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/6beebc1-contact-ui-custom-fields.png\",\n        \"contact-ui-custom-fields.png\",\n        3360,\n        1986,\n        \"#f1f1f2\"\n      ]\n    }\n  ]\n}\n[/block]\nAnd that's all there is to it!","updates":[],"order":7,"isReference":false,"hidden":false,"sync_unique":"","link_url":"","link_external":false,"_id":"5f286c2d242b59061685b168","createdAt":"2020-08-03T19:57:33.723Z","user":"5a70f375308ac0003288290d","category":{"sync":{"isSync":false,"url":""},"pages":["54f8de4f4339bb1900c8c010","54f8de4f4339bb1900c8c011","54f8de4f4339bb1900c8c012","54f8de4f4339bb1900c8c013"],"title":"Fleetio API","slug":"fleetio-api","order":0,"from_sync":false,"reference":false,"_id":"54f8de4e4339bb1900c8bffc","__v":1,"createdAt":"2015-01-22T11:54:59.216Z","project":"54c0e51215af820d001a38a6","version":"54f8de4e4339bb1900c8bffb"},"version":{"version":"1","version_clean":"1.0.0","codename":"","is_stable":true,"is_beta":false,"is_hidden":false,"is_deprecated":false,"categories":["54f8de4e4339bb1900c8bffc","54f8de4e4339bb1900c8bffd","54f8de4e4339bb1900c8bffe","54f8de4e4339bb1900c8bfff","54f8de4e4339bb1900c8c000","54ff6057563d7419002d666e","55007b6ecfeeea17004717dc","5501d779f2ef1e0d003116eb","55116ef89f7c7619005f853b","554bb366f245703100ddd39f","554d226b374fec0d007e64db","555e09f18ab3180d001ac605","555e0b2b4f5e5a0d00836d77","561d1f8b92a0cc350018b24f","562a956c96b5f40d0026eb60","5654c3378a26202b00c17cb8","5697a94b0b09a41900b24546","5739d89e37b52e3200a3a3cc","57ac94252c0b220e00a94570","57ac97a1ad44fc0e003be066","57ac9a3a8f312d0e00e96c75","57ac9c187ae5c60e004ba3a3","58178bee62e4500f009404f6","581a39711a63870f008b621d","581a3b4f0c65b20f00247fcb","5926e0606c729e0f00595f95","5954033ea5bbca002d27ae91","596ce53e0aeafe00157eb1ba","596ce87a8b79f4001a8f6139","598cad2e96193400190d879a","598cbcd3dc20c6000fdfb9c3","598cbd8496193400190d8955","59fcc7c9591add0026c91457","5a020b7856ea82001c8c9342","5a09bc64a91882001c56c2ed","5a71fa2de9aa84007a8bccdb","5b3a768a8a21dd0003ca080d","5c7030f099eeb6003116a106","5c9553a7b6957d005006fc09","5c955c3d04233b0063c9f450","5cfe73f7823bba005de7e1ed","5d07eb760568e70040d6ae21","5deec6550e90370067139979","5ec5a01754009700689296af"],"_id":"54f8de4e4339bb1900c8bffb","project":"54c0e51215af820d001a38a6","releaseDate":"2015-03-05T22:53:02.044Z","createdAt":"2015-03-05T22:53:02.044Z","forked_from":"54f8de14c6cabe23005c02a2","__v":40},"project":"54c0e51215af820d001a38a6","__v":0,"parentDoc":null}
Fleetio provides many pre-defined program fields to store details for various data records. You may wish to track additional information, and Custom Fields give you a place to store and report these values. An unlimited number of Custom Fields are available for Contacts, Expense Entries, Fuel Entries, Issues, Parts, Purchase Details, Purchase Orders, Service Entries, Vehicles, Vehicle Assignments, Vehicle Renewal Reminders, Vendors, and Work Orders. Custom Fields consist of two parts - a `Label` to name the field, and a `Data Type` that determines what sort of data this field supports. Available `Data Types` are: [block:parameters] { "data": { "h-0": "Data Type", "0-0": "Text", "1-0": "Drop-down", "2-0": "Checkbox", "3-0": "Date", "0-1": "Any text value is acceptable. Can be words, numbers, etc. as long as they are in String format. Examples: `\"Excellent\"`, `\"9\"`, or `\"1.5\"`.", "1-1": "The same as Text, except this is constrained to a pre-defined set of text values. Examples: `\"Excellent\"`, `\"9\"`, or `\"1.5\"`", "2-1": "Boolean. Examples: `true` or `false`.", "3-1": "Date value. Example: `\"2018-08-09 12:00:00 -0600\"`", "h-1": "Value" }, "cols": 2, "rows": 4 } [/block] To illustrate how Custom Fields work, let's say we want to store the T-shirt size for our Contacts in Fleetio so we can buy them a swaggy company shirt every now and then. Fleetio doesn't have a way to store this information by default for Contacts - there isn't a field for "Shirt Size" for Contacts. So we would create a Custom Field for Contacts, with a label called "Shirt Size". In this case, we also want to define the possible values it can have - (Small, Medium, Large, Extra Large, etc.). We wouldn't want anyone saying their T-shirt size was "Eleventeen", now would we? So we will choose the `Drop-down` data type to constrain the possible answers to our list of values. In order to create or update Custom Fields, we'll have to use the Fleetio UI. Full documentation available [here](https://help.fleetio.com/hc/en-us/articles/360019527331-Custom-Fields-Overview#add). For example: [block:image] { "images": [ { "image": [ "https://files.readme.io/ebdcaef-2020-08-03_15.54.44.gif", "2020-08-03 15.54.44.gif", 3840, 2008, "#ebeeef" ] } ] } [/block] Once we've created the Custom Fields for a given entity via the Fleetio UI, we can then utilize those custom fields in our API requests to pull or push information in and out of Fleetio. One important thing to note is that spaces get converted into `_`'s, and all uppercase letters are downcased. So `Shirt Size` as the Label in the UI will become `shirt_size` in API requests / responses. For example, let's say we have a Contact with the ID of `1234`, and we want to give them a `shirt_size` of `Medium`, we could do this using cURL like so: ``` curl \ --request PATCH \ --header "Authorization: Token abcdefghijklmnopqrstuvwxyz" \ --header "Account-Token: 9876543210" \ --header "Content-Type: application/json" \ --data '{"custom_fields": { "shirt_size": "Medium"}}' \ "https://secure.fleetio.com/api/v1/contacts/1234" ``` Now, you can see this value in the Fleetio web UI for this user: [block:image] { "images": [ { "image": [ "https://files.readme.io/6beebc1-contact-ui-custom-fields.png", "contact-ui-custom-fields.png", 3360, 1986, "#f1f1f2" ] } ] } [/block] And that's all there is to it!