Welcome to Onfleet’s API! This guide walks you through the basic topics you should consider when integrating with Onfleet.
node-onfleet. There are also some Ruby gems and other language libraries out there so you won't need to reinvent the wheel.
Testing your API key
Once you have an API key created, you can test it by hitting our authorization endpoint.
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
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:
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
Taskshould always have one
Destination, which can be created using an address or a set of GPS coordinates. Creating a
Destinationcan be done separately or during task creation.
Recipientfield 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.
Taskis 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:
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.
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.
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.
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):
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:
Onfleet offers the following as proof-of-delivery options:
- Barcode scanning (
Premiumor above plans)
- ID verification (
Premiumor 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!