Quickstart Guide

Welcome to Onfleet’s API! This guide walks you through the basic topics you should consider when integrating with Onfleet.

What programming language are you using for your integration?

If the answer is Python, PHP, Java, JavaScript, Ruby or Go you are more than welcome to jumpstart your integration by using our pre-built official API Wrappers: pyonfleet, php-onfleet, node-onfleet, java-onfleet, ruby-onfleet and gonfleet.

Other users have created their own scripts and features to make Onfleet work for them, and we love to see it! If you don’t see the language of your preference here, there may be an unofficial wrappers available through other users' repositories on github. However, we can only support issues with content in the official onfleet github.

Do you have an Onfleet API key?

If the answer is no, please log on to the Onfleet dashboard with your organization admin email and create an API key.

📘
Testing your API key
Once you have an API key created, you can test it by hitting our authorization endpoint.

Using the API key?

To interact with the Onfleet API, you will need to issue an HTTP request and each request will need to be authenticated using the Onfleet API key. Our examples in the documentation are shown in cURL command form, where the commands are executed via a terminal. This is an example of an HTTP request in the form of a cURL command, which includes a <METHOD> and you will need to input your preferred <api_endpoint>, <api_key>, and <body> (optional):

curl -X <METHOD> "https://onfleet.com/api/v2/<api_endpoint>" -u "<your_api_key>:" -d "<body>"

If you are not familiar with cURL commands, we recommend using the following tools to send test API requests to Onfleet:

What is your delivery business model?

Everything at Onfleet starts with a task, a task is a single unit of work performed at a destination, and is either a pickup or a dropoff.

If you perform deliveries that originate at one pickup location, an order in your e-commerce system can be represented by a single dropoff task in Onfleet. This approach is common for scheduled delivery models like produce, grocery, etc...

If you perform unique pickups for each order, then you will need to create two linked tasks in Onfleet to represent the pickup and then the subsequent dropoff. This approach is common for scheduled and on-demand models like laundry and dry cleaning, restaurant, etc...

🚧
Linked Pickup & Dropoff
For businesses creating a pickup/dropoff combo, learn more in linked tasks and task dependencies.

How do I create a task?

A Task should always have one Destination, which can be created using an address or a set of GPS coordinates. Creating a Destination can be done separately or during task creation.
The Recipient field can be used if someone needs to be informed that the task has started or completed. Recipients receive SMS text notifications and can track driver statuses when properly configured in the dashboard. The recipient field can be left empty. Like Destination, it can be created separately or during task creation.
A Task is created and managed by a registered Administrator (either on the dashboard or via the API), and can only be started and completed by a registered Worker (via the Onfleet mobile app).

You can decide whether to use more advanced features duringtask creation, including:

Task assignment: automatically or manually
Creating proof-of-delivery/completion requirements

Do you need any information sent back to your applications?

Information can be sent back to your application (ie: order management, e-commerce, customer-facing mobile apps) by utilizing Onfleet Webhooks, where we offer more than 10 event triggers.

Do you need custom information stored in Onfleet?

If you would like to interact with Onfleet’s API using external identifiers (ie: order numbers, driver’s licenses etc.), or display custom structured data to Onfleet dashboard and mobile app users, you can store custom information on many of Onfleet’s objects using the metadata fields. Learn more about creating and storing custom data using Metadata.

How will you validate address information prior to creating tasks in Onfleet?

It is critical that your team has accurate address information to successfully perform pickups and deliveries. Onfleet requires a valid destination address or coordinate pair (longitude, latitude) in order to create a task.

🚧
We highly recommend validating the address information prior to sending it to Onfleet and using a coordinate pair at task creation, ensuring tasks will always be created.

When only an address is provided, Onfleet uses Google Maps Javascript API to geocode the address information provided. In cases where your task destination creation fails geocoding, you can follow this troubleshooting guide to find a viable solution.

Here's a developer tool showing how the Maps API responds to an address, note that Onfleet will reject anything that is deemed inaccurate (a generic geographic region or multiple matching results):

How will you validate phone numbers prior to creating Recipients?

Onfleet utilizes Google's phone validation library to validate all phone inputs, that includes admins, workers, and recipients. In cases where you've encountered a failed request regarding an invalid phone number, it is recommended to set up a failover to capture the failed request and respond properly.

Here's a community tool that utilizes the same phone validation library, simply put in a phone number that you wish to test and click submit. The results shown under Validation Results will tell you whether the number is valid or not:

What proof-of-delivery options do you expect to use?

Onfleet offers the following as proof-of-delivery options:

Signature
Photo(s)
Barcode scanning (Premium or above plans)
ID verification (Premium or above plans)

All of these can be set on the task level depending on your subscribed Onfleet plan, learn more about them in Completion Requirements.

👍
Ready to roll?
Check out our blog post on how to get your first Onfleet task created if you are still having doubts about using the Onfleet API!