{"metadata":{"image":[],"title":"","description":""},"api":{"url":"","auth":"required","results":{"codes":[]},"settings":"","params":[]},"next":{"description":"","pages":[]},"title":"Bulk API","type":"basic","slug":"bulk-api","excerpt":"","body":"Fleetio offers a bulk api for certain endpoints. Bulk APIs allow you to create data in large batches via a single network request, saving on network overhead.\n[block:api-header]\n{\n  \"title\": \"Availability\"\n}\n[/block]\nThe Bulk API currently supports creating and updating records. Deleting records in bulk is not supported at this time.\n\nThe following record types can be interacted with in bulk:\n\n  * Meter Entries: **create only**\n  * Location Entries: **create only**\n  * Faults : **create only**\n  *  Vehicles: **create and update**\n[block:api-header]\n{\n  \"title\": \"Usage\"\n}\n[/block]\nUsing the bulk API is a two step process:\n* Creating a bulk job.\n* Retrieving the status of a bulk job\n[block:api-header]\n{\n  \"title\": \"Step 1: Creating a Bulk Job\"\n}\n[/block]\nTo create a bulk job you'll need to issue a `POST` request to `/api/v1/bulk_api_jobs`. The JSON body of the request requires three fields, `resource`, `operation`, and `records`. Below is a curl example for bulk creating meter entries.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"$ curl -X POST \\\"https://secure.fleetio.com/api/v1/bulk_api_jobs\\\" -H 'Authorization: Token token=\\\"YOUR_API_KEY\\\"' -H \\\"Account-Token: YOUR_ACCOUNT_TOKEN\\\" -H 'Content-Type: application/json' -d '{\\\"resource\\\":\\\"meter_entry\\\",\\\"operation\\\":\\\"create\\\",\\\"records\\\":[{\\\"vehicle_id\\\":100,\\\"date\\\":\\\"2020-01-01\\\",\\\"value\\\":10000},{\\\"vehicle_id\\\":200,\\\"date\\\":\\\"2020-01-01\\\",\\\"value\\\":25000}, ...]'\",\n      \"language\": \"shell\"\n    }\n  ]\n}\n[/block]\nNotice how `records` is an array of hashes/objects, where each hash represents a single meter entry to be created. Each hash will accept the exact same attribute set that is defined in the non-bulk create endpoint (https://developer.fleetio.com/docs/create-meter-entry for meter entries). Any non conforming attributes will be ignored.\n\nNote that there is no restriction regarding the variety of records included in the array. This means that you can include records for different parent vehicles, different dates, etc, as long as they're all of the same record type.\n\nOnce a bulk job is created it will be enqueued and processed in the background. A successful response will look as follows:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"id\\\": \\\"a0e1a07d-2412-47d9-8164-197c1da6a160\\\",\\n    \\\"completed_at\\\": null,\\n    \\\"completed_count\\\": 0,\\n    \\\"created_at\\\": \\\"2020-06-05T09:13:07.119-05:00\\\",\\n    \\\"failed_count\\\": 0,\\n    \\\"failed_records\\\": [],\\n    \\\"operation\\\": \\\"create\\\",\\n    \\\"resource\\\": \\\"meter_entry\\\",\\n    \\\"started_at\\\": null,\\n    \\\"state\\\": \\\"pending\\\",\\n    \\\"successful_record_ids\\\": [],\\n    \\\"total_count\\\": 100,\\n    \\\"updated_at\\\": \\\"2020-06-05T09:13:07.119-05:00\\\"\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nNote that the `state` is currently `pending` and `started_at` is `null`. This means that the job has been enqueued but processing has not been started. To check on the status of a job continue to step 2.\n[block:api-header]\n{\n  \"title\": \"Step 2: Processing and Checking Job State\"\n}\n[/block]\nSince creating records in bulk can be time consuming, bulk jobs are processed in the background. You will not be notified when a job has completed processing, but you can poll our API to check on the status by using the `id` returned in the create response.\n\nOnce a job has been completed you'll see the following response:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -X GET https://secure.fleetio.com/api/v1/bulk_api_jobs/a0e1a07d-2412-47d9-8164-197c1da6a160 -H 'Account-Token: YOUR_ACCOUNT_TOKEN' -H 'Authorization: Token token=\\\"YOUR_API_KEY\\\"'\\n\\n# Below is the response from the above request\\n\\n{\\n    \\\"id\\\": \\\"a0e1a07d-2412-47d9-8164-197c1da6a160\\\",\\n    \\\"completed_at\\\": \\\"2020-06-05T09:14:00.452-05:00\\\",\\n    \\\"completed_count\\\": 97,\\n    \\\"created_at\\\": \\\"2020-06-05T09:13:07.119-05:00\\\",\\n    \\\"failed_count\\\": 3,\\n    \\\"failed_records\\\": [\\n        {\\n            \\\"index\\\": 1,\\n            \\\"error_messages\\\": {\\n                \\\"vehicle\\\": [\\n                    \\\"can't be blank\\\"\\n                ]\\n            }\\n        },\\n        ...\\n    ],\\n    \\\"operation\\\": \\\"create\\\",\\n    \\\"resource\\\": \\\"meter_entry\\\",\\n    \\\"started_at\\\": \\\"2020-06-05T09:13:58.075-05:00\\\",\\n    \\\"state\\\": \\\"complete\\\",\\n    \\\"successful_records\\\": [\\n        {\\n            \\\"index\\\": 0,\\n            \\\"id\\\": 52378361\\n        },\\n        {\\n            \\\"index\\\": 1\\n            \\\"id\\\": 52378362\\n        },\\n        ...\\n    ],\\n    \\\"total_count\\\": 100,\\n    \\\"updated_at\\\": \\\"2020-06-05T09:13:07.119-05:00\\\"\\n}\",\n      \"language\": \"shell\"\n    }\n  ]\n}\n[/block]\nNotice that the `state` is now `complete`. A few other fields you'll want to pay attention to are:\n\n* **started_at**: time when the job was started\n* **completed_at**: time when the job was completed\n* **completed_count**: number of records that were successfully created\n* **failed_count**: the number of records that failed to create\n* **failed_records**: list of records that failed. Includes an index (starting at 0) and an error message. The index is based on the original order of records that were received.\n* **successful_records**: an array of Fleetio ids for the created records, includes and index.These can be used in future API requests, such as to retrieve or delete a record.\n[block:api-header]\n{\n  \"title\": \"Updating records\"\n}\n[/block]\nUpdating records is slightly different from creating them. The main difference is that you'll need to provide two extra fields with each object: `identifier_field_name` and `identifier_field_value`. `identifier_field_name` tells the API which attribute to use for lookup. For vehicles, `identifier_field_name` can be one of `id`, `vin`, or `name`.  `identifier_field_value` is the lookup value. Here is an example payload, notice how a single bulk api job can have mixed `identifier_field_name` values\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"// This payload assumes that these three vehicles already exist in Fleetio. \\n\\n{\\n  \\\"resource\\\":\\\"vehicle\\\",\\n  \\\"operation\\\":\\\"update\\\",\\n  \\\"records\\\":[\\n    {\\n      // update vehicle based on vin matching \\\"12345678901234567\\\"\\n      \\\"identifier_field_name\\\":\\\"vin\\\",\\n      \\\"identifier_field_value\\\":\\\"12345678901234567\\\",\\n      // The following fields are applied to the update\\n      \\\"name\\\":\\\"A new vehicle name\\\",\\n      \\\"color\\\": \\\"Blue\\\",\\n      //  ...\\n    },\\n    {\\n      // update vehicle based on name matching \\\"Current vehicle name\\\"\\n      \\\"identifier_field_name\\\":\\\"name\\\",\\n      \\\"identifier_field_value\\\":\\\"Current vehicle name\\\",\\n      // The following fields are applied to the update\\n      \\\"name\\\":\\\"Another new vehicle name\\\",\\n      \\\"color\\\": \\\"Black\\\",\\n      // ...\\n    },\\n    {\\n      // update vehicle based on id matching 123\\n      \\\"identifier_field_name\\\":\\\"id\\\",\\n      \\\"identifier_field_value\\\":123,\\n      // The following fields are applied to the update\\n      \\\"name\\\":\\\"A third new vehicle name\\\",\\n      \\\"color\\\": \\\"Red\\\",\\n      // ...\\n    }\\n  ]\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"Limitations\"\n}\n[/block]\n* The bulk api is currently limited to 100 records per bulk job\n* While you're able to create as many bulk api jobs as you'd like, we'll only process 10 jobs concurrently. Other jobs will be enqueued and will start processing as other jobs are completed.","updates":[],"order":13,"isReference":false,"hidden":false,"sync_unique":"","link_url":"","link_external":false,"_id":"5eda53b244c6a4004d54aa95","createdAt":"2020-06-05T14:16:18.551Z","user":"54cba76f6d1eee0d00c33dee","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 offers a bulk api for certain endpoints. Bulk APIs allow you to create data in large batches via a single network request, saving on network overhead. [block:api-header] { "title": "Availability" } [/block] The Bulk API currently supports creating and updating records. Deleting records in bulk is not supported at this time. The following record types can be interacted with in bulk: * Meter Entries: **create only** * Location Entries: **create only** * Faults : **create only** * Vehicles: **create and update** [block:api-header] { "title": "Usage" } [/block] Using the bulk API is a two step process: * Creating a bulk job. * Retrieving the status of a bulk job [block:api-header] { "title": "Step 1: Creating a Bulk Job" } [/block] To create a bulk job you'll need to issue a `POST` request to `/api/v1/bulk_api_jobs`. The JSON body of the request requires three fields, `resource`, `operation`, and `records`. Below is a curl example for bulk creating meter entries. [block:code] { "codes": [ { "code": "$ curl -X POST \"https://secure.fleetio.com/api/v1/bulk_api_jobs\" -H 'Authorization: Token token=\"YOUR_API_KEY\"' -H \"Account-Token: YOUR_ACCOUNT_TOKEN\" -H 'Content-Type: application/json' -d '{\"resource\":\"meter_entry\",\"operation\":\"create\",\"records\":[{\"vehicle_id\":100,\"date\":\"2020-01-01\",\"value\":10000},{\"vehicle_id\":200,\"date\":\"2020-01-01\",\"value\":25000}, ...]'", "language": "shell" } ] } [/block] Notice how `records` is an array of hashes/objects, where each hash represents a single meter entry to be created. Each hash will accept the exact same attribute set that is defined in the non-bulk create endpoint (https://developer.fleetio.com/docs/create-meter-entry for meter entries). Any non conforming attributes will be ignored. Note that there is no restriction regarding the variety of records included in the array. This means that you can include records for different parent vehicles, different dates, etc, as long as they're all of the same record type. Once a bulk job is created it will be enqueued and processed in the background. A successful response will look as follows: [block:code] { "codes": [ { "code": "{\n \"id\": \"a0e1a07d-2412-47d9-8164-197c1da6a160\",\n \"completed_at\": null,\n \"completed_count\": 0,\n \"created_at\": \"2020-06-05T09:13:07.119-05:00\",\n \"failed_count\": 0,\n \"failed_records\": [],\n \"operation\": \"create\",\n \"resource\": \"meter_entry\",\n \"started_at\": null,\n \"state\": \"pending\",\n \"successful_record_ids\": [],\n \"total_count\": 100,\n \"updated_at\": \"2020-06-05T09:13:07.119-05:00\"\n}", "language": "json" } ] } [/block] Note that the `state` is currently `pending` and `started_at` is `null`. This means that the job has been enqueued but processing has not been started. To check on the status of a job continue to step 2. [block:api-header] { "title": "Step 2: Processing and Checking Job State" } [/block] Since creating records in bulk can be time consuming, bulk jobs are processed in the background. You will not be notified when a job has completed processing, but you can poll our API to check on the status by using the `id` returned in the create response. Once a job has been completed you'll see the following response: [block:code] { "codes": [ { "code": "curl -X GET https://secure.fleetio.com/api/v1/bulk_api_jobs/a0e1a07d-2412-47d9-8164-197c1da6a160 -H 'Account-Token: YOUR_ACCOUNT_TOKEN' -H 'Authorization: Token token=\"YOUR_API_KEY\"'\n\n# Below is the response from the above request\n\n{\n \"id\": \"a0e1a07d-2412-47d9-8164-197c1da6a160\",\n \"completed_at\": \"2020-06-05T09:14:00.452-05:00\",\n \"completed_count\": 97,\n \"created_at\": \"2020-06-05T09:13:07.119-05:00\",\n \"failed_count\": 3,\n \"failed_records\": [\n {\n \"index\": 1,\n \"error_messages\": {\n \"vehicle\": [\n \"can't be blank\"\n ]\n }\n },\n ...\n ],\n \"operation\": \"create\",\n \"resource\": \"meter_entry\",\n \"started_at\": \"2020-06-05T09:13:58.075-05:00\",\n \"state\": \"complete\",\n \"successful_records\": [\n {\n \"index\": 0,\n \"id\": 52378361\n },\n {\n \"index\": 1\n \"id\": 52378362\n },\n ...\n ],\n \"total_count\": 100,\n \"updated_at\": \"2020-06-05T09:13:07.119-05:00\"\n}", "language": "shell" } ] } [/block] Notice that the `state` is now `complete`. A few other fields you'll want to pay attention to are: * **started_at**: time when the job was started * **completed_at**: time when the job was completed * **completed_count**: number of records that were successfully created * **failed_count**: the number of records that failed to create * **failed_records**: list of records that failed. Includes an index (starting at 0) and an error message. The index is based on the original order of records that were received. * **successful_records**: an array of Fleetio ids for the created records, includes and index.These can be used in future API requests, such as to retrieve or delete a record. [block:api-header] { "title": "Updating records" } [/block] Updating records is slightly different from creating them. The main difference is that you'll need to provide two extra fields with each object: `identifier_field_name` and `identifier_field_value`. `identifier_field_name` tells the API which attribute to use for lookup. For vehicles, `identifier_field_name` can be one of `id`, `vin`, or `name`. `identifier_field_value` is the lookup value. Here is an example payload, notice how a single bulk api job can have mixed `identifier_field_name` values [block:code] { "codes": [ { "code": "// This payload assumes that these three vehicles already exist in Fleetio. \n\n{\n \"resource\":\"vehicle\",\n \"operation\":\"update\",\n \"records\":[\n {\n // update vehicle based on vin matching \"12345678901234567\"\n \"identifier_field_name\":\"vin\",\n \"identifier_field_value\":\"12345678901234567\",\n // The following fields are applied to the update\n \"name\":\"A new vehicle name\",\n \"color\": \"Blue\",\n // ...\n },\n {\n // update vehicle based on name matching \"Current vehicle name\"\n \"identifier_field_name\":\"name\",\n \"identifier_field_value\":\"Current vehicle name\",\n // The following fields are applied to the update\n \"name\":\"Another new vehicle name\",\n \"color\": \"Black\",\n // ...\n },\n {\n // update vehicle based on id matching 123\n \"identifier_field_name\":\"id\",\n \"identifier_field_value\":123,\n // The following fields are applied to the update\n \"name\":\"A third new vehicle name\",\n \"color\": \"Red\",\n // ...\n }\n ]\n}", "language": "json" } ] } [/block] [block:api-header] { "title": "Limitations" } [/block] * The bulk api is currently limited to 100 records per bulk job * While you're able to create as many bulk api jobs as you'd like, we'll only process 10 jobs concurrently. Other jobs will be enqueued and will start processing as other jobs are completed.