{"__v":1,"_id":"54f8de4f4339bb1900c8c011","api":{"auth":"required","params":[],"results":{"codes":[]},"url":""},"body":"Our [REST API](http://en.wikipedia.org/wiki/Representational_state_transfer) allows programmatic access to Fleetio resources (e.g. vehicles, meter entries and fuel entries) so developers can build integrations with 3rd-party and/or internal software systems.\n\nEach API resource has available actions that can be performed on it. Supported resources and their endpoints are listed on the left.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Authentication\"\n}\n[/block]\nAuthentication is based on API keys. Each API key is associated with a Fleetio user. Results returned from various responses are based upon the role of the user to which the API key is tied.\n\n## Generating an API Key\n\nEach user account can have multiple API keys. To generate one [log in](http://secure.fleetio.com/users/sign_in) to Fleetio and navigate to the API Keys from the user dropdown in the top right corner.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/c3tefCQkS5Cz8inQXavS_Notification_Settings_-_Fleetio.jpg\",\n        \"Notification_Settings_-_Fleetio.jpg\",\n        \"252\",\n        \"253\",\n        \"#264b5d\",\n        \"\"\n      ],\n      \"caption\": \"Select the API Keys menu from the user drop-down.\"\n    }\n  ]\n}\n[/block]\nEach key can have a label, which is simply a way of allowing you to organize your keys. An API key may be revoked, making it unusable and non-recoverable.\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"API Key Security\",\n  \"body\": \"API keys are secret. We strongly recommend against pasting it online or committing it to a repository. Treat it as you would your password.\"\n}\n[/block]\n## API Key HTTP Header\n\nEach request to our API requires a valid API key to be passed as an ``HTTP header``. There is no need to issue any login commands or to maintain a session. The API key must be passed as a basic ``Authorization`` token header.\n\n## Account Token HTTP Header\n\nEach request also requires the presence of an Account token ``HTTP header``. This token must be a valid token belonging to one of the accounts that your user has a membership to. The account token must be passed using the ``Account-Token`` header.\n\nThe easiest way to find the account token in the for a particular account is in the URL. For example, if the Dashboard URL is `https://secure.fleetio.com/abc123/dashboard` then **`abc123`** is the account token.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/T8HKJB2TXizp7CbpZCAX_Dashboard_-_Fleetio.jpg\",\n        \"Dashboard_-_Fleetio.jpg\",\n        \"389\",\n        \"84\",\n        \"#509c68\",\n        \"\"\n      ],\n      \"caption\": \"Example account token in the URL of the Fleetio app.\"\n    }\n  ]\n}\n[/block]\n\n\nKeys cannot be passed as ``GET`` or ``POST`` parameters. We'll ignore them and you run the risk of jeopardizing the security your account.\n\n#### Getting an Account Token via the API\nIt's also possible to list all account tokens for a user through the API. Please see the [accounts api endpoint](http://developer.fleetio.com/v1/docs/accounts) for more information.\n\n#### Example request\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl https://secure.fleetio.com/api/v1/vehicles -H 'Authorization: Token token=\\\"YOUR_API_KEY\\\"' -H \\\"Account-Token: YOUR_ACCOUNT_TOKEN\\\"\",\n      \"language\": \"text\",\n      \"name\": \"Basic curl request with authentication headers.\"\n    }\n  ]\n}\n[/block]\n## Permissions\n\nEach API key is associated to a single, full fledged Fleetio user. Each Fleetio user has a set of permissions that limit what actions he or she can take on which resources. The same rules that apply to a user via the standard Fleetio interface also apply when interacting with the Fleetio API. \n\n[Read more about Fleetio permissions](http://help.fleetio.com/article/46-user-roles-and-permissions)\n\nIf an attempt is made to read or modify a resource for which the API user does not have access to, then a ``403 Forbidden`` response code will be returned. If you receive this response code then make sure that the API user has the correct permissions for that action.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Schema\"\n}\n[/block]\n- API Base URL: **https://secure.fleetio.com/api/v1/**\n- All API access is over **HTTPS**\n- All data is sent and received as **JSON**\n\n\n## Endpoints and Actions\n\nMost resources follow the same format, exposing 5 actions, ``index``, ``create``, ``show``, ``update``, and ``delete``. Each action will require that the correct ``http verb`` be specified, as a single endpoint can perform different actions depending on the verb.\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Action\",\n    \"h-1\": \"Endpoint\",\n    \"h-2\": \"Verb\",\n    \"h-3\": \"Description\",\n    \"0-0\": \"Index\",\n    \"0-3\": \"Returns an array of all vehicles.\",\n    \"0-1\": \"/vehicles\",\n    \"0-2\": \"GET\",\n    \"1-0\": \"Create\",\n    \"1-1\": \"/vehicles\",\n    \"1-2\": \"POST\",\n    \"1-3\": \"Creates a new vehicle\",\n    \"2-0\": \"Show\",\n    \"2-1\": \"/vehicles/:id\",\n    \"2-2\": \"GET\",\n    \"2-3\": \"Returns the vehicle corresponding to the id parameter.\",\n    \"3-0\": \"Update\",\n    \"3-1\": \"/vehicles/:id\",\n    \"3-2\": \"PATCH\",\n    \"3-3\": \"Updates the vehicle corresponding to the id parameter.\",\n    \"4-0\": \"Delete\",\n    \"4-1\": \"/vehicles/:id\",\n    \"4-2\": \"DELETE\",\n    \"4-3\": \"Deletes the vehicle corresponding to the id parameter.\",\n    \"h-4\": \"Response Data Type\",\n    \"0-4\": \"Array\",\n    \"1-4\": \"No content\",\n    \"2-4\": \"Hash\",\n    \"3-4\": \"No content\",\n    \"4-4\": \"No content\"\n  },\n  \"cols\": 5,\n  \"rows\": 5\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Response Codes\"\n}\n[/block]\n\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Code\",\n    \"0-0\": \"200\",\n    \"h-1\": \"Name\",\n    \"h-2\": \"Description\",\n    \"0-1\": \"OK\",\n    \"0-2\": \"Everything went as expected! Used on ``index`` and ``show`` actions.\",\n    \"1-0\": \"201\",\n    \"1-1\": \"Created\",\n    \"1-2\": \"Used on ``create`` actions. A 201 means that a record was created successfully. Check the ``location`` header for the url of the newly created object.\",\n    \"2-0\": \"204\",\n    \"2-1\": \"No Content\",\n    \"2-2\": \"Denotes that an action was successful, but the API does not need to return any data. Used on ``update`` and ``delete`` actions\",\n    \"5-0\": \"422\",\n    \"5-1\": \"Unprocessable Entity\",\n    \"5-2\": \"This is returned if a record cannot be ``created`` or ``updated``, usually due to validation errors. If you receive this response code check the response body for error messages.\",\n    \"3-0\": \"401\",\n    \"3-1\": \"Unauthorized\",\n    \"3-2\": \"Your API key or Account token is invalid. Make sure that both are specified correctly as described in the ``Authentication`` section.\",\n    \"4-0\": \"403\",\n    \"4-1\": \"Forbidden\",\n    \"4-2\": \"You are trying to access an endpoint for which you do not have permissions to. Check that the endpoint is correct and that your user has the necessary permissions to perform the action.\",\n    \"6-0\": \"500\",\n    \"6-1\": \"Internal Server Error\",\n    \"6-2\": \"Ideally you should never see this. If you do that means that we are either having some downtime or you found a bug. If the problem persists just let one of us know and we'll get right on it!\"\n  },\n  \"cols\": 3,\n  \"rows\": 7\n}\n[/block]","category":"54f8de4e4339bb1900c8bffc","createdAt":"2015-02-25T21:00:10.376Z","excerpt":"Welcome to the Fleetio API docs.","githubsync":"","hidden":false,"isReference":false,"link_external":false,"link_url":"","order":0,"parentDoc":null,"project":"54c0e51215af820d001a38a6","slug":"overview","sync_unique":"","title":"Overview","type":"basic","updates":[],"user":"54cba76f6d1eee0d00c33dee","version":"54f8de4e4339bb1900c8bffb","childrenPages":[]}

Overview

Welcome to the Fleetio API docs.

Our [REST API](http://en.wikipedia.org/wiki/Representational_state_transfer) allows programmatic access to Fleetio resources (e.g. vehicles, meter entries and fuel entries) so developers can build integrations with 3rd-party and/or internal software systems. Each API resource has available actions that can be performed on it. Supported resources and their endpoints are listed on the left. [block:api-header] { "type": "basic", "title": "Authentication" } [/block] Authentication is based on API keys. Each API key is associated with a Fleetio user. Results returned from various responses are based upon the role of the user to which the API key is tied. ## Generating an API Key Each user account can have multiple API keys. To generate one [log in](http://secure.fleetio.com/users/sign_in) to Fleetio and navigate to the API Keys from the user dropdown in the top right corner. [block:image] { "images": [ { "image": [ "https://files.readme.io/c3tefCQkS5Cz8inQXavS_Notification_Settings_-_Fleetio.jpg", "Notification_Settings_-_Fleetio.jpg", "252", "253", "#264b5d", "" ], "caption": "Select the API Keys menu from the user drop-down." } ] } [/block] Each key can have a label, which is simply a way of allowing you to organize your keys. An API key may be revoked, making it unusable and non-recoverable. [block:callout] { "type": "warning", "title": "API Key Security", "body": "API keys are secret. We strongly recommend against pasting it online or committing it to a repository. Treat it as you would your password." } [/block] ## API Key HTTP Header Each request to our API requires a valid API key to be passed as an ``HTTP header``. There is no need to issue any login commands or to maintain a session. The API key must be passed as a basic ``Authorization`` token header. ## Account Token HTTP Header Each request also requires the presence of an Account token ``HTTP header``. This token must be a valid token belonging to one of the accounts that your user has a membership to. The account token must be passed using the ``Account-Token`` header. The easiest way to find the account token in the for a particular account is in the URL. For example, if the Dashboard URL is `https://secure.fleetio.com/abc123/dashboard` then **`abc123`** is the account token. [block:image] { "images": [ { "image": [ "https://files.readme.io/T8HKJB2TXizp7CbpZCAX_Dashboard_-_Fleetio.jpg", "Dashboard_-_Fleetio.jpg", "389", "84", "#509c68", "" ], "caption": "Example account token in the URL of the Fleetio app." } ] } [/block] Keys cannot be passed as ``GET`` or ``POST`` parameters. We'll ignore them and you run the risk of jeopardizing the security your account. #### Getting an Account Token via the API It's also possible to list all account tokens for a user through the API. Please see the [accounts api endpoint](http://developer.fleetio.com/v1/docs/accounts) for more information. #### Example request [block:code] { "codes": [ { "code": "curl https://secure.fleetio.com/api/v1/vehicles -H 'Authorization: Token token=\"YOUR_API_KEY\"' -H \"Account-Token: YOUR_ACCOUNT_TOKEN\"", "language": "text", "name": "Basic curl request with authentication headers." } ] } [/block] ## Permissions Each API key is associated to a single, full fledged Fleetio user. Each Fleetio user has a set of permissions that limit what actions he or she can take on which resources. The same rules that apply to a user via the standard Fleetio interface also apply when interacting with the Fleetio API. [Read more about Fleetio permissions](http://help.fleetio.com/article/46-user-roles-and-permissions) If an attempt is made to read or modify a resource for which the API user does not have access to, then a ``403 Forbidden`` response code will be returned. If you receive this response code then make sure that the API user has the correct permissions for that action. [block:api-header] { "type": "basic", "title": "Schema" } [/block] - API Base URL: **https://secure.fleetio.com/api/v1/** - All API access is over **HTTPS** - All data is sent and received as **JSON** ## Endpoints and Actions Most resources follow the same format, exposing 5 actions, ``index``, ``create``, ``show``, ``update``, and ``delete``. Each action will require that the correct ``http verb`` be specified, as a single endpoint can perform different actions depending on the verb. [block:parameters] { "data": { "h-0": "Action", "h-1": "Endpoint", "h-2": "Verb", "h-3": "Description", "0-0": "Index", "0-3": "Returns an array of all vehicles.", "0-1": "/vehicles", "0-2": "GET", "1-0": "Create", "1-1": "/vehicles", "1-2": "POST", "1-3": "Creates a new vehicle", "2-0": "Show", "2-1": "/vehicles/:id", "2-2": "GET", "2-3": "Returns the vehicle corresponding to the id parameter.", "3-0": "Update", "3-1": "/vehicles/:id", "3-2": "PATCH", "3-3": "Updates the vehicle corresponding to the id parameter.", "4-0": "Delete", "4-1": "/vehicles/:id", "4-2": "DELETE", "4-3": "Deletes the vehicle corresponding to the id parameter.", "h-4": "Response Data Type", "0-4": "Array", "1-4": "No content", "2-4": "Hash", "3-4": "No content", "4-4": "No content" }, "cols": 5, "rows": 5 } [/block] [block:api-header] { "type": "basic", "title": "Response Codes" } [/block] [block:parameters] { "data": { "h-0": "Code", "0-0": "200", "h-1": "Name", "h-2": "Description", "0-1": "OK", "0-2": "Everything went as expected! Used on ``index`` and ``show`` actions.", "1-0": "201", "1-1": "Created", "1-2": "Used on ``create`` actions. A 201 means that a record was created successfully. Check the ``location`` header for the url of the newly created object.", "2-0": "204", "2-1": "No Content", "2-2": "Denotes that an action was successful, but the API does not need to return any data. Used on ``update`` and ``delete`` actions", "5-0": "422", "5-1": "Unprocessable Entity", "5-2": "This is returned if a record cannot be ``created`` or ``updated``, usually due to validation errors. If you receive this response code check the response body for error messages.", "3-0": "401", "3-1": "Unauthorized", "3-2": "Your API key or Account token is invalid. Make sure that both are specified correctly as described in the ``Authentication`` section.", "4-0": "403", "4-1": "Forbidden", "4-2": "You are trying to access an endpoint for which you do not have permissions to. Check that the endpoint is correct and that your user has the necessary permissions to perform the action.", "6-0": "500", "6-1": "Internal Server Error", "6-2": "Ideally you should never see this. If you do that means that we are either having some downtime or you found a bug. If the problem persists just let one of us know and we'll get right on it!" }, "cols": 3, "rows": 7 } [/block]