api.md
Introduction
Credentials Validation
Job
Job Action
Customer
Itinerary
Location
Vehicle
Operator
Geofencing
Capacity Management
Download OpenAPI specification:Download
API Support: [email protected]
Welcome to the Cigo Tracker API documentation. Below, you will find resource addresses, explanations, and examples showcasing how to use our API to access and manage Jobs, related Actions, and information regarding Itineraries created via Cigo Tracker.
On the right hand side, you can navigate all available resources along with the responses each API endpoint produces.
The Cigo Tracker API enables you to:
Create, retrieve, update and delete Jobs
Create, retrieve, update and delete Actions related to Jobs
Create, retrieve, update and delete Itineraries
Retrieve Locations, Vehicles and Operators created within the platform
For API connections in the production environment, specify the URL: https://app.cigotracker.com
For API connections in the sandbox environment, specify the URL: https://app-demo.cigotracker.com
Important: Jobs created with a valid email and/or a mobile_number may be notified via Email and SMS to follow their order even in the sandbox environment. In your testing, we recommend only sending notifications to internal recipients.
After enabling the API, you can manage webhooks from the web portal to monitor the following system actions:
Relay attacks are a common issue in webhook verification, where an attacker intercepts a webhook message and resends it to the intended recipient. This section outlines measures to prevent relay attacks using headers X-Cigo-Tracker-Timestamp and X-Cigo-Tracker-Signature.
When receiving a webhook message, your application should expect two headers:
X-Cigo-Tracker-TimestampThe timestamp of when the message was sent.
X-Cigo-Tracker-SignatureA digital signature generated using the API secret key, API account ID, message body and timestamp
Cigo allows Provider Administrators (or Super Admins managing them) to configure a Custom Webhook ID and a Custom Webhook Secret.
If these custom values are set, they will override the standard Public API Account ID and Secret Key. You can configure these custom values in your Provider Settings within the Cigo platform, under the Public API section in settings.
When you update your Custom Webhook ID or Custom Webhook Secret in the Cigo Provider Settings, please be aware of the following:
X-Cigo-Tracker-Signature for all subsequent webhook events.Cigo uses the JSON Canonicalization Scheme (JCS) to ensure all parties compute signatures on an identical, platform-independent JSON encoding.
JCS mandates:
This ensures that signature generation is deterministic :
Any JCS-compliant library in any language will produce the identical canonical JSON string for the same data.
Standard JSON encoding can differ by whitespace, key order, or encoding choices, causing signature mismatches across platforms.
By using JCS, you ensure that the hash or signature you compute in PHP, Python, Node.js, or Java will always match the signature Cigo supplies in the webhook header.
To verify the authenticity and prevent relay attacks, follow these steps:
API Account ID ($api_account_id_to_use):
Custom Webhook ID in your Cigo Provider Settings, use that value.Secret Key ($secret_key_to_use):
Custom Webhook Secret in your Cigo Provider Settings, use that value (the plain text secret).$payload be the raw (Unscaped) JSON string of the webhook request body. Must use JCS. You should either use a JCS-compliant canonicalize function or a library in your language.$timestamp be the integer value from the X-Cigo-Tracker-Timestamp header.:) as a delimiter.$message = $api_account_id_to_use . ':' . $payload . ':' . $timestamp;
Compute the signature:
Encode the signature:
// Generate your own signature
function generateSignature($api_account_id, $payload, $timestamp, $secret_key) {
$formatted = $api_account_id . ':' . $payload . ':' . $timestamp;
return base64_encode(hash_hmac('sha256', $formatted, $secret_key, true));
}
// Extract information
$timestamp = intval($_SERVER['HTTP_X_CIGO_TRACKER_TIMESTAMP']);
// Other information
$api_account_id = 'your-api-account-id'
$secret_key = 'your-api-secret-key';
$payload = json_decode('webhook-response-data');
$signature = generateSignature($api_account_id, $payload, $timestamp, $secret_key);
// Validate message
// Compare generated signature with provided X-Cigo-Tracker-Signature header value
if ($signature == $_SERVER['HTTP_X_CIGO_TRACKER_SIGNATURE']) {
// Check if timestamp is within 5 minutes of the current timestamp
$current_timestamp = time();
if ((abs($timestamp - $current_timestamp) / 60) <= 300) { // 300 seconds -> 5 minutes
echo('Message is valid and not a relay attack.');
}
} else {
echo('Invalid signature, consider re-sending the message.');
}
There are some key Cigo concepts to understand in order to easily navigate documentation and use our API.
A Job is a general term used in Cigo to describe a destination, such as a Customer, where your Operator(s) may do a delivery, a service call, an installation, or various Job Actions (see explanation on 'Job Action' below).
When a job is created via the API, its initial status value is staging. If you log in to Cigo, you can find this Job by opening the sidebar menu and navigating the Import Tool page. Once you've landed on the Import Tool page, you'll find your created API records under the 'Review records from API Integration' tab.
Dispatcher will typically use the Import Tool to validate and review upcoming Jobs prior to dispatching them to vehicles. At a glance, they can validate if the address of each Job will be properly geo-coded and if the address string is valid.
However, if this step is not needed for your integration, you can skip the Import Tool when the Job is created via the API by setting skip_staging to true (for details, refer to the POST Create a new Job).
Job statuses range from:
staging: Jobs created with skip_staging: false (default) will return this status. Jobs in this state cannot be routed and have to be reviewed in the Import Tool.new: Jobs post-import (or if created via the API with skip_staging: true). This is the base state of a job that can be or has been added to an Itinerary's route.in progress: Once an operator selects 'On Route' in the mobile app, the job will transition to this state. If this isn't the first Job in the itinerary, the Job prior must have been started and finished before this status can be set.completed: Once an operator selects 'Completed' in the mobile app, the job will transition to this state. A job must have been in progress to be transitioned in this state.incomplete: Once an operator selects 'Incomplete' in the mobile app, the job will transition to this state. From the Company Settings page, under the Operator App Options section, your organization can choose to disable this status option entirely, and it will not be available to the operator as a selection. Furthermore, your organization can choose to enforce a report with either images and/or text explanations required for said report. This is managed from the Company Settings page, under the Fulfillment Options section.partially completed: This state is special in the sense that an operator does not directly select it. Instead, a job is transitioned to this state only when an operator has one or many actions marked as either 'Damaged' or 'Incomplete' and chooses the 'Completed' state on the overall job. This results in a job being partially completed.damaged: Once an operator selects 'Damaged' in the mobile app, and fills out a report, the job will transition to this state. From the Company Settings page, under the Operator App Options section, your organization can choose to disable this status option entirely, and it will not be available to the operator as a selection.resolved: This status is special. It cannot be set by the operators. Instead it is managed from the web after a job has been transitioned from either incomplete, damaged or partially completed, the status of the job can be transitioned to 'Resolved' by a web user. This can be useful to indicate that a prior mishap has been resolved and that this job no longer requires attention.cancelled: This status marks that the job has been cancelled and won't be done in this route anymore.A Job can be assigned any number of Actions. These Actions serve as a to-do list for the Operator arriving on site (i.e. a customer's location). Actions have types (i.e. delivery, installation, service, etc.) and other attributes, such as handle time (the amount of time the action is estimated to take).
Job Action statuses range from:
undetermined: No status has been set for this Job Action yet. This is the default state.completed: This Job Action has been fulfilled without any issues.incomplete: This Job Action could not be fulfilled.damaged: An incident is related to this Job Action.When you create a new Job, an existing Customer profile is either linked or created. Customer profiles are created or updated based on a Job's first name, last name, phone number, and address fields.
When you first create a Job, you can assign a Customer Reference ID. When you create new Jobs assigned to the same Customer Reference ID, it'll keep all of them associated with the same Customer.
No, you cannot. Within the web interface, there are a few things you can update on an existing Customer profile, but this is not currently available via the API.
In order to prevent duplicate orders from being entered into Cigo Tracker, we prevent orders with the same core information from being re-entered. For example, if you have an order with the same first name, last name, address, and delivery date, we detect it as a duplicate job and prevent its creation.
This default behaviour may not be suitable for your business if you can receive multiples orders per day by the same customer. In that case, setting a unique reference_id during the Job creation process will allow you to workaround this restriction. If you have a unique Order ID from an external system (e.g. Shopify), you can use that in your reference_id field and Cigo Tracker will ignore the duplicate check.
If you did not specify skip_staging: true in your POST call to create a Job, it'll be created in the staging status.
You'll only be able to find this Job by logging into the Cigo Tracker web portal, opening the sidebar menu and navigating the Import Tool page. Once you've landed on the Import Tool page, you'll find your created Job records under the 'Review records from API Integration' tab.
Pickups and Drop-offs are automatically generated by Cigo. Every Pickup and Drop-off is directly corelated to a Job Action via its stop_location_id. For instance, if a Job has an Action of type 'pickup' with a valid stop_location_id, once an Itinerary is created by your Dispatcher, a Pickup will automatically be created to indicate that it must be done prior to the related Job.
An Itinerary is a detailed list of ordered Route Stops; including it's initial start and final return location, estimated time of departure, as well as the assigned Operator(s) and Vehicle.
A Stop, or Route Stop, is simply a geographical location on an Itinerary and it can either a Job, a Pickup, or a Drop-off.
An Operator is an individual assigned to an Itinerary. For instance, if your company handles the delivery of goods, you may already internally refer to your Operators as Drivers, as opposed to Technicians in other industries. Operators interact with Cigo via our mobile application.
A Dispatcher is a web platform user that is able to create Itineraries, create Jobs, Actions, and has direct access to the Staging Area (inside of Cigo, the Staging Area is referred to as the 'Import Tool').
A sub-user represents an authorized merchant who has restricted access to the API. Access to the API is limited to merchants at Level 2. When making requests, sub-users are subject to validation and filtering based on their assigned Locations.
Here's a Key Concepts Diagram to help you visualize how some of the concepts explained above correlate to one another.
If you still have questions, feel free to shoot us an email: [email protected]
Access Restrictions
Sub-users with API access have permission to use this endpoint.
Check that your authentication credentials are valid.
BasicAuth
200
A sample response validating your authentication credentials.
401
Authentication information is missing or invalid.
409
API access is disabled. For further details, reach out to [email protected] or talk to your account manager.
default
An unexpected error occurred.
get/ping
Production Environment
https://app.cigotracker.com/api/v1/ping
Sandbox (Demo) Environment
https://app-demo.cigotracker.com/api/v1/ping
Content type application/json
Copy Expand all Collapse all
`{
"statusCode": 200,
"status": "OK",
"message": "Welcome to the Cigo Tracker API!",
"details": {
"client_ip": "<CLIENT_IP>",
"api_account_id": "<API_ACCOUNT_ID>",
"company_name": "<COMPANY_NAME>",
"tenant_name": "<COMPANY_NAME>",
"docs": "<DOCS_URL>"
}
}`
Access Restrictions
Sub-users with API access have permission to use this endpoint, but they must specify both the
branch_idanddistribution_center_idin the request body.
Create a new Job in the staging area (also known as the Import Tool) to be reviewed by your Dispatcher(s). The staging area can be skipped if the Job is created with skip_staging set to true. However, if you do not provide the Job's precise coordinates, we will automatically geocode the address you provided.
BasicAuth
| type |
string
Default: "delivery"
Enum: "delivery" "return" "pickup" "installation" "service" "exchange" "custom"
Type of Job. If not set, the Job type will be delivery.
| | quick_desc |
string <= 10 characters
A short description regarding the Job that is visible throughout the platform for Dispatchers and Operators alike.
| | date required |
string <date>
ISO-8601 date format indicating when the Job is scheduled for. This date cannot be in the past (today or later, based on your timezone).
- Format: Year-Month-Day (YYYY-MM-DD)
- Optional: Timezone offset:
- If a timezone is included, it requires time to specify exact date
- Timezone can be added with +HH:MM or -HH:MM offset (e.g. 2024-08-01T15:30:00-06:00 or 2024-08-01T15:30:00+06:00)
Note : If no date has yet been determined for this Job to be fulfilled on, you may set this value as tbd (for 'To be determined' or 'To be dated'). Dispatchers will be able to set a date manually afterwards from within the web platform.
| | original_date |
string <date>
ISO-8601 date format indicating the Original Job Date.
- Format: Year-Month-Day (YYYY-MM-DD)
- Optional: Timezone offset:
- If a timezone is included, it requires time to specify exact date
- Timezone can be added with +HH:MM or -HH:MM offset (e.g. 2024-08-01T15:30:00-06:00 or 2024-08-01T15:30:00+06:00)
| | confirmation_status |
string
Enum: "confirmed" "pending" "awaiting_confirmation" "confirmed_by_customer" "reschedule_requested"
Specify the confirmation status of a Job.
Note : If Confirmation module is enabled- Then the following values are available: awaiting_confirmation, confirmed_by_customer, reschedule_requested.
| | first_name required |
string <= 255 characters
First name of the Customer associated with the Job.
Note : Use this field if it is a business name (without a last name).
| | last_name |
string <= 255 characters
Last name of the Customer associated with the Job.
| | phone_number required |
string
Phone number associated with the Job.
We accept formatted phone numbers as well as non-formatted, i.e.:
Note : For US and Canadian phone numbers, you do not have to include the country dial code (+1). For other regions , please include the country code prefixed with '+'.
| | mobile_number |
string
Mobile number associated with the Job (the tracking information will be sent to this number via SMS). *
We accept formatted phone numbers as well as non-formatted, i.e.:
| | email |
string <email> <= 255 characters
Email address of the customer (the tracking information will be sent to this email).
| | address required |
string <= 250 characters
Address associated with the Job. Within this field, include the following ( delimited by commas ):
| | coordinates |
Array of numbers <float> = 2 items [items <float >]
Coordinates of the corresponding location in GeoJSON format: [latitude, longitude] (both values are of type float). If you provide this information and set skip_staging to true, we will not attempt to geocode the address, and the country code will automatically be set to the business's country.
| | apartment |
string <= 100 characters
Apartment associated with the address. It should be separated from the address itself to prevent geocoding errors when determining the location's geographical coordinates.
| | postal_code |
string [5 .. 7] characters
Postal Code or ZIP code associated with the address.
| | time_preference |
string
Enum: "AM" "PM" "morning" "midday" "afternoon" "evening" "night" null
Defines the Customer's time preference for the Job's arrival at their door.
Note : There are two Time Preference modes available in the Company Settings within the platform: *
AM and PM.morning, midday, afternoon, evening, night.If the Time Preference mode is set to Advanced, and the AM value is submitted, it will be set to morning. Similarly, if PM is submitted, it will be converted to afternoon.
Conversely, if the Time Preference mode is set to Basic, and either morning or midday are submitted, they will be converted to AM, and afternoon, evening and night will be converted to PM.
| | balance_owed |
number <float> >= 0
Balance owed associated with the Job (positive number with up to 2 decimal points).
| | comment |
string <= 2500 characters
Any comment or note associated with the Job. Line breaks are supported using (\n) (newline) or ( ) (HTML line break) characters.
| | signature_agreement |
string <= 2500 characters
The signature agreement is used when the recipient of a Job is prompted to provide their signature as confirmation. This only applies if skip_staging is set to true.
| | branch_id |
string <= 30 characters
Branch or Store ID associated with this Job. Ensure this ID is associated to an existing Branch in our platform.
| | distribution_center_id |
string <= 30 characters
Distribution Center or Warehouse ID associated with this Job. Ensure this ID is associated to an existing Distribution Center in our platform.
| | time_frame |
object
Set the approximate Time Frame within which the Job should be started and operators should be on Customer site.
Note : Do not set these values if you want the platform to automatically calculate accurate time frame start and end values based on the Itinerary route and traffic data.
| | invoices |
Array of strings unique [items <= 60 characters]
List of Invoice numbers associated with this Job
| | barcodes |
Array of strings[items <= 60 characters]
List of barcodes associated with this Job
| | label_count |
integer >= 1
The number of labels associated with this Job.
Note : This variable is used exclusively with our label printing integration. Do not set this if it is not enabled.
| | reference_id |
string <= 25 characters
External system reference ID associated with this Job for your convenience. This ID should be unique for every new Job. If you do not provide one, we will automatically generate a unique Job ID. It should contain numbers, letters, hyphens or underscores only.
| | customer_reference_id |
string <= 25 characters
External system for Customer reference ID associated with this Job. This only applies if skip_staging is set to true. If you do not provide one, we will automatically generate one (this only applies if the Job is matched to a Customer that does not already exist in our system).
| | skip_staging |
boolean
If true, the Job created will skip the staging area (Import Tool). If you did not specify the geo-coordinates of this Job, we will automatically geocode the address you've provided. For invalid addresses that fail geocoding, the Job creation will be rejected and you will receive a 400 error response code.
| | actions |
Array of objects (Job Action model)
Actions to create in association with this Job. You can create a maximum of 200 actions via this POST request. Additional actions should be created via POST Create a new Job Action. For actions that are the same, we recommend grouping them together under one action and setting its quantity accordingly.
| | ignore_geo_zone_warnings |
boolean
If true, Zone Capacity geolocation warnings will not show. If Capacity Management and Zone Validations are enabled for your system, creating a Job will warn if the address falls outside any predefined Zones. Creating a Job outside these Zones, Zone Capacity validations will not run for that Job
| | bypass_zone_capacity_rules |
boolean
If true, Zone Capacity limit validation will not run.
|
201
Created Job resource for specified jobID successfully.
400
Missing or invalid fields for one or more fields when creating a new Job.
401
Authentication information is missing or invalid.
409
API access is disabled. For further details, reach out to [email protected] or talk to your account manager.
422
Invalid request parameters.
default
An unexpected error occurred.
post/jobs
Production Environment
https://app.cigotracker.com/api/v1/jobs
Sandbox (Demo) Environment
https://app-demo.cigotracker.com/api/v1/jobs
Content type application/json
Copy Expand all Collapse all
`{
"type": "delivery",
"quick_desc": "SAMPLE",
"date": "2024-08-01",
"original_date": "2019-03-29",
"confirmation_status": "confirmed",
"first_name": "John",
"last_name": "Doe",
"phone_number": "+15062345678",
"mobile_number": "+15062345678",
"email": "[email protected]",
"address": "275 Notre-Dame St. East, Montreal, QC, H2Y 1C6",
"coordinates": [
46.7727384, -71.3180309
],
"apartment": "Suite 101",
"postal_code": "H2Y 1C6",
"time_preference": "AM",
"balance_owed": 265.89,
"comment": "A sample comment regarding the job for John Doe. Please leave at the front door. \n\n Tips will be considered.",
"signature_agreement": "Sample signature agreement shared with customer.",
"branch_id": "S10",
"distribution_center_id": "DC12",
"time_frame": {
"start": "9:00 AM",
"end": "11:00 AM"
},
"invoices": ["17823657812563" ],
"barcodes": ["17823657812563" ],
"label_count": 3,
"reference_id": "J-WJG318322",
"customer_reference_id": "C-WJG178262",
"skip_staging": false,
"actions": [ {
"id": "73165560",
"type": "delivery",
"description": "Astin Sofa - Grey",
"value": 1149.96,
"unit_weight": 120.5,
"unit_volume": 2.75,
"piece_count": 1,
"piece_count_unit": "boxes",
"quantity": 2,
"quantity_unit": "bundles",
"handle_time": 10,
"stop_location_id": "B12",
"stop_location": {
"name": "Stop Location A",
"geolocation": { "coordinates": [
46.7727384, -71.3180309
]
},
"time_frame": {
"start": "9:00 AM",
"end": "11:00 AM"
}
},
"invoice_number": "9871236WE127836",
"shipping_barcode": "1234567890",
"external_reference_id": "CJA20121105TBA69420",
"bypass_zone_capacity_rules": "false",
"require_barcode": "false"
}
],
"ignore_geo_zone_warnings": "false",
"bypass_zone_capacity_rules": "false"
}`
Content type application/json
Copy Expand all Collapse all
`{
"statusCode": 201,
"status": "Created",
"message": "Successfully created a job for staging. Save 'job_id' to refer to this job in other operations.",
"job_id": "75bf34f9dd1c325a4542fcda7eb05794",
"actions": [ {
"action_id": "4658447740ea46059239b7184d374ff1",
"external_reference_id": "external_ref_12345"
}
]
}`
Access Restrictions
Sub-users with API access have permission to use this endpoint.
NOTE: Sub-users can only retrieve jobs associated with branches they are assigned or have been created by themselves.
Search for Job API IDs where the date is within a certain start and end range (within 30 days), as well as other criteria:
post_staging)The result, if it isn't filtered by Status, is broken down into two categories:
staging: Job API IDs that have the status stagingpost_staging: Job API IDs that have other statuses, and may or may not have been assigned to an itinerary.Fields start_date and end_date follows ISO-8601 date format:
Note : If you do not define the end_date, it will automatically be set to the same as the required start_date.
BasicAuth
| start_date required |
string <date>
Start date in ISO-8601 date format.
Format: Year-Month-Day (YYYY-MM-DD)
Optional: Timezone offset:
| | end_date |
string <date>
End Date in ISO-8601 date format.
Note :
start_date.start_date to tbd, this value will be ignored.| | status |
string
Enum: "staging" "new" "in progress" "damaged" "completed" "resolved" "incomplete" "partially completed" "cancelled"
Filter by status of Jobs
| | first_name |
string <= 255 characters
Filter by first name that may have been set on one or many Jobs
| | last_name |
string <= 255 characters
Filter by last name that may have been set on one or many Jobs
| | phone_number |
string <= 255 characters
Filter by phone number that may have been set on one or many Jobs
| | quick_desc |
string <= 10 characters
Filter by quick description that may have been set on one or many Jobs
| | invoice_number |
string <= 255 characters
Filter by invoice number that may have been set on one or many Jobs
| | shipping_barcode |
string <= 128 characters
Filter by barcode that may have been set on one or many Jobs actions and returns Job ID
| | reference_id |
string <= 255 characters
Filter by job system reference ID that may have been set on one or many Jobs
| | confirmation_status |
string
Enum: "confirmed" "pending" "awaiting_confirmation" "confirmed_by_customer" "reschedule_requested"
Filter by confirmation status of Jobs
| | branch_id |
string <= 30 characters
Branch or Store ID associated with one or many Jobs. Ensure this ID is associated to an existing Branch in our platform.
| | distribution_center_id |
string <= 30 characters
Distribution Center or Warehouse ID associated with one or many Jobs. Ensure this ID is associated to an existing Distribution Center in our platform.
| | job_type |
string
Enum: "Delivery" "Return" "Pick" "Installation" "Service" "Custom" "Exchange"
Filter by type of Jobs
| | creation_source |
string
Enum: "CSV" "DIRECT" "API" "STAGING" "CLONE" "RESCHEDULE"
Filter by creation source of Jobs
| | on_itinerary |
boolean
Use this filter to find jobs based on their itinerary assignment status. Setting the filter to false will list jobs that are not currently assigned to an itinerary, while setting it to true will list jobs that are assigned to an itinerary.
|
200
Searched for Job API IDs successfully
400
Missing required fields or invalid value in request body.
401
Authentication information is missing or invalid.
409
API access is disabled. For further details, reach out to [email protected] or talk to your account manager.
default
An unexpected error occurred.
post/jobs/search
Production Environment
https://app.cigotracker.com/api/v1/jobs/search
Sandbox (Demo) Environment
https://app-demo.cigotracker.com/api/v1/jobs/search
Content type application/json
Copy
`{
"start_date": "2020-01-01",
"end_date": "2020-01-31",
"status": "completed",
"first_name": "John",
"last_name": "Doe",
"phone_number": "5147894560",
"quick_desc": "SAMPLE",
"invoice_number": "818362",
"shipping_barcode": "8182258639",
"reference_id": "J-WJG318322",
"confirmation_status": "confirmed",
"branch_id": "S10",
"distribution_center_id": "DC12",
"job_type": "Delivery",
"creation_source": "DIRECT",
"on_itinerary": false
}`
Content type application/json
Copy Expand all Collapse all
`{
"statusCode": 200,
"status": "OK",
"in_staging": {
"count": 1,
"ids": ["37703edb3ce4532bc70e8b19b1989c52" ]
},
"post_staging": {
"count": 1,
"ids": ["864c4cb6402655563ed30fb5db298e90" ]
}
}`
Access Restrictions
Sub-users with API access have permission to use this endpoint.
NOTE: Sub-users can only retrieve jobs associated with branches they are assigned to or have been created by themselves.
Retrieve an existing Job whether it is in staging or it has been validated by your dispatcher(s).
BasicAuth
| jobID required |
string
|
200
Retrieved Job resource for specified jobID successfully.
400
Missing Required Fields in Create a new Job
401
Authentication information is missing or invalid.
403
You do not have permission to access the job associated with the given jobID
404
No Job found for given jobID.
409
API access is disabled. For further details, reach out to [email protected] or talk to your account manager.
422
Invalid request parameters.
default
An unexpected error occurred.
get/jobs/id/{jobID}
Production Environment
https://app.cigotracker.com/api/v1/jobs/id/{jobID}
Sandbox (Demo) Environment
https://app-demo.cigotracker.com/api/v1/jobs/id/{jobID}
Content type application/json
Copy Expand all Collapse all
`{
"statusCode": 200,
"status": "OK",
"job": {
"job_id": "f4e922d54b98a878488d2754fd4cfc0e",
"stop_type": "job",
"job_type": "delivery",
"status": "completed",
"status_metadata": "{'data': 'Example of Free Text (it doesn't have to be JSON!)'}",
"post_staging": {
"tracking": {
"url": "https://cigo.io/EXAMPLE",
"phone_number": "5148880000",
"access_code": "885854",
"tracking_number": "P35UWX-GPIP6C-7ZZSJ2",
"tracking_number_suffix": "7ZZSJ2"
},
"progress": {
"duration": 1063,
"start_datetime": "2024-08-01 09:23:21",
"end_datetime": "2024-08-01 09:41:04",
"started": true,
"finished": true
},
"scheduling": {
"operators": [ {
"operator_id": "56a5eb4a1b7b64d2d22232f74ca98523",
"name": "John Doe",
"reference_id": "95874-CA",
"username": "[email protected]",
"last_active": "2024-08-01 08:54:48"
}
],
"itinerary_id": "6452b37d5242d835ba9a246feab2127c",
"itinerary_api_id": "6452b37d5242d835ba9a246feab2127c",
"vehicle": "HINO 00765",
"vehicle_id": "00765",
"vehicle_api_id": "bdca6e528b4324a2279d7ab25265431f",
"position": 1,
"route_metrics": {
"est_arrival_time": "2024-08-01 10:03:00",
"est_road_time": 26340,
"est_distance": 407222.73
}
},
"coordinates": [
46.7727384, -71.3180309
],
"geocoding": {
"validity": "valid",
"subdivision_code": "QC",
"country_code": "CA",
"timezone": "America/Toronto"
},
"digital_signature": {
"agreement": "All items have been properly inspected during the delivery.",
"signed": false,
"name": null,
"datetime": null
},
"payment_collection": {
"payment_collection_allowed": false,
"balance_owed": 758.88,
"amount_collected": 758.88,
"payment_method": "cash",
"paid_in_full": true
},
"review": {
"score": 4,
"comment": "Had a great experience, friendly staff!",
"datetime": "2019-04-25 20:01:56",
"sales_score": 5
}
},
"quick_desc": "SAMPLE",
"date": "2024-08-01",
"original_date": "2019-03-29",
"confirmation_status": "confirmed",
"first_name": "John",
"last_name": "Doe",
"phone_number": "(000) 000-0001",
"mobile_number": "(000) 000-0002",
"email": "[email protected]",
"address": "275 Notre-Dame St. East, Montreal, QC, H2Y 1C6",
"apartment": "Suite 101",
"postal_code": "H2Y 1C6",
"time_preference": "AM",
"balance_owed": 265.89,
"comment": "A sample comment regarding the Job for John Doe!",
"branch_id": "S10",
"branch_api_id": "73de8cb492d22423a2a5a56f142b76b5",
"distribution_center_id": "DC12",
"distribution_center_api_id": "ba7ba295e3525fc61a4222d3674428db",
"time_frame": {
"start": "9:00 AM",
"end": "11:00 AM"
},
"invoices": ["17823657812563" ],
"barcodes": ["17823657812563" ],
"label_count": 3,
"wait_time": 90,
"metrics": {
"handle_time": 25,
"weight": 191.5,
"volume": 4.5,
"value": 330.57,
"piece_count": 2,
"quantity": 2
},
"pickup_metrics": {
"handle_time": 10,
"weight": 20.6,
"volume": 2.1,
"value": 499.9,
"piece_count": 3,
"quantity": 1
},
"return_metrics": {
"handle_time": 15,
"weight": 213.4,
"volume": 1.8,
"value": 678.99,
"piece_count": 3,
"quantity": 2
},
"reference_id": "J-WJG318322",
"customer_reference_id": "C-WJG178262",
"permanent_link": "https://cigotracker.com/share/job?hash={job_id}",
"creation_source": "API",
"create_datetime": "2019-04-28 18:32:41"
},
"actions": [ {
"action_id": "97a7f7052349acb9db2fb28b19df3ba5",
"id": "ASG819723891263",
"status": "completed",
"status_reason": "Review images associated with report for more details.",
"status_counters": {
"completed": 2,
"incomplete": 0,
"damaged": 0
},
"type": "delivery",
"description": "Astin Sofa - Grey",
"value": 330.57,
"unit_weight": 95.75,
"total_weight": 191.5,
"unit_volume": 2.25,
"total_volume": 4.5,
"piece_count": 1,
"piece_count_unit": "boxes",
"quantity": 2,
"quantity_unit": null,
"handle_time": 25,
"stop_location_id": "B12",
"stop_location_api_id": "ffc9bcc45b9031a55e9401d148b9cc22",
"stop_location": {
"name": "Stop Location A",
"geolocation": { "coordinates": [
46.7727384, -71.3180309
]
},
"time_frame": {
"start": "9:00 AM",
"end": "11:00 AM"
}
},
"invoice_number": "9871236WE127836",
"external_reference_id": "CJA20121105TBA69420",
"shipping_barcode": "1234567890",
"create_datetime": "2019-05-01 16:19:22",
"properties": { "require_barcode": "false"
}
}
],
"related_on_route_stops": [ {
"api_id": "fe9900e2b9d56b41465bb302127f6197",
"status": "completed",
"type": "pickup",
"location": "Stop Location A",
"address": "275 Notre-Dame St. East, Montreal, QC, H2Y 1C6",
"position": 1,
"eta": "09:30 AM",
"time_frame": {
"start": "09:00 AM",
"end": "11:00 AM"
}
}
]
}`
Access Restrictions
Sub-users with API access have permission to use this endpoint.
NOTE: Sub-users can only delete jobs they have created themselves; otherwise, they will receive a 403 Forbidden response.
Delete an existing job while it is still either in staging or its status is still Pending state; it has not been assigned to an itinerary.
BasicAuth
| jobID required |
string
|
204
Deleted Job resource for specified jobID successfully.
401
Authentication information is missing or invalid.
403
Job state prevents from deleting it. Job state is either no longer in staging or new, or the Job has been assigned to an Itinerary.
404
No Job found for given jobID.
409
API access is disabled. For further details, reach out to [email protected] or talk to your account manager.
422
Invalid request parameters.
default
An unexpected error occurred.
delete/jobs/id/{jobID}
Production Environment
https://app.cigotracker.com/api/v1/jobs/id/{jobID}
Sandbox (Demo) Environment
https://app-demo.cigotracker.com/api/v1/jobs/id/{jobID}
Content type application/json
Copy
`{
"statusCode": 401,
"status": "Unauthorized",
"error": "Unauthorized authentication credentials."
}`
Access Restrictions
Sub-users with API access have permission to use this endpoint.
NOTE: Sub-users can only update jobs they have created themselves; otherwise, they will receive a 403 Forbidden response.
Update an existing Job.
If the Job is already assigned to an Itinerary and its state is new, only the following properties can be updated:
quick_descfirst_namelast_namephone_numbermobile_numberemailapartmenttime_preferenceinvoicesbalance_owedBasicAuth
| jobID required |
string
|
| type |
string
Default: "delivery"
Enum: "delivery" "return" "pickup" "installation" "service" "exchange" "custom"
Type of Job. If not set, the Job type will be delivery.
| | quick_desc |
string <= 10 characters
A short description regarding the Job that is visible throughout the platform for Dispatchers and Operators alike.
| | date |
string <date>
ISO-8601 date format indicating when the Job is scheduled for. This date cannot be in the past (today or later, based on your timezone).
tbd (for 'To be determined' or 'To be dated'). Dispatchers will be able to set a date manually afterwards from within the web platform.| | confirmation_status |
string
Enum: "confirmed" "pending" "awaiting_confirmation" "confirmed_by_customer" "reschedule_requested"
Specify the confirmation status of a Job.
Note : If Confirmation module is enabled- Then the following values are available: awaiting_confirmation, confirmed_by_customer, reschedule_requested.
| | first_name |
string <= 255 characters
First name of the Customer associated with the Job.
Note : Use this field if it is a business name (without a last name).
| | last_name |
string <= 255 characters
Last name of the Customer associated with the Job.
| | phone_number |
string
Phone number associated with the Job.
We accept formatted phone numbers as well as non-formatted, i.e.:
Note : For US and Canadian phone numbers, you do not have to include the country dial code (+1). For other regions , please include the country code prefixed with '+'.
| | mobile_number |
string
Mobile number associated with the Job (the tracking information will be sent to this number via SMS). *
We accept formatted phone numbers as well as non-formatted, i.e.:
| | email |
string <email> <= 255 characters
Email address of the customer (the tracking information will be sent to this email).
| | address |
string <= 250 characters
Address associated with the Job. Within this field, include the following ( delimited by commas ):
| | apartment |
string <= 100 characters
Apartment associated with the address. It should be separated from the address itself to prevent geocoding errors when determining the location's geographical coordinates.
| | postal_code |
string [5 .. 7] characters
Postal Code or ZIP code associated with the address.
| | time_preference |
string
Enum: "AM" "PM" "morning" "midday" "afternoon" "evening" "night" null
Defines the Customer's time preference for the Job's arrival at their door.
Note : There are two Time Preference modes available in the Company Settings within the platform: *
AM and PM.morning, midday, afternoon, evening, night.If the Time Preference mode is set to Advanced, and the AM value is submitted, it will be set to morning. Similarly, if PM is submitted, it will be converted to afternoon.
Conversely, if the Time Preference mode is set to Basic, and either morning or midday are submitted, they will be converted to AM, and afternoon, evening and night will be converted to PM.
| | balance_owed |
number <float> >= 0
Balance owed associated with the Job (positive number with up to 2 decimal points).
| | comment |
string <= 2500 characters
Any comment or note associated with the Job. Line breaks are supported using (\n) (newline) or ( ) (HTML line break) characters.
| | signature_agreement |
string <= 2500 characters
The signature agreement is used when the recipient of a Job is prompted to provide their signature as confirmation. This only applies if skip_staging is set to true.
| | branch_id |
string <= 30 characters
Branch or Store ID associated with this Job. Ensure this ID is associated to an existing Branch in our platform.
| | distribution_center_id |
string <= 30 characters
Distribution Center or Warehouse ID associated with this Job. Ensure this ID is associated to an existing Distribution Center in our platform.
| | time_frame |
object
Set the approximate Time Frame within which the Job should be started and operators should be on Customer site.
Note : Do not set these values if you want the platform to automatically calculate accurate time frame start and end values based on the Itinerary route and traffic data.
| | invoices |
Array of strings unique [items <= 60 characters]
List of Invoice numbers associated with this Job
| | label_count |
integer >= 1
The number of labels associated with this Job.
Note : This variable is used exclusively with our label printing integration. Do not set this if it is not enabled.
| | reference_id |
string <= 25 characters
External system reference ID associated with this Job for your convenience. This ID should be unique for every new Job. If you do not provide one, we will automatically generate a unique Job ID. It should contain numbers, letters, hyphens or underscores only.
| | ignore_geo_zone_warnings |
boolean
If true, Zone Capacity geolocation warnings will not show. If Capacity Management and Zone Validations are enabled for your system, creating a Job will warn if the address falls outside any predefined Zones. Creating a Job outside these Zones, Zone Capacity validations will not run for that Job
| | bypass_zone_capacity_rules |
boolean
If true, Zone Capacity limit validation will not run.
|
200
Updated Job resource for specified jobID successfully.
401
Authentication information is missing or invalid.
403
Job state prevents from updating it. Job state is either no longer in staging or new, or the Job has been assigned to an Itinerary.
404
No Job found for given jobID.
409
API access is disabled. For further details, reach out to [email protected] or talk to your account manager.
422
Invalid request parameters.
default
An unexpected error occurred.
patch/jobs/id/{jobID}
Production Environment
https://app.cigotracker.com/api/v1/jobs/id/{jobID}
Sandbox (Demo) Environment
https://app-demo.cigotracker.com/api/v1/jobs/id/{jobID}
Content type application/json
Copy Expand all Collapse all
`{
"type": "delivery",
"quick_desc": "SAMPLE",
"date": "2024-08-01",
"confirmation_status": "confirmed",
"first_name": "John",
"last_name": "Doe",
"phone_number": "+15062345678",
"mobile_number": "+15062345678",
"email": "[email protected]",
"address": "275 Notre-Dame St. East, Montreal, QC, H2Y 1C6",
"apartment": "Suite 101",
"postal_code": "H2Y 1C6",
"time_preference": "AM",
"balance_owed": 265.89,
"comment": "A sample comment regarding the job for John Doe. Please leave at the front door. \n\n Tips will be considered.",
"signature_agreement": "Sample signature agreement shared with customer.",
"branch_id": "S10",
"distribution_center_id": "DC12",
"time_frame": {
"start": "9:00 AM",
"end": "11:00 AM"
},
"invoices": ["17823657812563" ],
"label_count": 3,
"reference_id": "J-WJG318322",
"ignore_geo_zone_warnings": "false",
"bypass_zone_capacity_rules": "false"
}`
Content type application/json
Copy
`{
"statusCode": 200,
"status": "OK",
"job_id": "75bf34f9dd1c325a4542fcda7eb05794",
"message": "Updated Job resource for specified jobID successfully."
}`
Access Restrictions
Sub-users with API access have permission to use this endpoint.
NOTE: Sub-users can only retrieve reports for jobs they have created themselves; otherwise, they will receive a 403 Forbidden response.
Retrieve an existing Job's reports. The reports included are:
Note : For any of the reports where a file was shared, downloading the files from URLs shared in the response requires that you pass the same Authorization header as with any other request in the Public API and also set the header Content-Type: application/octet-stream. Example with cURL:
curl --location --request GET 'https://cigotracker.com/api/v1/jobs/id/<job_id>?filename=<filename>' \
--header 'Content-Type: application/octet-stream' \
--header 'Authorization: Basic <encoded_credentials>'
BasicAuth
| jobID required |
string
|
200
Retrieved Job's reports resource for specified jobID successfully.
401
Authentication information is missing or invalid.
404
No Job found for given jobID.
409
API access is disabled. For further details, reach out to [email protected] or talk to your account manager.
422
Invalid request parameters.
default
An unexpected error occurred.
get/jobs/id/{jobID}/reports
Production Environment
https://app.cigotracker.com/api/v1/jobs/id/{jobID}/reports
Sandbox (Demo) Environment
https://app-demo.cigotracker.com/api/v1/jobs/id/{jobID}/reports
Content type application/json
Copy Expand all Collapse all
`{
"statusCode": 200,
"status": "OK",
"reports": {
"digital_signature": {
"agreement": "All items have been properly inspected during the delivery.",
"signed": false,
"file_url": "https://cigotracker.com/api/v1/jobs/id/<job_id>?filename=<filename>",
"name": null,
"coordinates": [ {
"latitude": "string",
"longitude": "string"
}
],
"datetime": null
},
"additional_digital_signatures": [ {
"id": 0,
"agreement_text": "string",
"agreement_type": "string",
"signer_name": "string",
"signed": true,
"file_url": "string",
"operator_name": "string",
"created_time": "2019-08-24T14:15:22Z",
"signed_time": "2019-08-24T14:15:22Z"
}
],
"fulfillment": {
"message": "Review images associated with report for more details.",
"reporter": {
"api_id": "b53387df22645251aa9b22d24b7ec4a6",
"username": "[email protected]",
"name": "John Doe",
"role": "Operator"
},
"submitted": true,
"file_urls": [
"https://cigotracker.com/api/v1/jobs/id/<job_id>?filename=<filename_1>",
"https://cigotracker.com/api/v1/jobs/id/<job_id>?filename=<filename_2>"
],
"coordinates": [ {
"latitude": "string",
"longitude": "string"
}
],
"datetime": null
},
"incidents": {
"message": "Review images associated with report for more details.",
"reporter": {
"api_id": "b53387df22645251aa9b22d24b7ec4a6",
"username": "[email protected]",
"name": "John Doe",
"role": "Operator"
},
"submitted": true,
"file_urls": [
"https://cigotracker.com/api/v1/jobs/id/<job_id>?filename=<filename_1>",
"https://cigotracker.com/api/v1/jobs/id/<job_id>?filename=<filename_2>"
],
"coordinates": [ {
"latitude": "string",
"longitude": "string"
}
],
"datetime": null
},
"incomplete": {
"message": "Review images associated with report for more details.",
"reporter": {
"api_id": "b53387df22645251aa9b22d24b7ec4a6",
"username": "[email protected]",
"name": "John Doe",
"role": "Operator"
},
"submitted": true,
"file_urls": [
"https://cigotracker.com/api/v1/jobs/id/<job_id>?filename=<filename_1>",
"https://cigotracker.com/api/v1/jobs/id/<job_id>?filename=<filename_2>"
],
"coordinates": [ {
"latitude": "string",
"longitude": "string"
}
],
"datetime": null,
"reason_approved": true,
"revised_reason": null
}
}
}`
Retrieve an existing Job's chat data.
Access Restrictions
Sub-users with API access have permission to use this endpoint.
NOTE: Sub-users can only retrieve chats for jobs they have created themselves; otherwise, they will receive a 403 Forbidden response.
Note : For any of the chat messages where a file was shared, downloading the files from URLs shared in the response requires that you pass the same Authorization header as with any other request in the Public API and also set the header Content-Type: application/octet-stream. Example with cURL:
curl --location --request GET 'https://cigotracker.com/api/v1/jobs/id/<job_id>?filename=<filename>' \
--header 'Content-Type: application/octet-stream' \
--header 'Authorization: Basic <encoded_credentials>'
BasicAuth
| jobID required |
string
|
200
Retrieved Job's chat data for specified jobID successfully.
401
Authentication information is missing or invalid.
404
No Job found for given jobID.
409
API access is disabled. For further details, reach out to [email protected] or talk to your account manager.
422
Invalid request parameters.
default
An unexpected error occurred.
get/jobs/id/{jobID}/chat
Production Environment
https://app.cigotracker.com/api/v1/jobs/id/{jobID}/chat
Sandbox (Demo) Environment
https://app-demo.cigotracker.com/api/v1/jobs/id/{jobID}/chat
Content type application/json
Copy Expand all Collapse all
`{
"statusCode": 200,
"status": "OK",
"chat": [ {
"message": "Seems like no one's home. I called them, no answer. Should I wait a little longer?",
"file_url": "https://cigo.local/api/v1/jobs/id/<job_id>?filename=<filename>",
"user": {
"api_id": "b53387df22645251aa9b22d24b7ec4a6",
"username": "[email protected]",
"name": "John Doe",
"role": "Operator"
},
"job_status": "in progress",
"update_time": "2022-10-11 22:47:58",
"sent_on": "2022-10-11 22:47:58",
"read_on": null,
"read_status": false
}
]
}`
Access Restrictions
Sub-users with API access have permission to use this endpoint.
Create a new message in a Job's 'Notes and Chat' section.
BasicAuth
| jobID required |
string
|
| message required |
string <= 2500 characters
The message content to be added to the job's chat. Line-breaks are supported via the newline (\n) character.
|
201
Successfully created a job message.
400
Missing required fields for creating a job message.
401
Authentication information is missing or invalid.
403
You do not have permission to access the job associated with the message.
409
API access is disabled. For further details, reach out to [email protected] or talk to your account manager.
422
Invalid request parameters.
default
An unexpected error occurred.
post/jobs/id/{jobID}/chat
Production Environment
https://app.cigotracker.com/api/v1/jobs/id/{jobID}/chat
Sandbox (Demo) Environment
https://app-demo.cigotracker.com/api/v1/jobs/id/{jobID}/chat
Content type application/json
Copy
`{ "message": "Items must be dropped off from side entrance."
}`
Content type application/json
Copy
`{
"statusCode": 201,
"status": "Created",
"job_id": "f22645251aa9b22d24b7ec4a6b53387d",
"message_id": "75bf34f9dd1c325a4542fcda7eb05794",
"message": "Successfully created a job message."
}`
Retrieve an existing Job's chat specific message.
Access Restrictions
Sub-users with API access have permission to use this endpoint.
NOTE: Sub-users can only retrieve chats for jobs they have created themselves; otherwise, they will receive a 403 Forbidden response.
Note : For any of the chat messages where a file was shared, downloading the files from URLs shared in the response requires that you pass the same Authorization header as with any other request in the Public API and also set the header Content-Type: application/octet-stream. Example with cURL:
curl --location --request GET 'https://cigotracker.com/api/v1/jobs/id/<job_id>?filename=<filename>' \
--header 'Content-Type: application/octet-stream' \
--header 'Authorization: Basic <encoded_credentials>'
BasicAuth
| jobID required |
string
| | messageID required |
string
|
200
Retrieved Job's chat data for specified jobID successfully.
401
Authentication information is missing or invalid.
404
No Job found for given jobID.
409
API access is disabled. For further details, reach out to [email protected] or talk to your account manager.
422
Invalid request parameters.
default
An unexpected error occurred.
get/jobs/id/{jobID}/chat/{messageID}
Production Environment
https://app.cigotracker.com/api/v1/jobs/id/{jobID}/chat/{messageID}
Sandbox (Demo) Environment
https://app-demo.cigotracker.com/api/v1/jobs/id/{jobID}/chat/{messageID}
Content type application/json
Copy
`{
"statusCode": 200,
"status": "OK",
"message_id": "aa9b22d24b7ec4a6b53387df22645251",
"job_id": "aa9b22d24b7ec4a6b53387df22645251",
"message": "Just a message",
"sent_on": "2022-10-11 22:47:58",
"is_read": "true"
}`
Access Restrictions
Sub-users with API access have permission to use this endpoint.
Update an existing message in a Job's 'Notes and Chat' section. Only messages created via the API can be edited through this endpoint.
BasicAuth
| jobID required |
string
| | messageID required |
string
|
| message required |
string <= 2500 characters
The updated message content. The message will be marked as edited, will appear as unread to operators, and relevant operators will be notified of the change.
|
200
Successfully updated a job message.
400
Missing required fields for updating a job message.
401
Authentication information is missing or invalid.
403
You do not have permission to access this message or the message was not created via API.
404
No message found for given messageID.
409
API access is disabled. For further details, reach out to [email protected] or talk to your account manager.
422
Invalid request parameters.
default
An unexpected error occurred.
put/jobs/id/{jobID}/chat/{messageID}
Production Environment
https://app.cigotracker.com/api/v1/jobs/id/{jobID}/chat/{messageID}
Sandbox (Demo) Environment
https://app-demo.cigotracker.com/api/v1/jobs/id/{jobID}/chat/{messageID}
Content type application/json
Copy
`{ "message": "Items must be dropped off at front door!"
}`
Content type application/json
Copy
`{
"statusCode": 200,
"status": "OK",
"job_id": "f22645251aa9b22d24b7ec4a6b53387d",
"message_id": "75bf34f9dd1c325a4542fcda7eb05794",
"update_time": "2022-10-11 22:47:58",
"message": "Successfully updated the job message."
}`
Access Restrictions
Sub-users with API access DO NOT have permission to use this endpoint.
Relative to a Job, retrieve the approximate geolocation of the assigned Operator, and their last known ETA and distance from the Job's geolocation.
This information can only be retrieved if:
In Progress;This information can only be retrieved if:
BasicAuth
| jobID required |
string
|
| route_data |
string
Default: "false"
If route_data is set to false or not defined, we will not calculate the ETA and distance. If it is set to true, then we will calculate both ETA and distance values relative to the Operator's last known geolocation and the Job's geolocation.
|
200
Retrieved Job and geolocation information for specified jobID successfully.
401
Authentication information is missing or invalid.
403
Access to the requested resource is forbidden.
404
No Job found for given jobID.
409
API access is disabled. For further details, reach out to [email protected] or talk to your account manager.
422
Invalid request parameters.
default
An unexpected error occurred.
get/jobs/id/{jobID}/location
Production Environment
https://app.cigotracker.com/api/v1/jobs/id/{jobID}/location
Sandbox (Demo) Environment
https://app-demo.cigotracker.com/api/v1/jobs/id/{jobID}/location
Content type application/json
Copy Expand all Collapse all
`{
"statusCode": 200,
"status": "OK",
"job": {
"job_id": "f4e922d54b98a878488d2754fd4cfc0e",
"status": "in progress",
"progress": {
"duration": null,
"start_datetime": "2024-08-01 09:23:21",
"end_datetime": null,
"started": true,
"finished": false
},
"coordinates": [
46.7727384, -71.3180309
],
"geocoding": {
"validity": "valid",
"subdivision_code": "QC",
"country_code": "CA",
"timezone": "America/Toronto"
},
"vehicle_tracking": {
"coordinates": [
46.7727384, -71.3180309
],
"last_known": "2024-08-01 08:15:00",
"route_data": {
"arrival_time": "2024-08-01 08:25:00",
"distance": 173.68,
"road_time": 10
}
}
}
}`
Access Restrictions
Only Supervisor Sub-users with API access have permission to use this endpoint, otherwise any other Sub-user will receive a 403 Forbidden response.
Cancel an existing Job by its ID. This action will update the job status to 'cancelled' and trigger any related cancellation workflows.
BasicAuth
| jobID required |
string
|
200
Job was cancelled successfully.
403
Access to the requested resource is forbidden for sub-users.
404
No Job found for given jobID.
409
API access is disabled. For further details, reach out to [email protected] or talk to your account manager.
post/jobs/id/{jobID}/cancel
Production Environment
https://app.cigotracker.com/api/v1/jobs/id/{jobID}/cancel
Sandbox (Demo) Environment
https://app-demo.cigotracker.com/api/v1/jobs/id/{jobID}/cancel
Content type application/json
Copy
`{
"success": true,
"message": "Job cancelled successfully."
}`
Access Restrictions
Sub-users with API access have permission to use this endpoint.
NOTE: Sub-users can only retrieve actions for jobs they have created themselves; otherwise, they will receive a 403 Forbidden response.
Retrieve all actions for a Job.
BasicAuth
| jobID required |
string
|
200
Retrieved Action resources for specified jobID successfully.
401
Authentication information is missing or invalid.
404
No Job found for given jobID.
409
API access is disabled. For further details, reach out to [email protected] or talk to your account manager.
422
Invalid request parameters.
default
An unexpected error occurred.
get/jobs/id/{jobID}/actions
Production Environment
https://app.cigotracker.com/api/v1/jobs/id/{jobID}/actions
Sandbox (Demo) Environment
https://app-demo.cigotracker.com/api/v1/jobs/id/{jobID}/actions
Content type application/json
Copy Expand all Collapse all
`{
"statusCode": 200,
"status": "OK",
"actions": [ {
"action_id": "97a7f7052349acb9db2fb28b19df3ba5",
"id": "ASG819723891263",
"status": "completed",
"status_reason": "Review images associated with report for more details.",
"status_counters": {
"completed": 2,
"incomplete": 0,
"damaged": 0
},
"type": "delivery",
"description": "Astin Sofa - Grey",
"value": 330.57,
"unit_weight": 95.75,
"total_weight": 191.5,
"unit_volume": 2.25,
"total_volume": 4.5,
"piece_count": 1,
"piece_count_unit": "boxes",
"quantity": 2,
"quantity_unit": null,
"handle_time": 25,
"stop_location_id": "B12",
"stop_location_api_id": "ffc9bcc45b9031a55e9401d148b9cc22",
"stop_location": {
"name": "Stop Location A",
"geolocation": { "coordinates": [
46.7727384, -71.3180309
]
},
"time_frame": {
"start": "9:00 AM",
"end": "11:00 AM"
}
},
"invoice_number": "9871236WE127836",
"external_reference_id": "CJA20121105TBA69420",
"shipping_barcode": "1234567890",
"create_datetime": "2019-05-01 16:19:22",
"properties": { "require_barcode": "false"
}
}
]
}`
Access Restrictions
Sub-users with API access have permission to use this endpoint.
NOTE: Sub-users can only create actions for jobs they have created themselves; otherwise, they will receive a 403 Forbidden response.
Create a new Job Action for an existing Job with a specific {jobID}.
A new Job Action cannot be created if the parent Job:
pick up, return, or exchange;stop_location_id or stop_location value is not supported;completed, incomplete, etc.).BasicAuth
| jobID required |
string
|
| id required |
string <= 30 characters
ID associated with the Action (i.e. SKU, Serial Number, etc.).
| | type required |
string
Enum: "delivery" "return" "pickup" "installation" "service" "exchange"
Type of Action.
| | description required |
string <= 100 characters
Description of the Action.
| | value |
number <float> >= 0
Value of the Action as a positive number with up to 2 decimal points.
Note : This is representative of the total value associated with the action (it is NOT multiplied by the quantity).
| | unit_weight |
number <float> >= 0
Unit weight of the Action in kilograms (kg) or pounds (lbs), depending on the account settings, as a positive number with up to 2 decimal points. Note : The total_weight is automatically calculated by multiplying the unit_weight set by the quantity.
You can retrieve the total_weight value via the GET endpoints:
| | unit_volume |
number <float> >= 0
Unit volume of the Action in meters (m) or feet (ft), depending on the account settings, as a positive number with up to 2 decimal points. Note : The total_volume is automatically calculated by multiplying the unit_volume set by the quantity.
You can retrieve the total_volume value via the GET endpoints:
| | piece_count |
integer >= 0
Piece count of the Action as a positive integer (i.e. quantity of 1 for a table, that comes in 3 boxes has a piece count of 3).
| | piece_count_unit |
string <= 15 characters
The (optional) unit of the piece count. Note : In order to be able to use custom units, the relevant toggle in the Job Creation Options section of the Company Settings must be enabled.
| | quantity |
integer >= 1
Quantity of the Action as a positive integer.
| | quantity_unit |
string <= 15 characters
The (optional) unit of the quantity. Note : In order to be able to use custom units, the relevant toggle in the Job Creation Options section of the Company Settings must be enabled.
| | handle_time |
integer >= 0
Estimated time to complete the Action (in minutes) as a positive integer. Note : This is representative of the total handle time associated with the Action (it is NOT multiplied by the quantity).
| | stop_location_id |
string <= 30 characters
Stop Location ID (this value will only be saved if the Action type is pickup, return or exchange)
| | stop_location |
object (Stop Location.)
Stop Location (this object will only be saved if stop_location_id is not set and the Action type is pickup, return or exchange)
| | invoice_number |
string <= 60 characters
Invoice Number associated specifically with this Action
| | shipping_barcode |
string <= 128 characters
Shipping label barcode
| | external_reference_id |
string <= 255 characters
External system reference ID associated with this Job Action for your convenience. This ID should be unique for every new Job Action. If you do not provide one, we will automatically generate a unique Job Action ID.
| | bypass_zone_capacity_rules |
boolean
Flag to bypass Zone Capacity limit validation. This flag will only work if the Users have permission to bypass Capacity Management validations.
| | require_barcode |
boolean
Flag used to enforce the barcode scan when completing the Action.
|
201
Create Action resource for specified jobID successfully.
400
Missing Required Fields in Create a new Job Action
401
Authentication information is missing or invalid.
403
Job state prevents adding new Actions. Job state is either no longer in staging or new, or the Job has been assigned to an Itinerary.
404
No Job found for given jobID.
409
API access is disabled. For further details, reach out to [email protected] or talk to your account manager.
422
Invalid request parameters.
default
An unexpected error occurred.
post/jobs/id/{jobID}/actions
Production Environment
https://app.cigotracker.com/api/v1/jobs/id/{jobID}/actions
Sandbox (Demo) Environment
https://app-demo.cigotracker.com/api/v1/jobs/id/{jobID}/actions
Content type application/json
Copy Expand all Collapse all
`{
"id": "73165560",
"type": "delivery",
"description": "Astin Sofa - Grey",
"value": 1149.96,
"unit_weight": 120.5,
"unit_volume": 2.75,
"piece_count": 1,
"piece_count_unit": "boxes",
"quantity": 2,
"quantity_unit": "bundles",
"handle_time": 10,
"stop_location_id": "B12",
"stop_location": {
"name": "Stop Location A",
"geolocation": { "coordinates": [
46.7727384, -71.3180309
]
},
"time_frame": {
"start": "9:00 AM",
"end": "11:00 AM"
}
},
"invoice_number": "9871236WE127836",
"shipping_barcode": "1234567890",
"external_reference_id": "CJA20121105TBA69420",
"bypass_zone_capacity_rules": "false",
"require_barcode": "false"
}`
Content type application/json
Copy
`{
"statusCode": 201,
"status": "Created",
"job_id": "75bf34f9dd1c325a4542fcda7eb05794",
"job_status": "staging",
"message": "Successfully created an action for staged job '75bf34f9dd1c325a4542fcda7eb05794'. Save 'action_id' to refer to this action in other operations.",
"action_id": "97a7f7052349acb9db2fb28b19df3ba5"
}`
Access Restrictions
Sub-users with API access have permission to use this endpoint.
NOTE: Sub-users can only delete actions for jobs they have created themselves; otherwise, they will receive a 403 Forbidden response.
Delete an existing Job's actions.
A Job Action cannot be deleted if the parent Job:
pickup, return, or exchange;completed, incomplete, etc.).BasicAuth
| jobID required |
string
|
204
Deleted all Action resources for specified jobID successfully.
401
Authentication information is missing or invalid.
403
Job state prevents from deleting its actions. Job state is either no longer in staging or new, or the Job has been assigned to an Itinerary.
404
No Job found for given jobID.
409
API access is disabled. For further details, reach out to [email protected] or talk to your account manager.
422
Invalid request parameters.
default
An unexpected error occurred.
delete/jobs/id/{jobID}/actions
Production Environment
https://app.cigotracker.com/api/v1/jobs/id/{jobID}/actions
Sandbox (Demo) Environment
https://app-demo.cigotracker.com/api/v1/jobs/id/{jobID}/actions
Content type application/json
Copy
`{
"statusCode": 401,
"status": "Unauthorized",
"error": "Unauthorized authentication credentials."
}`
Access Restrictions
Sub-users with API access have permission to use this endpoint.
NOTE: Sub-users can only retrieve actions for jobs they have created themselves; otherwise, they will receive a 403 Forbidden response.
Retrieve a specific action for a Job.
BasicAuth
| jobID required |
string
| | actionID required |
string
|
200
Retrieved Action resource with specified actionID successfully.
401
Authentication information is missing or invalid.
404
Either the Job for the given jobID or the Job Action for the given actionID could not be found.
409
API access is disabled. For further details, reach out to [email protected] or talk to your account manager.
422
Invalid request parameters.
default
An unexpected error occurred.
get/jobs/id/{jobID}/actions/{actionID}
Production Environment
https://app.cigotracker.com/api/v1/jobs/id/{jobID}/actions/{actionID}
Sandbox (Demo) Environment
https://app-demo.cigotracker.com/api/v1/jobs/id/{jobID}/actions/{actionID}
Content type application/json
Copy Expand all Collapse all
`{
"statusCode": 200,
"status": "OK",
"action": {
"action_id": "97a7f7052349acb9db2fb28b19df3ba5",
"id": "ASG819723891263",
"status": "completed",
"status_reason": "Review images associated with report for more details.",
"status_counters": {
"completed": 2,
"incomplete": 0,
"damaged": 0
},
"type": "delivery",
"description": "Astin Sofa - Grey",
"value": 330.57,
"unit_weight": 95.75,
"total_weight": 191.5,
"unit_volume": 2.25,
"total_volume": 4.5,
"piece_count": 1,
"piece_count_unit": "boxes",
"quantity": 2,
"quantity_unit": null,
"handle_time": 25,
"stop_location_id": "B12",
"stop_location_api_id": "ffc9bcc45b9031a55e9401d148b9cc22",
"stop_location": {
"name": "Stop Location A",
"geolocation": { "coordinates": [
46.7727384, -71.3180309
]
},
"time_frame": {
"start": "9:00 AM",
"end": "11:00 AM"
}
},
"invoice_number": "9871236WE127836",
"external_reference_id": "CJA20121105TBA69420",
"shipping_barcode": "1234567890",
"create_datetime": "2019-05-01 16:19:22",
"properties": { "require_barcode": "false"
}
}
}`
Access Restrictions
Sub-users with API access have permission to use this endpoint.
NOTE: Sub-users can only delete actions for jobs they have created themselves; otherwise, they will receive a 403 Forbidden response.
Delete an existing Job's specific action.
A Job Action cannot be deleted if the parent Job:
pickup, return, or exchange;completed, incomplete, etc.).BasicAuth
| jobID required |
string
| | actionID required |
string
|
204
Deleted Action resource with specified actionID successfully.
401
Authentication information is missing or invalid.
403
Job state prevents from deleting its actions. Job state is either no longer in staging or new, or the Job has been assigned to an Itinerary.
404
Either the job for the given jobID or the action for the given actionID could not be found.
409
API access is disabled. For further details, reach out to [email protected] or talk to your account manager.
422
Invalid request parameters.
default
An unexpected error occurred.
delete/jobs/id/{jobID}/actions/{actionID}
Production Environment
https://app.cigotracker.com/api/v1/jobs/id/{jobID}/actions/{actionID}
Sandbox (Demo) Environment
https://app-demo.cigotracker.com/api/v1/jobs/id/{jobID}/actions/{actionID}
Content type application/json
Copy
`{
"statusCode": 401,
"status": "Unauthorized",
"error": "Unauthorized authentication credentials."
}`
Access Restrictions
Sub-users with API access have permission to use this endpoint.
NOTE: Sub-users can only update actions for jobs they have created themselves; otherwise, they will receive a 403 Forbidden response.
Update an existing Job Action.
A Job Action cannot be updated if:
pickup, return, or exchange, the stop location_id and stop_location properties cannot be updated;completed, incomplete, etc.);completed, incomplete, damaged);pickup, return or exchange action is completed or in progress.BasicAuth
| jobID required |
string
| | actionID required |
string
|
| id |
string <= 30 characters
ID associated with the Action (i.e. SKU, Serial Number, etc.).
| | type |
string
Enum: "delivery" "return" "pickup" "installation" "service" "exchange"
Type of Action.
| | description |
string <= 100 characters
Description of the Action.
| | value |
number <float> >= 0
Value of the Action as a positive number with up to 2 decimal points.
Note : This is representative of the total value associated with the action (it is NOT multiplied by the quantity).
| | unit_weight |
number <float> >= 0
Unit weight of the Action in kilograms (kg) or pounds (lbs), depending on the account settings, as a positive number with up to 2 decimal points. Note : The total_weight is automatically calculated by multiplying the unit_weight set by the quantity.
You can retrieve the total_weight value via the GET endpoints:
| | unit_volume |
number <float> >= 0
Unit volume of the Action in meters (m) or feet (ft), depending on the account settings, as a positive number with up to 2 decimal points. Note : The total_volume is automatically calculated by multiplying the unit_volume set by the quantity.
You can retrieve the total_volume value via the GET endpoints:
| | piece_count |
integer >= 0
Piece count of the Action as a positive integer (i.e. quantity of 1 for a table, that comes in 3 boxes has a piece count of 3).
| | piece_count_unit |
string <= 15 characters
The (optional) unit of the piece count. Note : In order to be able to use custom units, the relevant toggle in the Job Creation Options section of the Company Settings must be enabled.
| | quantity |
integer >= 1
Quantity of the Action as a positive integer.
| | quantity_unit |
string <= 15 characters
The (optional) unit of the quantity. Note : In order to be able to use custom units, the relevant toggle in the Job Creation Options section of the Company Settings must be enabled.
| | handle_time |
integer >= 0
Estimated time to complete the Action (in minutes) as a positive integer. Note : This is representative of the total handle time associated with the Action (it is NOT multiplied by the quantity).
| | stop_location_id |
string <= 30 characters
Stop Location ID (this value will only be saved if the Action type is pickup, return or exchange)
| | stop_location |
object (Stop Location.)
Stop Location (this object will only be saved if stop_location_id is not set and the Action type is pickup, return or exchange)
| | invoice_number |
string <= 60 characters
Invoice Number associated specifically with this Action
| | shipping_barcode |
string <= 128 characters
Shipping label barcode
| | external_reference_id |
string <= 255 characters
External system reference ID associated with this Job Action for your convenience. This ID should be unique for every new Job Action. If you do not provide one, we will automatically generate a unique Job Action ID.
| | bypass_zone_capacity_rules |
boolean
Flag to bypass Zone Capacity limit validation. This flag will only work if the Users have permission to bypass Capacity Management validations.
| | require_barcode |
boolean
Flag used to enforce the barcode scan when completing the Action.
|
200
Updated Action resource with specified actionID successfully.
401
Authentication information is missing or invalid.
403
Job state prevents updating existing Actions. Job state is either no longer in staging or new, or the Job has been assigned to an Itinerary.
404
Either the job for the given jobID or the action for the given actionID could not be found.
409
API access is disabled. For further details, reach out to [email protected] or talk to your account manager.
422
Invalid request parameters.
default
An unexpected error occurred.
patch/jobs/id/{jobID}/actions/{actionID}
Production Environment
https://app.cigotracker.com/api/v1/jobs/id/{jobID}/actions/{actionID}
Sandbox (Demo) Environment
https://app-demo.cigotracker.com/api/v1/jobs/id/{jobID}/actions/{actionID}
Content type application/json
Copy Expand all Collapse all
`{
"id": "73165560",
"type": "delivery",
"description": "Astin Sofa - Grey",
"value": 1149.96,
"unit_weight": 120.5,
"unit_volume": 2.75,
"piece_count": 1,
"piece_count_unit": "boxes",
"quantity": 2,
"quantity_unit": "bundles",
"handle_time": 10,
"stop_location_id": "B12",
"stop_location": {
"name": "Stop Location A",
"geolocation": { "coordinates": [
46.7727384, -71.3180309
]
},
"time_frame": {
"start": "9:00 AM",
"end": "11:00 AM"
}
},
"invoice_number": "9871236WE127836",
"shipping_barcode": "1234567890",
"external_reference_id": "CJA20121105TBA69420",
"bypass_zone_capacity_rules": "false",
"require_barcode": "false"
}`
Content type application/json
Copy
`{
"statusCode": 200,
"status": "OK",
"job_id": "75bf34f9dd1c325a4542fcda7eb05794",
"action_id": "2bda0e305cfaa7010a697b99fd51a809",
"message": "Updated Job Action resource for specified actionID successfully."
}`
Access Restrictions
Sub-users with API access have permission to use this endpoint.
Retrieve an existing Customer with its details, and a list of its associated Job API IDs. Note that customer profiles only exist for Jobs that are not in staging.
BasicAuth
| customerID required |
string
|
200
Retrieved Job resource for specified customerID successfully.
401
Authentication information is missing or invalid.
404
No Customer information found for the given customerID.
405
The resource doesn't support the specified HTTP verb.
409
API access is disabled. For further details, reach out to [email protected] or talk to your account manager.
422
Invalid request parameters.
default
An unexpected error occurred.
get/customers/id/{customerID}
Production Environment
https://app.cigotracker.com/api/v1/customers/id/{customerID}
Sandbox (Demo) Environment
https://app-demo.cigotracker.com/api/v1/customers/id/{customerID}
Content type application/json
Copy Expand all Collapse all
`{
"statusCode": 200,
"status": "OK",
"customer": {
"customer_id": "f4e922d54b98a878488d2754fd4cfc0e",
"full_name": "John Doe",
"phone_number": "(000) 000-0001",
"mobile_number": "(000) 000-0002",
"address": "275 Notre-Dame St. East, Montreal, QC, H2Y 1C6",
"coordinates": [
46.7727384, -71.3180309
],
"reference_id": "C-WJG178262",
"defaults": {
"time_preference": "AM",
"job_type": "delivery",
"branch_id": "S10",
"branch_api_id": "73de8cb492d22423a2a5a56f142b76b5",
"distribution_center_id": "DC12",
"distribution_center_api_id": "ba7ba295e3525fc61a4222d3674428db",
"comment": "A sample comment",
"quick_description": "Quick description here",
"handle_time": 25,
"email": "[email protected]",
"time_frame": {
"start": "9:00 AM",
"end": "11:00 AM"
}
},
"jobs": [ [
"f4e922d54b98a878488d2754fdvkd94", "kle946d54vvsgd4g88d2754fd4cfc0e"
]
]
}
}`
Access Restrictions
Sub-users with API access have permission to use this endpoint.
NOTE: Sub-users can only retrieve jobs they have created themselves.
Search for Customer API IDs using various criteria, with results limited to the first 20 matches. The following fields are supported:
Note: The search supports a combination of criteria and prioritizes exact matches where possible. If no matches are found, the response will indicate so.
Request Body Format:
BasicAuth
| name |
string <= 255 characters
Customer name (supports partial matches)
| | phone_number |
string <= 20 characters
Customer phone number
| | mobile_number |
string <= 20 characters
Customer mobile number
| | email |
string <email> <= 255 characters
Customer email
| | invoice |
string <= 255 characters
Invoice ID associated with a customer's job
| | customer_reference_id |
string <= 255 characters
Customer Reference ID
| | job_reference_id |
string <= 255 characters
Job Reference API ID related to the customer
|
200
Searched for Customer successfully
401
Authentication information is missing or invalid.
405
Unsupported HTTP verb.
409
API access is disabled. For further details, reach out to [email protected] or talk to your account manager.
422
Missing required fields or invalid value in request body.
default
An unexpected error occurred.
post/customers/search
Production Environment
https://app.cigotracker.com/api/v1/customers/search
Sandbox (Demo) Environment
https://app-demo.cigotracker.com/api/v1/customers/search
Content type application/json
Copy
`{
"name": "John Doe",
"phone_number": "+15062345678",
"mobile_number": "+15062345679",
"email": "[email protected]",
"invoice": "INV123456",
"customer_reference_id": "C-WJG178262",
"job_reference_id": "78522cd9b5f4cf0892da8e4744e8f48d"
}`
Content type application/json
Copy Expand all Collapse all
`{
"statusCode": 200,
"status": "OK",
"customers": [ {
"customer_id": "8c7e5825f440f48d284e9fd497acd8b2",
"full_name": "John Doe",
"reference_id": "C-WJG178262",
"phone_number": "+15062345678",
"mobile_number": "+15062345678",
"email": "[email protected]"
}
]
}`
Access Restrictions
Sub-users with API access DO NOT have permission to use this endpoint.
Retrieve the details of all itineraries for a given date.
BasicAuth
| date required |
string <date>
Example: 2024-08-01 or 2024-08-01T15:30:00-06:00
ISO-8601 date format.
|
200
Retrieved Itinerary resources for specified date successfully.
401
Authentication information is missing or invalid.
403
Access to the requested resource is forbidden.
409
API access is disabled. For further details, reach out to [email protected] or talk to your account manager.
422
Invalid date value.
default
An unexpected error occurred.
get/itineraries/date/{date}
Production Environment
https://app.cigotracker.com/api/v1/itineraries/date/{date}
Sandbox (Demo) Environment
https://app-demo.cigotracker.com/api/v1/itineraries/date/{date}
Content type application/json
Copy Expand all Collapse all
`{
"statusCode": 200,
"status": "OK",
"date": "2024-08-01",
"itineraries": [ {
"itinerary_id": "b53387df22645251aa9b22d24b7ec4a6",
"numeric_id": 984753,
"date": "2024-08-01",
"planned_departure_datetime": "2024-08-01 08:15:00",
"time": {
"timezone": "America/Toronto",
"planned_start_time": "2021-04-09 06:30 AM",
"planned_start_time_unix": 1617949800,
"actual_start_time": "2021-04-09 07:30 AM",
"actual_start_time_unix": 1617946200,
"create_time": "2021-04-14 14:52:04",
"create_time_unix": 1617946200,
"update_time": "2021-04-14 14:52:04",
"update_time_unix": 1617946200
},
"time_frame_size": 2.5,
"start_location": {
"id": "b53387df22645251aa9b22d24b7ec4a6",
"name": "Main Distribution Center",
"reference_id": "001",
"address": "1455 Boulevard de Maisonneuve O, Montréal, QC H3G 1M8",
"coordinates": [
46.7727384, -71.3180309
]
},
"end_location": {
"id": "b53387df22645251aa9b22d24b7ec4a6",
"name": "Main Distribution Center",
"reference_id": "001",
"address": "1455 Boulevard de Maisonneuve O, Montréal, QC H3G 1M8",
"coordinates": [
46.7727384, -71.3180309
]
},
"route_status_code": 200,
"route_error_message": 200,
"round_trip": true,
"route_metrics": {
"distance": 407222.73,
"road_time": 439,
"handle_time": 56,
"duration": 495,
"value": 500.98,
"weight": 1500.18,
"volume": 900.18,
"quantity": 233,
"piece_count": 401,
"pickup_handle_time": 401,
"pickup_value": 401.22,
"pickup_weight": 401.33,
"pickup_volume": 401.33,
"pickup_quantity": 40,
"pickup_piece_count": 40,
"drop_off_handle_time": 401,
"drop_off_value": 401.22,
"drop_off_weight": 401.33,
"drop_off_volume": 401.33,
"drop_off_quantity": 40,
"drop_off_piece_count": 40,
"est_road_time": 26340,
"est_distance": 407222.73
},
"route_options": {
"optimized_route": true,
"avoid_tolls": true,
"avoid_highways": false,
"avoid_ferries": true,
"consider_traffic": true,
"street_side": "right",
"min_jobs": 10,
"max_jobs": 40,
"max_driving_time": 40000,
"max_distance": 40000,
"time_windows_type": "preference",
"ignore_min_jobs": true,
"ignore_max_jobs": true,
"ignore_max_driving_time": true,
"ignore_max_distance": true,
"ignore_max_volume": true,
"ignore_max_weight": true
},
"vehicle": {
"id": "b53387df22645251aa9b22d24b7ec4a6",
"name": "HINO 00765",
"reference_id": "001",
"type": "small_truck",
"weight_capacity": "19500",
"volume_capacity": "800",
"license_plate": "C1G 0TR",
"breaks": [ {
"break_api_id": "brk_fisdoa6h3472cio7823hxcb7f8",
"vehicle_api_id": "veh_5e6bdf4bg923hx7f8io2",
"schedule_id": "itn_8h3472cio78_f6b8f2c",
"window_start": "08:15 AM",
"window_end": "10:30 AM",
"start_time": "08:15 AM",
"end_time": "10:00 AM",
"break_timing": "before_departure",
"duration": 30,
"active": 1,
"position": 4,
"created_at": "2025-11-07 12:00:00"
}
]
},
"operators": [ {
"id": "b53387df22645251aa9b22d24b7ec4a6",
"name": "John Doe",
"reference_id": "95874-CA",
"username": "[email protected]",
"last_active": "2024-08-01 08:54:48",
"avg_rate": "4.95",
"seat": 1,
"shifts": [ {
"start_time": "2024-08-01 08:15:58",
"end_time": "2024-08-01 14:35:12"
}
]
}
],
"stops_count": 1,
"stops": [ {
"job_id": "97867f09fca1a2614f4d52615c13ded7",
"stop_type": "job",
"job_type": "delivery",
"position": 1,
"branch_id": "S10",
"branch_api_id": "73de8cb492d22423a2a5a56f142b76b5",
"distribution_center_id": "DC12",
"distribution_center_api_id": "ba7ba295e3525fc61a4222d3674428db",
"status": "completed",
"address": "275 Notre-Dame St. East, Montreal, QC, H2Y 1C6",
"apartment": "Suite 101",
"postal_code": "H2Y 1C6",
"coordinates": [
46.7727384, -71.3180309
],
"quick_desc": "SAMPLE",
"route_metrics": {
"est_arrival_time": "2024-08-01 10:03:00",
"est_road_time": 26340,
"est_distance": 407222.73
},
"progress": {
"duration": 1063,
"start_datetime": "2024-08-01 09:23:21",
"end_datetime": "2024-08-01 09:41:04",
"started": true,
"finished": true
},
"related_jobs": ["f4e922d54b98a878488d2754fd4cfc0e" ]
}
],
"options": {
"label": "Morning Route",
"color": "#0000FF",
"note": {
"text": "Track the weather and extreme weather situations along your route, whether it's sunny, rainy, or snowing.",
"create_user": "John Doe",
"create_time": "2021-04-14 14:52:04",
"update_user": "Jane Doe",
"update_time": "2021-04-14 15:52:04"
}
}
}
]
}`
Access Restrictions
Sub-users with API access DO NOT have permission to use this endpoint.
Retrieve the details of all itineraries for a given Operator by it's API ID.
BasicAuth
| operator required |
string
Example: 56a5eb4a1b7b64d2d22232f74ca98523
Operator API ID
|
| start_date |
string <date>
Example: start_date=2024-08-01
ISO-8601 date format. If no value is given, the last 7 days will be retrieved. Required if end_date is provided. Maximum difference with end_date is 30 days.
| | end_date |
string <date>
Example: end_date=2024-08-01
ISO-8601 date format. If no value is given, the last 7 days will be retrieved. Required if start_date is provided. Maximum difference with start_date is 30 days.
|
200
Retrieved Itinerary resources for specified operator by API ID successfully.
401
Authentication information is missing or invalid.
403
Access to the requested resource is forbidden.
409
API Access is disabled.
default
An unexpected error occurred.
get/itineraries/operator/{operator}
Production Environment
https://app.cigotracker.com/api/v1/itineraries/operator/{operator}
Sandbox (Demo) Environment
https://app-demo.cigotracker.com/api/v1/itineraries/operator/{operator}
Content type application/json
Copy Expand all Collapse all
`{
"statusCode": 200,
"status": "OK",
"date": {
"start_date": "2024-08-01",
"end_date": "2024-09-15"
},
"itineraries": [ {
"itinerary_id": "b53387df22645251aa9b22d24b7ec4a6",
"numeric_id": 984753,
"date": "2024-08-01",
"planned_departure_datetime": "2024-08-01 08:15:00",
"time": {
"timezone": "America/Toronto",
"planned_start_time": "2021-04-09 06:30 AM",
"planned_start_time_unix": 1617949800,
"actual_start_time": "2021-04-09 07:30 AM",
"actual_start_time_unix": 1617946200,
"create_time": "2021-04-14 14:52:04",
"create_time_unix": 1617946200,
"update_time": "2021-04-14 14:52:04",
"update_time_unix": 1617946200
},
"time_frame_size": 2.5,
"start_location": {
"id": "b53387df22645251aa9b22d24b7ec4a6",
"name": "Main Distribution Center",
"reference_id": "001",
"address": "1455 Boulevard de Maisonneuve O, Montréal, QC H3G 1M8",
"coordinates": [
46.7727384, -71.3180309
]
},
"end_location": {
"id": "b53387df22645251aa9b22d24b7ec4a6",
"name": "Main Distribution Center",
"reference_id": "001",
"address": "1455 Boulevard de Maisonneuve O, Montréal, QC H3G 1M8",
"coordinates": [
46.7727384, -71.3180309
]
},
"route_status_code": 200,
"route_error_message": 200,
"round_trip": true,
"route_metrics": {
"distance": 407222.73,
"road_time": 439,
"handle_time": 56,
"duration": 495,
"value": 500.98,
"weight": 1500.18,
"volume": 900.18,
"quantity": 233,
"piece_count": 401,
"pickup_handle_time": 401,
"pickup_value": 401.22,
"pickup_weight": 401.33,
"pickup_volume": 401.33,
"pickup_quantity": 40,
"pickup_piece_count": 40,
"drop_off_handle_time": 401,
"drop_off_value": 401.22,
"drop_off_weight": 401.33,
"drop_off_volume": 401.33,
"drop_off_quantity": 40,
"drop_off_piece_count": 40,
"est_road_time": 26340,
"est_distance": 407222.73
},
"route_options": {
"optimized_route": true,
"avoid_tolls": true,
"avoid_highways": false,
"avoid_ferries": true,
"consider_traffic": true,
"street_side": "right",
"min_jobs": 10,
"max_jobs": 40,
"max_driving_time": 40000,
"max_distance": 40000,
"time_windows_type": "preference",
"ignore_min_jobs": true,
"ignore_max_jobs": true,
"ignore_max_driving_time": true,
"ignore_max_distance": true,
"ignore_max_volume": true,
"ignore_max_weight": true
},
"vehicle": {
"id": "b53387df22645251aa9b22d24b7ec4a6",
"name": "HINO 00765",
"reference_id": "001",
"type": "small_truck",
"weight_capacity": "19500",
"volume_capacity": "800",
"license_plate": "C1G 0TR",
"breaks": [ {
"break_api_id": "brk_fisdoa6h3472cio7823hxcb7f8",
"vehicle_api_id": "veh_5e6bdf4bg923hx7f8io2",
"schedule_id": "itn_8h3472cio78_f6b8f2c",
"window_start": "08:15 AM",
"window_end": "10:30 AM",
"start_time": "08:15 AM",
"end_time": "10:00 AM",
"break_timing": "before_departure",
"duration": 30,
"active": 1,
"position": 4,
"created_at": "2025-11-07 12:00:00"
}
]
},
"operators": [ {
"id": "b53387df22645251aa9b22d24b7ec4a6",
"name": "John Doe",
"reference_id": "95874-CA",
"username": "[email protected]",
"last_active": "2024-08-01 08:54:48",
"avg_rate": "4.95",
"seat": 1,
"shifts": [ {
"start_time": "2024-08-01 08:15:58",
"end_time": "2024-08-01 14:35:12"
}
]
}
],
"stops_count": 1,
"stops": [ {
"job_id": "97867f09fca1a2614f4d52615c13ded7",
"stop_type": "job",
"job_type": "delivery",
"position": 1,
"branch_id": "S10",
"branch_api_id": "73de8cb492d22423a2a5a56f142b76b5",
"distribution_center_id": "DC12",
"distribution_center_api_id": "ba7ba295e3525fc61a4222d3674428db",
"status": "completed",
"address": "275 Notre-Dame St. East, Montreal, QC, H2Y 1C6",
"apartment": "Suite 101",
"postal_code": "H2Y 1C6",
"coordinates": [
46.7727384, -71.3180309
],
"quick_desc": "SAMPLE",
"route_metrics": {
"est_arrival_time": "2024-08-01 10:03:00",
"est_road_time": 26340,
"est_distance": 407222.73
},
"progress": {
"duration": 1063,
"start_datetime": "2024-08-01 09:23:21",
"end_datetime": "2024-08-01 09:41:04",
"started": true,
"finished": true
},
"related_jobs": ["f4e922d54b98a878488d2754fd4cfc0e" ]
}
],
"options": {
"label": "Morning Route",
"color": "#0000FF",
"note": {
"text": "Track the weather and extreme weather situations along your route, whether it's sunny, rainy, or snowing.",
"create_user": "John Doe",
"create_time": "2021-04-14 14:52:04",
"update_user": "Jane Doe",
"update_time": "2021-04-14 15:52:04"
}
}
}
]
}`
Access Restrictions
Sub-users with API access DO NOT have permission to use this endpoint.
Retrieve the details of all itineraries for a given Vehicle by it's API ID.
BasicAuth
| vehicle required |
string
Example: bdca6e528b4324a2279d7ab25265431f
Vehicle API ID
|
| start_date |
string <date>
Example: start_date=2024-08-01
ISO-8601 date format. If no value is given, the last 7 days will be retrieved. Required if end_date is provided. Maximum difference with end_date is 30 days.
| | end_date |
string <date>
Example: end_date=2024-08-01
ISO-8601 date format. If no value is given, the last 7 days will be retrieved. Required if start_date is provided. Maximum difference with start_date is 30 days.
|
200
Retrieved Itinerary resources for specified vehicle by API ID successfully.
401
Authentication information is missing or invalid.
403
Access to the requested resource is forbidden.
409
API Access is disabled.
default
An unexpected error occurred.
get/itineraries/vehicle/{vehicle}
Production Environment
https://app.cigotracker.com/api/v1/itineraries/vehicle/{vehicle}
Sandbox (Demo) Environment
https://app-demo.cigotracker.com/api/v1/itineraries/vehicle/{vehicle}
Content type application/json
Copy Expand all Collapse all
`{
"statusCode": 200,
"status": "OK",
"date": {
"start_date": "2024-08-01",
"end_date": "2024-09-15"
},
"itineraries": [ {
"itinerary_id": "b53387df22645251aa9b22d24b7ec4a6",
"numeric_id": 984753,
"date": "2024-08-01",
"planned_departure_datetime": "2024-08-01 08:15:00",
"time": {
"timezone": "America/Toronto",
"planned_start_time": "2021-04-09 06:30 AM",
"planned_start_time_unix": 1617949800,
"actual_start_time": "2021-04-09 07:30 AM",
"actual_start_time_unix": 1617946200,
"create_time": "2021-04-14 14:52:04",
"create_time_unix": 1617946200,
"update_time": "2021-04-14 14:52:04",
"update_time_unix": 1617946200
},
"time_frame_size": 2.5,
"start_location": {
"id": "b53387df22645251aa9b22d24b7ec4a6",
"name": "Main Distribution Center",
"reference_id": "001",
"address": "1455 Boulevard de Maisonneuve O, Montréal, QC H3G 1M8",
"coordinates": [
46.7727384, -71.3180309
]
},
"end_location": {
"id": "b53387df22645251aa9b22d24b7ec4a6",
"name": "Main Distribution Center",
"reference_id": "001",
"address": "1455 Boulevard de Maisonneuve O, Montréal, QC H3G 1M8",
"coordinates": [
46.7727384, -71.3180309
]
},
"route_status_code": 200,
"route_error_message": 200,
"round_trip": true,
"route_metrics": {
"distance": 407222.73,
"road_time": 439,
"handle_time": 56,
"duration": 495,
"value": 500.98,
"weight": 1500.18,
"volume": 900.18,
"quantity": 233,
"piece_count": 401,
"pickup_handle_time": 401,
"pickup_value": 401.22,
"pickup_weight": 401.33,
"pickup_volume": 401.33,
"pickup_quantity": 40,
"pickup_piece_count": 40,
"drop_off_handle_time": 401,
"drop_off_value": 401.22,
"drop_off_weight": 401.33,
"drop_off_volume": 401.33,
"drop_off_quantity": 40,
"drop_off_piece_count": 40,
"est_road_time": 26340,
"est_distance": 407222.73
},
"route_options": {
"optimized_route": true,
"avoid_tolls": true,
"avoid_highways": false,
"avoid_ferries": true,
"consider_traffic": true,
"street_side": "right",
"min_jobs": 10,
"max_jobs": 40,
"max_driving_time": 40000,
"max_distance": 40000,
"time_windows_type": "preference",
"ignore_min_jobs": true,
"ignore_max_jobs": true,
"ignore_max_driving_time": true,
"ignore_max_distance": true,
"ignore_max_volume": true,
"ignore_max_weight": true
},
"vehicle": {
"id": "b53387df22645251aa9b22d24b7ec4a6",
"name": "HINO 00765",
"reference_id": "001",
"type": "small_truck",
"weight_capacity": "19500",
"volume_capacity": "800",
"license_plate": "C1G 0TR",
"breaks": [ {
"break_api_id": "brk_fisdoa6h3472cio7823hxcb7f8",
"vehicle_api_id": "veh_5e6bdf4bg923hx7f8io2",
"schedule_id": "itn_8h3472cio78_f6b8f2c",
"window_start": "08:15 AM",
"window_end": "10:30 AM",
"start_time": "08:15 AM",
"end_time": "10:00 AM",
"break_timing": "before_departure",
"duration": 30,
"active": 1,
"position": 4,
"created_at": "2025-11-07 12:00:00"
}
]
},
"operators": [ {
"id": "b53387df22645251aa9b22d24b7ec4a6",
"name": "John Doe",
"reference_id": "95874-CA",
"username": "[email protected]",
"last_active": "2024-08-01 08:54:48",
"avg_rate": "4.95",
"seat": 1,
"shifts": [ {
"start_time": "2024-08-01 08:15:58",
"end_time": "2024-08-01 14:35:12"
}
]
}
],
"stops_count": 1,
"stops": [ {
"job_id": "97867f09fca1a2614f4d52615c13ded7",
"stop_type": "job",
"job_type": "delivery",
"position": 1,
"branch_id": "S10",
"branch_api_id": "73de8cb492d22423a2a5a56f142b76b5",
"distribution_center_id": "DC12",
"distribution_center_api_id": "ba7ba295e3525fc61a4222d3674428db",
"status": "completed",
"address": "275 Notre-Dame St. East, Montreal, QC, H2Y 1C6",
"apartment": "Suite 101",
"postal_code": "H2Y 1C6",
"coordinates": [
46.7727384, -71.3180309
],
"quick_desc": "SAMPLE",
"route_metrics": {
"est_arrival_time": "2024-08-01 10:03:00",
"est_road_time": 26340,
"est_distance": 407222.73
},
"progress": {
"duration": 1063,
"start_datetime": "2024-08-01 09:23:21",
"end_datetime": "2024-08-01 09:41:04",
"started": true,
"finished": true
},
"related_jobs": ["f4e922d54b98a878488d2754fd4cfc0e" ]
}
],
"options": {
"label": "Morning Route",
"color": "#0000FF",
"note": {
"text": "Track the weather and extreme weather situations along your route, whether it's sunny, rainy, or snowing.",
"create_user": "John Doe",
"create_time": "2021-04-14 14:52:04",
"update_user": "Jane Doe",
"update_time": "2021-04-14 15:52:04"
}
}
}
]
}`
Access Restrictions
Sub-users with API access DO NOT have permission to use this endpoint.
Retrieve an Itinerary details by its ID.
BasicAuth
| itineraryID required |
string
|
200
Retrieved Itinerary resource for specified itineraryID successfully.
401
Authentication information is missing or invalid.
403
Access to the requested resource is forbidden.
404
No Itinerary found for given itineraryID.
409
API access is disabled. For further details, reach out to [email protected] or talk to your account manager.
422
Invalid request parameters.
default
An unexpected error occurred.
get/itineraries/id/{itineraryID}
Production Environment
https://app.cigotracker.com/api/v1/itineraries/id/{itineraryID}
Sandbox (Demo) Environment
https://app-demo.cigotracker.com/api/v1/itineraries/id/{itineraryID}
Content type application/json
Copy Expand all Collapse all
`{
"statusCode": 200,
"status": "OK",
"itinerary": {
"itinerary_id": "b53387df22645251aa9b22d24b7ec4a6",
"numeric_id": 984753,
"date": "2024-08-01",
"planned_departure_datetime": "2024-08-01 08:15:00",
"time": {
"timezone": "America/Toronto",
"planned_start_time": "2021-04-09 06:30 AM",
"planned_start_time_unix": 1617949800,
"actual_start_time": "2021-04-09 07:30 AM",
"actual_start_time_unix": 1617946200,
"create_time": "2021-04-14 14:52:04",
"create_time_unix": 1617946200,
"update_time": "2021-04-14 14:52:04",
"update_time_unix": 1617946200
},
"time_frame_size": 2.5,
"start_location": {
"id": "b53387df22645251aa9b22d24b7ec4a6",
"name": "Main Distribution Center",
"reference_id": "001",
"address": "1455 Boulevard de Maisonneuve O, Montréal, QC H3G 1M8",
"coordinates": [
46.7727384, -71.3180309
]
},
"end_location": {
"id": "b53387df22645251aa9b22d24b7ec4a6",
"name": "Main Distribution Center",
"reference_id": "001",
"address": "1455 Boulevard de Maisonneuve O, Montréal, QC H3G 1M8",
"coordinates": [
46.7727384, -71.3180309
]
},
"route_status_code": 200,
"route_error_message": 200,
"round_trip": true,
"route_metrics": {
"distance": 407222.73,
"road_time": 439,
"handle_time": 56,
"duration": 495,
"value": 500.98,
"weight": 1500.18,
"volume": 900.18,
"quantity": 233,
"piece_count": 401,
"pickup_handle_time": 401,
"pickup_value": 401.22,
"pickup_weight": 401.33,
"pickup_volume": 401.33,
"pickup_quantity": 40,
"pickup_piece_count": 40,
"drop_off_handle_time": 401,
"drop_off_value": 401.22,
"drop_off_weight": 401.33,
"drop_off_volume": 401.33,
"drop_off_quantity": 40,
"drop_off_piece_count": 40,
"est_road_time": 26340,
"est_distance": 407222.73
},
"route_options": {
"optimized_route": true,
"avoid_tolls": true,
"avoid_highways": false,
"avoid_ferries": true,
"consider_traffic": true,
"street_side": "right",
"min_jobs": 10,
"max_jobs": 40,
"max_driving_time": 40000,
"max_distance": 40000,
"time_windows_type": "preference",
"ignore_min_jobs": true,
"ignore_max_jobs": true,
"ignore_max_driving_time": true,
"ignore_max_distance": true,
"ignore_max_volume": true,
"ignore_max_weight": true
},
"vehicle": {
"id": "b53387df22645251aa9b22d24b7ec4a6",
"name": "HINO 00765",
"reference_id": "001",
"type": "small_truck",
"weight_capacity": "19500",
"volume_capacity": "800",
"license_plate": "C1G 0TR",
"breaks": [ {
"break_api_id": "brk_fisdoa6h3472cio7823hxcb7f8",
"vehicle_api_id": "veh_5e6bdf4bg923hx7f8io2",
"schedule_id": "itn_8h3472cio78_f6b8f2c",
"window_start": "08:15 AM",
"window_end": "10:30 AM",
"start_time": "08:15 AM",
"end_time": "10:00 AM",
"break_timing": "before_departure",
"duration": 30,
"active": 1,
"position": 4,
"created_at": "2025-11-07 12:00:00"
}
]
},
"operators": [ {
"id": "b53387df22645251aa9b22d24b7ec4a6",
"name": "John Doe",
"reference_id": "95874-CA",
"username": "[email protected]",
"last_active": "2024-08-01 08:54:48",
"avg_rate": "4.95",
"seat": 1,
"shifts": [ {
"start_time": "2024-08-01 08:15:58",
"end_time": "2024-08-01 14:35:12"
}
]
}
],
"stops_count": 1,
"stops": [ {
"job_id": "97867f09fca1a2614f4d52615c13ded7",
"stop_type": "job",
"job_type": "delivery",
"position": 1,
"branch_id": "S10",
"branch_api_id": "73de8cb492d22423a2a5a56f142b76b5",
"distribution_center_id": "DC12",
"distribution_center_api_id": "ba7ba295e3525fc61a4222d3674428db",
"status": "completed",
"address": "275 Notre-Dame St. East, Montreal, QC, H2Y 1C6",
"apartment": "Suite 101",
"postal_code": "H2Y 1C6",
"coordinates": [
46.7727384, -71.3180309
],
"quick_desc": "SAMPLE",
"route_metrics": {
"est_arrival_time": "2024-08-01 10:03:00",
"est_road_time": 26340,
"est_distance": 407222.73
},
"progress": {
"duration": 1063,
"start_datetime": "2024-08-01 09:23:21",
"end_datetime": "2024-08-01 09:41:04",
"started": true,
"finished": true
},
"related_jobs": ["f4e922d54b98a878488d2754fd4cfc0e" ]
}
],
"options": {
"label": "Morning Route",
"color": "#0000FF",
"note": {
"text": "Track the weather and extreme weather situations along your route, whether it's sunny, rainy, or snowing.",
"create_user": "John Doe",
"create_time": "2021-04-14 14:52:04",
"update_user": "Jane Doe",
"update_time": "2021-04-14 15:52:04"
}
}
}
}`
Access Restrictions
Sub-users with API access DO NOT have permission to use this endpoint.
Delete existing Itinerary while it has not started yet.
BasicAuth
| itineraryID required |
string
|
204
Deleted Itinerary resource for specified itineraryID successfully.
401
Authentication information is missing or invalid.
404
The Itinerary for the given itineraryID could not be found.
409
API access is disabled. For further details, reach out to [email protected] or talk to your account manager.
422
Invalid request parameters.
default
An unexpected error occurred.
delete/itineraries/id/{itineraryID}
Production Environment
https://app.cigotracker.com/api/v1/itineraries/id/{itineraryID}
Sandbox (Demo) Environment
https://app-demo.cigotracker.com/api/v1/itineraries/id/{itineraryID}
Content type application/json
Copy
`{
"statusCode": 401,
"status": "Unauthorized",
"error": "Unauthorized authentication credentials."
}`
Access Restrictions
Sub-users with API access DO NOT have permission to use this endpoint.
Update an existing Itinerary while it has not completed yet.
BasicAuth
| itineraryID required |
string
|
| start_time |
string <time>
Enum: "12:00 AM" "12:30 AM" "8:00 AM" "11:45 PM"
Start Time.
| | time_frame_size |
number
Enum: 0 1 1.5 2 2.5 3 3.5 4 4.5 5 5.5 6
Set the approximate Time Frame on each Job (hour).
Note : In order to be able to use this property, the relevant toggle in the General Options section of the Company Settings must be enabled.
| | vehicle_id |
string
Vehicle ID.
| | bypass_zone_capacity_rules |
boolean
If 'true', Zone Capacity limit validation will not run. This flag will only work if the Users have permission to bypass Capacity Management validations.
| | vehicle_breaks |
Array of objects (VehicleBreaksAPIModel) <= 3
List of Schedule Vehicle Breaks configuration for this itinerary.
| | start_point |
ID (object) or Coordinates (object) or Address (object)
Start Location.
| | end_point |
ID (object) or Coordinates (object) or Address (object)
End Location.
| | routing_info |
object (Options)
Routing Information.
| | operators |
Array of objects (Operator model) <= 4
List of Operators to be assigned to the Itinerary. By default, you can assign a maximum of 4 operators. This limit may vary from 1 to 15 depending on your account settings.
| | options |
object (Options)
| | add_ids |
Array of strings
List of Job IDs to be assigned to the Itinerary.
Note : This list of Job IDs should not include Jobs that have already been assigned to another itinerary. If you need to move a job from one itinerary to another, you must first remove it from the itinerary it is currently assigned to.
| | delete_ids |
Array of strings
List of Job IDs (stop_type is equal to job) to be removed from the Itinerary. Notes :
stop_type is equal to pickup or dropoff) cannot be deleted by Job ID, in order to delete an On Route Stop, include all the associated Job IDs from the related_jobs property;status must be equal to new.| | include_stops_sequence |
boolean
Default: false
If set to true, the response will include the ordered list of stops of this itinerary as an array of Job IDs.
|
200
Updated Itinerary resource for specified itineraryID successfully.
204
Jobs resources for specified delete_ids were removed from specified itineraryID and the Itinerary was deleted successfully.
401
Authentication information is missing or invalid.
404
No Itinerary found for given itineraryID.
409
API access is disabled. For further details, reach out to [email protected] or talk to your account manager.
422
Invalid request parameters.
default
An unexpected error occurred.
patch/itineraries/id/{itineraryID}
Production Environment
https://app.cigotracker.com/api/v1/itineraries/id/{itineraryID}
Sandbox (Demo) Environment
https://app-demo.cigotracker.com/api/v1/itineraries/id/{itineraryID}
Content type application/json
Copy Expand all Collapse all
`{
"start_time": "08:30 AM",
"time_frame_size": 1.5,
"vehicle_id": "b53387df22645251aa9b22d24b7ec4a6",
"bypass_zone_capacity_rules": "false",
"vehicle_breaks": [ {
"window_start": "12:00 PM",
"window_end": "2:00 PM",
"duration": 30,
"break_timing": "custom_time"
}
],
"start_point": { "id": "b53387df22645251aa9b22d24b7ec4a6"
},
"end_point": { "id": "b53387df22645251aa9b22d24b7ec4a6"
},
"routing_info": {
"avoid_tolls": false,
"avoid_highways": false,
"avoid_ferries": false,
"consider_traffic": false,
"street_side": "any",
"optimized_route": true,
"ignore_min_jobs": false,
"ignore_max_jobs": false,
"ignore_max_driving_time": false,
"ignore_max_distance": false,
"ignore_max_volume": false,
"ignore_max_weight": false,
"min_jobs": 10,
"max_jobs": 40,
"max_driving_time": 40000,
"max_distance": 40000,
"time_windows_type": "preference"
},
"operators": [ {
"id": "b53387df22645251aa9b22d24b7ec4a6",
"seat": 1
}
],
"options": {
"label": "Morning Route",
"color": "#0000FF",
"note": "Track the weather and extreme weather situations along your route, whether it's sunny, rainy, or snowing."
},
"add_ids": ["f4e922d54b98a878488d2754fd4cfc0e" ],
"delete_ids": ["0347f675958fb0c0208d5d928c7b28c3" ],
"include_stops_sequence": false
}`
Content type application/json
Copy Expand all Collapse all
`{
"statusCode": 200,
"status": "OK",
"itinerary_id": "75bf34f9dd1c325a4542fcda7eb05794",
"message": "Updated Itinerary resource for specified itineraryID successfully.",
"warnings": [ {
"warning_code": 904901,
"field": "consider_traffic",
"message": "No route could be calculated with requested 'Consider Traffic' option.",
"details": {
"original_value": true,
"value": false
}
}
]
}`
Access Restrictions
Sub-users with API access DO NOT have permission to use this endpoint.
Retrieve an itinerary’s polyline GeoJSON by the itinerary API ID.
BasicAuth
| itineraryID required |
string
|
200
Retrieved Itinerary polyline GEOJson for specified itineraryID successfully.
401
Authentication information is missing or invalid.
403
Access to the requested resource is forbidden.
404
No Itinerary found for given itineraryID.
409
API Access is disabled.
422
Invalid request parameters.
default
An unexpected error occurred.
get/itineraries/id/{itineraryID}/polyline
Production Environment
https://app.cigotracker.com/api/v1/itineraries/id/{itineraryID}/polyline
Sandbox (Demo) Environment
https://app-demo.cigotracker.com/api/v1/itineraries/id/{itineraryID}/polyline
Content type application/json
Copy Expand all Collapse all
`{
"statusCode": 200,
"status": "OK",
"geojson": {
"type": "LineString",
"coordinates": [
46.7727384, -71.3180309
]
}
}`
Access Restrictions
- This endpoint is available only if access has been enabled for your account. For further details, please reach out to your account manager.
Sub-users with API access DO NOT have permission to use this endpoint.
Preview an Itinerary.
BasicAuth
| date required |
string <date>
ISO-8601 date format indicating when the Itinerary is scheduled for. This date cannot be in the past (today or later, based on your timezone).
- Format: Year-Month-Day (YYYY-MM-DD)
- Optional: Timezone offset:
- If a timezone is included, it requires time to specify exact date
- Timezone can be added with +HH:MM or -HH:MM offset (e.g. 2024-08-01T15:30:00-06:00 or 2024-08-01T15:30:00+06:00)
| | start_time required |
string <time>
Enum: "12:00 AM" "12:30 AM" "8:00 AM" "11:45 PM"
Start Time.
| | time_frame_size |
number
Enum: 0 1 1.5 2 2.5 3 3.5 4 4.5 5 5.5 6
Set the approximate Time Frame on each Job (hour). Note : In order to be able to use this property, the relevant toggle in the General Options section of the Company Settings must be enabled.
| | vehicle_id required |
string
Vehicle ID.
| | vehicle_breaks |
Array of objects (VehicleBreaksAPIModel) <= 3
List of Schedule Vehicle Breaks configuration for this itinerary.
| | start_point required |
ID (object) or Coordinates (object) or Address (object)
Start Location.
| | bypass_zone_capacity_rules |
boolean
If 'true', Zone Capacity limit validation will not run. This flag will only work if the Users have permission to bypass Capacity Management validations.
| | end_point required |
ID (object) or Coordinates (object) or Address (object)
End Location.
| | routing_info |
object (Options)
Routing Information.
| | job_ids |
Array of strings <= 150
List of Job IDs to be reviewed (maximum 150 Jobs including potential on route stops). Note : This list of Job IDs should not include Jobs that have already been assigned to another itinerary. If you need to move a job from one itinerary to another, you must first remove it from the itinerary it is currently assigned to.
| | stops |
Array of objects (Stop model) <= 150
List of Stops (Non-Cigo Jobs). Note : If the request contains the job_ids array that is not empty, the stops array of objects will be ignored.
|
200
Success.
401
Authentication information is missing or invalid.
403
Access to the requested resource is forbidden or disabled by administrator.
409
API access is disabled. For further details, reach out to [email protected] or talk to your account manager.
422
Invalid request parameters.
default
An unexpected error occurred.
post/itineraries/action/previewRoute
Production Environment
https://app.cigotracker.com/api/v1/itineraries/action/previewRoute
Sandbox (Demo) Environment
https://app-demo.cigotracker.com/api/v1/itineraries/action/previewRoute
Content type application/json
Copy Expand all Collapse all
`{
"date": "2024-08-01",
"start_time": "08:30 AM",
"time_frame_size": 1.5,
"vehicle_id": "b53387df22645251aa9b22d24b7ec4a6",
"vehicle_breaks": [ {
"window_start": "12:00 PM",
"window_end": "2:00 PM",
"duration": 30,
"break_timing": "custom_time"
}
],
"start_point": { "id": "b53387df22645251aa9b22d24b7ec4a6"
},
"bypass_zone_capacity_rules": "false",
"end_point": { "id": "b53387df22645251aa9b22d24b7ec4a6"
},
"routing_info": {
"avoid_tolls": false,
"avoid_highways": false,
"avoid_ferries": false,
"consider_traffic": false,
"street_side": "any",
"optimized_route": true,
"ignore_min_jobs": false,
"ignore_max_jobs": false,
"ignore_max_driving_time": false,
"ignore_max_distance": false,
"ignore_max_volume": false,
"ignore_max_weight": false,
"min_jobs": 10,
"max_jobs": 40,
"max_driving_time": 40000,
"max_distance": 40000,
"time_windows_type": "preference"
},
"job_ids": ["f4e922d54b98a878488d2754fd4cfc0e" ],
"stops": [ {
"id": "stop0123",
"coordinates": [
45.5449878, -73.6603738
],
"address": "9850 rue Saint-Urbain Montréal, QC",
"name": "deliver box",
"locked": false,
"handle_time": 10,
"value": 1149.96,
"weight": 120.5,
"volume": 2.75,
"piece_count": 1,
"quantity": 2,
"time_preference": "AM",
"time_frame": {
"start": "09:00 AM",
"end": "11:00 AM"
}
}
]
}`
Content type application/json
Copy Expand all Collapse all
`{
"statusCode": 200,
"status": "OK",
"itinerary": {
"itinerary_id": "b53387df22645251aa9b22d24b7ec4a6",
"date": "2024-08-01",
"time": {
"timezone": "America/Toronto",
"planned_start_time": "2021-04-09 06:30 AM",
"planned_start_time_unix": 1617949800,
"actual_start_time": "2021-04-09 07:30 AM",
"actual_start_time_unix": 1617946200,
"create_time": "2021-04-14 14:52:04",
"create_time_unix": 1617946200,
"update_time": "2021-04-14 14:52:04",
"update_time_unix": 1617946200
},
"time_frame_size": 2.5,
"start_location": {
"id": "b53387df22645251aa9b22d24b7ec4a6",
"name": "Main Distribution Center",
"reference_id": "001",
"address": "1455 Boulevard de Maisonneuve O, Montréal, QC H3G 1M8",
"coordinates": [
46.7727384, -71.3180309
]
},
"end_location": {
"id": "b53387df22645251aa9b22d24b7ec4a6",
"name": "Main Distribution Center",
"reference_id": "001",
"address": "1455 Boulevard de Maisonneuve O, Montréal, QC H3G 1M8",
"coordinates": [
46.7727384, -71.3180309
]
},
"route_status_code": 200,
"route_error_message": 200,
"round_trip": true,
"route_metrics": {
"distance": 407222.73,
"road_time": 439,
"handle_time": 56,
"duration": 495,
"value": 500.98,
"weight": 1500.18,
"volume": 900.18,
"quantity": 233,
"piece_count": 401,
"pickup_handle_time": 401,
"pickup_value": 401.22,
"pickup_weight": 401.33,
"pickup_volume": 401.33,
"pickup_quantity": 40,
"pickup_piece_count": 40,
"drop_off_handle_time": 401,
"drop_off_value": 401.22,
"drop_off_weight": 401.33,
"drop_off_volume": 401.33,
"drop_off_quantity": 40,
"drop_off_piece_count": 40,
"est_road_time": 26340,
"est_distance": 407222.73
},
"route_options": {
"optimized_route": true,
"avoid_tolls": true,
"avoid_highways": false,
"avoid_ferries": true,
"consider_traffic": true,
"street_side": "right",
"min_jobs": 10,
"max_jobs": 40,
"max_driving_time": 40000,
"max_distance": 40000,
"time_windows_type": "preference",
"ignore_min_jobs": true,
"ignore_max_jobs": true,
"ignore_max_driving_time": true,
"ignore_max_distance": true,
"ignore_max_volume": true,
"ignore_max_weight": true
},
"vehicle": {
"id": "b53387df22645251aa9b22d24b7ec4a6",
"name": "HINO 00765",
"reference_id": "001",
"type": "small_truck",
"weight_capacity": "19500",
"volume_capacity": "800",
"license_plate": "C1G 0TR",
"breaks": [ {
"break_api_id": "brk_fisdoa6h3472cio7823hxcb7f8",
"vehicle_api_id": "veh_5e6bdf4bg923hx7f8io2",
"schedule_id": "itn_8h3472cio78_f6b8f2c",
"window_start": "08:15 AM",
"window_end": "10:30 AM",
"start_time": "08:15 AM",
"end_time": "10:00 AM",
"break_timing": "before_departure",
"duration": 30,
"active": 1,
"position": 4,
"created_at": "2025-11-07 12:00:00"
}
]
},
"operators": [ {
"id": "b53387df22645251aa9b22d24b7ec4a6",
"name": "John Doe",
"reference_id": "95874-CA",
"username": "[email protected]",
"last_active": "2024-08-01 08:54:48",
"avg_rate": "4.95",
"seat": 1,
"shifts": [ {
"start_time": "2024-08-01 08:15:58",
"end_time": "2024-08-01 14:35:12"
}
]
}
],
"stops_count": 1,
"stops": [ {
"id": "stop0123",
"stop_type": "job",
"locked": false,
"name": "deliver box",
"coordinates": [
46.7727384, -71.3180309
],
"address": "275 Notre-Dame St. East, Montreal, QC",
"position": 1,
"road_time": 439,
"road_distance": 439,
"eta": "09:30 AM",
"handle_time": 10,
"value": 1149.96,
"weight": 120.5,
"volume": 2.75,
"piece_count": 1,
"quantity": 2,
"time_preference": "AM",
"time_frame": {
"start": "09:00 AM",
"end": "11:00 AM"
},
"related_jobs": ["f4e922d54b98a878488d2754fd4cfc0e" ]
}
],
"warnings": [ {
"warning_code": 904901,
"field": "consider_traffic",
"message": "No route could be calculated with requested 'Consider Traffic' option.",
"details": {
"original_value": true,
"value": false
}
}
]
}
}`
Access Restrictions
Sub-users with API access DO NOT have permission to use this endpoint.
Build an Itinerary.
BasicAuth
| date required |
string <date>
ISO-8601 date format indicating when the Itinerary is scheduled for. This date cannot be in the past (today or later, based on your timezone).
- Format: Year-Month-Day (YYYY-MM-DD)
- Optional: Timezone offset:
- If a timezone is included, it requires time to specify exact date
- Timezone can be added with +HH:MM or -HH:MM offset (e.g. 2024-08-01T15:30:00-06:00 or 2024-08-01T15:30:00+06:00)
| | start_time required |
string <time>
Enum: "12:00 AM" "12:30 AM" "8:00 AM" "11:45 PM"
Start Time.
| | bypass_zone_capacity_rules |
boolean
If 'true', Zone Capacity limit validation will not run. This flag will only work if the Users have permission to bypass Capacity Management validations.
| | time_frame_size |
number
Enum: 0 1 1.5 2 2.5 3 3.5 4 4.5 5 5.5 6
Set the approximate Time Frame on each Job (hour). Note : In order to be able to use this property, the relevant toggle in the General Options section of the Company Settings must be enabled.
| | vehicle_id required |
string
Vehicle ID.
| | vehicle_breaks |
Array of objects (VehicleBreaksAPIModel) <= 3
List of Schedule Vehicle Breaks configuration for this itinerary.
| | start_point required |
ID (object) or Coordinates (object) or Address (object)
Start Location.
| | end_point required |
ID (object) or Coordinates (object) or Address (object)
End Location.
| | routing_info |
object (Options)
Routing Information.
| | operators |
Array of objects (Operator model) <= 4
List of Operators to be assigned to the Itinerary. By default, you can assign a maximum of 4 operators. This limit may vary from 1 to 15 depending on your account settings.
| | options |
object (Options)
| | add_ids required |
Array of strings <= 150
List of Job IDs to be assigned to the Itinerary (maximum 150 Jobs including potential on route stops). Note : This list of Job IDs should not include Jobs that have already been assigned to another itinerary. If you need to move a job from one itinerary to another, you must first remove it from the itinerary it is currently assigned to.
| | include_stops_sequence |
boolean
Default: false
If set to true, the response will include the ordered list of stops of this itinerary as an array of Job IDs.
|
200
Itinerary was created successfully.
401
Authentication information is missing or invalid.
409
API access is disabled. For further details, reach out to [email protected] or talk to your account manager.
422
Invalid request parameters.
default
An unexpected error occurred.
post/itineraries
Production Environment
https://app.cigotracker.com/api/v1/itineraries
Sandbox (Demo) Environment
https://app-demo.cigotracker.com/api/v1/itineraries
Content type application/json
Copy Expand all Collapse all
`{
"date": "2024-08-01",
"start_time": "08:30 AM",
"bypass_zone_capacity_rules": "false",
"time_frame_size": 1.5,
"vehicle_id": "b53387df22645251aa9b22d24b7ec4a6",
"vehicle_breaks": [ {
"window_start": "12:00 PM",
"window_end": "2:00 PM",
"duration": 30,
"break_timing": "custom_time"
}
],
"start_point": { "id": "b53387df22645251aa9b22d24b7ec4a6"
},
"end_point": { "id": "b53387df22645251aa9b22d24b7ec4a6"
},
"routing_info": {
"avoid_tolls": false,
"avoid_highways": false,
"avoid_ferries": false,
"consider_traffic": false,
"street_side": "any",
"optimized_route": true,
"ignore_min_jobs": false,
"ignore_max_jobs": false,
"ignore_max_driving_time": false,
"ignore_max_distance": false,
"ignore_max_volume": false,
"ignore_max_weight": false,
"min_jobs": 10,
"max_jobs": 40,
"max_driving_time": 40000,
"max_distance": 40000,
"time_windows_type": "preference"
},
"operators": [ {
"id": "b53387df22645251aa9b22d24b7ec4a6",
"seat": 1
}
],
"options": {
"label": "Morning Route",
"color": "#0000FF",
"note": "Track the weather and extreme weather situations along your route, whether it's sunny, rainy, or snowing."
},
"add_ids": ["f4e922d54b98a878488d2754fd4cfc0e" ],
"include_stops_sequence": false
}`
Content type application/json
Copy Expand all Collapse all
`{
"statusCode": 201,
"status": "Created",
"message": "Successfully created an Itinerary. Save 'itinerary_id' to refer to this Itinerary in other operations.",
"itinerary_id": "75bf34f9dd1c325a4542fcda7eb05794",
"warnings": [ {
"warning_code": 904901,
"field": "consider_traffic",
"message": "No route could be calculated with requested 'Consider Traffic' option.",
"details": {
"original_value": true,
"value": false
}
}
]
}`
Access Restrictions
Sub-users with API access DO NOT have permission to use this endpoint.
Delete assigned Job while it has not started yet.
Note : On Route Stop (stop_type is equal to pickup or dropoff) cannot be deleted by Job ID, in order to delete an On Route Stop, delete all the associated Jobs that are listed in the related_jobs property.
BasicAuth
| itineraryID required |
string
| | jobID required |
string
|
204
Un-assigned Job resource from specified itineraryID for specified jobID successfully.
401
Authentication information is missing or invalid.
404
Either the Itinerary for the given itineraryID or the Job for the given jobID could not be found.
409
API access is disabled. For further details, reach out to [email protected] or talk to your account manager.
422
Invalid request parameters.
default
An unexpected error occurred.
delete/itineraries/id/{itineraryID}/job_id/{jobID}
Production Environment
https://app.cigotracker.com/api/v1/itineraries/id/{itineraryID}/job\_id/{jobID}
Sandbox (Demo) Environment
https://app-demo.cigotracker.com/api/v1/itineraries/id/{itineraryID}/job\_id/{jobID}
Content type application/json
Copy
`{
"statusCode": 401,
"status": "Unauthorized",
"error": "Unauthorized authentication credentials."
}`
Access Restrictions
Sub-users with API access DO NOT have permission to use this endpoint.
Update Operators.
BasicAuth
| itineraryID required |
string
|
| operators required |
Array of objects (Operator model)
Assign a list of Operators to specified Itinerary. By default, you can assign a maximum of 4 operators. This limit may vary from 1 to 15 depending on your account settings. Note : This action will remove existing Operators that have been assigned to specified Itinerary.
|
200
Operators were updated successfully.
401
Authentication information is missing or invalid.
404
One or more operator IDs are invalid or do not exist
409
API access is disabled. For further details, reach out to [email protected] or talk to your account manager.
422
Invalid request parameters.
default
An unexpected error occurred.
patch/itineraries/id/{itineraryID}/action/updateOperators
Production Environment
https://app.cigotracker.com/api/v1/itineraries/id/{itineraryID}/action/updateOperators
Sandbox (Demo) Environment
https://app-demo.cigotracker.com/api/v1/itineraries/id/{itineraryID}/action/updateOperators
Content type application/json
Copy Expand all Collapse all
`{ "operators": [ {
"id": "b53387df22645251aa9b22d24b7ec4a6",
"seat": 1
}
]
}`
Content type application/json
Copy
`{
"statusCode": 200,
"status": "OK",
"message": "Updated Operators resource for specified itineraryID successfully."
}`
Access Restrictions
Sub-users with API access DO NOT have permission to use this endpoint.
Unassign specific operators from an existing itinerary that has not yet been completed. When using URI parameters to unassign operators, you can specify multiple Operator API IDs as a comma-delimited list.
BasicAuth
| itineraryID required |
string
| | operatorID required |
string
|
204
Un-assigned Operators resource for specified itineraryID successfully.
401
Authentication information is missing or invalid.
404
Either the Itinerary for the given itineraryID or the Operators for the given operatorID could not be found.
409
API access is disabled. For further details, reach out to [email protected] or talk to your account manager.
422
Invalid request parameters.
default
An unexpected error occurred.
delete/itineraries/id/{itineraryID}/action/unassignOperators/operator_ids/{operatorID}
Production Environment
Sandbox (Demo) Environment
Content type application/json
Copy
`{
"statusCode": 401,
"status": "Unauthorized",
"error": "Unauthorized authentication credentials."
}`
Access Restrictions
Sub-users with API access DO NOT have permission to use this endpoint.
Change position of a single Job/Stop while it has not been starter/completed.
BasicAuth
| itineraryID required |
string
| | jobID required |
string
| | position required |
integer
|
200
Stop was moved successfully.
401
Authentication information is missing or invalid.
409
API access is disabled. For further details, reach out to [email protected] or talk to your account manager.
422
Invalid request parameters.
default
An unexpected error occurred.
patch/itineraries/id/{itineraryID}/job_id/{jobID}/position/{position}
Production Environment
https://app.cigotracker.com/api/v1/itineraries/id/{itineraryID}/job\_id/{jobID}/position/{position}
Sandbox (Demo) Environment
Content type application/json
Copy
`{
"statusCode": 200,
"status": "OK",
"message": "Changed Stop position for specified itineraryID successfully."
}`
Access Restrictions
Sub-users with API access DO NOT have permission to use this endpoint.
Change positions of a all Stops.
BasicAuth
| itineraryID required |
string
|
| stops required |
Array of strings unique
list of Job IDs in order of new Positions.
Note : Position of Started and/or Completed Stops cannot be changed.
|
200
Stop was moved successfully.
401
Authentication information is missing or invalid.
409
API access is disabled. For further details, reach out to [email protected] or talk to your account manager.
422
Invalid request parameters.
default
An unexpected error occurred.
patch/itineraries/id/{itineraryID}/action/updatePositions
Production Environment
https://app.cigotracker.com/api/v1/itineraries/id/{itineraryID}/action/updatePositions
Sandbox (Demo) Environment
https://app-demo.cigotracker.com/api/v1/itineraries/id/{itineraryID}/action/updatePositions
Content type application/json
Copy Expand all Collapse all
`{ "stops": ["f4e922d54b98a878488d2754fd4cfc0e" ]
}`
Content type application/json
Copy
`{
"statusCode": 200,
"status": "OK",
"message": "Changed Stops positions for specified itineraryID successfully."
}`
Access Restrictions
Sub-users with API access DO NOT have permission to use this endpoint.
Reverse order of Stops (not Started/Completed) of an existing itinerary.
BasicAuth
| itineraryID required |
string
|
200
Order of Stops was reversed successfully.
401
Authentication information is missing or invalid.
409
API access is disabled. For further details, reach out to [email protected] or talk to your account manager.
422
Invalid request parameters.
default
An unexpected error occurred.
patch/itineraries/id/{itineraryID}/action/reversePositions
Production Environment
https://app.cigotracker.com/api/v1/itineraries/id/{itineraryID}/action/reversePositions
Sandbox (Demo) Environment
https://app-demo.cigotracker.com/api/v1/itineraries/id/{itineraryID}/action/reversePositions
Content type application/json
Copy
`{
"statusCode": 200,
"status": "OK",
"message": "Reversed Stops for specified itineraryID successfully."
}`
Remove an existing break window for the specified vehicle in the specified route.
BasicAuth
| itineraryID required |
string
Itinerary API identifier (e.g., itn_fisdoa6h3472cio7823hxcb7f8).
| | vehicleID required |
string
Vehicle API identifier (e.g., veh_5e6bdf4bg923hx7f8io2).
| | breakID required |
string
Break API identifier (e.g., brk_fisdoa6h3472cio7823hxcb7f8).
|
204
Break deleted successfully. No content returned.
401
Authentication information is missing or invalid.
403
Forbidden for sub-users with API access.
404
Itinerary, Vehicle, or Break not found.
409
API access is disabled.
delete/itineraries/id/{itineraryID}/vehicles/id/{vehicleID}/breaks/{breakID}
Production Environment
Sandbox (Demo) Environment
Content type application/json
Copy
`{
"statusCode": 401,
"status": "Unauthorized",
"error": "Unauthorized authentication credentials."
}`
Access Restrictions
Sub-users with API access DO NOT have permission to use this endpoint.
Retrieve the details of all locations.
BasicAuth
200
Retrieved Location resources successfully.
401
Authentication information is missing or invalid.
404
No Location found.
409
API access is disabled. For further details, reach out to [email protected] or talk to your account manager.
default
An unexpected error occurred.
get/locations
Production Environment
https://app.cigotracker.com/api/v1/locations
Sandbox (Demo) Environment
https://app-demo.cigotracker.com/api/v1/locations
Content type application/json
Copy Expand all Collapse all
`{
"statusCode": 200,
"status": "OK",
"locations": [ {
"id": "b53387df22645251aa9b22d24b7ec4a6",
"type": "branch",
"name": "Main Distribution Center",
"reference_id": "001",
"address": "1455 Boulevard de Maisonneuve O, Montréal, QC H3G 1M8",
"postal_code": "H3G 1M8",
"coordinates": [
46.7727384, -71.3180309
],
"activated": true
}
]
}`
Access Restrictions
Sub-users with API access DO NOT have permission to use this endpoint.
Create a new Location.
BasicAuth
| type required |
string
Enum: "branch" "warehouse"
The type of the location.
| | name required |
string <= 256
Location name.
| | ref_no |
string <= 60
The reference number of the location. This is usually an identifier from an external system.
| | geolocation required |
Coordinates (object) or Address (object)
The geolocation of this Location.
|
201
Successfully created a new Location.
400
Property {property} is required.
405
Setting the property {property} is not allowed.
409
API access is disabled. For further details, reach out to [email protected] or talk to your account manager.
422
Invalid request parameters.
default
An unexpected error occurred.
post/locations
Production Environment
https://app.cigotracker.com/api/v1/locations
Sandbox (Demo) Environment
https://app-demo.cigotracker.com/api/v1/locations
Content type application/json
Copy Expand all Collapse all
`{
"type": "branch",
"name": "Main branch",
"ref_no": "1abd2l5k8",
"geolocation": { "coordinates": [
46.7727384, -71.3180309
]
}
}`
Content type application/json
Copy
`{
"statusCode": 201,
"status": "Created",
"location_id": "75bf34f9dd1c325a4542fcda7eb05794"
}`
Access Restrictions
Sub-users with API access DO NOT have permission to use this endpoint.
Retrieve a Location details by its ID.
BasicAuth
| locationID required |
string
|
200
Retrieved Location resource for specified locationID successfully.
401
Authentication information is missing or invalid.
404
No Location found for given locationID.
409
API access is disabled. For further details, reach out to [email protected] or talk to your account manager.
422
Invalid request parameters.
default
An unexpected error occurred.
get/locations/id/{locationID}
Production Environment
https://app.cigotracker.com/api/v1/locations/id/{locationID}
Sandbox (Demo) Environment
https://app-demo.cigotracker.com/api/v1/locations/id/{locationID}
Content type application/json
Copy Expand all Collapse all
`{
"statusCode": 200,
"status": "OK",
"location": {
"id": "b53387df22645251aa9b22d24b7ec4a6",
"type": "branch",
"name": "Main Distribution Center",
"reference_id": "001",
"address": "1455 Boulevard de Maisonneuve O, Montréal, QC H3G 1M8",
"postal_code": "H3G 1M8",
"coordinates": [
46.7727384, -71.3180309
],
"activated": true
}
}`
Access Restrictions
Sub-users with API access DO NOT have permission to use this endpoint.
Update Location.
BasicAuth
| locationID required |
string
|
| active |
boolean
Enum: true false
Choose false to deactivate the location and true for activation.
| | type |
string
Enum: "branch" "warehouse"
The type of the location.
| | name |
string <= 256
Location name.
| | ref_no |
string <= 60
The reference number of the location. This is usually an identifier from an external system.
| | geolocation |
Coordinates (object) or Address (object)
The geolocation of this Location.
|
200
Updated Location resource for specified location id successfully.
400
Unknown property {property}.
404
No Location found for given location id.
405
Setting the property {property} is not allowed.
409
API access is disabled. For further details, reach out to [email protected] or talk to your account manager.
422
Invalid request parameters.
default
An unexpected error occurred.
patch/locations/id/{locationID}
Production Environment
https://app.cigotracker.com/api/v1/locations/id/{locationID}
Sandbox (Demo) Environment
https://app-demo.cigotracker.com/api/v1/locations/id/{locationID}
Content type application/json
Copy Expand all Collapse all
`{
"active": true,
"type": "warehouse",
"name": "New warehouse",
"ref_no": "1abd2l5k8",
"geolocation": { "coordinates": [
46.7727384, -71.3180309
]
}
}`
Content type application/json
Copy
`{
"statusCode": 200,
"status": "Ok",
"message": "Updated Location resource for specified location id successfully."
}`
Access Restrictions
Sub-users with API access DO NOT have permission to use this endpoint.
Retrieve the details of all Vehicles.
BasicAuth
200
Retrieved Vehicle resources successfully.
401
Authentication information is missing or invalid.
404
No Vehicle found.
409
API access is disabled. For further details, reach out to [email protected] or talk to your account manager.
default
An unexpected error occurred.
get/vehicles
Production Environment
https://app.cigotracker.com/api/v1/vehicles
Sandbox (Demo) Environment
https://app-demo.cigotracker.com/api/v1/vehicles
Content type application/json
Copy Expand all Collapse all
`{
"statusCode": 200,
"status": "OK",
"vehicles": [ {
"id": "b53387df22645251aa9b22d24b7ec4a6",
"name": "HINO 00765",
"reference_id": "001",
"type": "small_truck",
"weight_capacity": "19500",
"volume_capacity": "800",
"license_plate": "C1G 0TR",
"start_time": "08:00 AM",
"start_location": {
"id": "b53387df22645251aa9b22d24b7ec4a6",
"type": "branch",
"name": "Main Distribution Center",
"reference_id": "001",
"address": "1455 Boulevard de Maisonneuve O, Montréal, QC H3G 1M8",
"postal_code": "H3G 1M8",
"coordinates": [
46.7727384, -71.3180309
],
"activated": true
},
"end_location": {
"id": "b53387df22645251aa9b22d24b7ec4a6",
"type": "branch",
"name": "Main Distribution Center",
"reference_id": "001",
"address": "1455 Boulevard de Maisonneuve O, Montréal, QC H3G 1M8",
"postal_code": "H3G 1M8",
"coordinates": [
46.7727384, -71.3180309
],
"activated": true
},
"activated": true,
"breaks": [ {
"break_api_id": "brk_fisdoa6h3472cio7823hxcb7f8",
"vehicle_api_id": "veh_5e6bdf4bg923hx7f8io2",
"window_start": "01:30 PM",
"window_end": "03:15 PM",
"break_timing": "before_departure",
"duration": 30,
"created_at": "2025-11-07 12:00:00"
}
]
}
]
}`
Access Restrictions
Sub-users with API access DO NOT have permission to use this endpoint.
Retrieve a Vehicle details by its ID.
BasicAuth
| vehicleID required |
string
|
200
Retrieved Vehicle resource for specified vehicleID successfully.
401
Authentication information is missing or invalid.
404
No Vehicle found for given vehicleID.
409
API access is disabled. For further details, reach out to [email protected] or talk to your account manager.
422
Invalid request parameters.
default
An unexpected error occurred.
get/vehicles/id/{vehicleID}
Production Environment
https://app.cigotracker.com/api/v1/vehicles/id/{vehicleID}
Sandbox (Demo) Environment
https://app-demo.cigotracker.com/api/v1/vehicles/id/{vehicleID}
Content type application/json
Copy Expand all Collapse all
`{
"statusCode": 200,
"status": "OK",
"vehicle": {
"id": "b53387df22645251aa9b22d24b7ec4a6",
"name": "HINO 00765",
"reference_id": "001",
"type": "small_truck",
"weight_capacity": "19500",
"volume_capacity": "800",
"license_plate": "C1G 0TR",
"start_time": "08:00 AM",
"start_location": {
"id": "b53387df22645251aa9b22d24b7ec4a6",
"type": "branch",
"name": "Main Distribution Center",
"reference_id": "001",
"address": "1455 Boulevard de Maisonneuve O, Montréal, QC H3G 1M8",
"postal_code": "H3G 1M8",
"coordinates": [
46.7727384, -71.3180309
],
"activated": true
},
"end_location": {
"id": "b53387df22645251aa9b22d24b7ec4a6",
"type": "branch",
"name": "Main Distribution Center",
"reference_id": "001",
"address": "1455 Boulevard de Maisonneuve O, Montréal, QC H3G 1M8",
"postal_code": "H3G 1M8",
"coordinates": [
46.7727384, -71.3180309
],
"activated": true
},
"activated": true,
"breaks": [ {
"break_api_id": "brk_fisdoa6h3472cio7823hxcb7f8",
"vehicle_api_id": "veh_5e6bdf4bg923hx7f8io2",
"window_start": "01:30 PM",
"window_end": "03:15 PM",
"break_timing": "before_departure",
"duration": 30,
"created_at": "2025-11-07 12:00:00"
}
]
}
}`
Access Restrictions
Sub-users with API access DO NOT have permission to use this endpoint.
Get all break windows configured for a vehicle by its ID.
BasicAuth
| vehicleID required |
string
Vehicle API identifier (string like fisdoa6h3472cio7823hxcb7f8).
|
200
Break windows retrieved successfully.
401
Authentication information is missing or invalid.
403
Forbidden for sub-users with API access.
404
No Vehicle found for given vehicleID.
409
API access is disabled. For further details, reach out to [email protected] or talk to your account manager.
422
Invalid request parameters.
default
An unexpected error occurred.
get/vehicles/id/{vehicleID}/breaks
Production Environment
https://app.cigotracker.com/api/v1/vehicles/id/{vehicleID}/breaks
Sandbox (Demo) Environment
https://app-demo.cigotracker.com/api/v1/vehicles/id/{vehicleID}/breaks
Content type application/json
Copy Expand all Collapse all
`{ "breaks": [
{
"break_api_id": "brk_fisdoa6h3472cio7823hxcb7f8",
"vehicle_api_id": "veh_5e6bdf4bg923hx7f8io2",
"window_start": "02:30 PM",
"window_end": "04:15 PM",
"break_timing": "custom_time",
"duration": 30,
"created_at": "2025-11-07 12:00:00"
},
{
"break_api_id": "brk_ah27d8g4n38f0s92kx0",
"vehicle_api_id": "veh_5e6bdf4bg923hx7f8io2",
"window_start": "08:00 AM",
"window_end": "09:00 AM",
"break_timing": "before_departure",
"duration": 30,
"created_at": "2025-11-07 12:30:00"
}
]
}`
Access Restrictions
Sub-users with API access DO NOT have permission to use this endpoint.
Create a new break window for a vehicle. A vehicle can have up to 3 break windows.
BasicAuth
| vehicleID required |
string
Vehicle API identifier (string like fisdoa6h3472cio7823hxcb7f8).
|
| window_start |
string
Earliest time of day when the break can start (hh:mm AM/PM). The system may schedule the break to begin anytime after this time. This field is required only when break_timing is set to custom_time and must be aligned with 15-minute intervals (allowed minutes: 00, 15, 30, 45).
| | window_end |
string
Latest time of day by which the break must be finished (hh:mm AM/PM). The system ensures the break ends before or at this time. This field is required only when break_timing is set to custom_time and must be aligned with 15-minute intervals (allowed minutes: 00, 15, 30, 45).
| | duration required |
integer [1 .. 120]
Duration of the break in minutes. Once started, the break lasts this long
| | break_timing required |
string (VehicleBreakTiming)
Enum: "before_departure" "custom_time" "after_itinerary_end"
When the break should happen.
custom_time: Requires both window_start and window_end. Defines a custom break period during the route
before_departure: Defines a break that occurs before departure, such as rest or preparation time before the itinerary begins.
after_itinerary_end: Defines a break that occurs after the itinerary ends, such as rest period or wrap-up time once the final stop has been completed.
|
201
Break created successfully.
400
Malformed body or JSON.
401
Authentication information is missing or invalid.
403
Forbidden for sub-users with API access.
404
No Vehicle found for given vehicleID.
409
API access is disabled.
422
Validation failed (e.g., overlapping windows, invalid time order, duration out of range, or max breaks reached).
post/vehicles/id/{vehicleID}/breaks
Production Environment
https://app.cigotracker.com/api/v1/vehicles/id/{vehicleID}/breaks
Sandbox (Demo) Environment
https://app-demo.cigotracker.com/api/v1/vehicles/id/{vehicleID}/breaks
Content type application/json
Copy
`{
"window_start": "12:00 PM",
"window_end": "02:30 PM",
"duration": 30,
"break_timing": "custom_time"
}`
Content type application/json
Copy
`{
"break_api_id": "brk_fisdoa6h3472cio7823hxcb7f8",
"vehicle_api_id": "veh_5e6bdf4bg923hx7f8io2",
"window_start": "01:30 PM",
"window_end": "03:15 PM",
"break_timing": "before_departure",
"duration": 30,
"created_at": "2025-11-07 12:00:00"
}`
Access Restrictions
Sub-users with API access DO NOT have permission to use this endpoint.
Update fields of an existing break window for a vehicle.
BasicAuth
| vehicleID required |
string
Vehicle API identifier (string like fisdoa6h3472cio7823hxcb7f8).
| | breakID required |
string
Break API identifier (e.g., brk_fisdoa6h3472cio7823hxcb7f8).
|
| window_start |
string
Earliest time of day when the break can start (hh:mm AM/PM). The system may schedule the break to begin anytime after this time. This field is required only when break_timing is set to custom_time and must be aligned with 15-minute intervals (allowed minutes: 00, 15, 30, 45).
| | window_end |
string
Latest time of day by which the break must be finished (hh:mm AM/PM). The system ensures the break ends before or at this time. This field is required only when break_timing is set to custom_time and must be aligned with 15-minute intervals (allowed minutes: 00, 15, 30, 45).
| | duration |
integer [1 .. 120]
Duration of the break in minutes. Once started, the break lasts this long
| | break_timing |
string (VehicleBreakTiming)
Enum: "before_departure" "custom_time" "after_itinerary_end"
When the break should happen.
custom_time: Requires both window_start and window_end. Defines a custom break period during the route
before_departure: Defines a break that occurs before departure, such as rest or preparation time before the itinerary begins.
after_itinerary_end: Defines a break that occurs after the itinerary ends, such as rest period or wrap-up time once the final stop has been completed.
|
200
Break updated successfully.
401
Authentication information is missing or invalid.
403
Forbidden for sub-users with API access.
404
Vehicle or Break not found.
409
API access is disabled.
422
Validation failed (e.g., overlapping windows, invalid time order, duration out of range, or max breaks reached).
put/vehicles/id/{vehicleID}/breaks/{breakID}
Production Environment
https://app.cigotracker.com/api/v1/vehicles/id/{vehicleID}/breaks/{breakID}
Sandbox (Demo) Environment
https://app-demo.cigotracker.com/api/v1/vehicles/id/{vehicleID}/breaks/{breakID}
Content type application/json
Copy
`{
"duration": 30,
"break_timing": "before_departure"
}`
Content type application/json
Copy
`{
"break_api_id": "brk_fisdoa6h3472cio7823hxcb7f8",
"vehicle_api_id": "veh_5e6bdf4bg923hx7f8io2",
"window_start": "01:30 PM",
"window_end": "03:15 PM",
"break_timing": "before_departure",
"duration": 30,
"created_at": "2025-11-07 12:00:00"
}`
Access Restrictions
Sub-users with API access DO NOT have permission to use this endpoint.
Remove an existing break window for a vehicle.
BasicAuth
| vehicleID required |
string
Vehicle API identifier (string like fisdoa6h3472cio7823hxcb7f8).
| | breakID required |
string
Break API identifier (string like brk_7e6b8f2c8a).
|
204
Break deleted successfully. No content returned.
401
Authentication information is missing or invalid.
403
Forbidden for sub-users with API access.
404
Vehicle or Break not found.
409
API access is disabled.
delete/vehicles/id/{vehicleID}/breaks/{breakID}
Production Environment
https://app.cigotracker.com/api/v1/vehicles/id/{vehicleID}/breaks/{breakID}
Sandbox (Demo) Environment
https://app-demo.cigotracker.com/api/v1/vehicles/id/{vehicleID}/breaks/{breakID}
Content type application/json
Copy
`{
"statusCode": 401,
"status": "Unauthorized",
"error": "Unauthorized authentication credentials."
}`
Access Restrictions
Sub-users with API access DO NOT have permission to use this endpoint.
Retrieve the details of all Operators.
BasicAuth
200
Retrieved Operator resources successfully.
401
Authentication information is missing or invalid.
404
No Operator found.
409
API access is disabled. For further details, reach out to [email protected] or talk to your account manager.
default
An unexpected error occurred.
get/operators
Production Environment
https://app.cigotracker.com/api/v1/operators
Sandbox (Demo) Environment
https://app-demo.cigotracker.com/api/v1/operators
Content type application/json
Copy Expand all Collapse all
`{
"statusCode": 200,
"status": "OK",
"operators": [ {
"id": "b53387df22645251aa9b22d24b7ec4a6",
"name": "John Doe",
"reference_id": "95874-CA",
"username": "[email protected]",
"phone_number": "+1347XXXXXXX",
"language": "en",
"timezone": "America/New_York",
"last_active": "2024-08-01 08:54:48",
"avg_rate": "4.95",
"activated": true
}
]
}`
Access Restrictions
Sub-users with API access DO NOT have permission to use this endpoint.
Create a new Operator.
BasicAuth
| full_name required |
string <= 256
Operator first and last name.
| | email required |
string <email> <= 128
The operator's email address.
| | password required |
string >= 10
The operator's login password.
| | reference_id |
string <= 30
Employee ID from an external system.
|
201
Successfully created a new Operator.
400
Property {property} is required.
405
Setting the property {property} is not allowed.
409
API access is disabled. For further details, reach out to [email protected] or talk to your account manager.
422
Invalid request parameters.
default
An unexpected error occurred.
post/operators
Production Environment
https://app.cigotracker.com/api/v1/operators
Sandbox (Demo) Environment
https://app-demo.cigotracker.com/api/v1/operators
Content type application/json
Copy
`{
"full_name": "John Doe",
"email": "[email protected]",
"password": "9g125ak141l9a",
"reference_id": "1ABD2l5K8"
}`
Content type application/json
Copy
`{
"statusCode": 201,
"status": "Created",
"operator_id": "6c89f32048f964a88f3da6b16abc43d4"
}`
Access Restrictions
Sub-users with API access DO NOT have permission to use this endpoint.
Retrieve an Operator details by its ID.
BasicAuth
| operatorID required |
string
|
200
Retrieved Operator resource for specified OperatorID successfully.
401
Authentication information is missing or invalid.
404
No Operator found for given OperatorID.
409
API access is disabled. For further details, reach out to [email protected] or talk to your account manager.
422
Invalid request parameters.
default
An unexpected error occurred.
get/operators/id/{operatorID}
Production Environment
https://app.cigotracker.com/api/v1/operators/id/{operatorID}
Sandbox (Demo) Environment
https://app-demo.cigotracker.com/api/v1/operators/id/{operatorID}
Content type application/json
Copy Expand all Collapse all
`{
"statusCode": 200,
"status": "OK",
"operator": {
"id": "b53387df22645251aa9b22d24b7ec4a6",
"name": "John Doe",
"reference_id": "95874-CA",
"username": "[email protected]",
"phone_number": "+1347XXXXXXX",
"language": "en",
"timezone": "America/New_York",
"last_active": "2024-08-01 08:54:48",
"avg_rate": "4.95",
"activated": true
}
}`
Access Restrictions
Sub-users with API access DO NOT have permission to use this endpoint.
Update Operator.
BasicAuth
| operatorID required |
string
|
| active |
boolean
Enum: true false
Change the status of the Operator user. Set it to false to deactivate the operator's access and true for activation. Setting it to false will block their access.
| | full_name |
string <= 256
Operator first and last name.
| | email |
string <email> <= 128
The operator's email address.
| | password |
string
The operator's login new password.
| | reference_id |
string <= 30
Employee ID from an external system.
|
200
Updated Operator resource for specified Operator API ID successfully.
400
Unknown property {property}.
404
No Operator found for given Operator API ID.
405
Setting the property {property} is not allowed.
409
API access is disabled. For further details, reach out to [email protected] or talk to your account manager.
422
Invalid request parameters.
default
An unexpected error occurred.
patch/operators/id/{operatorID}
Production Environment
https://app.cigotracker.com/api/v1/operators/id/{operatorID}
Sandbox (Demo) Environment
https://app-demo.cigotracker.com/api/v1/operators/id/{operatorID}
Content type application/json
Copy
`{
"active": true,
"full_name": "John Doe",
"email": "[email protected]",
"password": "9ka68f1mb3a",
"reference_id": "1ABD2l5K8"
}`
Content type application/json
Copy
`{
"statusCode": 200,
"status": "Ok",
"message": "Updated Operator resource for specified Operator API ID successfully."
}`
Access Restrictions
Sub-users with API access have permission to use this endpoint.
NOTE: Sub-users can only retrieve geofencing events of jobs they have created themselves; otherwise, they will receive a 403 Forbidden response.
Retrieve all Job geofencing events.
BasicAuth
| job_id required |
string
|
200
List with first and last Geofence entries and all events related to specified Job.
400
Invalid ID type.
401
Authentication information is missing or invalid.
403
Access to the requested resource is forbidden.
404
Job not found.
405
Method not allowed.
default
An unexpected error occurred.
get/geofencing/job_id/{job_id}
Production Environment
https://app.cigotracker.com/api/v1/geofencing/job\_id/{job\_id}
Sandbox (Demo) Environment
https://app-demo.cigotracker.com/api/v1/geofencing/job\_id/{job\_id}
Content type application/json
Copy Expand all Collapse all
`{
"statusCode": 200,
"status": "OK",
"geofence_events": [ {
"operator_full_Name": "John Doe",
"arrival": "08:00:00 AM",
"departure": "10:00:00 AM"
}
],
"first_geofence_entry": "03:00:00 AM",
"last_geofence_exit": "03:10:00 AM"
}`
Access Restrictions
- This endpoint is available only if access has been enabled for your account. For further details, please reach out to your account manager.
Sub-users with API access DO NOT have permission to use this endpoint.
Retrieve available booking dates for a given geolocation or address.
BasicAuth
| geolocation |
string
Example: geolocation=40.7128,-74.0060
Geolocation coordinates in the format latitude,longitude. If not provided, the address parameter is required.
| | address |
string
Address to get geolocation coordinates. If not provided, the geolocation parameter is required. Within this field, include the following ( delimited by commas ):
| | year_and_month |
string
Example: year_and_month=2024-12
Year and month in the format YYYY-MM.
| | days_ahead |
integer
Example: days_ahead=30
Number of days ahead to look for available booking dates. By default this is set to 90 days.
| | weight |
number <float>
Example: weight=10.5
Weight of the job.
| | volume |
number <float>
Example: volume=2.5
Volume of the job.
| | handle_time |
number <integer>
Example: handle_time=25
Handle time of the job.
| | days_offset |
integer
Example: days_offset=5
Minimum number of days ahead for available booking dates.
|
200
Retrieved available booking dates successfully.
401
Authentication information is missing or invalid.
403
Access to requested resource is forbidden.
404
No available dates found.
409
API Access is disabled.
default
An unexpected error occurred.
get/available-booking-dates
Production Environment
https://app.cigotracker.com/api/v1/available-booking-dates
Sandbox (Demo) Environment
https://app-demo.cigotracker.com/api/v1/available-booking-dates
Content type application/json
Copy Expand all Collapse all
`{
"statusCode": 200,
"status": "OK",
"available_booking_dates": ["2023-10-15" ]
}`
Access Restrictions
- This endpoint is available only if access has been enabled for your account. For further details, please reach out to your account manager.
Sub-users with API access DO NOT have permission to use this endpoint.
Retrieve available slots for a given geolocation and date.
BasicAuth
| date required |
string
Example: date=2024-12-12
Date for which to get available slots in the format YYYY-MM-DD.
| | geolocation required |
string
Example: geolocation=40.7128,-74.0060
Geolocation coordinates in the format latitude,longitude.
|
200
Retrieved available slots successfully.
400
Invalid date format or geolocation.
403
Access to requested resource is forbidden.
404
No available slots found.
default
An unexpected error occurred.
get/available-slots
Production Environment
https://app.cigotracker.com/api/v1/available-slots
Sandbox (Demo) Environment
https://app-demo.cigotracker.com/api/v1/available-slots
Content type application/json
Copy
`{
"max_jobs": 10,
"available_jobs_slots": 5,
"max_weight": 200,
"available_weight_slots": 150.5,
"max_volume": 100,
"available_volume_slots": 75.3
}`