In order to get started with the Smartlane API, you need to get your own personal access key and database instance. Just get in touch with us directly at [email protected].

We will then provide you with a link to a registration form. Your email address will be set as your user name and once you choose your private password, you're ready for authentication with our API.

📘

Data privacy and security

All API calls are secured by SSL via HTTPS, so you don't have to worry about anybody intercepting your data via the Internet. All supplied data are stored securely on professionally operated servers in Germany and they are only accessible by the API itself - they cannot be accessed by anyone outside the application. The API itself is secured by a user name and password, which are supplied only to you during the registration process. Of course, passwords are always stored as encrypted hashes and thus are never readable by anybody.

Authentication

Next to being accessible exclusively via https, all API calls (exceptions aside) are secured by JWT tokens. That means you always need to provide an authorization header with a security token.

The token is generated via a POST request to the API endpoint /auth, with your registered email address and password information in the body:

curl --request POST \
     --url 'https://dispatch.smartlane.io/your_company_name/auth' \
     --header 'Content-Type: application/json' \
     --data '{"email": "[email protected]", 
              "password": "your_choosen_password"}'

import requests

url = "https://dispatch.smartlane.io/your_company_name/auth"
login = {'email': '[email protected]', 'password': 'your_choosen_password'}

response = requests.post(url, json=login)

jQuery, yet to be added

If done successfully, this responds with a JSON body containing the access_token,

{'access_token': 'your.Long_Randomfghxlcnebem.Secure_AccessToken'}

which can - and must - be used for all further API calls in the request header in the following form as a JSON object:

{'Authorization': 'JWT your.Long_Randomfghxlcnebem.Secure_AccessToken'}

Please make sure that you don't miss the mandatory `JWT ` prefix!




[block:callout]
{
  "type": "info",
  "title": "API Endpoint URLs",
  "body": "All URLs of the API requests are composed of the the base url `https://dispatch.smartlane.io/your_company_name` plus `/api` and the `/name` of the API endpoint. The only exception is the call to `/auth`, where `/api` is absent."
}
[/block]



### Basic API Requests

Now that we've got our JWT access token, we can acutally try making the first call to our API. As an example, it may serve a request to the [/company](/reference#getcompany) endpoint,
which contains the data you provided with your registration.



[block:code]
{
  "codes": [
    {
      "code": "curl --request GET \\\n     \"https://dispatch.smartlane.io/your_company_name/api/company\" \\\n     --header \"Authorization: JWT your.Long_Randomfghxlcnebem.Secure_AccessToken\"",
      "language": "curl"
    },
    {
      "code": "import requests\n\napi_url = \"https://dispatch.smartlane.io/your_company_name/api/company\"\n\nauth_header = {'Authorization': 'JWT your.Long_Randomfghxlcnebem.Secure_AccessToken'}\n\nresponse = requests.get(url, headers=auth_header)",
      "language": "python"
    }
  ]
}
[/block]




If everything goes right, the response is a HTTP status code `200` containing a body similar to

{'num_results': 1,
 'objects': [{'companyname': 'Your_company_name',
              'id': 1,
              'location_id': 1,
              'pricing_package': 500,
              'test_phase': True}],
 'page': 1,
 'total_pages': 1}

Yay, now you know what your companyname is! Great success, but there are also some other bits of information, like the location_id, so check out the first chapter on geocoding addresses to figure out whats up with that, or jump directly to chapter 3 if you don't care about all those details and start optimizing your first tour right away.

📘

It's all JSON

All request bodies and headers, as well as the produced responses, are exclusively of the type application/json.

🚧

Request limit

There is a general limit of 200 API requests per second. If more requests are called, the response will be 429 Too Many Requests. If you need a higher request frequency, please let us know at [email protected]