Visit our blog post on the API wrapper project to learn more about our initiatives.
If you have any questions, please reach us by submitting an issue here or contact support@onfleet.com.
- Onfleet Node.js Wrapper
The Onfleet Node.js library provides convenient access to the Onfleet API.
npm install @onfleet/node-onfleet
For TypeScript, install the typed definition:
npm install @types/onfleet__node-onfleet
Kudos to @marcobeltempo for the contribution!
Before using the API wrapper, you will need to obtain an API key from one of your organization's admins.
Creation and integration of API keys are performed through the Onfleet dashboard.
To start utilizing the library, you simply need to create an Onfleet object with your API key:
constonfleetApi=newOnfleet("<your_api_key>");Optionally, you can introduce a customized timeout that is less than the default Onfleet API timeout (70,000 ms) by providing a 2nd parameter:
constonfleetApi=newOnfleet("<your_api_key>",30000);Optionally again, you can introduce an options object for Bottleneck as a 3rd parameter:
constonfleetApi=newOnfleet("<your_api_key>",30000,{LIMITER_RESERVOIR: 10,// Default: 20LIMITER_WAIT_UPON_DEPLETION: 20000,// Default: 10000LIMITER_MAX_CONCURRENT: 5,// Default: 1LIMITER_MIN_TIME: 50,// Default: 50});Once the Onfleet object is created, you can test on the authentication endpoint:
onfleetApi.verifyKey();// Returns a booleannpm test
docker-compose up --build
Rate limiting is enforced by the API with a threshold of 20 requests per second across all your organization's API keys. Learn more about it here.
We have also implemented a limiter on this library to avoid you from unintentionally exceeding your rate limitations and eventually be banned for.
Responses of this library are instances of Response.
Here are the operations available for each entity:
| Entity | GET | POST | PUT | DELETE |
|---|---|---|---|---|
| Admins/Administrators | get() | create(obj) matchMetadata(obj) | update(id, obj) | deleteOne(id) |
| Containers | get(id, 'workers') get(id, 'teams') get(id, 'organizations') | x | insertTask(id, obj) | x |
| Destinations | get(id) | create(obj) matchMetadata(obj) | x | x |
| Hubs | get() | create(obj) | update(id, obj) | x |
| Organization | get() get(id) | x | x | x |
| Recipients | get(id) get(name, 'name') get(phone, 'phone') | create(obj) matchMetadata(obj) | update(id, obj) | x |
| Route Plans | get(id) get(queryParams="") | create(obj) | update(id, obj) addTasksToRoutePlan(id, obj) | deleteOne(id) |
| Tasks | get(query) get(id) get(shortId, 'shortId') | create(obj) clone(id) clone(id, obj) forceComplete(id, obj) batchCreate(obj) batchCreateAsync(obj) getBatch(id) autoAssign(obj) matchMetadata(obj) | update(id, obj) | deleteOne(id) |
| Teams | get() get(id) getWorkerEta(id, obj) getTasks(id) | create(obj) autoDispatch(id, obj) matchMetadata(obj) | update(id, obj) | deleteOne(id) |
| Webhooks | get() | create(obj) | x | deleteOne(id) |
| Workers | get() get(query) get(id) getByLocation(obj) getSchedule(id) getTasks(id) | create(obj) setSchedule(id, obj) matchMetadata(obj) getDeliveryManifest(obj) | update(id, obj) insertTask(id, obj) | deleteOne(id) |
| Custom Fields | get(integration) | create(obj) | update(obj) | delete(obj) |
To get all the documents within an endpoint, this returns a Promise containing an array of results:
get();onfleetApi.workers.get().then((results)=>{/* ... */});onfleetApi.workers.get({ queryParams }).then((results)=>{/* ... */});Optionally you can send a JSON object of query params for some certain endpoints.
Refer back to API documentation for endpoints that support query parameters.
onfleetApi.workers.get({phones: "<phone_number>"}).then((results)=>{/* ... */});onfleetApi.tasks.get({from: "<from_time>",to: "<to_time>"}).then((results)=>{/* ... */});Both
{ 'analytics': 'true' }and{ analytics: true }work as query params since they represent a valid JSON object
To get one of the documents within an endpoint, if the optional paramName is not provided, the library will search by ID. If paramName is provided, it will search by paramName:
get(<parameter>, <paramName> (optional), <queryParam> (optional));paramName can be any of:
idnamephoneshortId
onfleetApi.workers.get("<24_digit_ID>").then((result)=>{/* ... */});onfleetApi.workers.get("<24_digit_ID>",{analytics: true}).then((result)=>{/* ... */});onfleetApi.tasks.get("<shortId>","shortId").then((result)=>{/* ... */});onfleetApi.recipients.get("<phone_number>","phone").then((result)=>{/* ... */});onfleetApi.recipients.get("<recipient_name>","name").then((result)=>{/* ... */});onfleetApi.recipients.get("<recipient_name>","name",{skipPhoneNumberValidation: true}).then((result)=>{/* ... */});onfleetApi.containers.get("<24_digit_ID>","workers").then((result)=>{/* ... */});onfleetApi.containers.get("<24_digit_ID>","teams").then((result)=>{{/* ... */});onfleetApi.containers.get("<24_digit_ID>","organizations").then((result)=>{/* ... */});To obtain information for a specific batch
onfleetAPI.tasks.getBatch("<jobId>","jobId").then((result)=>{/* ... */});To get a driver by location, use the getByLocation function:
getByLocation({ queryParams });constlocationParams={longitude: -122.404,latitude: 37.789,radius: 10000,};onfleetApi.workers.getByLocation(locationParams).then((results)=>{/* ... */});To create a document within an endpoint:
create({ data });constdata={name: "John Driver",phone: "+16173428853",teams: ["<team_ID>","<team_ID> (optional)", ...],vehicle: {type: "CAR",description: "Tesla Model 3",licensePlate: "FKNS9A",color: "purple",},};onfleetApi.workers.create(data);constdata={hubId: "<hubId>",// RequiredworkerId: "<workerId",// RequiredgoogleApiKey: "<google_direction_api_key>",// OptionalstartDate: "<startDate>",// OptionalendDate: "<endDate>"// Optional};onfleetApi.workers.getDeliveryManifest(data);Extended POST requests include clone, forceComplete, batchCreate,batchCreateAsync, autoAssign on the Tasks endpoint; setSchedule on the Workers endpoint; autoDispatch on the Teams endpoint; and matchMetadata on all supported entities. For instance:
onfleetApi.tasks.clone('<24_digit_ID>');onfleetApi.tasks.forceComplete('<24_digit_ID>',{ data });onfleetApi.tasks.batchCreate({ data });onfleetApi.tasks.batchCreateAsync({ data });onfleetApi.tasks.autoAssign({ data });onfleetApi.workers.setSchedule('<24_digit_ID>',{ data });onfleetAPI.workers.getDeliveryManifest({ data });onfleetApi.teams.autoDispatch('<24_digit_ID>',{ data });onfleetApi.<entity_name_pluralized>.matchMetadata({ data });For more details, check our documentation on clone, forceComplete, batchCreate, autoAssign, setSchedule, getDeliveryManifestmatchMetadata, and autoDispatch.
To update a document within an endpoint:
update("<24_digit_ID>",{ data });constnewData={name: "Jack Driver",};onfleetApi.workers.update("<24_digit_ID>",newData);onfleetApi.workers.insertTask("<24_digit_ID>",{ data }).then((result)=>{/* ... */});To delete a document within an endpoint:
deleteOne("<24_digit_ID>");onfleetApi.workers.deleteOne("<24_digit_ID>");Get all the recipients:
onfleetApi.tasks.get({from: "1557936000000",to: "1558022400000"}).then((tasks)=>{for(lettaskoftasks){if(task.recipients[0]!==undefined){// Do something with the recipients}}}).catch((err)=>{/* ... */});
async/awaitcan also be used like this:asyncfunctionfindAllWorkers(){try{letresponse=awaitonfleetApi.workers.get();// Do something with the response}catch(err){/* ... */}}findAllWorkers();
- Inefficient pattern, use metadata instead:
// DONTonfleetApi.workers.get().then((workers)=>{for(letworkerofworkers){for(letmetadataEntryofworker.metadata){if(metadataEntry.name==="hasFreezer"&&metadataEntry.value){// Do something}}}}).catch((err)=>{/* ... */});// DOonfleetApi.workers.matchMetadata([{"name": "hasFreezer","type": "boolean","value": true}]).then((workers)=>{for(letworkerofworkers){// Do something}}).catch((err)=>{/* ... */});
Go to top.