Introduction

NowGo allows you to create and schedule logistics jobs, and to modify those schedules in real time. The NowGo optimisation engine enhances this capability with best-in-class vehicle routing AI. The NowGo API gives you programmatic access to all this functionality.

Key Concepts

Stops and Jobs

Example Stop

"...deliver the package to 12 Smith St on the afternoon of January 1st..."

The key unit of work in NowGo is the stop.

A Stop represents a requirement to send a driver to a particular location, subject to constraints. NowGo will achieve this goal as efficiently as possible.

A stop might be a pickup, or a delivery, or even a service call. Stops have a single location, a service time, and a window of time when they can be performed. It's also possible to add other requirements, like a specific driver.

Example Job

"...collect the package from the depot before midday of January 1st, and deliver it to 12 Smith St that afternoon..."

The example job above would consist of two stops, in order: collection at the depot, and delivery to 12 Smith St.

A Job groups stops together. Each stop belongs to exactly one job; each job may contain any number of stops. All the stops in a job will be performed by the same driver.

A pickup from one location and delivery to another is a job, consisting of two stops. An assistant collecting money to be deposited, doing so at the bank, and returning to the office is a job with three stops. A service call is also a job, but has only a single stop.

Show me the Jobs API

Shifts

Example Shift

"...Andrew has a shift from 10:00am until 6:00pm on 1 Jan..."

A Shift represents a period of time in which a driver is working in the NowGo system. Shifts tell the system when drivers can be scheduled to complete stops.

You can think of a shift like an itinerary or runsheet, with a starting time and list of work to do. NowGo will work out who should do what, and when.

Stops and Shifts

Stops are assigned to shifts for completion, either automatically by the system or manually by a dispatcher.

Stops can be assigned to at most one shift at a time. A stop not assigned to any shift is said to be unassigned.

Show me the Shifts API

Drivers and Vehicles

Example Driver and Vehicle

"...We've assigned the 9am Melbourne run to Cheryl, in the fridge truck..."

Drivers and Vehicles are the real-world resources used to complete jobs. Shifts can be assigned to a driver and a vehicle.

When a driver is assigned a shift, they can use the driver app to see the stops scheduled in that shift, and complete them. Scheduled stops will also have an ETA. Dispatchers can change the order of planned stops, and the app will show the changes.

Further Concepts

Plans

When optimising vehicle movements, sometimes the world changes very quickly. It is important to maintain a stable view of the world, so that changes can be made in a reasonable way. Plans are used to take a snapshot of the state of a channel, so that the solver or a user can change it without having to deal with concurrent world events.

Plans can capture either the full state of a channel in a given window of time, or a view of specific jobs and channels. This allows plans to be created with fine-grained contents, allowing a single shift to be optimised without dealing with concurrent effects.

Plans can also be merged back into the world. This will update the world with the changes made in the plan. If stops have been completed in the world since being added to the plan, they will not be reassigned to shifts.

Sometimes, a plan cannot be merged if the world has changed too much since the plan was created. For example, the plan may have assigned stops to a shift that has been cancelled. In these cases, the plan is conflicting and cannot normally be merged.

Show me the Plans API

Solves

When working inside a Plan, you can instruct NowGo to apply its optimisation engine to the contents of that plan. Depending on the preferences chosen, this will change the plan in different ways. The specifics of available solves are detailed in the documentation for the solve creation endpoint.

When you start a solve, the response contains an object documenting the current state of that solve. Solves complete asynchronously, so it is necessary to poll the object if you wish to wait for the solve to finish.

Show me the Solves API

Capacities

Example Capacity

"...large vans have a maximum cargo capacity of 6 m^3..."

"...carrying that consignment will take 2 m^3 of space..."

In the above example, the capacity is the cargo capacity of the vehicle. The van has a capacity limit of 6. The consignment has a capacity cost of 2.

When optimizing logistics decisions, it is often necessary to consider capacity limits. These can be quantities that rise and fall below a certain threshold, or quantities that only increase.

An example of a rising and falling capacity is the weight carried by a vehicle. When the vehicle takes on cargo, the carried weight increases. When the vehicle offloads cargo, the carried weight decreases again.

An example of a rising capacity is a limit on the number of jobs a driver can perform in a day. As the driver completes jobs, the number rises. There's no way that the number of jobs performed can decrease.

NowGo treats capacities as first-class objects. Capacities have ids, and names. Stops can have capacity costs, which indicate that the stop will use a certain quantity of the relevant capacity. Vehicle types can have capacity quantities, which indicate that a limited quantity of the capacity is available. If no capacity quantity is set, the capacity is assumed to be infinite.

Capacity costs can be negative. When completing a stop that adds weight to a vehicle, for instance, the stop has a weight cost of 4. The next stop in the job that delivers that cargo would have a weight cost of -4.

If the capacity you're representing is a weight, you can configure capacities to display in specific units on the app and dashboard. Internally, these capacities use a quantity in milligrams that is converted for display.

Show me the Capacities API

Attributes

Example Attributes

Boolean: "...is the vehicle refrigerated?..."

Numeric: "...how much weight can the tailgate lift? ..."

In addition to capacity limits, vehicles and vehicle types can also have attribute values. Whereas a capacity limit describes a finite resource which may be exhausted (e.g. by loading a vehicle until its weight capacity is reached), an attribute value is constant (a refrigeration truck remains refrigerated regardless of the load).

Show me the Attributes API

Example values for Attributes

Boolean: "...that job's vehicle is refrigerated..."

Numeric: "...and has a 50kg tailgate ..."

In the above example, the shift's vehicle is refrigerated and hence suitable for carrying frozen goods, and has a tailgate that can lift 50kg.

Each vehicle or vehicle type may define a value for a given Attribute. For example, a specific vehicle type may be refrigerated and have a tailgate with a load capacity of 50kg. A vehicle type must have at most one value per attribute. For example, a vehicle type cannot both have a 50kg tailgate and a 100kg tailgate.

Attributes are first-class values and can be retrieved via attribute endpoints. Attribute values are not first-class objects. Attribute values are created implicitly when creating vehicles or vehicle types (via the 'attribute_values' field), and are returned as part of the vehicle or vehicle type JSON object.

Show me the Vehicle Types API that includes attribute values Show me the Vehicles API that includes attribute values

Example Attribute requirements

Boolean: "...since this job transports frozen goods, a refrigerated vehicle is required..."

Numeric: "...and because heavy goods are to be loaded, it must have a tailgate able to lift at least 40kg ..."

In the above example, any vehicle to be assigned to the job must be refrigerated and must have a tailgate capable of lifting at least 4kg. Because the vehicle type described in Example Attributes meets these requirements, it can be considered for this job.

Vehicle and vehicle type attribute values are checked on a per-job basis against a job's vehicle requirements. A job can have zero or more requirements, each of which will be a condition that will be tested for any vehicle or vehicle type candidates for that job. Only vehicles or vehicle types meeting all of a job's requirements will be considered for that job. Vehicle requirements are not first-class objects and are created and queried as part of their parent job.

Requirement types: - Boolean requirement - test whether a vehicle or vehicle type's value for that attribute matches the requirement's value. As an example, a vehicle with an Attribute Value of 'true' for the Attribute 'is-refrigerated' can carry out jobs with a requirement of having 'is-refrigerated' be 'true' - Numerical requirements - test whether a vehicle or vehicle type's value for that attribute is (less than or equal to max, greater than or equal to min, between min and max) to the requirement's value. As an example, a vehicle with an Attribute Value of 5 will not be considered for a job which has a less-than requirement for that Attribute of 4, since 5 is greater than 4.

Show me the Jobs API that includes requirements

Vehicle Types

Example Vehicle Type

"...that shift's vehicle is a small truck..."

NowGo models groups of vehicles via vehicle types, such as defining a 'motorbike' vehicle type to group all motorbikes. Vehicle types can be used to constrain which vehicles are chosen for a job; for example, the 'motorbike' vehicle type can be used to indicate that motorbikes should be preferred to perform deliveries in the CBD. Vehicle types also allow the definition of common attributes and capacity limits that apply to a group of vehicles.

Vehicle types are first-class objects and can be referred to by id or by ext_ref.

Vehicle types can be used for preferences, and for requirements. A positive preference means that a vehicle type should perform a particular job if possible. A negative preference means that a particular vehicle type should not perform a particular job, unless doing so would reduce completion rates. Vehicle type requirements mean that a particular vehicle type must perform the given job.

Vehicle types can have capacity limits associated with them. For example, large vans may be able to carry a certain volume of cargo. Vehicles can also have attribute values associated with them. For example, given an attribute 'is-refrigerated', a vehicle may have the value 'true' indicating that it is a refrigerated vehicle.

Vehicles

Example Vehicle Type

"...that shift's vehicle is one of our refrigerated trucks, 'RefrigeratedTruck3'."

Vehicles are individual instances of a vehicle type. For example, a generic refrigerated truck may be represented by a vehicle type 'refrigerated-truck' with an attribute 'is-refrigerated' that is set to 'true'. A vehicle with the 'refrigerated-truck' vehicle type represents a concrete instance of this abstract vehicle type. Any number of vehicles can have the same vehicle type. All these vehicles inherit the vehicle type's attribute values and capacity limits. In the example of the 'refrigerated-truck' vehicle type, any vehicles using it will have an attribute value 'is-refrigerated' set to 'true'.

In addition to inheriting attribute values and capacity limits from the vehicle type, vehicles can also define additional attribute values and capacity limits which apply only to that vehicle. If an attribute value or capacity limit is defined for both the vehicle type and the vehicle, then the vehicle's value will be used instead of the parent's value. As an example, if the vehicle's vehicle type has an attribute value 'refrigerated' that is set to 'true' and the vehicle itself also has the 'refrigerated' attribute value, but set to 'false', then the vehicle's 'refrigerated' attribute will be 'false'.

Vehicles can also 'delete' their parent type's attribute value or capacity limit by omitting the 'value' or 'limit' field. This means the vehicle will not inherit its parent type's attribute value or capacity limit. For example, deleting the 'cargo-volume' capacity limit on a vehicle means the vehicle will not have a 'cargo-volume' capacity limit even if its vehicle type defines one.

Show me the Vehicles API

Vehicles are first-class objects and can be referred to by id or by ext_ref. Just as it is possible to filter vehicle types using vehicle type preferences, vehicles can be filtered using vehicle preferences. Job attribute requirements are used to filter both vehicles and vehicle types.

Locations

Example location

"This particular location is a depot."

Locations are addresses or coordinates associated with a real-world place. The location object can be used to create something like an address book where destinations can be recorded along with other useful information.

Location objects can be used to create stops and pre-fill the address and coordinate fields by referring to them using an id or external reference. For details on this see the stops section.

Show me the Locations API

Location Groups

Example Location Group

"Whenever you do work at the port, always allow 30 minutes for parking."

Location Groups are used to indicate that multiple stops are performed at a similar location. For example, a location group could be created to mark all stops at a particular port.

Location Groups can have time costs associated with them, which are applied only once whenever multiple stops in the group are performed together. For example, the port location group mentioned above may have a time cost of thirty minutes, to represent the waiting time to enter the port. This cost is only incurred once each time multiple stops at the port are performed.

The system will consider the benefits of performing stops with a location group time cost at the same time when optimizing. Location group time costs are also reflected in ETA and travel calculations.

Show me the Location Groups API

Annotations

Example Annotation

"... the driver commented on this job, saying that the package was left at the door..."

"... the driver noted that this job included a 30 minute wait time..."

In the above examples, these two statements can be expressed as two annotations associated with the job. The annotations could be called Driver Comments and Waiting Time. Annotations provide a way for drivers to input information about specific jobs as they are performed in the field.

Annotations are driver editable attachments to job objects.

An annotation consists of two parts. The first is the annotation type which specifies the name of this field, such as "Notes", "Waiting Time", "Service fee", etc. Annotation types are first-class objects and can be referred to by id or by ext_ref.

The second object is the annotation value which specifies the value of annotation for a particular job. This is also a first-class object, indexed by job id and annotation type id.

Show me the Annotations API.

Stop dependencies

Example Stop Dependencies

"... the line-haul driver will drop off the container at the warehouse, then the local drivers can pick up these packages ..."

"... these two drivers will meet at the designated location to transfer the package ..."

Stop dependencies are the mechanism that NowGo uses to represent the requirement that one stop must only be completed after (or perhaps at the same time as) a stop in another job. When representing a stop dependency, there is an explicit "dependent" stop, and "precursor" stop, even if these stops are meant to occur at the same time. Stop dependencies are attached to the dependent stop, and stop dependencies can only be modified by making changes to the dependent stop.

A common use case for stop dependencies is when two drivers are involved in the delivery of the same consignment. Here there would be an implicit relationship between the stops in these jobs, whereby the delivery of the first job must come before the pickup of the second.

In some instances, two stops must occur at the same time, such as in a transfer or an assisted job. In these instances, it is possible to flag a stop dependency as having the additional requirement that both the precursor stop and the dependent stop must have the same starting time.

Consignments

"... my goods are travelling as one consignment between Sydney and Melbourne ..."

A Consignment represents one or more physical items in the system that are generally intended to travel as a group with the same purpose, and it includes contextual information about the movement.

Articles

"... there are 4 articles on this consignment ..."

An Article directly represents a trackable physical object. One or more of these make up a Consignment.

The item count is used in the case that not all real-world objects have a trackable ID. In this case one trackable object, the article, can be used to represent more than one physical item.

Workflow completions

"... a workflow completion was created when the driver finished the delivery workflow ..."

"... a workflow completion was created by the integration when the consignment was scheduled in a run ..."

"... a workflow completion completed 3 stops related to the target consignment ..."

A workflow completion represents an event in NowGo. They are created when a driver completes a workflow on the NowGo app, or directly through the API.

The creation of a workflow completion can trigger a number of additional interactions in NowGo, including:

1. Creating stop completions.
2. Creating and updating consumer tracking sessions.
3. Triggering communications with consumers.
4. Updating a driver's onboard register.

Workflow completions and consignments

Articles that a workflow interacts with are referred to as the subject articles of a workflow completion.

Interactions with target articles can trigger events relating to the target article's consignments such as updates to consumer tracking sessions and stop completions.

Workflow completions and drivers

When a driver completes a workflow in the NowGo app, this will create a workflow completion that contains driver-related information:

1. An id or external reference for the driver that completed the workflow.
2. A device id for the device used to complete the workflow.
3. A local device id for the workflow completion.
4. An id for the shift the driver completed the workflow in.
5. Any attachments that were created during the workflow, which may include proof of delivery photos and signatures.
6. The latitude and longitude of where the workflow completion occurred, where available.

The driver's onboard register may also update if the workflow completion has subject consignments and articles.

Workflow completions and stops

A workflow completion can contain stop completions. When a workflow completion is created with stop completions objects they are created in NowGo, updating the completion status of the relevant stops.

Actions

"... when a driver scans this article, they need to complete the "onboard" action ..."

"... a new custom action has been added to the app ..."

"... the deliver action was unsuccessful with outcome deliver_failure_no_atl ..."

An action represents an operation associated with an article and by extension, consignments, stops and jobs.

When a driver scans an article in the NowGo app, they are presented with a list of actions. If no custom actions are set, a default set of actions are shown which are:

• Pickup
• Dropoff
• Onboard
• Offboard
• Sort

Custom actions can be set to override the behaviour of a default action or to create a completely new flow in the app (although this requires Thunder configuration).

Actions will have an associated outcome once completed. Outcomes are either successful or unsuccessful and can contain some context around why the outcome happened.

API Basics

The NowGo API is provided via HTTP (over SSL). Most programming languages will have an HTTP client library that can be used to access the NowGo API.

Some examples given below are cURL statements. You can run them on a command line to try out different API requests.

Beside each endpoint is a descriptor such as GET /drivers or POST /shifts. The first word indicates the type of HTTP request to send to that endpoint (e.g. GET for accessing resources, and POST for creating them). The remainder is a partial URI, which should be prefixed with https://api.nowgo.io/v0/ to get the full URL for that endpoint.

E.g. to access an endpoint described in the documentation as GET /drivers, you would send a GET request to https://api.nowgo.io/v0/drivers.

Curly braces indicate placeholders for more specific values (path parameters).

E.g. the endpoint GET /shifts/{id} views details a shift with a given ID. To access details for the shift with ID 123, you would send a GET request to https://api.nowgo.io/v0/shifts/123.

Security and authentication

The API is accessed over SSL only. You must have an API token issued by Premonition for your organisation's NowGo account.

Requests are authenticated using basic authentication, with the API token as the password and the username left blank.

For example, if your API token is e3b0c442, you might run:

curl -u :e3b0c442 https://api.nowgo.io/v0/drivers

Obtaining API tokens

API tokens are issued on request by Premonition. Speak to your Premonition contact for more details.

Request format

The NowGo API is a JSON API. You must supply a Content-Type: application/json header in POST requests. You must set an Accept: application/json header on all requests.

Some errors (e.g. bad URL) may produce a text/plain response.

Response format

When you create or update a resource, NowGo returns a JSON representation of the (updated) resource in the response body.

Errors

The NowGo API uses HTTP response codes to specify the success or failure of a request. Following convention, 2xx codes indicate success, 4xx indicate an error originating with the request, and 5xx indicate a server-side error. In general, 4xx errors are returned with a JSON object with a short message indicating what was wrong, and if possible, which parameter and value failed.

Rate Limiting

To ensure that we can maintain a high level of availability, limits are in place for the rate at which we service requests to our API. The limits we enforce may vary over time in response to changing conditions.

If an API request exceeds rate limits, a 429 Too Many Requests response will be returned. This response includes a Retry-After header with the number of seconds a client should wait before attempting another request.

Rate limits are currently enforced per org, and read-only requests are considered separately from requests that make changes.

Timestamps and timezones

An ISO8601 timestamp in UTC

2000-01-01T00:00:00.0000Z

When the NowGo API needs to send or receive timestamps, we use ISO 8601 unless otherwise specified. Timestamps we produce will always be in UTC with an explicit time designator (Z or +00:00).

If data includes a specific time zone, it will be included as a separate field. We use the IANA time zone database as our source for time zones.

If you're displaying timestamps to users, you should normalise them to a human-readable format, including changing the time zone to what your users might expect.

If you're loading timestamps from NowGo to another system, you should transform them to the format and time zone that the system expects.

Pagination

Example request

curl -u :{auth_token} 'https://api.nowgo.io/v0/channels'

Example response

The request has returned the first page of data, and a next_page_token that can be used to fetch subsequent pages.

{
  "data": [
    {
      "id": "193",
      "name": "West"
    }
  ],
  "next_page_token": "7f42d53f"
}

Request for next page

curl -u :{auth_token} 'https://api.nowgo.io/v0/channels?page_token=7f42d53f'

Response for next page

The request hasn't returned a next_page_token, so this is the final page of data.

{
  "data": [
    {
      "id": "254",
      "name": "South"
    }
  ],
  "next_page_token": null
}

Sometimes, an endpoint might need to return multiple objects in a list. The NowGo API paginates data to keep query time and response sizes manageable.

Our standard pagination mechanism is token-based. Requests that return lists of objects might also have a next_page_token. If a response has a next_page_token, there might be more data to fetch - repeat the request with the page_token query parameter set to the next_page_token you just received.

If a response has next_page_token = null, then there's no more data to fetch.

Each next_page_token is intended to be opaque to the caller. The implementation and contents may vary per-endpoint and over time. Tokens should be used soon after they are fetched, and they aren't guaranteed to be ordered.

You can also pass page_size as a parameter. If you don't, we'll use a default size. If you request a page size that's larger than we support, we'll return as large a page as we can.

Pagination - cursor-based (legacy)

This method of pagination is being phased out. See the above Pagination section

Example request

curl -u :{auth_token} 'https://api.nowgo.io/v0/stops/bad-geocodes?limit=3'

Example response (default cursor)

In the below example, we made a request with a limit of three and without specifying a cursor position. Three results were found, and the has_more parameter was true indicating that more results were found. If no cursor position is specified using starting_after or ending_before, the most recently created results will be displayed in ascending order with the most recent at the end of the list. We can retrieve more of the list by specifying ending_before = 193

{
    "data": [
        {
          "id": "193",
          "location": {}
        },
        {
          "id": "194",
          "location": {}
        },
        {
          "id": "195",
          "location": {}
        }
    ],
    "has_more": true
}

Example request (looking backwards)

curl -u :{auth_token} 'https://api.nowgo.io/v0/stops/bad-geocodes?limit=3&ending_before=193'

Example response

In this example, we made a request with a limit of three and with explicitly specifying a cursor position using ending_before to look backwards through the entire collection of stops. Three results were found, and the has_more parameter was false indicating that no more results were found ending before the start of this list.

{
    "data": [
        {
          "id": "190",
          "location": {}
        },
        {
          "id": "191",
          "location": {}
        },
        {
          "id": "192",
          "location": {}
        }
    ],
    "has_more": false
}

Example request (looking forwards)

curl -u :{auth_token} 'https://api.nowgo.io/v0/stops/bad-geocodes?limit=2&starting_after=192'

Example response

In this example, we made a request with a limit of two and with explicitly specifying a cursor position using starting_after to look forwards through the entire collection of stops. We get a page starting after our previous request by specifying the last id in that page. Two results were found, and the has_more parameter was true indicating that there are more results starting after the end of this list.

{
    "data": [
        {
          "id": "193",
          "location": {}
        },
        {
          "id": "194",
          "location": {}
        }
    ],
    "has_more": true
}

The NowGo API separates the results of endpoints that provide a list of things (such as listing invalid stop locations) into pages. These pages can be navigated and specified using the limit, starting_after and ending_before query parameters. The position of the current page is described using a cursor specified using the starting_after and ending_before parameters.

Specifying the limit parameter will set the number of items in a page received in each request. Pages can be navigated by specifying the starting_after and ending_before parameters. Both take an existing object ID value in either a numeric or UUID format depending on the object.

The ending_before parameter returns objects created before the named object. The starting_after parameter returns objects created after the named object. If both parameters are provided, only ending_before is used. If neither parameter is provided, the default cursor is used. In many endpoints, the default cursor is the equivalent of the back page of a book, containing the most recently created resources. In this case, we can view the entire list of resources by starting at the default last page and reading backwards by subsequently setting the ending_before parameter to the id at the head of each list.

The input parameters are: - limit: An integer between 1 and 100, specifying the maximum number of items returned by each request. The default value is 10.

The JSON message returned will contain the following entries:

• data: A list containing the requested results.
• has_more: A boolean specifying if there are more results to be fetched.

Pagination - page-based (legacy)

This method of pagination is being phased out. See the above Pagination section

Endpoints that provide a list of things (e.g. "List all drivers") provide a default of 10 results per page. To see subsequent pages, set the page parameter in the request URL parameters. Pages are numbered starting at 1.

Example request

curl -u :{auth_token} 'https://api.nowgo.io/v0/drivers?page=2&perPage=1'

Example response

{
    "page": 2,
    "totalPages": 11,
    "totalResults": 11,
    "results": [
        {
          "id": 6,
          "name": "Phillip Jones",
          "email": "phillip@jones.example.com",
          "enabled": true
        }
    ]
}

You may also set the perPage parameter in the request URL parameters, which alters the number of results shown per page. Most endpoints will enforce limits on the number of items returned per page.

The JSON message returned will contain the following entries:

• page: The page number requested. (Defaults to 1 if none given.)
• total_pages: The number of available pages of results (i.e. the highest page that can be sensibly requested).
• total_results: The total number of results available.
• results: An array containing the requested results.

Updating resources

Example driver object

{
  "id": "15114",
  "ext_ref": "syd01D",
  "name": "John Smith",
  "email": "john.smith@example.com",
  "color": "red"
}

Partial update with PATCH

$ curl https://api.nowgo.io/drivers/15114 \
    -X PATCH \
    -u :{auth_token} \
    -d

{
  "name": "John Smyth",
  "email": null
}

Resulting object

{
  "id": "15114",
  "ext_ref": "syd01D",
  "name": "John Smyth",
  "color": "red"
}

This example request contained a name field, so the name of the driver was updated. The email field in the request was set to null, so the driver's email was cleared. The color field was not in the request, and so was not changed in the object.

Where possible, updates to resources are performed using a PATCH command. This is to help ensure that existing implementations remain compatible with future versions of the API. PATCH allows partial updates to a resource by selectively including or omitting values in the request body.

The NowGo PATCH implementation follows RFC7396 Json Merge Patch.

External references

Successful request

> POST /stops/
> { "ext_ref": "only-one" }

< 200 Ok

Conflicting request

> POST /stops/
> { "ext_ref": "only-one" }

< 200 Ok

> POST /stops/
> { "ext_ref": "only-one" }

< 409 Conflict

NowGo uses its own internal ID numbers for most resources. To simplify integration with external systems, NowGo allows some types of resources to include an external reference. These can be used later to look up those resources.

External references:

• Must be unique - no two resources of the same type can have the same external reference.
• Are written once and cannot be changed, expect in special cases.
• Cannot be reused even if the resource is deleted, unless otherwise specified.

External references are formed from a subset of url safe characters - valid characters are:

• uppercase and lowercase letters [A-Za-z]
• decimal digits [0-9]
• hyphen -
• period .
• underscore _
• tilde ~

External references can be up to 64 characters in length.

When the external reference provided for a created object conflicts with an already existing external reference, a 409 Conflict response containing the conflicting object will be returned.

Accessing resources using external references

Example GET request using an external reference

# curl https://api.nowgo.io/v0/jobs/ext-ref/job-123 \
  -u :{auth_token}

Example PATCH request using an external reference

# curl https://api.nowgo.io/v0/shifts/ext-ref/shift-99 \
  -X PATCH \
  -u :{auth_token} \
  -d {body}

Resources can be retrieved or modified using their external references, in addition to accessing them using their ID. When accessing a created resource in this way, the external reference should be prefixed with /ext-ref/, as outlined in the examples.

Entity versions

Example object

{
  "id": "123545gDVE4",
  "version": 7
}

Failing request

> PATCH /stops/123545gDVE4
> Nowgo-If-Match: 6

< 412 Precondition Failed

Successful request

> PATCH /stops/123545gDVE4
> Nowgo-If-Match: 7

< 200 Ok

Sometimes when returning a response, the NowGo API will include a version number for an object. This can be used to safely make changes to an object and avoid the lost update problem.

If you include the header Nowgo-If-Match in a request to update an entity, and the current version of the object does not match the version passed in the header, the API will respond with 412 Precondition Failed.

Clients should never include the version field in the body of an object in a request. If it is included, it will be silently ignored.

Shifts

The shift object

You can read more about shifts in Key Concepts.

Example Object

{
  "id": "1e0e27a4-0956-4fbc-b594-d82867a5ac7e",
  "ext_ref": "2017VR882D",
  "channel_id": "4414",
  "time_window_start": "2017-02-13T20:46:30Z",
  "time_window_end": "2017-02-13T20:50:30Z",
  "driver_id": "2",
  "driver": {},
  "complete": [
    {
      "stop_id": "43b6fb8a-854c-4a46-8df5-b1f1194ab009",
      "most_recent_completion": "2017-01-01T14:00:32Z",
      "most_recent_is_success": true,
      "completion_ids": [
        "827492"
      ]
    }
  ],
  "planned_events": [
    {
      "stop_id": "43b6fb8a-854c-4a46-8df5-b1f1194ab010",
      "ext_ref": "stop123",
      "expected_start": "2024-01-01T14:00:32Z",
      "locked": false,
      "locked_by_driver": false
    },
    {
      "break_id": "43b6fb8a-854c-4a46-8df5-b1f1194ab010",
      "ext_ref": "break123",
      "expected_start": "2024-01-01T14:00:32Z",
      "locked": false,
      "locked_by_driver": false
    },
  ],
  "jobs": [{}],
  "vehicle_type_id": "44131",
  "vehicle_type_ext_ref": "small-truck",
  "vehicle_id": "157",
  "vehicle_ext_ref": "truck-B7V-A6M",
  "type": null,
  "data": null,
  "start_location_latitude": -33.9181216,
  "start_location_longitude": 151.1470805,
  "start_location_address": "466 Illawarra Rd, Dulwich Hill NSW 2203",
  "end_location_latitude": -33.873828,
  "end_location_longitude": 151.1920326,
  "end_location_address": "Bank St & Pyrmont Bridge Road, Sydney NSW 2009",
  "allow_driver_edit_stop": true,
  "frozen": true,
  "name": "twilight",
  "allow_driver_self_assign": true
}

Create a shift

Example Request

# curl https://api.nowgo.io/v0/shifts \
  -u :{auth_token} \
  -d {body}

Example Request (in plan)

# curl https://api.nowgo.io/v0/plans/{plan_id}/shifts \
  -u :{auth_token} \
  -d {body}

Example Body

{
  "ext_ref": "2017VR882D",
  "channel_ext_ref": "61",
  "time_window_start": "2016-04-01T13:15:00+10:00",
  "time_window_end": "2016-04-01T17:00:00+10:00",
  "driver_ext_ref": "959",
  "stop_ids": [
    "929",
    "142",
    "991"
  ],
  "vehicle_type_ext_ref": "small-van",
  "vehicle_id": "124",
  "type": "afternoon-run",
  "data": {
    "depot_warning": "All drivers must wear safety gear on site."
  },
  "start_location_latitude": -33.9181216,
  "start_location_longitude": 151.1470805,
  "start_location_address": "466 Illawarra Rd, Dulwich Hill NSW 2203",
  "end_location_latitude": -33.873828,
  "end_location_longitude": 151.1920326,
  "end_location_address": "Bank St & Pyrmont Bridge Road, Sydney NSW 2009",
  "allow_driver_edit_stop": true,
  "frozen": false,
  "name": "twilight",
  "allow_driver_self_assign": true
}

Response

Returns a shift object if creation was successful. Returns an error if something goes wrong.

Retrieve a shift

Example Request (using id)

# curl https://api.nowgo.io/v0/shifts/{id} \
  -u :{auth_token}

Example Request (using external reference)

# curl https://api.nowgo.io/v0/shifts/ext-ref/{ext_ref} \
  -u :{auth_token}

Shifts can be retrieved using their id or external reference.

Response

Returns a shift object if the given identifier is valid, and returns an error otherwise.

Update a shift

Example Request (using id)

# curl https://api.nowgo.io/v0/shifts/{id} \
  -X PATCH \
  -u :{auth_token} \
  -d {body}

Example Request (using external reference)

# curl https://api.nowgo.io/v0/shifts/ext-ref/{ext_ref} \
  -X PATCH \
  -u :{auth_token} \
  -d {body}

Example Body

{
  "time_window_start": "2016-04-01T13:15:00+10:00",
  "time_window_end": "2016-04-01T17:00:00+10:00",
  "stop_ids": [
    "929",
    "142",
    "991"
  ],
  "vehicle_type_ext_ref": "large-van",
  "vehicle_ext_ref": "van-B51-M42",
  "type": null,
  "data": {
    "depot_warning": "All drivers must wear safety gear on site."
  },
  "start_location_latitude": -33.9181216,
  "start_location_longitude": 151.1470805,
  "start_location_address": "466 Illawarra Rd, Dulwich Hill NSW 2203",
  "end_location_latitude": -33.873828,
  "end_location_longitude": 151.1920326,
  "end_location_address": "Bank St & Pyrmont Bridge Road, Sydney NSW 2009",
  "allow_driver_edit_stop": true,
  "frozen": true,
  "name": "twilight",
  "allow_driver_self_assign": true
}

Applies an update to the given shift. Any parameters set to null in the request will be cleared if valid. Any parameters not passed in the request will remain unchanged. You can read more about the semantics of PATCH in updating resources.

Response

Returns a shift object if the update was successful. Returns an error if something goes wrong.

Update the stops in a shift

The behavior of this request varies depending on the request method used. If the method is PUT, the shift's planned stops will be replaced with the given list. If POST, the given stops will be appended to the shift's planned stops.

Example request (using id)

# curl https://api.nowgo.io/v0/shifts/{id}/stops \
  -X PUT \
  -u :{auth_token} \
  -d {body}

Example request (using external reference)

# curl https://api.nowgo.io/v0/shifts/ext-ref/{ext_ref}/stops \
  -X PUT \
  -u :{auth_token} \
  -d {body}

Example body

[
  "334145",
  "449274"
]

Unassign the stops in a shift

Example request (using id)

# curl https://api.nowgo.io/v0/shifts/{shift_id}/stops/unassign \
  -u :{auth_token} \
  -d {body}

Example request (using external reference)

# curl https://api.nowgo.io/v0/shifts/ext-ref/{shift_ext_ref}/stops/unassign \
  -u :{auth_token} \
  -d {body}

Example body

[
  {
    "id": "1e0e27a4-0956-4fbc-b594-d82867a5ac7e"
  },
  {
    "ext_ref": "other_stop"
  }
]

Stops which have been planned in a shift can be unassigned using this endpoint by supplying a list of stop ids or external references.

Response

Returns a list of ids of stops which were unassigned from this shift. This request will fail if any supplied ids or external references are invalid or not assigned to this shift.

Delete a shift

Example request (using id)

# curl https://api.nowgo.io/v0/shifts/{shift_id} \
  -u :{auth_token} \
  -X DELETE

Example request (using external reference)

# curl https://api.nowgo.io/v0/shifts/ext-ref/{shift_ext_ref} \
  -u :{auth_token} \
  -X DELETE

Deletes a shift. Any stops assigned to the shift will become unassigned.

When a shift is deleted via the API, the shift's external reference is cleared and can be used again elsewhere.

Jobs

The job object

You can read more about jobs in Key Concepts. Vehicle requirements are described in more detail in Further Concepts. Annotations are described in more detail in the annotations section. Priorities are described in more detail in the priorities section.

Example Response

{
  "id": "5f125674-f403-4fe4-803d-f1dd56ce8267",
  "ext_ref": "2017-33232",
  "channel_id": "4414",
  "stops": [{}],
  "priority_weighting": 1.1,
  "priority_id": "1",
  "priority_ext_ref": "high",
  "allowed_driver_ids": [
    "434"
  ],
  "allowed_shifts": [
    {
      "id": "22313"
    },
    {
      "ext_ref": "shift1"
    }
  ],
  "allowed_vehicle_types": [
    {
      "vehicle_type_id": "414"
    },
    {
      "vehicle_type_ext_ref": "red_bikes"
    },
    {
      "vehicle_type_id": "416",
      "vehicle_type_ext_ref": "blue_cars"
    }
  ],
  "vehicle_type_preferences": [
    {
      "vehicle_type_id": "414",
      "preference": "positive"
    },
    {
      "vehicle_type_ext_ref": "blue_cars",
      "preference": "negative"
    }
  ],
  "allowed_vehicles": [
    {
      "vehicle_id": "91"
    },
    {
      "vehicle_ext_ref": "car_14"
    },
    {
      "vehicle_id": "93",
      "vehicle_ext_ref": "car_15"
    }
  ],
  "vehicle_preferences": [
    {
      "vehicle_id": "92",
      "preference": "positive"
    },
    {
      "vehicle_ext_ref": "car_14",
      "preference": "negative"
    }
  ],
  "vehicle_requirements": [
    {
      "id": "43",
      "ext_ref": "refrigerated",
      "pass_if_absent": true,
      "expected": false
    },
    {
      "id": "2854",
      "pass_if_absent": false,
      "min": 12
    },
    {
      "id": "9464",
      "pass_if_absent": true,
      "max": 100
    },
    {
      "id": "129",
      "pass_if_absent": true,
      "min": 10,
      "max": 20
    }
  ],
  "active_outbound_delegation_request": {
    "delegated_channel": {
      "id": "123",
      "ext_ref": null,
      "display_name": "Acme Third Party P/L"
    },
    "reason": "Not enough capacity",
    "accepted": true
  },
  "type": null,
  "data": null
}

Create a job

Example Request

# curl https://api.nowgo.io/v0/jobs \
  -u :{auth_token} \
  -d {body}

Example Request (in plan)

# curl https://api.nowgo.io/v0/plans/{plan_id}/jobs \
  -u :{auth_token} \
  -d {body}

Example Body

{
  "ext_ref": "2017-33232",
  "channel_ext_ref": "61",
  "stops": [
    {
      "ext_ref": "2017-33232-1",
      "time_window_start": "2016-04-01T13:20:00+10:00",
      "time_window_end": "2016-04-01T14:00:00+10:00",
      "service_time": 180,
      "location": {
        "address": "483 George St, Sydney NSW 2000",
        "latitude": -33.8727137,
        "longitude": 151.2059311
      },
      "type": "pickup"
    },
    {
      "ext_ref": "2017-33232-2",
      "time_window_start": "2016-04-01T13:20:00+10:00",
      "time_window_end": "2016-04-01T14:00:00+10:00",
      "service_time": 180,
      "location": {
        "id": "141",
        "ext_ref": "warehouse_21"
      },
      "type": "dropoff"
    }
  ],
  "priority_weighting": 1.1,
  "priority_ext_ref": "high",
  "allowed_driver_ids": [
    "434"
  ],
  "allowed_shifts": [
    {
      "ext_ref": "shift1"
    }
  ],
  "allowed_vehicle_types": [
    {
      "vehicle_type_id": "414"
    },
    {
      "vehicle_type_ext_ref": "red_bikes"
    },
    {
      "vehicle_type_id": "414",
      "vehicle_type_ext_ref": "blue_cars"
    }
  ],
  "vehicle_type_preferences": [
    {
      "vehicle_type_id": "414",
      "preference": "positive"
    },
    {
      "vehicle_type_ext_ref": "blue_cars",
      "preference": "negative"
    }
  ],
  "allowed_vehicles": [
    {
      "vehicle_id": "91"
    },
    {
      "vehicle_ext_ref": "car_14"
    },
    {
      "vehicle_id": "93",
      "vehicle_ext_ref": "car_15"
    }
  ],
  "vehicle_preferences": [
    {
      "vehicle_id": "92",
      "preference": "positive"
    },
    {
      "vehicle_ext_ref": "car_14",
      "preference": "negative"
    }
  ],
  "vehicle_requirements": [
    {
      "id": "43",
      "ext_ref": "refrigerated",
      "pass_if_absent": true,
      "expected": false
    },
    {
      "id": "9464",
      "pass_if_absent": true,
      "max": 100
    }
  ],
  "type": "afternoon-pickup",
  "data": {
    "depot-safety": "Drivers to wear high-vis on site at all times."
  },
  "start_comms_sessions": [
    {
      "comms_plan_id": "123",
    },
    {
      "comms_plan_ext_ref": "standard-comms",
    }
  ],
  "initial_assignment": {
    "shift_id": "11a0a9d5-7e6c-484d-b273-95a87c0b49f3",
    "shift_ext_ref": "shift-123"
  }
}

This operation is available in plans.

Response

Returns a job object if creation was successful. Returns an error if something goes wrong.

Retrieve a job

Example Request (using job id)

# curl https://api.nowgo.io/v0/jobs/{job_id} \
  -u :{auth_token}

Example Request (using job external reference)

# curl https://api.nowgo.io/v0/jobs/ext-ref/{job_ext_ref} \
  -u :{auth_token}

Example Request (using stop id)

# curl https://api.nowgo.io/v0/stops/{stop_id}/jobs \
  -u :{auth_token}

Example Request (using stop external reference)

# curl https://api.nowgo.io/v0/stops/ext-ref/{stop_ext_ref}/jobs \
  -u :{auth_token}

Example Request (in plan using job id)

# curl https://api.nowgo.io/v0/plans/{plan_id}/jobs/{job_id} \
  -u :{auth_token}

Example Request (in plan using job external reference)

# curl https://api.nowgo.io/v0/plans/{plan_id}/jobs/ext-ref/{job_ext_ref} \
  -u :{auth_token}

Job objects can be retrieved using a job id or job external reference. They can also be retrieved using a stop id or stop external reference.

This operation is available in plans.

Response

Returns a job if the given identifier is valid, and returns an error otherwise.

Update a job

Example Request (using job id)

# curl https://api.nowgo.io/v0/jobs/{job_id} \
  -X PATCH \
  -u :{auth_token} \
  -d {body}

Example Request (using external reference)

# curl https://api.nowgo.io/v0/jobs/ext-ref/{ext_ref} \
  -X PATCH \
  -u :{auth_token} \
  -d {body}

Example Request (in plan using id)

# curl https://api.nowgo.io/v0/plans/{plan_id}/jobs/{job_id} \
  -X PATCH \
  -u :{auth_token} \
  -d {body}

Example Request (in plan using external reference)

# curl https://api.nowgo.io/v0/plans/{plan_id}/jobs/ext-ref/{ext_ref} \
  -X PATCH \
  -u :{auth_token} \
  -d {body}

Example Body

{
  "priority_weighting": 1.4,
  "priority_id": "1",
  "priority_ext_ref": "high",
  "allowed_driver_ids": [
    "434",
    "552"
  ],
  "allowed_shifts": [
    {
      "ext_ref": "shift1"
    }
  ],
  "allowed_vehicle_types": [
    {
      "vehicle_type_id": "414"
    },
    {
      "vehicle_type_id": "419"
    }
  ],
  "vehicle_type_preferences": [
    {
      "vehicle_type_id": "414",
      "preference": "positive"
    }
  ],
  "allowed_vehicles": [
    {
      "vehicle_id": "103",
      "vehicle_ext_ref": "truck_11"
    }
  ],
  "vehicle_requirements": [
    {
      "id": "9464",
      "ext_ref": "height",
      "pass_if_absent": true,
      "max": 100
    }
  ],
  "type": "priority-delivery",
  "data": {
    "customer-relations": "Remember to wish the customer a lovely day."
  }
}

Applies an update to the given job. Any parameters set to null in the request will be cleared if valid. Any parameters not passed in the request will remain unchanged. You can read more about the semantics of PATCH in updating resources.

Note that the deprecated allowed_vehicle_type_ids and allowed_vehicle_types field fulfil the same purpose. If either is used, then all existing values will be replaced by the new values

This operation is available in plans.

Response

Returns a job object if the update was successful. Returns an error if something goes wrong.

Unassign a job

Example Request (using id)

# curl https://api.nowgo.io/v0/jobs/{job_id}/assignment \
  -X DELETE \
  -u :{auth_token}

Example Request (using external reference)

# curl https://api.nowgo.io/v0/jobs/ext-ref/{ext_ref}/assignment \
  -X DELETE \
  -u :{auth_token}

Example Request (in plan using job id)

# curl https://api.nowgo.io/v0/plans/{plan_id}/job/{job_id}/assignment \
  -X DELETE \
  -u :{auth_token}

Example Request (in plan using external reference)

# curl https://api.nowgo.io/v0/plans/{plan_id}/job/ext-ref/{ext_ref}/assignment \
  -X DELETE \
  -u :{auth_token}

Makes a job's stops unassigned. This will remove stops from any shift that they are assigned to.

This operation is available in plans.

Delete a job

Example Request (using id)

# curl https://api.nowgo.io/v0/jobs/{job_id} \
  -X DELETE \
  -u :{auth_token}

Example Request (using external reference)

# curl https://api.nowgo.io/v0/jobs/ext-ref/{ext_ref} \
  -X DELETE \
  -u :{auth_token}

Example Request (in plan using job id)

# curl https://api.nowgo.io/v0/plans/{plan_id}/job/{job_id} \
  -X DELETE \
  -u :{auth_token}

Example Request (in plan using external reference)

# curl https://api.nowgo.io/v0/plans/{plan_id}/job/ext-ref/{ext_ref} \
  -X DELETE \
  -u :{auth_token}

Deletes a job and all its stops. This operation is not reversible. Deleting a job will not delete completions for its stops. Jobs deleted this way will remain in unrefreshed plans.

This operation is available in plans. When a job in a plan is deleted, that job is removed from the plan but is not deleted from dispatch. Explicitly delete the job from dispatch if want it removed completely.

Annotations

Annotations can be recorded on Jobs. This allows drivers to attach information to jobs. This is described in detail in the annotations section.

Stops

The stop object

You can read more about stops in Key Concepts.

Example Object

{
  "id": "e802d0be-46f9-4809-8ab4-cc30ab65ca54",
  "ext_ref": "2017-33232-1",
  "job_id": "e8fc77b5-650c-4e84-b7fa-4a338f7870a9",
  "shift_id": "95c9ed20-df91-4770-a620-10200d965703",
  "time_window_start": "2017-02-13T12:00:00Z",
  "time_window_end": "2017-02-13T14:00:00Z",
  "service_time": 240,
  "location_time": 60,
  "location": {
    "address": "75 Bronte Rd",
    "locality": "Bondi Junction",
    "state": "NSW",
    "postal_code": "2022",
    "latitude": -33.8925275,
    "longitude": 151.2492009,
    "contact_name": "John Smith",
    "contact_phone": "04--------",
    "contact_email": "example@nowgo.io",
    "business_name": "Example Industries"
  },
  "disposition": {
    "sticky": true
  },
  "closed": false,
  "visible_to_driver": true,
  "capacity_costs": [
    {
      "capacity_id": "5525",
      "capacity_ext_ref": "weight-kgs",
      "cost": 30
    }
  ],
  "force_individual_workflow": true,
  "location_groups": [{}],
  "type": "delivery",
  "data": {
    "atl": "Please leave package by the front gate."
  },
  "precursors": [
    {
      "precursor_id": "042fcc7b-a391-4935-b99b-c67c377d3a7d",
      "same_start": false
    }
  ],
  "autocomplete_rule": {
    "radius_metres": 400,
    "trigger_type": "enter",
    "can_complete_out_of_sequence": true
  },
  "target_article_ids": [
    "182712871581385864",
    "182713139773572237"
  ],
  "action_id": 661,
  "action_ext_ref": "pickup",
  "delegation_pending": false,
  "delegated": false
}

Locations in stops

Optionally, stops can have a location specified by id or external reference, which we refer to as a first-class location. If a location is specified in this way, the data from that location will be populated on the stop. The location's data acts like a template, which fills in the stop's data.

Updating a location's data will not change existing stops with that first-class location set. Existing stops will only be updated when their individual location data changes. This is so that, among other reasons, even if a location changes historical data remains consistent.

If you provide both a first-class location and extra location data, the extra data provided will override the data from the first-class location for the stop. For example, you could provide both a location.id to attach a first-class location, but also an overriding latitude and longitude to direct a driver to the other end of a large block for a particular stop.

Adding stops to jobs

Example Request (using id)

# curl https://api.nowgo.io/v0/jobs/{job_id}/stops \
  -u :{auth_token} \
  -d {body}

Example Request (using external reference)

# curl https://api.nowgo.io/v0/jobs/ext-ref/{job_ext_ref}/stops \
  -u :{auth_token} \
  -d {body}

Example Request (in plan using id)

# curl https://api.nowgo.io/v0/plans/{plan_id}/jobs/{job_id}/stops \
  -u :{auth_token} \
  -d {body}

Example Request (in plan using external reference)

# curl https://api.nowgo.io/v0/plans/{plan_id}/jobs/ext-ref/{job_ext_ref}/stops \
  -u :{auth_token} \
  -d {body}

Example Body (using address)

{
  "ext_ref": "2017-33232-1",
  "time_window_start": "2017-02-13T12:00:00Z",
  "time_window_end": "2017-02-13T14:00:00Z",
  "service_time": 240,
  "location": {
    "address": "75 Bronte Rd",
    "locality": "Bondi Junction",
    "state": "NSW",
    "postal_code": "2022",
    "latitude": -33.8925275,
    "longitude": 151.2492009,
    "contact_name": "John Smith",
    "contact_phone": "04--------",
    "contact_email": "example@nowgo.io",
    "business_name": "Example Industries"
  },
  "disposition": {
    "sticky": true
  },
  "visible_to_driver": true,
  "capacity_costs": [
    {
      "capacity_id": "5525",
      "capacity_ext_ref": "weight-kgs",
      "cost": 30
    }
  ],
  "location_groups": [
    {
      "id": "321"
    }
  ],
  "type": "delivery",
  "data": {
    "atl": "Please leave package by the front gate."
  },
  "precursors": [
    {
      "precursor_id": "042fcc7b-a391-4935-b99b-c67c377d3a7d",
      "precursor_ext_ref": "2017-88787-2",
      "same_start": false
    }
  ],
  "autocomplete_rule": {
    "radius_metres": 200,
    "trigger_type": "enter_or_leave",
    "can_complete_out_of_sequence": true
  },
  "target_article_ids": [
    "182712871581385864",
    "182713139773572237"
  ]
}

Example Body (using location id and/or ext_ref)

{
  "time_window_start": "2017-02-13T12:00:00Z",
  "time_window_end": "2017-02-13T14:00:00Z",
  "service_time": 240,
  "location": {
    "id": "41",
    "ext_ref": "warehouse"
  }
}

Stops always exist within a job. As such, there is no top-level endpoint to create a stop. Stops can be added to a job either when the job is created, or afterwards. When a stop is added to an existing job, the stop is appended to the end of the job's stops.

The location of a stop can be set using an address, as shown in the first example, or using an id or external reference of an existing location object, as shown in the second example.

If an id and/or external reference is supplied in the location parameter, the system will search for a location object matching those identifiers. If a matching location object is found, the stop will be created using that first-class location. Any additional location data in the request will override data from the first-class location. If both an id and an external reference for a location are supplied, the external reference will be ignored.

This operation is available in plans.

Retrieve a stop

Example Request (using id)

# curl https://api.nowgo.io/v0/stops/{stop_id} \
  -u :{auth_token}

Example Request (using external reference)

# curl https://api.nowgo.io/v0/stops/ext-ref/{ext_ref} \
  -u :{auth_token}

Example Request (in plan using id)

# curl https://api.nowgo.io/v0/plans/{plan_id}/stops/{stop_id} \
  -u :{auth_token}

Example Request (in plan using external reference)

# curl https://api.nowgo.io/v0/plans/{plan_id}/stops/ext-ref/{ext_ref} \
  -u :{auth_token}

Stop objects can be retrieved using their ids or external references. This is an alternative method to retrieving the stop as part of the job object that the stop was attached to, as outlined in the jobs section.

This operation is available in plans.

Response

Returns a stop object if the request is valid.

Update a stop

Example Request (using id)

# curl https://api.nowgo.io/v0/stops/{stop_id} \
  -X PATCH \
  -u :{auth_token} \
  -d {body}

Example Request (using external reference)

# curl https://api.nowgo.io/v0/stops/ext-ref/{ext_ref} \
  -X PATCH \
  -u :{auth_token} \
  -d {body}

Example Request (using id)

# curl https://api.nowgo.io/v0/plans/{plan_id}/stops/{stop_id} \
  -X PATCH \
  -u :{auth_token} \
  -d {body}

Example Request (using external reference)

# curl https://api.nowgo.io/v0/plans/{plan_id}/stops/ext-ref/{ext_ref} \
  -X PATCH \
  -u :{auth_token} \
  -d {body}

Example Body

{
  "time_window_start": "2017-02-13T12:00:00Z",
  "time_window_end": "2017-02-13T14:00:00Z",
  "service_time": 240,
  "location": {
    "address": "75 Bronte Rd",
    "locality": "Bondi Junction",
    "state": "NSW",
    "postal_code": "2022",
    "latitude": -33.8925275,
    "longitude": 151.2492009,
    "contact_name": "John Smith",
    "contact_phone": "04--------",
    "contact_email": "example@nowgo.io",
    "business_name": "Example Industries"
  },
  "disposition": {
    "sticky": true
  },
  "visible_to_driver": true,
  "capacity_costs": [
    {
      "capacity_id": "5525",
      "capacity_ext_ref": "weight-kgs",
      "cost": 30
    }
  ],
  "location_groups": [
    {
      "id": "456"
    }
  ],
  "type": "delivery",
  "data": {
    "atl": "Please leave package by the front gate."
  }
}

Applies an update to the given stop. Any parameters set to null in the request will be cleared if valid. Any parameters not passed in the request will remain unchanged. You can read more about the semantics of PATCH in updating resources.

This operation is available in plans.

Update requests can change stop location data, but cannot change the stop to a different location. Passing a change value in location.id is an invalid request. Passing null will clear the stop's location id.

The stop completion object

Example Object

{
  "id": "12",
  "stop_id": "f8168f4e-41dc-4971-aeb3-49f9c8fb69f7",
  "stop_ext_ref": "2017-33232-1",
  "ext_ref": "20170213111",
  "time": "2017-02-13T12:00:00Z",
  "is_by_token": true,
  "shift_id": "1bbd4c14-d1a1-4f12-a6b8-e06c39d713cfu",
  "attachments": [
    {
      "label": "Receipt Scan",
      "media_type": "image/png"
    },
    {
      "label": "Customer Signature",
      "media_type": "application/pdf"
    }
  ],
  "attachment_ids": ["856", "862"],
  "data": {
    "reason": "Wasp infestation in the driveway."
  },
  "is_success": false,
  "timezone": "Australia/Sydney",
  "location": {
    "latitude": -33.8925275,
    "longitude": 151.2492009
  },
  "workflow_completion_id": "7723123829138",
}

The stop completion object is a record of when a stop was completed, whether or not it was completed successfully, and in which shift it was completed.

Complete a stop

Example Request (using id)

# curl https://api.nowgo.io/v0/stops/{stop_id}/completions \
  -u :{auth_token} \
  -d {body}

Example Request (using external reference)

# curl https://api.nowgo.io/v0/stops/ext-ref/{ext_ref}/completions \
  -u :{auth_token} \
  -d {body}

Example Body

{
  "time": "2017-02-13T12:00:00Z",
  "stop_id": "f8168f4e-41dc-4971-aeb3-49f9c8fb69f7",
  "shift_id": "1bbd4c14-d1a1-4f12-a6b8-e06c39d713cfu",
  "ext_ref": "20170213111",
  "is_success": false,
  "attachments": [
    {
      "label": "Receipt Scan",
      "media_type": "image/png"
    }
  ],
  "attachment_ids": ["856", "862"],
  "data": {
    "reason": "Wasp infestation in the driveway."
  },
  "timezone": "Australia/Sydney",
  "location": {
    "latitude": -33.8925275,
    "longitude": 151.2492009
  }
}

Example Response

{
  "id": "12",
  "stop_id": "f8168f4e-41dc-4971-aeb3-49f9c8fb69f7",
  "ext_ref": "20170213111",
  "time": "2017-02-13T12:00:00Z",
  "shift_id": "1bbd4c14-d1a1-4f12-a6b8-e06c39d713cfu",
  "is_success": false,
  "attachments": [
    {
      "id": "862",
      "name": "Order",
      "media_type": "application/msword",
      "has_content": false
    },
    {
      "id": "901",
      "label": "Receipt Scan",
      "media_type": "image/png",
      "has_content": true
    }
  ],
  "data": {
    "reason": "Wasp infestation in the driveway."
  },
  "timezone": "Australia/Sydney",
  "location": {
    "latitude": -33.8925275,
    "longitude": 151.2492009
  }
}

Mark a stop as complete. This will create a record as a stop completion object. In doing so, the work that this stop represented will be considered as complete by the system.

It is possible to attach files to stop completions. Existing files are attached by adding their ids to the 'attachment_ids' field, whereas new files can be created by adding their metadata to the 'attachments' field. The response will include all file metadata including metadata for newly created files in the 'attachments' field. Note that a file's contents will need to be uploaded via a separate request. Learn how to create/upload files.

Stop Completions also have External references. Unlike other external references in NowGo, these are only unique per-stop. These are useful for de-duplicating stop completions when syncing them from another source. Premonition may also generate external references for stop completions, in the form of a Version 4 UUID.

Response

Returns a stop completion object.

Retrieve completion details

Example Request (using id)

# curl https://api.nowgo.io/v0/stops/{stop_id}/completions \
  -u :{auth_token}

Example Request (using external reference)

# curl https://api.nowgo.io/v0/stops/ext-ref/{ext_ref}/completions \
  -u :{auth_token}

Retrieve all stop completion objects referring to this stop.

Validate stop locations

Example Request (with no arguments)

# curl https://api.nowgo.io/v0/stops/bad-geocodes \
  -u :{auth_token}

Example Response (default pagination and parameters)

{
  "results": [
    {
      "id": "605a9d83-b23f-4456-85c9-ae81277050d6",
      "time_window_start": "2017-08-13T12:00:00Z",
      "time_window_end": "2017-08-13T14:00:00Z",
      "service_time": 240,
      "location": {
        "id": "123",
        "address": "75 Bront Rd, Bondi Junction NSW 2022",
        "latitude": 0,
        "longitude": 0
      }
    }
  ],
  "has_more": false
}

Example Request (restricting channel and time ranges)

# curl https://api.nowgo.io/v0/stops/bad-geocodes?channel_id=19&from=2017-08-14T00:00:00.000Z&until=2017-08-15T23:00:00.000Z \
  -u :{auth_token}

Example Request (restricting channel using external reference)

# curl https://api.nowgo.io/v0/stops/bad-geocodes?channel_ext_ref=other_channel \
  -u :{auth_token}

Example Request (pagination parameters)

# curl https://api.nowgo.io/v0/stops/bad-geocodes?limit=5&ending_before=605a9d83-b23f-4456-85c9-ae81277050d6 \
  -u :{auth_token}

Returns stops which do not have a valid latitude and longitude. As mentioned previously, if latitude and longitude are not provided, the system will attempt to geocode the given address and will use the best available result. Sometimes this doesn't work, because the address is invalid or is otherwise unable to be parsed by the system. The result will be a stop with latitude and longitude values of 0. Stops such as these are returned by this endpoint.

This endpoint returns a paginated list. For more information about pagination and its parameters see here.

The search can be restricted to a specific channel by specifying the channel_id or channel_ext_ref query parameter. If neither of these are given, the response will include stops from all channels. The time range of the search can be restricted by specifying the from and until query parameters as timestamps conforming to ISO 8601, as demonstrated above.

Response

Returns an array of stop objects where the latitude and longitude values were invalid. The results are displayed in order of most recently updated first. As a result, if a time range isn't specified using from and to, the most recently updated stops with invalid coordinates will be displayed.

Delete a stop

Example Request (using id)

# curl https://api.nowgo.io/v0/stops/{stop_id} \
  -X DELETE \
  -u :{auth_token}

Example Request (using external reference)

# curl https://api.nowgo.io/v0/stops/ext-ref/{ext_ref} \
  -X DELETE \
  -u :{auth_token}

Example Request (in plan using id)

# curl https://api.nowgo.io/v0/plans/{plan_id}/stops/{stop_id} \
  -X DELETE \
  -u :{auth_token}

Example Request (in plan using external reference)

# curl https://api.nowgo.io/v0/plans/{plan_id}/stops/ext-ref/{ext_ref} \
  -X DELETE \
  -u :{auth_token}

Deletes a stop from its job. This operation is not reversible. Deleting a stop will not delete its completions, but will unassign the stop. Stops deleted this way will remain in unrefreshed plans.

This operation is available in plans.

Consignments

The consignment object

Example object

{
    "id": "729592901402625730",
    "priority_id": "123456",
    "priority_ext_ref": "high",
    "is_return": null,
    "ext_ref": null,
    "articles": [
        {
            "consignment_id": "729592902600031",
            "item_count": 1,
            "identifiers": [
                {
                    "is_primary_display_identifier": true,
                    "relation": null,
                    "identifier": "PPHP50WG01"
                }
            ],
            "id": "729592901485001",
            "custom_data": {
                "type": "CTN"
            }
        }
    ],
    "receiver": {
        "address_line_1": "55 Pyrmont Bridge Road",
        "address_line_2": null,
        "address_line_3": null,
        "address_line_4": null,
        "address_line_5": null
        "postal_code": "2007",
        "locality": "Pyrmont",
        "state": "NSW",
        "latitude": -33.87227166182225,
        "longitude": 151.1946738493009,
        "is_business": false,
        "business_name": null,
        "contact_phone": "0411111111",
        "email": "test.user@example.com",
        "contact_name": "Test User",
        "custom_data": {},
    },
    "return_to": null,
    "identifiers": [
        {
            "identifier": "PPHP580WI",
            "relation": null,
            "is_primary_display_identifier": true
        }
    ],
    "origin": null,
    "sender": {
        "id": "97500566829804483",
        "name": "Stacey Smith",
        "is_business": false,
        "business_name": null,
        "email": "staceysmith@example.com",
        "address_line_1": "74 Forest Road",
        "address_line_2": null,
        "address_line_3": null,
        "address_line_4": null,
        "address_line_5": null,
        "locality": "Springfield",
        "state": "NSW",
        "postal_code": "2020",
        "contact_name": "Stacey Smith",
        "contact_phone": "0412345678",
        "latitude": "-33.9181216",
        "longitude": "151.1470805",
        "custom_data": {
            "lorem": "ipsum",
            "dolor": "sit amet",
            "consectetur": "adipiscing elit"
        }
    },
    "destination": null,
    "custom_data": {
        "dangerous_goods": false,
        "authority_to_leave": false,
        "delivery_instructions": "Signature Required"
    },
}

You can read more about consignments in Further Concepts. Priorities are described in more detail in the priorities section.

To understand in clearer detail what a consignment is composed of, you may be interested in reading about:
The Party object, which describes how to specify sender, recipient and other addresses,
The Article object, which describes how to specify the contents of a consignment - e.g. the individually trackable physical objects to be delivered as part of this consignment,
The Consignment identifier object, which describes how to specify barcodes or identifiers for the consignment, and
The Article identifier object, which describes how to specify barcodes or identifiers for articles.

The party object

Example object

{
  "id": "97500566829804483",
  "name": "Stacey Smith",
  "is_business": false,
  "business_name": null,
  "email": "staceysmith@example.com",
  "address_line_1": "74 Forest Road",
  "address_line_2": null,
  "address_line_3": null,
  "address_line_4": null,
  "address_line_5": null,
  "locality": "Springfield",
  "state": "NSW",
  "postal_code": "2020",
  "contact_name": "Stacey Smith",
  "contact_phone": "0412345678",
  "latitude": "-33.9181216",
  "longitude": "151.1470805",
  "custom_data": {
    "lorem": "ipsum",
    "dolor": "sit amet",
    "consectetur": "adipiscing elit"
  }
}

A party represents a person or entity that is related to a consignment. A party can contain information about the party's name, location, contact details, as well as additional custom data.

The consignment identifier object

Example object

{
  "identifier": "ABC123456789",
  "relation": "label"
}

Create a consignment

Example Request

# curl https://api.nowgo.io/v0/consignments \
  -X PATCH \
  -u :{auth_token} \
  -d {body}

Example Body

{
  "identifiers": [
    {
      "identifier": "PPHP580WI",
      "relation": null,
      "is_primary_display_identifier": true
    }
  ],
  "receiver": {
    "id": "97500566829804483",
    "name": "Stacey Smith",
    "is_business": false,
    "email": "staceysmith@example.com",
    "address_line_1": "74 Forest Road",
    "locality": "Springfield",
    "state": "NSW",
    "postal_code": "2020",
    "contact_name": "Stacey Smith",
    "contact_phone": "0412345678",
    "latitude": "-33.9181216",
    "longitude": "151.1470805",
    "custom_data": {
      "lorem": "ipsum",
      "dolor": "sit amet",
      "consectetur": "adipiscing elit"
    }
  },
  "sender": {
    "address_line_1": "55 Pyrmont Bridge Road",
    "postal_code": "2007",
    "locality": "Pyrmont",
    "state": "NSW",
    "latitude": -33.87227166182225,
    "longitude": 151.1946738493009,
    "is_business": false,
    "contact_phone": "0411111111",
    "email": "test.user@example.com",
    "contact_name": "Test User",
    "custom_data": {},
  },
  "origin": null,
  "destination": null,
  "is_return": false,
  "return_to": {},
  "articles": [
    {
      "identifiers": [
        {
          "is_primary_display_identifier": true,
          "relation": null,
          "identifier": "PPHP50WG01"
        }
      ],
      "item_count": 1,
      "custom_data": {
        "type": "CTN"
      }
    }
  ],
  "priority_ext_ref": "high",
  "custom_data": {
    "dangerous_goods": false,
    "authority_to_leave": false,
    "delivery_instructions": "Signature Required"
  }
}

Response

Returns a consignment object if creation was successful. Returns an error if something goes wrong.

Retrieve a consignment

Example Request

# curl https://api.nowgo.io/v0/consignments/{consignment_id} \
  -u :{auth_token}

Consignments can be retrieved using a consignment id.

Update a consignment

Example Request

# curl https://api.nowgo.io/v0/consignments/{consignment_id} \
  -X PATCH \
  -u :{auth_token} \
  -d {body}

Example Body

{
  "identifiers": [{
    "identifier": "123"
  }],
  "sender": {
    "email": "nowgo@nowgo.io"
  },
  "is_return": false,
  "articles": [{
    "item_count": 6,
    "identifiers": [{
      "identifier": "456"
    }]
  }],
  "priority_ext_ref": "prem_highest",
  "custom_data": {
    "lorem": "ipsum",
    "dolor": "sit amet",
    "consectetur": "adipiscing elit"
  }
}

Applies an update to the given consignment. Any parameters set to null in the request will be cleared if valid. Any parameters not passed in the request will remain unchanged. You can read more about the semantics of PATCH in updating resources.

Search for consignments

Example Request

# curl https://api.nowgo.io/v0/consignments/search?identifier=BARCODE1000&page_size=100 \
  -u :{auth_token}

Returns a paginated list of consignment objects consignments matching the identifier query parameter.

This query will return consignments which either have a matching consignment identifier, or have an associated article with a matching article identifier.

Articles

The article object

Example object

{
  "id": "47500564578487767",
  "consignment_id": "47829599378998346",
  "identifiers": [
    {
      "identifier": "XGS4983189",
      "relation": "label_number"
    },
    {
      "identifier": "XGS2393721",
      "relation": "additional_reference"
    }
  ],
  "item_count": "1",
  "custom_data": {
    "lorem": "ipsum",
    "dolor": "sit amet",
    "consectetur": "adipiscing elit"
  },
  "notes": "lorem ipsum"
}

You can read more about articles in Further Concepts.

The article identifier object

Example object

{
  "identifier": "XGS4983189",
  "relation": "label_number"
}

Create an article

Example Request

# curl https://api.nowgo.io/v0/consignments/-/articles \
  -X PATCH \
  -u :{auth_token} \
  -d {body}

Example Body

{
  "identifiers": [
    {
      "identifier": "XGS4983189",
      "relation": "label_number"
    },
    {
      "identifier": "XGS2393721",
      "relation": "additional_reference"
    }
  ],
  "item_count": "1",
  "custom_data": {
    "lorem": "ipsum",
    "dolor": "sit amet",
    "consectetur": "adipiscing elit"
  },
  "notes": "Lorem ipsum, dolor sit amet"
}

Retrieve an article

Example Request

# curl https://api.nowgo.io/v0/consignments/-/articles/{article_id} \
  -u :{auth_token}

Articles can be retrieved using a consignment id and article id.

Update an article

Example Request

# curl https://api.nowgo.io/v0/consignments/-/articles/{article_id} \
  -X PATCH \
  -u :{auth_token} \
  -d {body}

Example Body

{
  "identifiers": [
    {
      "identifier": "XGS4983189",
      "relation": "label_number"
    },
    {
      "identifier": "XGS2393721",
      "relation": "additional_reference"
    }
  ],
  "item_count": "1",
  "custom_data": {
    "lorem": "ipsum",
    "dolor": "sit amet",
    "consectetur": "adipiscing elit"
  },
  "notes": "Lorem ipsum, dolor sit amet"
}

Applies an update to the given article. Any parameters set to null in the request will be cleared if valid. Any parameters not passed in the request will remain unchanged. You can read more about the semantics of PATCH in updating resources.

Actions

Actions can be (and are typically) configured via the NowGo Dashboard, however there are API methods that allow API users to create, read and update actions. See actions for more details.

The action object

Example object

{
  "id": "6631",
  "display_name": "Pickup",
  "ext_ref": "pickup",
  "legacy_stop_type": "pickup",
  "legacy_workflow_type": null,
  "color": "#00e397"
  "archived_at": null,
  "outcomes": [{
    "id": "125",
    "code": "failed-already-picked-up",
    "display_name": "Unsuccessful pickup - already picked up",
    "archived_at": null
  }, {
    "id": "437",
    "code": "succeeded-pickup",
    "display_name": "Successful pickup",
    "archived_at": null
  }]
}

You can read more about actions in Key Concepts.

The action outcome object

Example object

{
  "id": "437",
  "code": "succeeded-pickup",
  "display_name": "Successful pickup",
  "archived_at": null
}

The action outcome field is used to specify what the possible results or outcomes exist for a workflow completion using actions. The code field will be returned as the outcome` field of the workflow completion. See the workflow completion API for more information.

Create an action

Example Request

curl https://api.nowgo.io/v0/actions \
  -X POST \
  -u :{auth_token} \
  -d {body}

Example Body

{
  "display_name": "Pickup",
  "ext_ref": "pickup",
  "color": "#00e397"
  "outcomes": [{
    "code": "failed-already-picked-up",
    "display_name": "Unsuccessful pickup - already picked up",
  }, {
    "code": "succeeded-pickup",
    "display_name": "Successful pickup",
  }]
}

Retrieve an action

Example Request

curl https://api.nowgo.io/v0/actions/{action_id} \
  -u :{auth_token}

curl https://api.nowgo.io/v0/actions/ext-ref/{action_ext_ref} \
  -u :{auth_token}

Actions can be retrieved via their id.

Actions can also be retrieved via their ext_ref.

List actions

Example Request

curl https://api.nowgo.io/v0/actions \
  -u :{auth_token}

Example Response

{
  "data": [
    {
      "id": "6631",
      "display_name": "Pickup",
      "ext_ref": "pickup",
      "legacy_stop_type": "pickup",
      "legacy_workflow_type": null,
      "color": "#00e397"
      "archived_at": null,
      "outcomes": [{
        "id": "125",
        "code": "failed-already-picked-up",
        "display_name": "Unsuccessful pickup - already picked up",
        "archived_at": null
      }, {
        "id": "437",
        "code": "succeeded-pickup",
        "display_name": "Successful pickup",
        "archived_at": null
      }]
    }
  ],
  "next_page_token": null
}

All existing actions in your org can be queried for. Note that the response is returned in a paginated manner.

Update an action

Example Request

curl https://api.nowgo.io/v0/actions/{action_id} \
  -X PATCH \
  -u :{auth_token} \
  -d {body}

curl https://api.nowgo.io/v0/actions/ext-ref/{action_ext_ref} \
  -X PATCH \
  -u :{auth_token} \
  -d {body}

Example Body

{
  "display_name": "Pickup (new color)",
  "ext_ref": "pickup_new_color",
  "color": "#ef9a21"
}

Applies an update to the given action. Any fields set to null in the request will be cleared if valid. Any fields not passed in the request will remain unchanged. You can read more about the semantics of PATCH in updating resources.

Actions can also be updated via their ext_ref.

Archiving an action

Example Request

curl https://api.nowgo.io/v0/actions/{action_id} \
  -X DELETE \
  -u :{auth_token}

curl https://api.nowgo.io/v0/actions/ext-ref/{action_ext_ref} \
  -X DELETE \
  -u :{auth_token}

Actions can also be archived via their ext_ref.

Drivers

The driver object

Example object

{
  "id": "44482",
  "ext_ref": "driver772",
  "name": "Andrew Jones",
  "email": "d772@courier.com",
  "phone": "+61400000000",
  "is_password_set": true,
  "travel_duration_multiplier": 1.2,
  "calculated_travel_duration_multiplier": 1.1,
  "use_calculated_travel_duration_multiplier": false,
  "require_sso": false,
  "default_channel_id": "1234",
  "default_channel_ext_ref": "channel1",
  "data": {
    "lorem": "ipsum",
    "dolor": "sit amet"
  }
}

For more information about Single Sign On, contact our team.

Create a driver

Example request

$ curl https://api.nowgo.io/v0/drivers \
    -u :{auth_token} \
    -d {body}

Example body

{
  "ext_ref": "driver772",
  "name": "Andrew Jones",
  "email": "d772@example.com",
  "phone": "+61400000000",
  "password": "verysecretpw",
  "use_calculated_travel_duration_multiplier": false,
  "travel_duration_multiplier": 1.2,
  "default_channel_id": "1234",
  "default_channel_ext_ref": "channel1",
  "data": {
    "lorem": "ipsum",
    "dolor": "sit amet"
  }
}

Response

Returns a driver object if creation was successful. Returns an error if something goes wrong.

Retrieve a driver

Example Request (using id)

# curl https://api.nowgo.io/v0/drivers/{id} \
  -u :{auth_token}

Example Request (using external reference)

# curl https://api.nowgo.io/v0/drivers/ext-ref/{ext_ref} \
  -u :{auth_token}

Drivers can be retrieved using their id or external reference.

Response

Returns a driver object if the given identifier is valid, and returns an error otherwise.

Retrieve all drivers

Example Request

# curl https://api.nowgo.io/v0/drivers \
  -u :{auth_token}

Example Response

Returns a paginated list of driver objects.

{
  "data": [{}],
  "next_page_token": "db05252b"
}

Alternative pagination styles

The /v0/drivers endpoint also supports page-based pagination, which was exposed in the API but never documented. If you're not already using that style of pagination on this endpoint, please use token-based pagination as described above.

Update a driver

Example request (using id)

$ curl https://api.nowgo.io/v0/drivers/{id} \
    -X PATCH \
    -u :{auth_token} \
    -d {body}

Example request (using external reference)

$ curl https://api.nowgo.io/v0/drivers/ext-ref/{ext_ref} \
    -X PATCH \
    -u :{auth_token} \
    -d {body}

Example body

{
  "name": "Andrew Jones",
  "email": null,
  "phone": "+61400000000",
  "use_calculated_travel_duration_multiplier": false,
  "travel_duration_multiplier": 1.3,
  "default_channel_id": "1234",
  "default_channel_ext_ref": "channel1",
  "data": {
    "lorem": "ipsum",
    "dolor": "sit amet",
    "consectetur": "adipiscing elit"
  }
}

Applies an update to the given driver. Any parameters set to null in the request will be cleared if valid. Any parameters not passed in the request will remain unchanged. You can read more about the semantics of PATCH in updating resources.

Response

Returns a driver object if the update was successful. Returns an error if something goes wrong.

Archive a driver

Example request (using id)

$ curl https://api.nowgo.io/v0/drivers/{id} \
    -X DELETE \
    -u :{auth_token}

Example request (using external reference)

$ curl https://api.nowgo.io/v0/drivers/ext-ref/{ext_ref} \
    -X DELETE \
    -u :{auth_token}

Archives a driver.

When a driver is archived via the API, the driver’s external reference is cleared and can be used again elsewhere. An archived driver can be restored via the restore endpoint.

Response

Returns a driver object if the archive was successful. Returns an error if something goes wrong.

Restore a driver

Example request

$ curl https://api.nowgo.io/v0/drivers/{id}/restore \
    -X POST \
    -u :{auth_token} \
    -d {body}

Restores a driver.

When a driver is restored via the API, the driver’s new external reference can be set using the ext_ref parameter (this must not conflict with any existing, unarchived drivers).

Response

Returns a driver object if the restoration was successful. Returns an error if something goes wrong, such as when a conflicting external reference is used.

Update a driver's location

Example Request (using id)

$ curl https://api.nowgo.io/v0/drivers/{id}/tracking-points \
    -u :{auth_token} \
    -d {body}

Example Request (using external reference)

$ curl https://api.nowgo.io/v0/drivers/ext-ref/{ext_ref}/tracking-points \
    -u :{auth_token} \
    -d {body}

Example body

{
  "latitude": -33.8605187,
  "longitude": 151.2039825,
  "time": "2017-01-01T05:24:41Z"
}

Adds a tracking point for a driver. If the tracking point is more recent than those from other sources, stop etas and other time-dependent calculations are also updated accordingly.

The created point's provider field will contain the value api.

Response

Returns 200 Ok if the location update was successful. Returns an error if something goes wrong.

Get a driver's travel history

Example Request (using id)

$ curl https://api.nowgo.io/v0/drivers/{id}/track?date=2017-01-01 \
    -u :{auth_token}

Example Request (using external reference)

$ curl https://api.nowgo.io/v0/drivers/ext-ref/{ext_ref}/track?date=2017-01-01 \
    -u :{auth_token}

Returns information about a driver's travel. This information is gathered from in-app location tracking, driver locations added via the API, and from stop completion information. If no time range is specified, this endpoint returns the most recent known location of the driver.

Example Response

{
  "driver_id": "4321",
  "points": [
    {
      "provider": "gps",
      "time": "2017-01-01T05:24:41Z",
      "latitude": -33.8605187,
      "longitude": 151.2039825,
      "accuracy": 11.3
    },
    {
      "provider": "completion",
      "time": "2017-01-01T05:25:00Z",
      "latitude": -33.8605187,
      "longitude": 151.2039825,
      "stop_id": "58cacd4e-4f9f-47bc-9a2f-74e5ffc67ad5"
    }
  ]
}

Response

An object containing driver id, and a list of points. If the list of points is empty, no location information is available for the driver within the requested period.

Update the locations of many drivers

Example Request

$ curl https://api.nowgo.io/v0/tracking-points \
    -u :{auth_token} \
    -d {body}

Example body

[
  {
    "driver_id": "4321",
    "latitude": -33.8605187,
    "longitude": 151.2039825,
    "time": "2017-01-01T05:24:41Z"
  },
  {
    "driver_ext_ref": "driver_13",
    "latitude": -33.8688,
    "longitude": 151.2093,
    "time": "2017-01-01T05:24:41Z"
  }
]

Adds many tracking points from a list of tracking point objects. Each object consists of an id or external reference of a driver along with coordinates and a time stamp.

Channels

The channel object

Example object

{
  "id": "44482",
  "ext_ref": "sydney-west",
  "name": "Sydney West",
  "ext_version": 3371645,
  "bounding_box_enabled": true,
  "bounding_box_north": -33.8207615,
  "bounding_box_south": -34.0819139,
  "bounding_box_east": 151.0422459,
  "bounding_box_west": 150.6851903,
  "timezone": "Australia/Sydney",
  "delegated_channel_ids:": ["44483", "ext-ref-channel-1"]
}

Bounding Box

Channels in NowGo can optionally have a bounding box. The bounding box is used to filter geocode results for stops in the channel. If a stop geocodes to a point outside the channel bounding box, the point is presumed to be incorrect and not used.

Create a channel

Example request

$ curl https://api.nowgo.io/v0/channels \
    -u :{auth_token} \
    -d {body}

Example body

{
  "ext_ref": "sydney-west",
  "name": "Sydney West",
  "bounding_box_enabled": true,
  "bounding_box_north": -33.8207615,
  "bounding_box_south": -34.0819139,
  "bounding_box_east": 151.0422459,
  "bounding_box_west": 150.6851903,
  "timezone": "Australia/Sydney",
  "delegated_channel_ids:": ["ext-ref-channel-2"]
}

Response

Returns a channel object if creation was successful. Returns an error if something goes wrong.

Update a channel

Example request (using id)

$ curl https://api.nowgo.io/v0/channels/{id} \
    -X PATCH \
    -u :{auth_token} \
    -d {body}

Example request (using external reference)

$ curl https://api.nowgo.io/v0/channels/ext-ref/{ext_ref} \
    -X PATCH \
    -u :{auth_token} \
    -d {body}

Example body

{
  "name": "Sydney Northwest",
  "ext_version": 100,
  "bounding_box_enabled": true,
  "bounding_box_north": -33.8207615,
  "bounding_box_south": -34.0819139,
  "bounding_box_east": 151.0422459,
  "bounding_box_west": 150.6851903,
  "timezone": "Australia/Sydney",
  "delegated_channel_ids:": ["ext-ref-channel-2"]
}

Applies an update to the given channel. Any parameters set to null in the request will be cleared if valid. Any parameters not passed in the request will remain unchanged. You can read more about the semantics of PATCH in updating resources.

Response

Returns a channel object if the update was successful. Returns an error if something goes wrong.

Retrieve a channel

Example Request (using id)

# curl https://api.nowgo.io/v0/channels/{id} \
  -u :{auth_token}

Example Request (using external reference)

# curl https://api.nowgo.io/v0/channels/ext-ref/{ext_ref} \
  -u :{auth_token}

Channel objects can be retrieved using their ids or external references.

Response

Returns a channel object if the request is valid.

Retrieve all channels

Example Request

# curl https://api.nowgo.io/v0/channels \
  -u :{auth_token}

Example Response

Returns a paginated list of channel objects.

{
  "data": [{}],
  "next_page_token": "db05252b"
}

Plans

The plan object

You can read more about plans in Further Concepts.

Example object

{
  "id": "44234",
  "shift_ids": ["4412", "4413", "4416"],
  "shifts": [{}],
  "job_ids": ["44516531", "5615251"],
  "jobs": [{}]
}

The plan object contains a snapshot of the state of the world at a particular point in time. You can change the contents of a plan without worrying about concurrent modification, and then resolve any conflicts at a later point. Plans are always created within the context of a channel, and cannot cross channel boundaries.

Updates to plans use a similar set of operations and endpoints as updates to other entities. See the Interacting with plans section for more information.

Create a plan

Example request (using id)

$ curl https://api.nowgo.io/v0/channels/{channel_id}/plans \
    -u :{auth_token} \
    -d {body}

Example request (using external reference)

$ curl https://api.nowgo.io/v0/channels/ext-ref/{channel_ext_ref}/plans \
    -u :{auth_token} \
    -d {body}

Example body based on specific shifts and jobs

{
  "shift_ids": ["4412", "4413", "4416"],
  "job_ids": ["44516531", "5615251"]
}

Example body based on a time window

{
  "time_window_start": "2017-01-01T08:00:00Z",
  "time_window_end": "2017-01-01T17:00:00Z"
}

If a time window and specific ids are both present, only entities matching the ids provided will be included in the plan. This can be useful for attempting to assign a specific job, for example. If a plan is created with an empty list of ids, no entities of that type will be included. Note that some additional entities may be brought into the plan if they are attached to entities that are explicitly included (for example, including a shift will include its assigned stops and jobs).

Response

Returns a plan object if creation was successful. Returns an error if something goes wrong.

Retrieve a plan

Example Request (using id)

# curl https://api.nowgo.io/v0/channels/{channel_id}/plans/{id} \
  -u :{auth_token}

Example Request (using external reference)

# curl https://api.nowgo.io/v0/channels/ext-ref/{channel_ext_ref}/plans/{id} \
  -u :{auth_token}

Merge a plan

Example Request (using id)

# curl https://api.nowgo.io/v0/channels/{channel_id}/plans/{id}/merge \
  -X POST
  -u :{auth_token}

Example Request (using external reference)

# curl https://api.nowgo.io/v0/channels/ext-ref/{channel_ext_ref}/plans/{id}/merge \
  -X POST
  -u :{auth_token}

Update a plan

Example Request (using id)

# curl https://api.nowgo.io/v0/channels/{channel_id}/plans/{id}/fix \
  -X POST
  -u :{auth_token}

Example Request (using external reference)

# curl https://api.nowgo.io/v0/channels/ext-ref/{ext_ref}/plans/{id}/fix \
  -X POST
  -u :{auth_token}

Interacting with plans

Plans use similar endpoints and requests as other operations. Not all endpoints are supported in plans. When an endpoint is supported, the documentation will contain an example of performing an operation on a plan.

Common operations

Jobs

• Create a job in a plan
• Retrieve a job in a plan
• Update a job in a plan
• Delete a job in a plan

Stops

• Add stops to a job in a plan
• Retrieve a stop in a plan
• Update a stop in a plan
• Delete a stop in a plan

Solves

The solve object

You can read more about solves in Further Concepts.

Example object

{
  "id": "5152",
  "solve_profile_ext_ref": "full-solve",
  "status": "in-progress",
  "all_shifts_locked": false,
  "shift_ids": ["4414"],
  "locked_shift_ids": ["4414, 4415"],
  "all_unassigned_jobs_locked": true,
  "job_ids": [],
  "locked_job_ids": []
}

The solve object contains information about a currently running or completed solve operation. The solve object also contains information about the shifts and jobs currently locked within the plan due to the solve.

Create a solve

Example request (using channel id)

$ curl https://api.nowgo.io/v0/channels/{channel_id}/plans/{plan_id}/solves \
    -u :{auth_token} \
    -d {body}

Example request (using channel external reference)

$ curl https://api.nowgo.io/v0/channels/ext-ref/{channel_ext_ref}/plans/{plan_id}/solves \
    -u :{auth_token} \
    -d {body}

Example body

{
  "solve_profile_ext_ref": "full-solve",
  "shift_ids": ["4414"],
  "job_ids": ["1141", "1146"],
  "exclude_unassigned_jobs": true
}

When a solve is created, NowGo begins working in the background to complete it. When a solve is completed, any effects are applied in the plan automatically. You can retrieve a plan at any time to check its current status.

Default solve profiles

Response

Returns a solve object if creation was successful. Returns an error if something goes wrong.

Retrieve a solve

Retrieves the status of a solve. Possible values for status include:

• in-progress - the solve is still pending.
• complete - the solve has completed, and the plan has been updated accordingly
• cancelled - the solve has been cancelled, through user request or otherwise.
• failed - an error has occurred during the solve

Example Request (using channel id)

# curl https://api.nowgo.io/v0/channels/{channel_id}/plans/{plan_id}/solves/{id} \
  -u :{auth_token}

Example Request (using channel external reference)

# curl https://api.nowgo.io/v0/channels/ext-ref/{channel_ext_ref}/{plan_id}/solves/{id} \
  -u :{auth_token}

List all solves in progress

Example Request (using channel id)

# curl https://api.nowgo.io/v0/channels/{channel_id}/plans/{plan_id}/solves \
  -u :{auth_token}

Example Request (using channel external reference)

# curl https://api.nowgo.io/v0/channels/ext-ref/{channel_ext_ref}/plans/{plan_id}/solves \
  -u :{auth_token}

Response

Returns the list of currently in-progress solve objects for the specified plan and channel.

Capacities

The capacity object

You can read more about capacities in Further Concepts.

Example Response

{
  "id": "11314",
  "ext_ref": "weight-kgs",
  "name": "Weight (kgs)",
  "service_time_seconds_per_unit": 0.2,
  "is_weight": true,
  "session_weight_unit": "kilograms",
  "app_weight_unit": "kilograms",
  "default_limit_setting": "default_zero"
}

Create a capacity

Example Request

# curl https://api.nowgo.io/v0/capacities \
  -u :{auth_token} \
  -d {body}

Example Body

{
  "ext_ref": "weight-kgs",
  "name": "Weight (kgs)",
  "service_time_seconds_per_unit": 0.2,
  "is_weight": true,
  "session_weight_unit": "kilograms",
  "app_weight_unit": "kilograms",
  "default_limit_setting": "default_zero"
}

Response

Returns a capacity object if creation was successful. Returns an error if something goes wrong.

Retrieve capacities

Example Request

# curl https://api.nowgo.io/v0/capacities \
  -u :{auth_token}

Example Response

[
  {
    "id": "9226",
    "ext_ref": "weight-kgs",
    "name": "Weight (kgs)",
    "is_weight": true,
    "session_weight_unit": "kilograms",
    "app_weight_unit": "kilograms"
  },
  {
    "id": "4154"
    "ext_ref": "volume-m3",
    "name": "Volume (m3)"
  }
]

Response

A list of capacity objects.

Attributes

The attribute object

You can read more about attributes in Further Concepts.

Example Response

{
  "id": "321",
  "name": "Refrigerated",
  "ext_ref": "is-refrigerated",
  "is_boolean": true
}

Create an attribute

Example Request

# curl https://api.nowgo.io/v0/attributes \
  -u :{auth_token} \
  -d {body}

Example Body

{
  "name": "Refrigerated",
  "ext_ref": "is-refrigerated",
  "is_boolean": true
}

Response

Returns an attribute object if creation was successful. Returns an error if something goes wrong.

Retrieve attributes

Example Request

# curl https://api.nowgo.io/v0/attributes \
  -u :{auth_token}

Example Response

[
  {
    "id": "3957",
    "name": "Refrigerated",
    "ext_ref": "is-refrigerated",
    "is_boolean": true
  },
  {
    "id": "293",
    "name": "Vehicle height",
    "ext_ref": "vehicle-height",
    "is_boolean": false
  }
]

Response

A list of attribute objects.

Vehicle Types

The vehicle type object

You can read more about vehicle types in Vehicle Types. Vehicle attributes (attribute values) are described in more detail in Further Concepts.

Example Response

{
  "id": "5256",
  "ext_ref": "large-van",
  "capacity_limits": [
    {
      "capacity_id": "552132",
      "capacity_ext_ref": "weight-kgs",
      "limit": 1540
    },
    {
      "capacity_id": "5525",
      "capacity_ext_ref": "volume-m3",
      "limit": 7
    }
  ],
  "attribute_values": [
    {
      "attribute_id": "56",
      "attribute_ext_ref": "is-refrigerated",
      "value": true
    },
    {
      "attribute_id": "83",
      "attribute_ext_ref": "capacity-kg",
      "value": 2000
    }
  ],
  "travel_duration_multiplier": 1.2
}

Create a vehicle type

Example Request

# curl https://api.nowgo.io/v0/vehicle-types \
  -u :{auth_token} \
  -d {body}

Example Body

{
  "ext_ref": "large-van",
  "name": "Large van",
  "capacity_limits": [
    {
      "capacity_ext_ref": "weight-kgs",
      "limit": 1540
    },
    {
      "capacity_id": "5525",
      "limit": 7
    }
  ],
  "attribute_values": [
    {
      "attribute_id": "938",
      "value": 5
    },
    {
      "attribute_ext_ref": "is-refrigerated",
      "value": false
    }
  ],
  "travel_duration_multiplier": 1.2
}

Response

Returns a vehicle type object if creation was successful. Returns an error if something goes wrong.

Retrieve vehicle types

Example Request

# curl https://api.nowgo.io/v0/vehicle-types \
  -u :{auth_token}

Example Response

[
  {
    "id": "5256",
    "ext_ref": "large-van",
    "name": "Large van",
    "capacity_limits": [
      {
        "capacity_id": "552132",
        "capacity_ext_ref": "weight-kgs",
        "limit": 1540
      },
      {
        "capacity_id": "5525",
        "capacity_ext_ref": "volume-m3",
        "limit": 7
      }
    ],
    "attribute_values": [
      {
        "attribute_id": "56",
        "attribute_ext_ref": "is-refrigerated",
        "value": true
      },
      {
        "attribute_id": "83",
        "attribute_ext_ref": "capacity-kg",
        "value": 2000
      }
    ]
  },
  {
    "id": "515",
    "ext_ref": "motorbike",
    "capacity_limits": [
      {
        "capacity_id": "62",
        "capacity_ext_ref": "max-jobs",
        "limit": 12
      }
    ],
    "attribute_values": [
      {
        "attribute_id": "4",
        "attribute_ext_ref": "has-tailgate",
        "value": false
      }
    ]
  }
]

Response

A list of vehicle type objects.

Retrieve a vehicle type

Example Request (using id)

# curl https://api.nowgo.io/v0/vehicle-types/{id} \
  -u :{auth_token}

Example Request (using external reference)

# curl https://api.nowgo.io/v0/vehicle-types/ext-ref/{ext_ref} \
  -u :{auth_token}

Vehicle type objects can be retrieved by id or external reference.

Response

Returns a vehicle type object if the request is valid.

Update a vehicle type

Example Request (using id)

# curl -X PATCH https://api.nowgo.io/v0/vehicle-types/{id} \
  -u :{auth_token} \
  -d {body}

Example Request (using external reference)

# curl -X PATCH https://api.nowgo.io/v0/vehicle-types/ext-ref/{ext_ref} \
  -u :{auth_token}

Example Body

{
  "travel_duration_multiplier": 1.2,
  "name": "Large van",
  "capacity_limits": [
    {
      "capacity_ext_ref": "weight-kgs",
      "capacity_id": "10",
      "limit": 1500
    },
    {
      "capacity_ext_ref": "litres",
      "capacity_id": "5"
    }
  ],
  "attribute_values": [
    {
      "attribute_id": "11",
      "attribute_ext_ref": "is-refrigerated",
      "value": false
    },
    {
      "attribute_id": "16",
      "attribute_ext_ref": "vehicle-height-metres",
      "value": 3
    }
  ]
}

This endpoint allows us to update vehicle types.

If either the capacity_limits and attribute_values object lists are included in the request, they will overwrite their respective existing values. As such, you should include all values, including the parameters you wish to change, as well as those that should remain the same. Otherwise, if the entire list is omitted, no changes to those fields will be applied, following PATCH semantics.

Changing vehicle type parameters such as capacity_limits or attribute_values may make existing data in shifts and solves invalid. It could mean that already existing shifts and solves using the old parameters will be in place and won't match up with new requirements. This could be addressed by reattempting a solve using the new vehicle type parameters.