{ "openapi": "3.0.0", "info": { "title": "Cigo Tracker API", "description": "# Introduction\n\nWelcome 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.\n\nOn the right hand side, you can navigate all available resources along with the responses each API endpoint produces.\n\n## What can you do with our API?\nThe Cigo Tracker API enables you to:\n- Create, retrieve, update and delete Jobs\n- Create, retrieve, update and delete Actions related to Jobs\n- Create, retrieve, update and delete Itineraries\n - This also allows you to dynamically preview potential Itinerary routes, assign operators, vehicles, and change stop positions\n- Retrieve Locations, Vehicles and Operators created within the platform\n\n## API Connections\n### Production\nFor API connections in the production environment, specify the URL: https://app.cigotracker.com\n### Sandbox (Demo)\nFor API connections in the sandbox environment, specify the URL: https://app-demo.cigotracker.com\n\n **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.\n\n## Webhooks\nAfter enabling the API, you can [manage webhooks from the web portal](/webhook/manage) to monitor the following system actions:\n\n### Job-related events\n- All Job status changes\n- Independent Job status changes: In Progress, Completed, Incomplete, Partially Completed, Damaged, Resolved, Cancelled\n- Job creation, information updates, and assignation to itinerary\n- Job Action creation, information updates (excluding status changes) or deletion via the Operator mobile app\n\n### Itinerary-related events\n- Itinerary creation (including when cloned from the Planner page)\n- Itinerary updates (triggered by changes to stops, assigned vehicle, start or end location, or assigned operators)\n- Itinerary deletion\n\n#### Notes\n- At this time, you cannot manage your webhooks via the API\n- You must login as the Administrator of the account to [enable the API](/public-api/settings) and [manage webhooks](/webhook/manage)\n\n\n## Webhooks Signature Verification\n\nRelay 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`.\n\n### Headers Overview\nWhen receiving a webhook message, your application should expect two headers:\n\n#### `X-Cigo-Tracker-Timestamp`\n\nThe timestamp of when the message was sent.\n\n#### `X-Cigo-Tracker-Signature`\n\nA digital signature generated using the API secret key, API account ID, message body and timestamp\n\n### Using Custom Webhook Credentials\nCigo allows Provider Administrators (or Super Admins managing them) to configure a **Custom Webhook ID** and a **Custom Webhook Secret**.\n\n* **Custom Webhook ID**: If configured, this value will be used by Cigo.\n* **Custom Webhook Secret**: If configured, this value will be used by Cigo.\n\nIf these custom values are set, they will override the standard Public API Account ID and Secret Key.\nYou can configure these custom values in your Provider Settings within the Cigo platform, under the `Public API` section in settings.\n\n### Important: Handling Changes to Custom Webhook ID or Secret\nWhen you update your `Custom Webhook ID` or `Custom Webhook Secret` in the Cigo Provider Settings, please be aware of the following:\n\n* **New Signatures Only**: Cigo will immediately start using the **new** Custom Webhook ID and/or Secret to generate the `X-Cigo-Tracker-Signature` for all subsequent webhook events.\n\n### Why Canonicalize JSON Using JCS?\nCigo uses the **JSON Canonicalization Scheme (JCS)** to ensure all parties compute signatures on an identical, platform-independent JSON encoding.\n\n#### What is JCS?\nJCS mandates:\n- **Lexicographic key sorting:** \n All keys in every object must appear in sorted order.\n- **Consistent number formatting:** \n No redundant zeros, correct exponent notation.\n- **Standard string escaping:** \n Only necessary characters are escaped, per Unicode and ECMAScript rules.\n- **No extra whitespace and object key uniqueness:** \n The output contains no unnecessary whitespace, and all object properties must be unique.\n\nThis ensures that signature generation is **deterministic**: \nAny JCS-compliant library in any language will produce the identical canonical JSON string for the same data.\n\n- **Reference:** [RFC 8785 – JSON Canonicalization Scheme (JCS)](https://datatracker.ietf.org/doc/rfc8785/)\n\n#### Why does this matter for signatures?\nStandard JSON encoding can differ by whitespace, key order, or encoding choices, causing signature mismatches across platforms. \nBy 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.\n\n### Verification Process\nTo verify the authenticity and prevent relay attacks, follow these steps:\n\n#### Generate your own signature\n1. Determine Credentials to Use:\n * **API Account ID (`$api_account_id_to_use`)**:\n * If you have configured a `Custom Webhook ID` in your Cigo Provider Settings, use that value.\n * Otherwise, use your standard Public API Account ID.\n * **Secret Key (`$secret_key_to_use`)**:\n * If you have configured a `Custom Webhook Secret` in your Cigo Provider Settings, use that value (the plain text secret).\n * Otherwise, use your standard Public API Secret Key.\n2. Prepare the Signature String:\n * Let `$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.\n * Let `$timestamp` be the integer value from the `X-Cigo-Tracker-Timestamp` header.\n * Concatenate the API Account ID to use, the payload, and the timestamp, using a colon (`:`) as a delimiter.\n\n```\n$message = $api_account_id_to_use . ':' . $payload . ':' . $timestamp;\n```\n\n3. Compute the signature:\n - Using your `Public API Secret Key`, generate an `HMAC SHA-256` hash of the `$message`:\n\n ```php\n $signature = hash_hmac('sha256', $message, $secret_key_to_use, true);\n ```\n\n4. Encode the signature:\n - Base64-encode the resulting `HMAC SHA-256` hash:\n\n ```php\n $encoded_signature = base64_encode($signature);\n ```\n\n### Example Code\n```php\n// Generate your own signature\nfunction generateSignature($api_account_id, $payload, $timestamp, $secret_key) {\n $formatted = $api_account_id . ':' . $payload . ':' . $timestamp;\n return base64_encode(hash_hmac('sha256', $formatted, $secret_key, true));\n}\n\n// Extract information\n$timestamp = intval($_SERVER['HTTP_X_CIGO_TRACKER_TIMESTAMP']);\n\n// Other information\n$api_account_id = 'your-api-account-id'\n$secret_key = 'your-api-secret-key';\n$payload = json_decode('webhook-response-data');\n\n$signature = generateSignature($api_account_id, $payload, $timestamp, $secret_key);\n\n// Validate message\n// Compare generated signature with provided X-Cigo-Tracker-Signature header value\nif ($signature == $_SERVER['HTTP_X_CIGO_TRACKER_SIGNATURE']) {\n // Check if timestamp is within 5 minutes of the current timestamp\n $current_timestamp = time();\n if ((abs($timestamp - $current_timestamp) / 60) <= 300) { // 300 seconds -> 5 minutes\n echo('Message is valid and not a relay attack.');\n }\n} else {\n echo('Invalid signature, consider re-sending the message.');\n}\n```\n\n## Key Concepts & FAQ\nThere are some key Cigo concepts to understand in order to easily navigate documentation and use our API.\n\n#### What is a Job?\nA [Job](#tag/job) is a general term used in Cigo to describe a destination, such as a Customer, where your Operator(s) may do a\ndelivery, a service call, an installation, or various Job Actions (see explanation on 'Job Action' below).\n\nWhen 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.\nOnce you've landed on the Import Tool page, you'll find your created API records under the 'Review records from API Integration' tab.\n\nDispatcher 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.\n\nHowever, 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](#tag/job/paths/~1jobs/post)).\n\nJob statuses range from:\n- `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.\n- `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.\n- `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.\n- `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.\n- `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.\n- `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`.\n- `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.\n- `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.\n- `cancelled`: This status marks that the job has been cancelled and won't be done in this route anymore.\n\n#### What is a Job Action?\nA Job can be assigned any number of [Actions](#tag/action). These Actions serve as a to-do list for the Operator arriving on site\n(i.e. a customer's location). Actions have types (i.e. `delivery`, `installation`, `service`, etc.) and other attributes,\nsuch as handle time (the amount of time the action is estimated to take).\n\nJob Action statuses range from:\n- `undetermined`: No status has been set for this Job Action yet. This is the default state.\n- `completed`: This Job Action has been fulfilled without any issues.\n- `incomplete`: This Job Action could not be fulfilled.\n- `damaged`: An incident is related to this Job Action.\n\n#### How are Customer profiles created and updated?\nWhen you create a new Job, an existing Customer profile is either linked or created. Customer profiles are created or updated\nbased on a Job's first name, last name, phone number, and address fields.\n\nWhen you first create a Job, you can assign a Customer Reference ID. When you create new Jobs assigned to the same\nCustomer Reference ID, it'll keep all of them associated with the same Customer.\n\n##### Can I create or update a Customer profile without creating or updating a Job?\nNo, you cannot. Within the web interface, there are a few things you can update on an existing Customer profile, but\nthis is not currently available via the API.\n\n#### Sometimes when I create a new Job, I get a 409 Conflict. What does it mean?\nIn order to prevent duplicate orders from being entered into Cigo Tracker, we prevent orders with the same core\ninformation from being re-entered. For example, if you have an order with the same first name, last name, address, and\ndelivery date, we detect it as a duplicate job and prevent its creation.\n\nThis default behaviour may not be suitable for your business if you can receive multiples orders per day by the same customer.\nIn that case, setting a unique `reference_id` during the Job creation process will allow you to workaround this restriction.\nIf you have a unique Order ID from an external system (e.g. Shopify), you can use that in your `reference_id` field and\nCigo Tracker will ignore the duplicate check.\n\n#### Jobs were created via the API, but I can't find them anywhere.\nIf you did not specify `skip_staging: true` in your POST call to create a Job, it'll be created in the `staging` status.\n\nYou'll only be able to find this Job by logging into the Cigo Tracker web portal, opening the sidebar menu and navigating\nthe Import Tool page. Once you've landed on the Import Tool page, you'll find your created Job records under the\n'Review records from API Integration' tab.\n\n#### What are Pickups and Drop-offs? How are they created?\nPickups and Drop-offs are automatically generated by Cigo. Every Pickup and Drop-off is directly corelated to a Job Action\nvia its `stop_location_id`. For instance, if a Job has an Action of type 'pickup' with a valid `stop_location_id`,\nonce an Itinerary is created by your Dispatcher, a Pickup will automatically be created to indicate that it must be\ndone prior to the related Job.\n\n#### What is an Itinerary?\nAn [Itinerary](#tag/itinerary) is a detailed list of ordered Route Stops; including it's initial start and final return location,\nestimated time of departure, as well as the assigned Operator(s) and Vehicle.\n\n#### What is a Stop?\nA Stop, or Route Stop, is simply a geographical location on an Itinerary and it can either a Job, a Pickup, or a Drop-off.\n\n#### What is an Operator?\nAn Operator is an individual assigned to an Itinerary. For instance, if your company handles the delivery of goods, you\nmay already internally refer to your Operators as Drivers, as opposed to Technicians in other industries.\nOperators interact with Cigo via our mobile application.\n\n#### What is a Dispatcher?\nA Dispatcher is a web platform user that is able to create Itineraries, create Jobs, Actions, and has direct access to the\nStaging Area (inside of Cigo, the Staging Area is referred to as the 'Import Tool').\n\n#### What is a Sub-user?\nA sub-user represents an authorized merchant who has restricted access to the API. Access to the API is limited to merchants at Level 2.\nWhen making requests, sub-users are subject to validation and filtering based on their assigned Locations.\n\n#### General Notes\n\n- Unless specified otherwise, time and datetime values returned by the API are in GMT (UTC+00:00).\n\n### Diagram\nHere's a Key Concepts Diagram to help you visualize how some of the concepts explained above correlate to one another.\n\n![Key Concepts Diagram](/reference/cigo-diagram.png)\n\n#### I still have questions!\nIf you still have questions, feel free to shoot us an email: api.support@cigotracker.com\n", "contact": { "name": "API Support", "email": "api.support@cigotracker.com" }, "version": "1.11.1", "x-tagGroups": [ { "name": "Credentials Validation", "tags": [ "auth" ] }, { "name": "Job", "tags": [ "job" ] }, { "name": "Job Action", "tags": [ "action" ] }, { "name": "Itinerary", "tags": [ "itinerary" ] }, { "name": "Location", "tags": [ "location" ] }, { "name": "Vehicle", "tags": [ "vehicle" ] }, { "name": "Operator", "tags": [ "operator" ] }, { "name": "Geofencing", "tags": [ "geofencing" ] }, { "name": "Capacity Management", "tags": [ "capacity_management" ] } ] }, "servers": [ { "url": "https://app.cigotracker.com/api/v1", "description": "Production Environment" }, { "url": "https://app-demo.cigotracker.com/api/v1", "description": "Sandbox (Demo) Environment" } ], "paths": { "/ping": { "get": { "tags": [ "auth" ], "summary": "Validate Credentials", "description": "\n> #### Access Restrictions\n> ##### Sub-users with API access have permission to use this endpoint.\n\nCheck that your authentication credentials are valid.", "responses": { "200": { "description": "A sample response validating your authentication credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PingResponse" } } } }, "401": { "description": "Authentication information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedResponse" } } } }, "409": { "description": "API access is disabled. For further details, reach out to api.support@cigotracker.com or talk to your account manager.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiDisabledResponse" } } } }, "default": { "description": "An unexpected error occurred." } }, "security": [ { "BasicAuth": [] } ] } }, "/jobs": { "post": { "tags": [ "job" ], "summary": "Create a new Job", "description": "\n> #### Access Restrictions\n> ##### Sub-users with API access have permission to use this endpoint, but they **must** specify both the `branch_id` and `distribution_center_id` in the request body.\n\nCreate 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.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostJobRequestBody" } } } }, "responses": { "201": { "description": "Created Job resource for specified `jobID` successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobCreateResponse" } } } }, "400": { "description": "Missing or invalid fields for one or more fields when creating a new Job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequiredFieldsJobResponse" } } } }, "401": { "description": "Authentication information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedResponse" } } } }, "409": { "description": "API access is disabled. For further details, reach out to api.support@cigotracker.com or talk to your account manager.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiDisabledResponse" } } } }, "422": { "description": "Invalid request parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidParametersResponse" } } } }, "default": { "description": "An unexpected error occurred." } }, "security": [ { "BasicAuth": [] } ] } }, "/jobs/search": { "post": { "tags": [ "job" ], "summary": "Search for Job API IDs", "description": "\n> #### Access Restrictions\n> ##### Sub-users with API access have permission to use this endpoint.\n> ##### NOTE: Sub-users can only retrieve jobs associated with branches they are assigned or have been created by themselves.\n\nSearch for Job API IDs where the date is within a certain start and end range (within 30 days), as well as other criteria:\n- Status\n- Quick description\n- Job Reference ID\n- Confirmation status\n- Branch Reference ID\n- Distribution Center Reference ID\n- Job type\n- Creation Source\n- Assigned to an itinerary (only applies to Jobs in `post_staging`)\n\nThe result, if it isn't filtered by Status, is broken down into two categories:\n- `staging`: Job API IDs that have the status `staging`\n- `post_staging`: Job API IDs that have other statuses, and may or may not have been assigned to an itinerary.\n\nFields `start_date` and `end_date` follows ISO-8601 date format:\n\n- Format: Year-Month-Day (YYYY-MM-DD)\n- Optional: Timezone offset:\n - If a timezone is included, it requires time to specify exact date\n - 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)\n\n**Note**: If you do not define the `end_date`, it will automatically be set to the same as the required `start_date`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostSearchJobsRequestBody" } } } }, "responses": { "200": { "description": "Searched for Job API IDs successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchJobsResponse" } } } }, "400": { "description": "Missing required fields or invalid value in request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequiredFieldsSearchJobResponse" } } } }, "401": { "description": "Authentication information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedResponse" } } } }, "409": { "description": "API access is disabled. For further details, reach out to api.support@cigotracker.com or talk to your account manager.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiDisabledResponse" } } } }, "default": { "description": "An unexpected error occurred." } }, "security": [ { "BasicAuth": [] } ] } }, "/jobs/id/{jobID}": { "get": { "tags": [ "job" ], "summary": "Retrieve a Job", "description": "\n> #### Access Restrictions\n> ##### Sub-users with API access have permission to use this endpoint.\n> ##### NOTE: Sub-users can only retrieve jobs associated with branches they are assigned to or have been created by themselves.\n\nRetrieve an existing Job whether it is in staging or it has been validated by your dispatcher(s).", "parameters": [ { "name": "jobID", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Retrieved Job resource for specified `jobID` successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetrieveJobResponse" } } } }, "400": { "description": "Missing Required Fields in Create a new Job", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequiredFieldsJobResponse" } } } }, "401": { "description": "Authentication information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedResponse" } } } }, "403": { "description": "You do not have permission to access the job associated with the given `jobID`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenResponse" } } } }, "404": { "description": "No Job found for given `jobID`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobNotFoundResponse" } } } }, "409": { "description": "API access is disabled. For further details, reach out to api.support@cigotracker.com or talk to your account manager.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiDisabledResponse" } } } }, "422": { "description": "Invalid request parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidParametersResponse" } } } }, "default": { "description": "An unexpected error occurred." } }, "security": [ { "BasicAuth": [] } ] }, "delete": { "tags": [ "job" ], "summary": "Delete a Job", "description": "\n> #### Access Restrictions\n> ##### Sub-users with API access have permission to use this endpoint.\n> ##### NOTE: Sub-users can only delete jobs they have created themselves; otherwise, they will receive a 403 Forbidden response.\n\nDelete 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.", "parameters": [ { "name": "jobID", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted Job resource for specified `jobID` successfully." }, "401": { "description": "Authentication information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedResponse" } } } }, "403": { "description": "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobStateForbiddenResponse" } } } }, "404": { "description": "No Job found for given `jobID`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobNotFoundResponse" } } } }, "409": { "description": "API access is disabled. For further details, reach out to api.support@cigotracker.com or talk to your account manager.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiDisabledResponse" } } } }, "422": { "description": "Invalid request parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidParametersResponse" } } } }, "default": { "description": "An unexpected error occurred." } }, "security": [ { "BasicAuth": [] } ] }, "patch": { "tags": [ "job" ], "summary": "Update a Job", "description": "\n> #### Access Restrictions\n> ##### Sub-users with API access have permission to use this endpoint.\n> ##### NOTE: Sub-users can only update jobs they have created themselves; otherwise, they will receive a 403 Forbidden response.\n\nUpdate an existing Job.\n\n#### Exceptions\nIf the Job is already assigned to an Itinerary and its `state` is `new`, only the following properties can be updated:\n- `quick_desc`\n- `first_name`\n- `last_name`\n- `phone_number`\n- `mobile_number`\n- `email`\n- `apartment`\n- `time_preference`\n- `invoices`\n- `balance_owed`", "parameters": [ { "name": "jobID", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchJobRequestBody" } } } }, "responses": { "200": { "description": "Updated Job resource for specified `jobID` successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateJobResponse" } } } }, "401": { "description": "Authentication information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedResponse" } } } }, "403": { "description": "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobStateForbiddenResponse" } } } }, "404": { "description": "No Job found for given `jobID`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobNotFoundResponse" } } } }, "409": { "description": "API access is disabled. For further details, reach out to api.support@cigotracker.com or talk to your account manager.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiDisabledResponse" } } } }, "422": { "description": "Invalid request parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidParametersResponse" } } } }, "default": { "description": "An unexpected error occurred." } }, "security": [ { "BasicAuth": [] } ] } }, "/jobs/id/{jobID}/reports": { "get": { "tags": [ "job" ], "summary": "Retrieve a Job's reports", "description": "\n> #### Access Restrictions\n> ##### Sub-users with API access have permission to use this endpoint.\n> ##### NOTE: Sub-users can only retrieve reports for jobs they have created themselves; otherwise, they will receive a 403 Forbidden response.\n\n Retrieve an existing Job's reports. The reports included are:\n- Digital signature\n- Additional digital signatures\n- Fulfillment report\n- Incidents report\n- Incomplete report\n\n**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`.\nExample with cURL:\n\n```\ncurl --location --request GET 'https://cigotracker.com/api/v1/jobs/id/?filename=' \\\n--header 'Content-Type: application/octet-stream' \\\n--header 'Authorization: Basic '\n```\n", "parameters": [ { "name": "jobID", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Retrieved Job's reports resource for specified `jobID` successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetrieveJobReportsResponse" } } } }, "401": { "description": "Authentication information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedResponse" } } } }, "404": { "description": "No Job found for given `jobID`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobNotFoundResponse" } } } }, "409": { "description": "API access is disabled. For further details, reach out to api.support@cigotracker.com or talk to your account manager.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiDisabledResponse" } } } }, "422": { "description": "Invalid request parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidParametersResponse" } } } }, "default": { "description": "An unexpected error occurred." } }, "security": [ { "BasicAuth": [] } ] } }, "/jobs/id/{jobID}/chat": { "get": { "tags": [ "job" ], "summary": "Retrieve a Job's chat", "description": "Retrieve an existing Job's chat data.\n> #### Access Restrictions\n> ##### Sub-users with API access have permission to use this endpoint.\n> ##### NOTE: Sub-users can only retrieve chats for jobs they have created themselves; otherwise, they will receive a 403 Forbidden response.\n\n**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`.\nExample with cURL:\n\n```\ncurl --location --request GET 'https://cigotracker.com/api/v1/jobs/id/?filename=' \\\n--header 'Content-Type: application/octet-stream' \\\n--header 'Authorization: Basic '\n```\n", "parameters": [ { "name": "jobID", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Retrieved Job's chat data for specified `jobID` successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetrieveJobChatResponse" } } } }, "401": { "description": "Authentication information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedResponse" } } } }, "404": { "description": "No Job found for given `jobID`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobNotFoundResponse" } } } }, "409": { "description": "API access is disabled. For further details, reach out to api.support@cigotracker.com or talk to your account manager.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiDisabledResponse" } } } }, "422": { "description": "Invalid request parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidParametersResponse" } } } }, "default": { "description": "An unexpected error occurred." } }, "security": [ { "BasicAuth": [] } ] }, "post": { "tags": [ "job" ], "summary": "Create a new Job chat message", "description": "\n> #### Access Restrictions\n> ##### Sub-users with API access have permission to use this endpoint.\n\nCreate a new message in a Job's 'Notes and Chat' section.", "parameters": [ { "name": "jobID", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostJobChatRequestBody" } } } }, "responses": { "201": { "description": "Successfully created a job message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobChatCreateResponse" } } } }, "400": { "description": "Missing required fields for creating a job message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequiredFieldsJobChatResponse" } } } }, "401": { "description": "Authentication information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedResponse" } } } }, "403": { "description": "You do not have permission to access the job associated with the message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenResponse" } } } }, "409": { "description": "API access is disabled. For further details, reach out to api.support@cigotracker.com or talk to your account manager.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiDisabledResponse" } } } }, "422": { "description": "Invalid request parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidParametersResponse" } } } }, "default": { "description": "An unexpected error occurred." } }, "security": [ { "BasicAuth": [] } ] } }, "/jobs/id/{jobID}/chat/{messageID}": { "get": { "tags": [ "job" ], "summary": "Retrieve a Job's chat specific message", "description": "Retrieve an existing Job's chat specific message.\n> #### Access Restrictions\n> ##### Sub-users with API access have permission to use this endpoint.\n> ##### NOTE: Sub-users can only retrieve chats for jobs they have created themselves; otherwise, they will receive a 403 Forbidden response.\n\n**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`.\nExample with cURL:\n\n```\ncurl --location --request GET 'https://cigotracker.com/api/v1/jobs/id/?filename=' \\\n--header 'Content-Type: application/octet-stream' \\\n--header 'Authorization: Basic '\n```\n", "parameters": [ { "name": "jobID", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "messageID", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Retrieved Job's chat data for specified `jobID` successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetrieveJobChatMessageByIDResponse" } } } }, "401": { "description": "Authentication information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedResponse" } } } }, "404": { "description": "No Job found for given `jobID`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobNotFoundResponse" } } } }, "409": { "description": "API access is disabled. For further details, reach out to api.support@cigotracker.com or talk to your account manager.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiDisabledResponse" } } } }, "422": { "description": "Invalid request parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidParametersResponse" } } } }, "default": { "description": "An unexpected error occurred." } }, "security": [ { "BasicAuth": [] } ] }, "put": { "tags": [ "job" ], "summary": "Update a Job chat message", "description": "\n> #### Access Restrictions\n> ##### Sub-users with API access have permission to use this endpoint.\n\nUpdate an existing message in a Job's 'Notes and Chat' section. Only messages created via the API can be edited through this endpoint.", "parameters": [ { "name": "jobID", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "messageID", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PutJobChatRequestBody" } } } }, "responses": { "200": { "description": "Successfully updated a job message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobChatUpdateResponse" } } } }, "400": { "description": "Missing required fields for updating a job message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequiredFieldsJobChatResponse" } } } }, "401": { "description": "Authentication information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedResponse" } } } }, "403": { "description": "You do not have permission to access this message or the message was not created via API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenResponse" } } } }, "404": { "description": "No message found for given `messageID`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageNotFoundResponse" } } } }, "409": { "description": "API access is disabled. For further details, reach out to api.support@cigotracker.com or talk to your account manager.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiDisabledResponse" } } } }, "422": { "description": "Invalid request parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidParametersResponse" } } } }, "default": { "description": "An unexpected error occurred." } }, "security": [ { "BasicAuth": [] } ] } }, "/jobs/id/{jobID}/location": { "get": { "tags": [ "job" ], "summary": "Retrieve Job's latest geolocation", "description": "\n> #### Access Restrictions\n> ##### Sub-users with API access *DO NOT* have permission to use this endpoint.\n\n Relative to a Job, retrieve the approximate geolocation of the assigned Operator, and their last known ETA and distance from the Job's geolocation.\n\n This information can only be retrieved if:\n - The Job's status is currently `In Progress`;\n - The assigned Operator is connected to the internet;\n - The assigned Operator has location reporting correctly enabled within the Cigo Tracker app permissions (on either Android or iOS).\n\n This information can only be retrieved if:\n - Admin configuration allows it via 'Fetch Location and relative ETA and distancia via Public API' configuration\n ", "parameters": [ { "name": "jobID", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "route_data", "in": "query", "required": false, "schema": { "type": "string", "default": "false", "description": "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." } } ], "responses": { "200": { "description": "Retrieved Job and geolocation information for specified `jobID` successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetrieveJobLocationResponse" } } } }, "401": { "description": "Authentication information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedResponse" } } } }, "403": { "description": "Access to the requested resource is forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenResponse" } } } }, "404": { "description": "No Job found for given `jobID`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobNotFoundResponse" } } } }, "409": { "description": "API access is disabled. For further details, reach out to api.support@cigotracker.com or talk to your account manager.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiDisabledResponse" } } } }, "422": { "description": "Invalid request parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidParametersResponse" } } } }, "default": { "description": "An unexpected error occurred." } }, "security": [ { "BasicAuth": [] } ] } }, "/jobs/id/{jobID}/actions": { "get": { "tags": [ "action" ], "summary": "Retrieve all Actions for a Job", "description": "\n> #### Access Restrictions\n> ##### Sub-users with API access have permission to use this endpoint.\n> ##### NOTE: Sub-users can only retrieve actions for jobs they have created themselves; otherwise, they will receive a 403 Forbidden response.\n\n Retrieve all actions for a Job.", "parameters": [ { "name": "jobID", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Retrieved Action resources for specified `jobID` successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetrieveJobActionsResponse" } } } }, "401": { "description": "Authentication information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedResponse" } } } }, "404": { "description": "No Job found for given `jobID`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobNotFoundResponse" } } } }, "409": { "description": "API access is disabled. For further details, reach out to api.support@cigotracker.com or talk to your account manager.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiDisabledResponse" } } } }, "422": { "description": "Invalid request parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidParametersResponse" } } } }, "default": { "description": "An unexpected error occurred." } }, "security": [ { "BasicAuth": [] } ] }, "post": { "tags": [ "action" ], "summary": "Create a new Job Action", "description": "\n> #### Access Restrictions\n> ##### Sub-users with API access have permission to use this endpoint.\n> ##### NOTE: Sub-users can only create actions for jobs they have created themselves; otherwise, they will receive a 403 Forbidden response.\n\nCreate a new Job Action for an existing Job with a specific `{jobID}`.\n\n#### Exceptions\nA new Job Action **cannot** be created if the parent Job:\n- is already assigned to an itinerary and the Action is of type `pick up`, `return`, or `exchange`;\n- is already assigned to an itinerary, setting the `stop_location_id` or `stop_location` value is not supported;\n- is marked as fulfilled (e.g. `completed`, `incomplete`, etc.).", "parameters": [ { "name": "jobID", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostJobActionRequestBody" } } } }, "responses": { "201": { "description": "Create Action resource for specified `jobID` successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobActionCreateResponse" } } } }, "400": { "description": "Missing Required Fields in Create a new Job Action", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequiredFieldsJobActionResponse" } } } }, "401": { "description": "Authentication information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedResponse" } } } }, "403": { "description": "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobStateForbiddenResponse" } } } }, "404": { "description": "No Job found for given `jobID`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobNotFoundResponse" } } } }, "409": { "description": "API access is disabled. For further details, reach out to api.support@cigotracker.com or talk to your account manager.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiDisabledResponse" } } } }, "422": { "description": "Invalid request parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidParametersResponse" } } } }, "default": { "description": "An unexpected error occurred." } }, "security": [ { "BasicAuth": [] } ] }, "delete": { "tags": [ "action" ], "summary": "Delete all Actions for a Job", "description": "\n> #### Access Restrictions\n> ##### Sub-users with API access have permission to use this endpoint.\n> ##### NOTE: Sub-users can only delete actions for jobs they have created themselves; otherwise, they will receive a 403 Forbidden response.\n\nDelete an existing Job's actions.\n\n#### Exceptions\nA Job Action **cannot** be deleted if the parent Job:\n- is already assigned to an itinerary and the Action is of type `pickup`, `return`, or `exchange`;\n- is marked as fulfilled (e.g. `completed`, `incomplete`, etc.).", "parameters": [ { "name": "jobID", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted all Action resources for specified `jobID` successfully." }, "401": { "description": "Authentication information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedResponse" } } } }, "403": { "description": "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobStateForbiddenResponse" } } } }, "404": { "description": "No Job found for given `jobID`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobNotFoundResponse" } } } }, "409": { "description": "API access is disabled. For further details, reach out to api.support@cigotracker.com or talk to your account manager.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiDisabledResponse" } } } }, "422": { "description": "Invalid request parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidParametersResponse" } } } }, "default": { "description": "An unexpected error occurred." } }, "security": [ { "BasicAuth": [] } ] } }, "/jobs/id/{jobID}/actions/{actionID}": { "get": { "tags": [ "action" ], "summary": "Retrieve an Action for a Job", "description": "\n> #### Access Restrictions\n> ##### Sub-users with API access have permission to use this endpoint.\n> ##### NOTE: Sub-users can only retrieve actions for jobs they have created themselves; otherwise, they will receive a 403 Forbidden response.\n\nRetrieve a specific action for a Job.", "parameters": [ { "name": "jobID", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "actionID", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Retrieved Action resource with specified `actionID` successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetrieveJobActionResponse" } } } }, "401": { "description": "Authentication information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedResponse" } } } }, "404": { "description": "Either the Job for the given `jobID` or the Job Action for the given `actionID` could not be found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobOrActionNotFoundResponse" } } } }, "409": { "description": "API access is disabled. For further details, reach out to api.support@cigotracker.com or talk to your account manager.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiDisabledResponse" } } } }, "422": { "description": "Invalid request parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidParametersResponse" } } } }, "default": { "description": "An unexpected error occurred." } }, "security": [ { "BasicAuth": [] } ] }, "delete": { "tags": [ "action" ], "summary": "Delete an Action for a Job", "description": "\n> #### Access Restrictions\n> ##### Sub-users with API access have permission to use this endpoint.\n> ##### NOTE: Sub-users can only delete actions for jobs they have created themselves; otherwise, they will receive a 403 Forbidden response.\n\nDelete an existing Job's specific action.\n\n#### Exceptions\nA Job Action **cannot** be deleted if the parent Job:\n- is already assigned to an itinerary and the Action is of type `pickup`, `return`, or `exchange`;\n- is marked as fulfilled (e.g. `completed`, `incomplete`, etc.).", "parameters": [ { "name": "jobID", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "actionID", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted Action resource with specified `actionID` successfully." }, "401": { "description": "Authentication information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedResponse" } } } }, "403": { "description": "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobStateForbiddenResponse" } } } }, "404": { "description": "Either the job for the given `jobID` or the action for the given `actionID` could not be found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobOrActionNotFoundResponse" } } } }, "409": { "description": "API access is disabled. For further details, reach out to api.support@cigotracker.com or talk to your account manager.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiDisabledResponse" } } } }, "422": { "description": "Invalid request parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidParametersResponse" } } } }, "default": { "description": "An unexpected error occurred." } }, "security": [ { "BasicAuth": [] } ] }, "patch": { "tags": [ "action" ], "summary": "Update a Job Action", "description": "\n> #### Access Restrictions\n> ##### Sub-users with API access have permission to use this endpoint.\n> ##### NOTE: Sub-users can only update actions for jobs they have created themselves; otherwise, they will receive a 403 Forbidden response.\n\nUpdate an existing Job Action.\n\n#### Exceptions\nA Job Action **cannot** be updated if:\n- the parent Job is already assigned to an itinerary and the action is of type `pickup`, `return`, or `exchange`, the `stop location_id` and `stop_location` properties cannot be updated;\n- the parent Job is fulfilled (e.g. `completed`, `incomplete`, etc.);\n- the Job Action itself is fulfilled (e.g. `completed`, `incomplete`, `damaged`);\n- the related stop of the `pickup`, `return` or `exchange` action is completed or in progress.", "parameters": [ { "name": "jobID", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "actionID", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchJobActionRequestBody" } } } }, "responses": { "200": { "description": "Updated Action resource with specified `actionID` successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateJobActionResponse" } } } }, "401": { "description": "Authentication information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedResponse" } } } }, "403": { "description": "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobStateForbiddenResponse" } } } }, "404": { "description": "Either the job for the given `jobID` or the action for the given `actionID` could not be found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobOrActionNotFoundResponse" } } } }, "409": { "description": "API access is disabled. For further details, reach out to api.support@cigotracker.com or talk to your account manager.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiDisabledResponse" } } } }, "422": { "description": "Invalid request parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidParametersResponse" } } } }, "default": { "description": "An unexpected error occurred." } }, "security": [ { "BasicAuth": [] } ] } }, "/customers/id/{customerID}": { "get": { "tags": [ "customer" ], "summary": "Retrieve a Customer", "description": "\n> #### Access Restrictions\n> ##### Sub-users with API access have permission to use this endpoint.\n\nRetrieve 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.", "parameters": [ { "name": "customerID", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Retrieved Job resource for specified `customerID` successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetrieveCustomerResponse" } } } }, "401": { "description": "Authentication information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedResponse" } } } }, "404": { "description": "No Customer information found for the given `customerID`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerNotFoundResponse" } } } }, "405": { "description": "The resource doesn't support the specified HTTP verb.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenHTTPRequest" } } } }, "409": { "description": "API access is disabled. For further details, reach out to api.support@cigotracker.com or talk to your account manager.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiDisabledResponse" } } } }, "422": { "description": "Invalid request parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidParametersResponse" } } } }, "default": { "description": "An unexpected error occurred." } }, "security": [ { "BasicAuth": [] } ] } }, "/customers/search": { "post": { "tags": [ "customer" ], "summary": "Search for Customer API IDs", "description": "\n> #### Access Restrictions\n> ##### Sub-users with API access have permission to use this endpoint.\n> ##### NOTE: Sub-users can only retrieve jobs they have created themselves.\n\nSearch for Customer API IDs using various criteria, with results limited to the first 20 matches. The following fields are supported:\n- Name (supports partial matches)\n- Phone number\n- Mobile number\n- Email\n- Invoice\n- Customer Reference ID\n- Job Reference ID\n\n **Note:** The search supports a combination of criteria and prioritizes exact matches where possible. If no matches are found, the response will indicate so.\n\n **Request Body Format:**\n- All fields are optional except at least one search parameter must be provided.\n- Supports a JSON object with key-value pairs for the search parameters.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostSearchCustomersRequestBody" } } } }, "responses": { "200": { "description": "Searched for Customer successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchCustomersResponse" } } } }, "422": { "description": "Missing required fields or invalid value in request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequiredFieldsSearchCustomerResponse" } } } }, "401": { "description": "Authentication information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedResponse" } } } }, "405": { "description": "Unsupported HTTP verb." }, "409": { "description": "API access is disabled. For further details, reach out to api.support@cigotracker.com or talk to your account manager.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiDisabledResponse" } } } }, "default": { "description": "An unexpected error occurred." } }, "security": [ { "BasicAuth": [] } ] } }, "/itineraries/date/{date}": { "get": { "tags": [ "itinerary" ], "summary": "Retrieve Itineraries by Date", "description": "\n> #### Access Restrictions\n> ##### Sub-users with API access *DO NOT* have permission to use this endpoint.\n\nRetrieve the details of all itineraries for a given date.", "parameters": [ { "name": "date", "in": "path", "description": "ISO-8601 date format.\n\n - Format: Year-Month-Day (YYYY-MM-DD)\n - Optional: Timezone offset:\n - If a timezone is included, it requires time to specify exact date\n - 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)", "required": true, "schema": { "type": "string", "format": "date" }, "example": "2024-08-01 or 2024-08-01T15:30:00-06:00" } ], "responses": { "200": { "description": "Retrieved Itinerary resources for specified `date` successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetrieveItinerariesResponse" } } } }, "401": { "description": "Authentication information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedResponse" } } } }, "403": { "description": "Access to the requested resource is forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenResponse" } } } }, "409": { "description": "API access is disabled. For further details, reach out to api.support@cigotracker.com or talk to your account manager.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiDisabledResponse" } } } }, "422": { "description": "Invalid date value.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidDateResponse" } } } }, "default": { "description": "An unexpected error occurred." } }, "security": [ { "BasicAuth": [] } ] } }, "/itineraries/operator/{operator}": { "get": { "tags": [ "itinerary" ], "summary": "Retrieve Itineraries by Operator", "description": "\n> #### Access Restrictions\n> ##### Sub-users with API access *DO NOT* have permission to use this endpoint.\n\nRetrieve the details of all itineraries for a given Operator by it's API ID.", "parameters": [ { "name": "operator", "in": "path", "description": "Operator API ID", "required": true, "schema": { "type": "string" }, "example": "56a5eb4a1b7b64d2d22232f74ca98523" }, { "name": "start_date", "in": "query", "description": "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.", "required": false, "schema": { "type": "string", "format": "date" }, "example": "2024-08-01" }, { "name": "end_date", "in": "query", "description": "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.", "required": false, "schema": { "type": "string", "format": "date" }, "example": "2024-08-01" } ], "responses": { "200": { "description": "Retrieved Itinerary resources for specified `operator` by API ID successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetrieveItinerariesResponse2" } } } }, "401": { "description": "Authentication information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedResponse" } } } }, "403": { "description": "Access to the requested resource is forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenResponse" } } } }, "409": { "description": "API Access is disabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiDisabledResponse" } } } }, "default": { "description": "An unexpected error occurred." } }, "security": [ { "BasicAuth": [] } ] } }, "/itineraries/vehicle/{vehicle}": { "get": { "tags": [ "itinerary" ], "summary": "Retrieve Itineraries by Vehicle", "description": "\n> #### Access Restrictions\n> ##### Sub-users with API access *DO NOT* have permission to use this endpoint.\n\nRetrieve the details of all itineraries for a given Vehicle by it's API ID.", "parameters": [ { "name": "vehicle", "in": "path", "description": "Vehicle API ID", "required": true, "schema": { "type": "string" }, "example": "bdca6e528b4324a2279d7ab25265431f" }, { "name": "start_date", "in": "query", "description": "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.", "required": false, "schema": { "type": "string", "format": "date" }, "example": "2024-08-01" }, { "name": "end_date", "in": "query", "description": "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.", "required": false, "schema": { "type": "string", "format": "date" }, "example": "2024-08-01" } ], "responses": { "200": { "description": "Retrieved Itinerary resources for specified `vehicle` by API ID successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetrieveItinerariesResponse2" } } } }, "401": { "description": "Authentication information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedResponse" } } } }, "403": { "description": "Access to the requested resource is forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenResponse" } } } }, "409": { "description": "API Access is disabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiDisabledResponse" } } } }, "default": { "description": "An unexpected error occurred." } }, "security": [ { "BasicAuth": [] } ] } }, "/itineraries/id/{itineraryID}": { "get": { "tags": [ "itinerary" ], "summary": "Retrieve Itinerary", "description": "\n> #### Access Restrictions\n> ##### Sub-users with API access *DO NOT* have permission to use this endpoint.\n\nRetrieve an Itinerary details by its ID.", "parameters": [ { "name": "itineraryID", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Retrieved Itinerary resource for specified `itineraryID` successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetrieveItineraryResponse" } } } }, "401": { "description": "Authentication information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedResponse" } } } }, "403": { "description": "Access to the requested resource is forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenResponse" } } } }, "404": { "description": "No Itinerary found for given `itineraryID`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItineraryNotFoundResponse" } } } }, "409": { "description": "API access is disabled. For further details, reach out to api.support@cigotracker.com or talk to your account manager.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiDisabledResponse" } } } }, "422": { "description": "Invalid request parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidParametersResponse" } } } }, "default": { "description": "An unexpected error occurred." } }, "security": [ { "BasicAuth": [] } ] }, "delete": { "tags": [ "itinerary" ], "summary": "Delete Itinerary", "description": "\n> #### Access Restrictions\n> ##### Sub-users with API access *DO NOT* have permission to use this endpoint.\n\nDelete existing Itinerary while it has not started yet.", "parameters": [ { "name": "itineraryID", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted Itinerary resource for specified `itineraryID` successfully." }, "401": { "description": "Authentication information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedResponse" } } } }, "404": { "description": "The Itinerary for the given `itineraryID` could not be found." }, "409": { "description": "API access is disabled. For further details, reach out to api.support@cigotracker.com or talk to your account manager.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiDisabledResponse" } } } }, "422": { "description": "Invalid request parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidParametersResponse" } } } }, "default": { "description": "An unexpected error occurred." } }, "security": [ { "BasicAuth": [] } ] }, "patch": { "tags": [ "itinerary" ], "summary": "Update an Itinerary", "description": "\n> #### Access Restrictions\n> ##### Sub-users with API access *DO NOT* have permission to use this endpoint.\n\nUpdate an existing Itinerary while it has not completed yet.", "parameters": [ { "name": "itineraryID", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostItineraryUpdateRequestBody" } } } }, "responses": { "200": { "description": "Updated Itinerary resource for specified `itineraryID` successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItineraryUpdateResponse" } } } }, "204": { "description": "Jobs resources for specified `delete_ids` were removed from specified `itineraryID` and the Itinerary was deleted successfully." }, "401": { "description": "Authentication information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedResponse" } } } }, "404": { "description": "No Itinerary found for given `itineraryID`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItineraryNotFoundResponse" } } } }, "409": { "description": "API access is disabled. For further details, reach out to api.support@cigotracker.com or talk to your account manager.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiDisabledResponse" } } } }, "422": { "description": "Invalid request parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItineraryInvalidParametersResponse" } } } }, "default": { "description": "An unexpected error occurred." } }, "security": [ { "BasicAuth": [] } ] } }, "/itineraries/id/{itineraryID}/polyline": { "get": { "tags": [ "itinerary" ], "summary": "Retrieve Itinerary Polyline GeoJSON", "description": "\n> #### Access Restrictions\n> ##### Sub-users with API access DO NOT have permission to use this endpoint.\n\nRetrieve an itinerary’s polyline GeoJSON by the itinerary API ID.", "parameters": [ { "name": "itineraryID", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Retrieved Itinerary polyline GEOJson for specified `itineraryID` successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetrieveItineraryPolylineResponse" } } } }, "401": { "description": "Authentication information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedResponse" } } } }, "403": { "description": "Access to the requested resource is forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenResponse" } } } }, "404": { "description": "No Itinerary found for given `itineraryID`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItineraryNotFoundResponse" } } } }, "409": { "description": "API Access is disabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiDisabledResponse" } } } }, "422": { "description": "Invalid request parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidParametersResponse" } } } }, "default": { "description": "An unexpected error occurred." } }, "security": [ { "BasicAuth": [] } ] } }, "/itineraries/action/previewRoute": { "post": { "tags": [ "itinerary" ], "summary": "Preview Route", "description": "\n> #### Access Restrictions\n> ##### - This endpoint is available only if access has been enabled for your account. For further details, please reach out to your account manager.\n> ##### Sub-users with API access *DO NOT* have permission to use this endpoint.\n\nPreview an Itinerary.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostItineraryPreviewRequestBody" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreviewItineraryResponse" } } } }, "401": { "description": "Authentication information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedResponse" } } } }, "403": { "description": "Access to the requested resource is forbidden or disabled by administrator.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenDisabledResponse" } } } }, "409": { "description": "API access is disabled. For further details, reach out to api.support@cigotracker.com or talk to your account manager.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiDisabledResponse" } } } }, "422": { "description": "Invalid request parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItineraryInvalidParametersResponse" } } } }, "default": { "description": "An unexpected error occurred." } }, "security": [ { "BasicAuth": [] } ] } }, "/itineraries": { "post": { "tags": [ "itinerary" ], "summary": "Create Itinerary", "description": "\n> #### Access Restrictions\n> ##### Sub-users with API access *DO NOT* have permission to use this endpoint.\n\nBuild an Itinerary.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostItineraryCreateRequestBody" } } } }, "responses": { "200": { "description": "Itinerary was created successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItineraryCreateResponse" } } } }, "401": { "description": "Authentication information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedResponse" } } } }, "409": { "description": "API access is disabled. For further details, reach out to api.support@cigotracker.com or talk to your account manager.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiDisabledResponse" } } } }, "422": { "description": "Invalid request parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItineraryInvalidParametersResponse" } } } }, "default": { "description": "An unexpected error occurred." } }, "security": [ { "BasicAuth": [] } ] } }, "/itineraries/id/{itineraryID}/job_id/{jobID}": { "delete": { "tags": [ "itinerary" ], "summary": "Delete Stop", "description": "\n> #### Access Restrictions\n> ##### Sub-users with API access *DO NOT* have permission to use this endpoint.\n\n Delete assigned Job while it has not started yet.\n\n **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.", "parameters": [ { "name": "itineraryID", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "jobID", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Un-assigned Job resource from specified `itineraryID` for specified `jobID` successfully." }, "401": { "description": "Authentication information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedResponse" } } } }, "404": { "description": "Either the Itinerary for the given `itineraryID` or the Job for the given `jobID` could not be found." }, "409": { "description": "API access is disabled. For further details, reach out to api.support@cigotracker.com or talk to your account manager.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiDisabledResponse" } } } }, "422": { "description": "Invalid request parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidParametersResponse" } } } }, "default": { "description": "An unexpected error occurred." } }, "security": [ { "BasicAuth": [] } ] } }, "/itineraries/id/{itineraryID}/action/updateOperators": { "patch": { "tags": [ "itinerary" ], "summary": "Update Operators", "description": "\n> #### Access Restrictions\n> ##### Sub-users with API access *DO NOT* have permission to use this endpoint.\n\nUpdate Operators.", "parameters": [ { "name": "itineraryID", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostItineraryUpdateOperatorsRequestBody" } } } }, "responses": { "200": { "description": "Operators were updated successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItineraryUpdateOperatorsResponse" } } } }, "404": { "description": "One or more operator IDs are invalid or do not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItineraryUpdateOperatorsBadRequestResponse" } } } }, "401": { "description": "Authentication information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedResponse" } } } }, "409": { "description": "API access is disabled. For further details, reach out to api.support@cigotracker.com or talk to your account manager.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiDisabledResponse" } } } }, "422": { "description": "Invalid request parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidParametersResponse" } } } }, "default": { "description": "An unexpected error occurred." } }, "security": [ { "BasicAuth": [] } ] } }, "/itineraries/id/{itineraryID}/action/unassignOperators/operator_ids/{operatorID}": { "delete": { "tags": [ "itinerary" ], "summary": "Delete Operators", "description": "\n> #### Access Restrictions\n> ##### Sub-users with API access *DO NOT* have permission to use this endpoint.\n\nUnassign 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.", "parameters": [ { "name": "itineraryID", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "operatorID", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Un-assigned Operators resource for specified `itineraryID` successfully." }, "401": { "description": "Authentication information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedResponse" } } } }, "404": { "description": "Either the Itinerary for the given `itineraryID` or the Operators for the given `operatorID` could not be found." }, "409": { "description": "API access is disabled. For further details, reach out to api.support@cigotracker.com or talk to your account manager.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiDisabledResponse" } } } }, "422": { "description": "Invalid request parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidParametersResponse" } } } }, "default": { "description": "An unexpected error occurred." } }, "security": [ { "BasicAuth": [] } ] } }, "/itineraries/id/{itineraryID}/job_id/{jobID}/position/{position}": { "patch": { "tags": [ "itinerary" ], "summary": "Change Stop position", "description": "\n> #### Access Restrictions\n> ##### Sub-users with API access *DO NOT* have permission to use this endpoint.\n\nChange position of a single Job/Stop while it has not been starter/completed.", "parameters": [ { "name": "itineraryID", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "jobID", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "position", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Stop was moved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItineraryChangePositionResponse" } } } }, "401": { "description": "Authentication information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedResponse" } } } }, "409": { "description": "API access is disabled. For further details, reach out to api.support@cigotracker.com or talk to your account manager.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiDisabledResponse" } } } }, "422": { "description": "Invalid request parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidParametersResponse" } } } }, "default": { "description": "An unexpected error occurred." } }, "security": [ { "BasicAuth": [] } ] } }, "/itineraries/id/{itineraryID}/action/updatePositions": { "patch": { "tags": [ "itinerary" ], "summary": "Change Stops positions", "description": "\n> #### Access Restrictions\n> ##### Sub-users with API access *DO NOT* have permission to use this endpoint.\n\nChange positions of a all Stops.", "parameters": [ { "name": "itineraryID", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostItineraryUpdatePositionsRequestBody" } } } }, "responses": { "200": { "description": "Stop was moved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItineraryChangePositionsResponse" } } } }, "401": { "description": "Authentication information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedResponse" } } } }, "409": { "description": "API access is disabled. For further details, reach out to api.support@cigotracker.com or talk to your account manager.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiDisabledResponse" } } } }, "422": { "description": "Invalid request parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidParametersResponse" } } } }, "default": { "description": "An unexpected error occurred." } }, "security": [ { "BasicAuth": [] } ] } }, "/itineraries/id/{itineraryID}/action/reversePositions": { "patch": { "tags": [ "itinerary" ], "summary": "Reverse Stops positions", "description": "\n> #### Access Restrictions\n> ##### Sub-users with API access *DO NOT* have permission to use this endpoint.\n\nReverse order of Stops (not Started/Completed) of an existing itinerary.", "parameters": [ { "name": "itineraryID", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Order of Stops was reversed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItineraryReversePositionsResponse" } } } }, "401": { "description": "Authentication information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedResponse" } } } }, "409": { "description": "API access is disabled. For further details, reach out to api.support@cigotracker.com or talk to your account manager.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiDisabledResponse" } } } }, "422": { "description": "Invalid request parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidParametersResponse" } } } }, "default": { "description": "An unexpected error occurred." } }, "security": [ { "BasicAuth": [] } ] } }, "/itineraries/id/{itineraryID}/vehicles/id/{vehicleID}/breaks/{breakID}": { "delete": { "tags": [ "itinerary" ], "summary": "Delete a vehicle break", "description": "Remove an existing break window for the specified vehicle in the specified route.", "parameters": [ { "name": "itineraryID", "in": "path", "description": "Itinerary API identifier (e.g., `itn_fisdoa6h3472cio7823hxcb7f8`).", "required": true, "schema": { "type": "string" } }, { "name": "vehicleID", "in": "path", "description": "Vehicle API identifier (e.g., `veh_5e6bdf4bg923hx7f8io2`).", "required": true, "schema": { "type": "string" } }, { "name": "breakID", "in": "path", "description": "Break API identifier (e.g., `brk_fisdoa6h3472cio7823hxcb7f8`).", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Break deleted successfully. No content returned." }, "401": { "description": "Authentication information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedResponse" } } } }, "403": { "description": "Forbidden for sub-users with API access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenResponse" } } } }, "404": { "description": "Itinerary, Vehicle, or Break not found.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ItineraryNotFoundResponse" }, { "$ref": "#/components/schemas/VehicleNotFoundResponse" }, { "$ref": "#/components/schemas/BreakNotFoundResponse" } ] } } } }, "409": { "description": "API access is disabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiDisabledResponse" } } } } }, "security": [ { "BasicAuth": [] } ] } }, "/locations": { "get": { "tags": [ "location" ], "summary": "Retrieve all Locations", "description": "\n> #### Access Restrictions\n> ##### Sub-users with API access *DO NOT* have permission to use this endpoint.\n\nRetrieve the details of all locations.", "responses": { "200": { "description": "Retrieved Location resources successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetrieveLocationsResponse" } } } }, "401": { "description": "Authentication information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedResponse" } } } }, "404": { "description": "No Location found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LocationsNotFoundResponse" } } } }, "409": { "description": "API access is disabled. For further details, reach out to api.support@cigotracker.com or talk to your account manager.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiDisabledResponse" } } } }, "default": { "description": "An unexpected error occurred." } }, "security": [ { "BasicAuth": [] } ] }, "post": { "tags": [ "location" ], "summary": "Create Location", "description": "\n> #### Access Restrictions\n> ##### Sub-users with API access *DO NOT* have permission to use this endpoint.\n\nCreate a new Location.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostLocationCreateRequestBody" } } } }, "responses": { "201": { "description": "Successfully created a new Location.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LocationCreateResponse" } } } }, "405": { "description": "Setting the property {property} is not allowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LocationNotAllowedAttribute" } } } }, "400": { "description": "Property {property} is required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LocationPropertyRequiredResponse" } } } }, "409": { "description": "API access is disabled. For further details, reach out to api.support@cigotracker.com or talk to your account manager.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiDisabledResponse" } } } }, "422": { "description": "Invalid request parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidParametersResponse" } } } }, "default": { "description": "An unexpected error occurred." } }, "security": [ { "BasicAuth": [] } ] } }, "/locations/id/{locationID}": { "get": { "tags": [ "location" ], "summary": "Retrieve Location", "description": "\n> #### Access Restrictions\n> ##### Sub-users with API access *DO NOT* have permission to use this endpoint.\n\nRetrieve a Location details by its ID.", "parameters": [ { "name": "locationID", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Retrieved Location resource for specified `locationID` successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetrieveLocationResponse" } } } }, "401": { "description": "Authentication information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedResponse" } } } }, "404": { "description": "No Location found for given `locationID`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LocationNotFoundResponse" } } } }, "409": { "description": "API access is disabled. For further details, reach out to api.support@cigotracker.com or talk to your account manager.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiDisabledResponse" } } } }, "422": { "description": "Invalid request parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidParametersResponse" } } } }, "default": { "description": "An unexpected error occurred." } }, "security": [ { "BasicAuth": [] } ] }, "patch": { "tags": [ "location" ], "summary": "Update Location", "description": "\n> #### Access Restrictions\n> ##### Sub-users with API access *DO NOT* have permission to use this endpoint.\n\nUpdate Location.", "parameters": [ { "name": "locationID", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchLocationUpdateRequestBody" } } } }, "responses": { "200": { "description": "Updated Location resource for specified location id successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LocationUpdateResponse" } } } }, "400": { "description": "Unknown property {property}.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LocationUnknownPropertyResponse" } } } }, "404": { "description": "No Location found for given location id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LocationNotFoundResponse" } } } }, "405": { "description": "Setting the property {property} is not allowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LocationNotAllowedAttribute" } } } }, "409": { "description": "API access is disabled. For further details, reach out to api.support@cigotracker.com or talk to your account manager.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiDisabledResponse" } } } }, "422": { "description": "Invalid request parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidParametersResponse" } } } }, "default": { "description": "An unexpected error occurred." } }, "security": [ { "BasicAuth": [] } ] } }, "/vehicles": { "get": { "tags": [ "vehicle" ], "summary": "Retrieve all Vehicles", "description": "\n> #### Access Restrictions\n> ##### Sub-users with API access *DO NOT* have permission to use this endpoint.\n\nRetrieve the details of all Vehicles.", "responses": { "200": { "description": "Retrieved Vehicle resources successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetrieveVehiclesResponse" } } } }, "401": { "description": "Authentication information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedResponse" } } } }, "404": { "description": "No Vehicle found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VehiclesNotFoundResponse" } } } }, "409": { "description": "API access is disabled. For further details, reach out to api.support@cigotracker.com or talk to your account manager.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiDisabledResponse" } } } }, "default": { "description": "An unexpected error occurred." } }, "security": [ { "BasicAuth": [] } ] } }, "/vehicles/id/{vehicleID}": { "get": { "tags": [ "vehicle" ], "summary": "Retrieve Vehicle", "description": "\n> #### Access Restrictions\n> ##### Sub-users with API access *DO NOT* have permission to use this endpoint.\n\nRetrieve a Vehicle details by its ID.", "parameters": [ { "name": "vehicleID", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Retrieved Vehicle resource for specified `vehicleID` successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetrieveVehicleResponse" } } } }, "401": { "description": "Authentication information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedResponse" } } } }, "404": { "description": "No Vehicle found for given `vehicleID`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VehicleNotFoundResponse" } } } }, "409": { "description": "API access is disabled. For further details, reach out to api.support@cigotracker.com or talk to your account manager.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiDisabledResponse" } } } }, "422": { "description": "Invalid request parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidParametersResponse" } } } }, "default": { "description": "An unexpected error occurred." } }, "security": [ { "BasicAuth": [] } ] } }, "/vehicles/id/{vehicleID}/breaks": { "get": { "tags": [ "vehicle" ], "summary": "Retrieve configured breaks from a vehicle", "description": "\n> #### Access Restrictions\n> ##### Sub-users with API access *DO NOT* have permission to use this endpoint.\n\nGet all break windows configured for a vehicle by its ID.", "parameters": [ { "name": "vehicleID", "in": "path", "description": "Vehicle API identifier (string like `fisdoa6h3472cio7823hxcb7f8`).", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Break windows retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VehicleBreakListResponse" } } } }, "401": { "description": "Authentication information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedResponse" } } } }, "403": { "description": "Forbidden for sub-users with API access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenResponse" } } } }, "404": { "description": "No Vehicle found for given `vehicleID`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VehicleNotFoundResponse" } } } }, "409": { "description": "API access is disabled. For further details, reach out to api.support@cigotracker.com or talk to your account manager.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiDisabledResponse" } } } }, "422": { "description": "Invalid request parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidParametersResponse" } } } }, "default": { "description": "An unexpected error occurred." } }, "security": [ { "BasicAuth": [] } ] }, "post": { "tags": [ "vehicle" ], "summary": "Create a break for a vehicle", "description": "\n > #### Access Restrictions\n > ##### Sub-users with API access *DO NOT* have permission to use this endpoint.\n \n Create a new break window for a vehicle. A vehicle can have up to **3** break windows.", "parameters": [ { "name": "vehicleID", "in": "path", "description": "Vehicle API identifier (string like `fisdoa6h3472cio7823hxcb7f8`).", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VehicleBreakCreateRequest" } } } }, "responses": { "201": { "description": "Break created successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VehicleBreakResource" } } } }, "400": { "description": "Malformed body or JSON." }, "401": { "description": "Authentication information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedResponse" } } } }, "403": { "description": "Forbidden for sub-users with API access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenResponse" } } } }, "404": { "description": "No Vehicle found for given `vehicleID`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VehicleNotFoundResponse" } } } }, "409": { "description": "API access is disabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiDisabledResponse" } } } }, "422": { "description": "Validation failed (e.g., overlapping windows, invalid time order, duration out of range, or max breaks reached).", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/InvalidParametersResponse" }, { "$ref": "#/components/schemas/MaxBreaksResponse" } ] } } } } }, "security": [ { "BasicAuth": [] } ] } }, "/vehicles/id/{vehicleID}/breaks/{breakID}": { "put": { "tags": [ "vehicle" ], "summary": "Update a vehicle break", "description": "\n> #### Access Restrictions\n> ##### Sub-users with API access *DO NOT* have permission to use this endpoint.\n\nUpdate fields of an existing break window for a vehicle.", "parameters": [ { "name": "vehicleID", "in": "path", "description": "Vehicle API identifier (string like `fisdoa6h3472cio7823hxcb7f8`).", "required": true, "schema": { "type": "string" } }, { "name": "breakID", "in": "path", "description": "Break API identifier (e.g., `brk_fisdoa6h3472cio7823hxcb7f8`).", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VehicleBreakUpdateRequest" } } } }, "responses": { "200": { "description": "Break updated successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VehicleBreakResource" } } } }, "401": { "description": "Authentication information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedResponse" } } } }, "403": { "description": "Forbidden for sub-users with API access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenResponse" } } } }, "404": { "description": "Vehicle or Break not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BreakNotFoundResponse" } } } }, "409": { "description": "API access is disabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiDisabledResponse" } } } }, "422": { "description": "Validation failed (e.g., overlapping windows, invalid time order, duration out of range, or max breaks reached).", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/InvalidParametersResponse" }, { "$ref": "#/components/schemas/MaxBreaksResponse" } ] } } } } }, "security": [ { "BasicAuth": [] } ] }, "delete": { "tags": [ "vehicle" ], "summary": "Delete a vehicle break", "description": "\n> #### Access Restrictions\n> ##### Sub-users with API access *DO NOT* have permission to use this endpoint.\n\nRemove an existing break window for a vehicle.", "parameters": [ { "name": "vehicleID", "in": "path", "description": "Vehicle API identifier (string like `fisdoa6h3472cio7823hxcb7f8`).", "required": true, "schema": { "type": "string" } }, { "name": "breakID", "in": "path", "description": "Break API identifier (string like `brk_7e6b8f2c8a`).", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Break deleted successfully. No content returned." }, "401": { "description": "Authentication information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedResponse" } } } }, "403": { "description": "Forbidden for sub-users with API access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenResponse" } } } }, "404": { "description": "Vehicle or Break not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BreakNotFoundResponse" } } } }, "409": { "description": "API access is disabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiDisabledResponse" } } } } }, "security": [ { "BasicAuth": [] } ] } }, "/operators": { "get": { "tags": [ "operator" ], "summary": "Retrieve all Operators", "description": "\n> #### Access Restrictions\n> ##### Sub-users with API access *DO NOT* have permission to use this endpoint.\n\nRetrieve the details of all Operators.", "responses": { "200": { "description": "Retrieved Operator resources successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetrieveOperatorsResponse" } } } }, "401": { "description": "Authentication information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedResponse" } } } }, "404": { "description": "No Operator found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperatorsNotFoundResponse" } } } }, "409": { "description": "API access is disabled. For further details, reach out to api.support@cigotracker.com or talk to your account manager.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiDisabledResponse" } } } }, "default": { "description": "An unexpected error occurred." } }, "security": [ { "BasicAuth": [] } ] }, "post": { "tags": [ "operator" ], "summary": "Create Operator", "description": "\n> #### Access Restrictions\n> ##### Sub-users with API access *DO NOT* have permission to use this endpoint.\n\nCreate a new Operator.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostOperatorCreateRequestBody" } } } }, "responses": { "201": { "description": "Successfully created a new Operator.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperatorCreateResponse" } } } }, "405": { "description": "Setting the property {property} is not allowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperatorNotAllowedAttribute" } } } }, "400": { "description": "Property {property} is required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperatorPropertyRequiredResponse" } } } }, "409": { "description": "API access is disabled. For further details, reach out to api.support@cigotracker.com or talk to your account manager.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiDisabledResponse" } } } }, "422": { "description": "Invalid request parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidParametersResponse" } } } }, "default": { "description": "An unexpected error occurred." } }, "security": [ { "BasicAuth": [] } ] } }, "/operators/id/{operatorID}": { "get": { "tags": [ "operator" ], "summary": "Retrieve Operator", "description": "\n> #### Access Restrictions\n> ##### Sub-users with API access *DO NOT* have permission to use this endpoint.\n\nRetrieve an Operator details by its ID.", "parameters": [ { "name": "operatorID", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Retrieved Operator resource for specified `OperatorID` successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetrieveOperatorResponse" } } } }, "401": { "description": "Authentication information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedResponse" } } } }, "404": { "description": "No Operator found for given `OperatorID`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperatorNotFoundResponse" } } } }, "409": { "description": "API access is disabled. For further details, reach out to api.support@cigotracker.com or talk to your account manager.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiDisabledResponse" } } } }, "422": { "description": "Invalid request parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidParametersResponse" } } } }, "default": { "description": "An unexpected error occurred." } }, "security": [ { "BasicAuth": [] } ] }, "patch": { "tags": [ "operator" ], "summary": "Update Operator", "description": "\n> #### Access Restrictions\n> ##### Sub-users with API access *DO NOT* have permission to use this endpoint.\n\nUpdate Operator.", "parameters": [ { "name": "operatorID", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchOperatorUpdateRequestBody" } } } }, "responses": { "200": { "description": "Updated Operator resource for specified Operator API ID successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperatorUpdateResponse" } } } }, "400": { "description": "Unknown property {property}.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperatorUnknownPropertyResponse" } } } }, "404": { "description": "No Operator found for given Operator API ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperatorNotFoundResponse" } } } }, "405": { "description": "Setting the property {property} is not allowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperatorNotAllowedAttribute" } } } }, "409": { "description": "API access is disabled. For further details, reach out to api.support@cigotracker.com or talk to your account manager.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiDisabledResponse" } } } }, "422": { "description": "Invalid request parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidParametersResponse" } } } }, "default": { "description": "An unexpected error occurred." } }, "security": [ { "BasicAuth": [] } ] } }, "/available-booking-dates": { "get": { "tags": [ "capacity_management" ], "summary": "Retrieve available booking dates", "description": "\n> #### Access Restrictions\n> ##### - This endpoint is available only if access has been enabled for your account. For further details, please reach out to your account manager.\n> ##### Sub-users with API access *DO NOT* have permission to use this endpoint.\n\nRetrieve available booking dates for a given geolocation or address.", "parameters": [ { "name": "geolocation", "in": "query", "description": "Geolocation coordinates in the format latitude,longitude. If not provided, the address parameter is required.", "schema": { "type": "string", "example": "40.7128,-74.0060" } }, { "name": "address", "in": "query", "description": "Address to get geolocation coordinates. If not provided, the geolocation parameter is required. Within this field, include the following (**delimited by commas**):\n- Civic number\n- Street name\n- Street Type (Blvd, Street, Ave, etc.)\n- City\n- Province or State\n- Postal Code or ZIP Code", "required": false, "schema": { "type": "string" } }, { "name": "year_and_month", "in": "query", "description": "Year and month in the format YYYY-MM.", "required": false, "schema": { "type": "string", "example": "2024-12" } }, { "name": "days_ahead", "in": "query", "description": "Number of days ahead to look for available booking dates. By default this is set to 90 days.", "schema": { "type": "integer", "example": 30 } }, { "name": "weight", "in": "query", "description": "Weight of the job.", "schema": { "type": "number", "format": "float", "example": 10.5 } }, { "name": "volume", "in": "query", "description": "Volume of the job.", "schema": { "type": "number", "format": "float", "example": 2.5 } }, { "name": "handle_time", "in": "query", "description": "Handle time of the job.", "schema": { "type": "number", "format": "integer", "example": 25 } }, { "name": "days_offset", "in": "query", "description": "Minimum number of days ahead for available booking dates.", "required": false, "schema": { "type": "integer", "example": 5 } } ], "responses": { "200": { "description": "Retrieved available booking dates successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AvailableBookingDatesResponse" } } } }, "401": { "description": "Authentication information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedResponse" } } } }, "403": { "description": "Access to requested resource is forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenResponseCapacityManagement" } } } }, "409": { "description": "API Access is disabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiDisabledResponse" } } } }, "404": { "description": "No available dates found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NoAvailableDatesResponse" } } } }, "default": { "description": "An unexpected error occurred." } }, "security": [ { "BasicAuth": [] } ] } }, "/available-slots": { "get": { "tags": [ "capacity_management" ], "summary": "Retrieve available slots", "description": "\n> #### Access Restrictions\n> ##### - This endpoint is available only if access has been enabled for your account. For further details, please reach out to your account manager.\n> ##### Sub-users with API access *DO NOT* have permission to use this endpoint.\n\nRetrieve available slots for a given geolocation and date.", "parameters": [ { "name": "date", "in": "query", "description": "Date for which to get available slots in the format YYYY-MM-DD.", "required": true, "schema": { "type": "string", "example": "2024-12-12" } }, { "name": "geolocation", "in": "query", "description": "Geolocation coordinates in the format latitude,longitude.", "required": true, "schema": { "type": "string", "example": "40.7128,-74.0060" } } ], "responses": { "200": { "description": "Retrieved available slots successfully.", "content": { "application/json": { "schema": { "properties": { "max_jobs": { "description": "Maximum number of jobs allowed.", "type": "integer", "example": 10 }, "available_jobs_slots": { "description": "Number of available job slots.", "type": "integer", "example": 5 }, "max_weight": { "description": "Maximum weight capacity.", "type": "number", "format": "float", "example": 200 }, "available_weight_slots": { "description": "Available weight capacity.", "type": "number", "format": "float", "example": 150.5 }, "max_volume": { "description": "Maximum volume capacity.", "type": "number", "format": "float", "example": 100 }, "available_volume_slots": { "description": "Available volume capacity.", "type": "number", "format": "float", "example": 75.3 } }, "type": "object" } } } }, "400": { "description": "Invalid date format or geolocation.", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Invalid date format. Expected format: YYYY-MM-DD." } }, "type": "object" } } } }, "403": { "description": "Access to requested resource is forbidden.", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Access to requested resource is forbidden. Please turn on Capacity Management to access this resource." } }, "type": "object" } } } }, "404": { "description": "No available slots found.", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "No Zone found for given Date." } }, "type": "object" } } } }, "default": { "description": "An unexpected error occurred." } }, "security": [ { "BasicAuth": [] } ] } }, "/geofencing/job_id/{job_id}": { "get": { "tags": [ "geofencing" ], "summary": "Retrieve all Job geofencing events.", "description": "\n> #### Access Restrictions\n> ##### Sub-users with API access have permission to use this endpoint.\n> ##### NOTE: Sub-users can only retrieve geofencing events of jobs they have created themselves; otherwise, they will receive a 403 Forbidden response.\n\nRetrieve all Job geofencing events.", "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List with first and last Geofence entries and all events related to specified Job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeofencingGetAllResponse" } } } }, "400": { "description": "Invalid ID type.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeofencingInvalidIDResponse" } } } }, "401": { "description": "Authentication information is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedResponse" } } } }, "403": { "description": "Access to the requested resource is forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenResponse" } } } }, "404": { "description": "Job not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeofencingJobNotFoundResponse" } } } }, "405": { "description": "Method not allowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeofencingMethodNotAllowedResponse" } } } }, "default": { "description": "An unexpected error occurred." } }, "security": [ { "BasicAuth": [] } ] } }, "/jobs/id/{jobID}/cancel": { "post": { "tags": [ "job" ], "summary": "Cancel a Job", "description": "\n> #### Access Restrictions\n> ##### Only Supervisor Sub-users with API access have permission to use this endpoint, otherwise any other Sub-user will receive a 403 Forbidden response.\n\nCancel an existing Job by its ID. This action will update the job status to 'cancelled' and trigger any related cancellation workflows.", "parameters": [ { "name": "jobID", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Job was cancelled successfully.", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Job cancelled successfully." } }, "type": "object" } } } }, "403": { "description": "Access to the requested resource is forbidden for sub-users.", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Sub-users are not allowed to access this resource." } }, "type": "object" } } } }, "404": { "description": "No Job found for given `jobID`.", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Job not found." } }, "type": "object" } } } }, "409": { "description": "API access is disabled. For further details, reach out to api.support@cigotracker.com or talk to your account manager.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiDisabledResponse" } } } } }, "security": [ { "BasicAuth": [] } ] } } }, "components": { "schemas": { "PingDetails": { "title": "Ping Details", "properties": { "client_ip": { "description": "Your IP address as seen by our servers.", "type": "string", "example": "" }, "api_account_id": { "description": "API Account ID associated with this session.", "type": "string", "example": "" }, "company_name": { "description": "Name of the company for this authentication.", "type": "string", "example": "" }, "tenant_name": { "description": "If any, name of the tenant for this authentication.", "type": "string", "example": "" }, "docs": { "description": "URL to the Public API documentation.", "type": "string", "example": "" } }, "type": "object" }, "JobModel": { "title": "Job", "properties": { "job_id": { "description": "Job ID", "type": "string", "example": "f4e922d54b98a878488d2754fd4cfc0e" }, "stop_type": { "description": "Stop Type", "type": "string", "example": "job" }, "job_type": { "description": "Job Type: Potential job types are `delivery`, `return`, `exchange`, `installation`, `service`, `pick up`, and `custom`\n\n **Note**: This property is only there if the `stop_type` is equal to `job`.", "type": "string", "example": "delivery" }, "status": { "description": "Status: Potential statuses are `staging`, `new`, `in progress`, `damaged`, `completed`, `resolved`, `incomplete`, `cancelled` and `partially completed`", "type": "string", "example": "completed" }, "status_metadata": { "description": "Status Metadata set via in Cigo's Operator API. This is a free text field, and it can be formatted as you wish, as long as it is a string.", "type": "string", "example": "{'data': 'Example of Free Text (it doesn't have to be JSON!)'}" }, "post_staging": { "description": "Information available once the job is no longer in status `staging`", "properties": { "tracking": { "$ref": "#/components/schemas/TrackingInformation" }, "progress": { "$ref": "#/components/schemas/ProgressInformation" }, "scheduling": { "$ref": "#/components/schemas/SchedulingInformation" }, "coordinates": { "description": "Coordinates in GeoJSON format: `[latitude, longitude]` (both values are of type `float`)", "type": "array", "items": { "type": "number", "format": "float" }, "maxItems": 2, "minItems": 2, "example": [ 46.7727384, -71.3180309 ] }, "geocoding": { "$ref": "#/components/schemas/GeocodingInformation" }, "digital_signature": { "$ref": "#/components/schemas/DigitalSignatureInformation" }, "payment_collection": { "$ref": "#/components/schemas/PaymentCollectionInformation" }, "review": { "$ref": "#/components/schemas/ReviewInformation" } }, "type": "object" }, "quick_desc": { "description": "Quick Description\n\n **Note**: This property is only there if the `stop_type` is equal to `job`.", "type": "string", "example": "SAMPLE" }, "date": { "description": "Date (ISO-8601)\n\n **Note**: If no date has yet been determined for this Job to be fulfilled on, this value will be `tbd` (for To be determined).", "type": "string", "format": "date", "example": "2024-08-01" }, "original_date": { "description": "Original Job Date", "type": "string", "format": "date", "example": "2019-03-29" }, "confirmation_status": { "description": "Confirmation Status: Possible statuses are `pending`, and `confirmed`", "type": "string", "example": "confirmed" }, "first_name": { "description": "First name", "type": "string", "example": "John" }, "last_name": { "description": "Last name", "type": "string", "example": "Doe" }, "phone_number": { "description": "Phone number", "type": "string", "example": "(000) 000-0001" }, "mobile_number": { "description": "Mobile number", "type": "string", "example": "(000) 000-0002" }, "email": { "description": "Email", "type": "string", "format": "email", "example": "john.doe@example.com" }, "address": { "description": "Address", "type": "string", "example": "275 Notre-Dame St. East, Montreal, QC, H2Y 1C6" }, "apartment": { "description": "Apartment", "type": "string", "example": "Suite 101" }, "postal_code": { "description": "Postal code or ZIP code", "type": "string", "example": "H2Y 1C6" }, "time_preference": { "description": "Preference", "type": "string", "example": "AM" }, "balance_owed": { "description": "Balance Owed (positive number with up to 2 decimal points)", "type": "number", "format": "float", "example": 265.89 }, "comment": { "description": "Comment", "type": "string", "example": "A sample comment regarding the Job for John Doe!" }, "branch_id": { "description": "Branch ID (corresponding to the Location Ref. ID)", "type": "string", "example": "S10" }, "branch_api_id": { "description": "Branch API ID (corresponding to the Location API ID)", "type": "string", "example": "73de8cb492d22423a2a5a56f142b76b5" }, "distribution_center_id": { "description": "Distribution Center ID (corresponding to the Location Ref. ID)", "type": "string", "example": "DC12" }, "distribution_center_api_id": { "description": "Distribution Center API ID (corresponding to the Location API ID)", "type": "string", "example": "ba7ba295e3525fc61a4222d3674428db" }, "time_frame": { "description": "Time Frame", "properties": { "start": { "description": "Start time value has to be before End time value.", "type": "string", "example": "9:00 AM" }, "end": { "description": "End time value has to be after Start time value.", "type": "string", "example": "11:00 AM" } }, "type": "object" }, "invoices": { "description": "Invoices", "type": "array", "items": { "type": "string", "maxLength": 60, "example": "17823657812563" }, "uniqueItems": true }, "barcodes": { "description": "Barcodes", "type": "array", "items": { "type": "string", "maxLength": 60, "example": "17823657812563" } }, "label_count": { "description": "Label Count", "type": "integer", "example": 3 }, "wait_time": { "description": "Additional wait time (min)", "type": "integer", "example": 90 }, "metrics": { "description": "Total metrics associated with this Job.", "properties": { "handle_time": { "description": "Estimated time on site to fulfill this Job in minutes.", "type": "integer", "example": 25 }, "weight": { "description": "Total weight.", "type": "number", "format": "float", "example": 191.5 }, "volume": { "description": "Total volume.", "type": "number", "format": "float", "example": 4.5 }, "value": { "description": "Total value.", "type": "number", "format": "float", "example": 330.57 }, "piece_count": { "description": "Total piece count.", "type": "integer", "example": 2 }, "quantity": { "description": "Total quantity.", "type": "integer", "example": 2 } }, "type": "object" }, "pickup_metrics": { "description": "Total metrics associated with this Job's Pickup actions.", "properties": { "handle_time": { "description": "Estimated time on site to fulfill these actions in minutes.", "type": "integer", "example": 10 }, "weight": { "description": "Total weight.", "type": "number", "format": "float", "example": 20.6 }, "volume": { "description": "Total volume.", "type": "number", "format": "float", "example": 2.1 }, "value": { "description": "Total value.", "type": "number", "format": "float", "example": 499.9 }, "piece_count": { "description": "Total piece count.", "type": "integer", "example": 3 }, "quantity": { "description": "Total quantity.", "type": "integer", "example": 1 } }, "type": "object" }, "return_metrics": { "description": "Total metrics associated with this Job's Return and Exchange actions.", "properties": { "handle_time": { "description": "Estimated time on site to fulfill these actions in minutes.", "type": "integer", "example": 15 }, "weight": { "description": "Total weight.", "type": "number", "format": "float", "example": 213.4 }, "volume": { "description": "Total volume.", "type": "number", "format": "float", "example": 1.8 }, "value": { "description": "Total value.", "type": "number", "format": "float", "example": 678.99 }, "piece_count": { "description": "Total piece count.", "type": "integer", "example": 3 }, "quantity": { "description": "Total quantity.", "type": "integer", "example": 2 } }, "type": "object" }, "reference_id": { "description": "Reference ID", "type": "string", "example": "J-WJG318322" }, "customer_reference_id": { "description": "Customer Reference ID", "type": "string", "example": "C-WJG178262" }, "permanent_link": { "description": "Permanent link to this job to share externally", "type": "string", "example": "https://cigotracker.com/share/job?hash={job_id}" }, "creation_source": { "description": "Creation Source (possible options: `API`, `CSV`, `DIRECT`", "type": "string", "example": "API" }, "create_datetime": { "description": "Create Datetime", "type": "string", "format": "date", "example": "2019-04-28 18:32:41" } }, "type": "object" }, "CustomerModel": { "title": "Customer", "properties": { "customer_id": { "description": "Customer API ID", "type": "string", "example": "f4e922d54b98a878488d2754fd4cfc0e" }, "full_name": { "description": "Full name of the customer", "type": "string", "example": "John Doe" }, "phone_number": { "description": "Customer's phone number", "type": "string", "example": "(000) 000-0001" }, "mobile_number": { "description": "Customer's mobile number", "type": "string", "example": "(000) 000-0002" }, "address": { "description": "Customer's address", "type": "string", "example": "275 Notre-Dame St. East, Montreal, QC, H2Y 1C6" }, "coordinates": { "description": "Customer's coordinates `[latitude, longitude]`", "type": "array", "items": { "type": "number", "format": "float" }, "example": [ 46.7727384, -71.3180309 ] }, "reference_id": { "description": "Reference ID for the customer", "type": "string", "example": "C-WJG178262" }, "defaults": { "description": "customer-specific default preferences", "properties": { "time_preference": { "type": "string", "example": "AM" }, "job_type": { "type": "string", "example": "delivery" }, "branch_id": { "type": "string", "example": "S10" }, "branch_api_id": { "type": "string", "example": "73de8cb492d22423a2a5a56f142b76b5" }, "distribution_center_id": { "type": "string", "example": "DC12" }, "distribution_center_api_id": { "type": "string", "example": "ba7ba295e3525fc61a4222d3674428db" }, "comment": { "type": "string", "example": "A sample comment" }, "quick_description": { "type": "string", "example": "Quick description here" }, "handle_time": { "type": "integer", "example": 25 }, "email": { "type": "string", "format": "email", "example": "john.doe@example.com" }, "time_frame": { "description": "Preferred time frame for the customer", "properties": { "start": { "type": "string", "example": "9:00 AM" }, "end": { "type": "string", "example": "11:00 AM" } }, "type": "object" } }, "type": "object" }, "jobs": { "description": "List of job API IDs associated with the customer", "type": "array", "items": { "type": "string", "example": [ "f4e922d54b98a878488d2754fdvkd94", "kle946d54vvsgd4g88d2754fd4cfc0e" ] } } }, "type": "object" }, "JobReportsModel": { "title": "Job's Reports", "properties": { "digital_signature": { "$ref": "#/components/schemas/DigitalSignatureReport" }, "additional_digital_signatures": { "description": "A list of additional digital signatures.", "type": "array", "items": { "properties": { "id": { "description": "The ID of the digital signature.", "type": "integer" }, "agreement_text": { "description": "The text of the agreement.", "type": "string" }, "agreement_type": { "description": "The type of agreement.", "type": "string" }, "signer_name": { "description": "The name of the signer.", "type": "string" }, "signed": { "description": "Whether the signature is signed.", "type": "boolean" }, "file_url": { "description": "URL of the signature.", "type": "string", "format": "url" }, "operator_name": { "description": "Operator's name.", "type": "string" }, "created_time": { "description": "Creation time (GMT).", "type": "string", "format": "date-time" }, "signed_time": { "description": "Signature time (GMT).", "type": "string", "format": "date-time" } }, "type": "object" } }, "fulfillment": { "$ref": "#/components/schemas/GenericJobReport" }, "incidents": { "$ref": "#/components/schemas/GenericJobReport" }, "incomplete": { "$ref": "#/components/schemas/IncompleteJobReport" } }, "type": "object" }, "JobChatModel": { "title": "Job's chat", "properties": { "message": { "nullable": true, "description": "Chat message sent by web or mobile user.", "type": "string", "example": "Seems like no one's home. I called them, no answer. Should I wait a little longer?" }, "file_url": { "nullable": true, "description": "Link to the image shared (if any).", "type": "string", "example": "https://cigo.local/api/v1/jobs/id/?filename=" }, "user": { "$ref": "#/components/schemas/ReporterUserObject" }, "job_status": { "description": "Job status at the time of the chat message or image being sent.", "type": "string", "example": "in progress" }, "update_time": { "description": "Datetime the chat message or image was updated on (in GMT).", "type": "string", "example": "2022-10-11 22:47:58" }, "sent_on": { "description": "Datetime the chat message or image was sent on (in GMT).", "type": "string", "format": "date", "example": "2022-10-11 22:47:58" }, "read_on": { "nullable": true, "description": "Datetime the chat message or image was read on (in GMT).", "type": "string", "format": "date", "example": null }, "read_status": { "description": "Read status of the message. If `true`, the message has been read by at least 1 other user.", "type": "boolean", "format": "date", "example": false } }, "type": "object" }, "JobActionModel": { "title": "Job Action", "properties": { "action_id": { "description": "Action ID", "type": "string", "example": "97a7f7052349acb9db2fb28b19df3ba5" }, "id": { "description": "Some Internal ID, such as SKU, Product Code, etc.", "type": "string", "example": "ASG819723891263" }, "status": { "description": "Status: Potential statuses are `undetermined`, `completed`, `incomplete`, and `damaged`", "type": "string", "example": "completed" }, "status_reason": { "description": "Report message as entered by the `reporter`.", "type": "string", "example": "Review images associated with report for more details." }, "status_counters": { "description": "Status counters to breakdown of items marked `completed`, `incomplete` and `damaged`. The sum of these counters is always equal to the `quantity` set on the `action`.", "properties": { "completed": { "description": "Number of items marked as `completed`.", "type": "integer", "example": 2 }, "incomplete": { "description": "Number of items marked as `incomplete`.", "type": "integer", "example": 0 }, "damaged": { "description": "Number of items marked as `damaged`.", "type": "integer", "example": 0 } }, "type": "object" }, "type": { "description": "Type: Potential types are `delivery`, `return`, `pick up`, `installation`, `service`, `exchange`, and `custom`", "type": "string", "example": "delivery" }, "description": { "description": "Description", "type": "string", "example": "Astin Sofa - Grey" }, "value": { "description": "Value (positive number with up to 2 decimal points)", "type": "number", "format": "float", "example": 330.57 }, "unit_weight": { "description": "Unit Weight (positive number with up to 2 decimal points)", "type": "number", "format": "float", "example": 95.75 }, "total_weight": { "description": "Total Weight (positive number with up to 2 decimal points)", "type": "number", "format": "float", "example": 191.5 }, "unit_volume": { "description": "Unit Volume (positive number with up to 2 decimal points)", "type": "number", "format": "float", "example": 2.25 }, "total_volume": { "description": "Total Volume (positive number with up to 2 decimal points)", "type": "number", "format": "float", "example": 4.5 }, "piece_count": { "description": "Piece count (positive integer)", "type": "integer", "example": 1 }, "piece_count_unit": { "description": "The unit of the piece count.", "type": "string", "example": "boxes" }, "quantity": { "description": "Quantity (positive integer)", "type": "integer", "example": 2 }, "quantity_unit": { "description": "The unit of the quantity.", "type": "string", "example": null }, "handle_time": { "description": "Handle Time (positive integer)", "type": "integer", "example": 25 }, "stop_location_id": { "description": "Stop Location ID", "type": "string", "example": "B12" }, "stop_location_api_id": { "description": "Stop Location API ID", "type": "string", "example": "ffc9bcc45b9031a55e9401d148b9cc22" }, "stop_location": { "description": "Stop Location (this object will only be available if `stop_location_id` is not set and the Action type is `pickup`, `return` or `exchange`)", "properties": { "name": { "description": "Stop Location name.", "type": "string", "example": "Stop Location A" }, "geolocation": { "description": "The geolocation of this Stop Location.", "oneOf": [ { "$ref": "#/components/schemas/ItineraryPayloadLocationCoordinates" }, { "$ref": "#/components/schemas/ItineraryPayloadLocationAddress" } ] }, "time_frame": { "description": "Time Frame", "properties": { "start": { "description": "Start time value.", "type": "string", "example": "9:00 AM" }, "end": { "description": "End time value.", "type": "string", "example": "11:00 AM" } }, "type": "object" } }, "type": "object" }, "invoice_number": { "description": "Invoice Number", "type": "string", "example": "9871236WE127836" }, "external_reference_id": { "description": "External system reference ID", "type": "string", "example": "CJA20121105TBA69420" }, "shipping_barcode": { "description": "Shipping label barcode", "type": "string", "example": "1234567890" }, "create_datetime": { "description": "Create Datetime", "type": "string", "example": "2019-05-01 16:19:22" }, "properties": { "description": "Action properties", "properties": { "require_barcode": { "description": "Flag used to enforce the barcode scan when completing the Action.", "type": "boolean", "example": "false" } }, "type": "object" } }, "type": "object" }, "JobRelatedOnRouteStopsModel": { "title": "Related On-Route Stops", "properties": { "api_id": { "description": "API ID of On-Route Stop", "type": "string", "example": "fe9900e2b9d56b41465bb302127f6197" }, "status": { "description": "Status: Potential statuses are `new`, `in progress`, `damaged`, `completed`, `resolved`, `incomplete`, `cancelled` and `partially completed`", "type": "string", "example": "completed" }, "type": { "description": "Type: `pickup`, and `drop-off`", "type": "string", "example": "pickup" }, "location": { "description": "Stop Location name", "type": "string", "example": "Stop Location A" }, "address": { "description": "Location Address", "type": "string", "example": "275 Notre-Dame St. East, Montreal, QC, H2Y 1C6" }, "position": { "description": "Position on Itinerary", "type": "integer", "example": 1 }, "eta": { "description": "Estimated time for operators to be on arrive at On-Route Stop's Location", "type": "string", "format": "time", "example": "09:30 AM" }, "time_frame": { "description": "Time frame for operators to arrive at On-Route Stop's Location", "properties": { "start": { "type": "string", "example": "09:00 AM" }, "end": { "type": "string", "example": "11:00 AM" } }, "type": "object" } }, "type": "object" }, "VehicleModelOld": { "title": "Vehicle", "properties": { "name": { "description": "Vehicle name", "type": "string", "example": "HINO 00765" }, "reference_id": { "description": "Vehicle Reference ID", "type": "string", "example": "00765" }, "license_plate": { "description": "License Plate", "type": "string", "example": "C1G 0TR" } }, "type": "object" }, "ItineraryLocation": { "title": "Location", "properties": { "id": { "description": "Location ID (if applicable)", "type": "string", "example": "b53387df22645251aa9b22d24b7ec4a6" }, "name": { "description": "Location Name", "type": "string", "example": "Main Distribution Center" }, "reference_id": { "description": "Location Reference ID", "type": "string", "example": "001" }, "address": { "description": "Location Address", "type": "string", "example": "1455 Boulevard de Maisonneuve O, Montréal, QC H3G 1M8" }, "coordinates": { "description": "Coordinates in GeoJSON format: `[latitude, longitude]` (both values are of type `float`)", "type": "array", "items": { "type": "number", "format": "float" }, "maxItems": 2, "minItems": 2, "example": [ 46.7727384, -71.3180309 ] } }, "type": "object" }, "ItineraryTime": { "title": "Time", "properties": { "timezone": { "description": "Itinerary Timezone", "type": "string", "example": "America/Toronto" }, "planned_start_time": { "description": "Planned Start Time", "type": "string", "format": "date", "example": "2021-04-09 06:30 AM" }, "planned_start_time_unix": { "description": "Planned Start Time in Unix time", "type": "integer", "example": 1617949800 }, "actual_start_time": { "description": "Actual Start Time", "type": "string", "format": "date", "example": "2021-04-09 07:30 AM" }, "actual_start_time_unix": { "description": "Actual Start Time in Unix time", "type": "integer", "example": 1617946200 }, "create_time": { "description": "Create Time (GMT)", "type": "string", "format": "date", "example": "2021-04-14 14:52:04" }, "create_time_unix": { "description": "Create Time in Unix time", "type": "integer", "example": 1617946200 }, "update_time": { "description": "Update Time (GMT)", "type": "string", "format": "date", "example": "2021-04-14 14:52:04" }, "update_time_unix": { "description": "Update Time in Unix time", "type": "integer", "example": 1617946200 } }, "type": "object" }, "ItineraryRouteMetrics": { "title": "Itinerary Route Metrics", "properties": { "distance": { "description": "Distance in meters", "type": "number", "format": "float", "example": 407222.73 }, "road_time": { "description": "Road Time in minutes", "type": "integer", "example": 439 }, "handle_time": { "description": "Total Handle Time in minutes", "type": "integer", "example": 56 }, "duration": { "description": "Duration (road_time + handle_time) in minutes", "type": "integer", "example": 495 }, "value": { "description": "Total Value of Jobs", "type": "number", "format": "float", "example": 500.98 }, "weight": { "description": "Total Weight of Jobs", "type": "number", "format": "float", "example": 1500.18 }, "volume": { "description": "Total Volume of Jobs", "type": "number", "format": "float", "example": 900.18 }, "quantity": { "description": "Total Quantity of Jobs", "type": "integer", "example": 233 }, "piece_count": { "description": "Total Piece Count of Jobs", "type": "integer", "example": 401 }, "pickup_handle_time": { "description": "Total Handle Time of Pickup Stops in minutes", "type": "integer", "example": 401 }, "pickup_value": { "description": "Total Value of Pickup Stops", "type": "number", "format": "float", "example": 401.22 }, "pickup_weight": { "description": "Total Weight of Pickup Stops", "type": "number", "format": "float", "example": 401.33 }, "pickup_volume": { "description": "Total Volume of Pickup Stops", "type": "number", "format": "float", "example": 401.33 }, "pickup_quantity": { "description": "Total Quantity of Pickup Stops", "type": "integer", "example": 40 }, "pickup_piece_count": { "description": "Total Piece Count of Pickup Stops", "type": "integer", "example": 40 }, "drop_off_handle_time": { "description": "Total Handle Time of Drop-off Stops in minutes", "type": "integer", "example": 401 }, "drop_off_value": { "description": "Total Value of Drop-off Stops", "type": "number", "format": "float", "example": 401.22 }, "drop_off_weight": { "description": "Total Weight of Drop-off Stops", "type": "number", "format": "float", "example": 401.33 }, "drop_off_volume": { "description": "Total Volume of Drop-off Stops", "type": "number", "format": "float", "example": 401.33 }, "drop_off_quantity": { "description": "Total Quantity of Drop-off Stops", "type": "integer", "example": 40 }, "drop_off_piece_count": { "description": "Total Piece Count of Drop-off Stops", "type": "integer", "example": 40 }, "est_road_time": { "description": "Estimated Road Time in seconds", "type": "integer", "example": 26340, "deprecated": true }, "est_distance": { "description": "Distance in meters", "type": "number", "format": "float", "example": 407222.73, "deprecated": true } }, "type": "object" }, "ItineraryRouteOptions": { "title": "Itinerary Route Options", "properties": { "optimized_route": { "description": "Optimized Route", "type": "boolean", "example": true }, "avoid_tolls": { "description": "Avoid Tolls", "type": "boolean", "example": true }, "avoid_highways": { "description": "Avoid Highways", "type": "boolean", "example": false }, "avoid_ferries": { "description": "Avoid Ferries", "type": "boolean", "example": true }, "consider_traffic": { "description": "Consider Traffic", "type": "boolean", "example": true }, "street_side": { "description": "Indicates the preferred side of the street the Vehicle should arrive on relative to each of its planned stops.", "type": "string", "example": "right" }, "min_jobs": { "description": "Minimum number of Jobs", "type": "integer", "example": 10 }, "max_jobs": { "description": "Maximum number of Jobs", "type": "integer", "maximum": 150, "example": 40 }, "max_driving_time": { "description": "Maximum drive time (in seconds)", "type": "integer", "example": 40000 }, "max_distance": { "description": "Maximum distance (in meters)", "type": "integer", "example": 40000 }, "time_windows_type": { "description": "Indicates type of the Time Windows of `Jobs`", "type": "string", "enum": [ "none", "preference", "slot" ], "example": "preference" }, "ignore_min_jobs": { "description": "Indicates whether the `min_jobs` limitation was ignored", "type": "boolean", "example": true }, "ignore_max_jobs": { "description": "Indicates whether the `max_jobs` limitation was ignored", "type": "boolean", "example": true }, "ignore_max_driving_time": { "description": "Indicates whether the `max_driving_time` limitation was ignored", "type": "boolean", "example": true }, "ignore_max_distance": { "description": "Indicates whether the `max_distance` limitation was ignored", "type": "boolean", "example": true }, "ignore_max_volume": { "description": "Indicates whether the volume limitation of the assigned vehicle `{vehicle_id}` was ignored.", "type": "boolean", "example": true }, "ignore_max_weight": { "description": "Indicates whether the weight limitation of the assigned vehicle `{vehicle_id}` was ignored.", "type": "boolean", "example": true } }, "type": "object" }, "OperatorModelOld": { "title": "Operator", "properties": { "operator_id": { "description": "Operator API ID", "type": "string", "example": "56a5eb4a1b7b64d2d22232f74ca98523" }, "name": { "description": "Operator name", "type": "string", "example": "John Doe" }, "reference_id": { "description": "Operator Reference ID", "type": "string", "example": "95874-CA" }, "username": { "description": "Operator Login Username", "type": "string", "example": "example@domain.com" }, "last_active": { "description": "Last Active Datetime", "type": "string", "format": "date", "example": "2024-08-01 08:54:48" } }, "type": "object" }, "TrackingInformation": { "title": "Tracking information", "properties": { "url": { "description": "Tracking URL", "type": "string", "example": "https://cigo.io/EXAMPLE" }, "phone_number": { "description": "Tracking Phone Number", "type": "string", "example": "5148880000" }, "access_code": { "description": "Tracking Access Code", "type": "string", "example": "885854" }, "tracking_number": { "description": "Full hyphenated tracking number (16 or 18 characters)", "type": "string", "example": "P35UWX-GPIP6C-7ZZSJ2" }, "tracking_number_suffix": { "description": "Last 5 or 6 characters of the tracking number", "type": "string", "example": "7ZZSJ2" } }, "type": "object" }, "StopRouteMetrics": { "title": "Stop's route metrics in relation to the previous stop.", "properties": { "est_arrival_time": { "description": "At the time of planning the itinerary, the estimated arrival time. Once the route is in progress, this value may be adjusted dynamically if your account has dynamic ETAs enabled. The time zone of this value is based on the geocoding data of the related job (see `job.post_staging.geocoding.timezone` in [GET Retrieve a Job](#tag/job/paths/~1jobs~1id~1{jobID}/get)).", "type": "string", "example": "2024-08-01 10:03:00" }, "est_road_time": { "description": "At the time of planning the itinerary, the estimated road time (in minutes) between the previous stop (or the start location) to this stop.", "type": "integer", "example": 26340 }, "est_distance": { "description": "At the time of planning the itinerary, the estimated road distance (in meters) between the previous stop (or the start location) to this stop.", "type": "number", "format": "float", "example": 407222.73 } }, "type": "object" }, "ProgressInformation": { "title": "Progress information", "properties": { "duration": { "description": "Duration (in seconds)", "type": "integer", "example": 1063 }, "start_datetime": { "description": "Start Datetime", "type": "string", "format": "date", "example": "2024-08-01 09:23:21" }, "end_datetime": { "description": "End Datetime", "type": "string", "format": "date", "example": "2024-08-01 09:41:04" }, "started": { "description": "Job Started", "type": "boolean", "example": true }, "finished": { "description": "Job Finished", "type": "boolean", "example": true } }, "type": "object" }, "InProgressInformation": { "title": "Progress information", "properties": { "duration": { "description": "Duration (in seconds)", "type": "integer", "example": null }, "start_datetime": { "description": "Start Datetime", "type": "string", "format": "date", "example": "2024-08-01 09:23:21" }, "end_datetime": { "description": "End Datetime", "type": "string", "format": "date", "example": null }, "started": { "description": "Job Started", "type": "boolean", "example": true }, "finished": { "description": "Job Finished", "type": "boolean", "example": false } }, "type": "object" }, "SchedulingInformation": { "title": "Scheduling information", "properties": { "operators": { "description": "Operators assigned to handle this Job", "type": "array", "items": { "$ref": "#/components/schemas/OperatorModelOld" } }, "itinerary_id": { "description": "Itinerary API ID", "type": "string", "example": "6452b37d5242d835ba9a246feab2127c", "deprecated": true }, "itinerary_api_id": { "description": "Itinerary API ID", "type": "string", "example": "6452b37d5242d835ba9a246feab2127c" }, "vehicle": { "description": "Vehicle Name", "type": "string", "example": "HINO 00765" }, "vehicle_id": { "description": "Vehicle Reference ID", "type": "string", "example": "00765" }, "vehicle_api_id": { "description": "Vehicle API ID", "type": "string", "example": "bdca6e528b4324a2279d7ab25265431f" }, "position": { "description": "Position on Itinerary", "type": "integer", "example": 1 }, "route_metrics": { "$ref": "#/components/schemas/StopRouteMetrics" } }, "type": "object" }, "GeocodingInformation": { "title": "Geocoding information", "properties": { "validity": { "description": "Validity of the geocoded address. Possible values are: `valid`, `invalid`, `partial`, `partial_eav` (if you have the 'Enhanced Address Validation' feature enabled), `multi`, `manual`, and `error` (if an error occurred while attempting to geocode).", "type": "string", "example": "valid" }, "subdivision_code": { "description": "This should generally be set to the ISO 3166-2 code (principal subdivision - e.g. province or state) of the geocoded address.", "type": "string", "example": "QC" }, "country_code": { "description": "This should generally be set to the ISO 3166-1 code (country code) of the geocoded address.", "type": "string", "example": "CA" }, "timezone": { "description": "Timezone identifier based on the geolocation.", "type": "string", "example": "America/Toronto" } }, "type": "object" }, "VehicleTrackingInformation": { "title": "Vehicle tracking information", "properties": { "coordinates": { "description": "Coordinates in GeoJSON format: `[latitude, longitude]` (both values are of type `float`)", "type": "array", "items": { "type": "number", "format": "float" }, "maxItems": 2, "minItems": 2, "example": [ 46.7727384, -71.3180309 ] }, "last_known": { "description": "Last known time in GMT", "type": "string", "format": "date", "example": "2024-08-01 08:15:00" }, "route_data": { "$ref": "#/components/schemas/VehicleTrackingInformationRouteData" } }, "type": "object" }, "VehicleTrackingInformationRouteData": { "title": "Route data", "properties": { "arrival_time": { "description": "Estimated arrival time in GMT", "type": "string", "format": "date", "example": "2024-08-01 08:25:00" }, "distance": { "description": "Estimated Distance in meters.", "type": "number", "format": "float", "example": 173.68 }, "road_time": { "description": "Estimated Road Time in minutes.", "type": "integer", "example": 10 } }, "type": "object" }, "DigitalSignatureInformation": { "title": "Digital signature information", "properties": { "agreement": { "description": "Digital signature agreement text.", "type": "string", "example": "All items have been properly inspected during the delivery." }, "signed": { "description": "Digital signature status.", "type": "boolean", "example": false }, "name": { "description": "Signature print name of the customer. In some organization accounts, this field is not mandatory.", "type": "string", "example": null }, "datetime": { "description": "Datetime the digital signature was captured (in GMT).", "type": "string", "format": "date", "example": null } }, "type": "object" }, "ReporterUserObject": { "title": "Reporter user information", "properties": { "api_id": { "description": "User's API ID.", "type": "string", "example": "b53387df22645251aa9b22d24b7ec4a6" }, "username": { "description": "User's login username.", "type": "string", "example": "example@domain.com" }, "name": { "description": "User's full name.", "type": "string", "example": "John Doe" }, "role": { "description": "User's role within the platform.", "type": "string", "example": "Operator" } }, "type": "object" }, "PaymentCollectionInformation": { "title": "Payment collection information", "properties": { "payment_collection_allowed": { "description": "Indicates if payment collection is allowed for this job.", "type": "boolean", "example": false }, "balance_owed": { "description": "Balance owed upon arrival on job site.", "type": "number", "format": "float", "example": 758.88 }, "amount_collected": { "description": "Amount collected", "type": "number", "format": "float", "example": 758.88 }, "payment_method": { "description": "Payment method used. Potential values are `cash`, `debit`, `credit`, `cheque`, and `etransfer`", "type": "string", "example": "cash" }, "paid_in_full": { "description": "Marks if the balance owed has been paid in full.", "type": "boolean", "example": true } }, "type": "object" }, "DigitalSignatureReport": { "title": "Digital signature report", "properties": { "agreement": { "nullable": true, "description": "Digital signature agreement text.", "type": "string", "example": "All items have been properly inspected during the delivery." }, "signed": { "description": "Digital signature status.", "type": "boolean", "example": false }, "file_url": { "nullable": true, "description": "Digital signature file URL.", "type": "string", "example": "https://cigotracker.com/api/v1/jobs/id/?filename=" }, "name": { "nullable": true, "description": "Signature print name of the customer.", "type": "string", "example": null }, "coordinates": { "nullable": true, "description": "GPS coordinates of the report location.", "type": "array", "items": { "properties": { "latitude": { "description": "GPS Coordinate where report was sent.", "type": "string" }, "longitude": { "description": "GPS Coordinate where report was sent.", "type": "string" } }, "type": "object" } }, "datetime": { "nullable": true, "description": "Datetime the digital signature was captured (in GMT).", "type": "string", "format": "date", "example": null } }, "type": "object" }, "GenericJobReport": { "title": "Job report", "properties": { "message": { "nullable": true, "description": "Report message as entered by the `reporter`.", "type": "string", "example": "Review images associated with report for more details." }, "reporter": { "$ref": "#/components/schemas/ReporterUserObject" }, "submitted": { "description": "Indicates if this report was submitted or not.", "type": "boolean", "example": true }, "file_urls": { "description": "List of files uploaded in association with this report by the `reporter`.", "type": "array", "items": { "type": "string" }, "maxItems": 5, "minItems": 1, "example": [ "https://cigotracker.com/api/v1/jobs/id/?filename=", "https://cigotracker.com/api/v1/jobs/id/?filename=" ] }, "coordinates": { "nullable": true, "description": "GPS coordinates of the report location.", "type": "array", "items": { "properties": { "latitude": { "description": "GPS Coordinate where report was sent.", "type": "string" }, "longitude": { "description": "GPS Coordinate where report was sent.", "type": "string" } }, "type": "object" } }, "datetime": { "nullable": true, "description": "Datetime the report was submitted by the `reporter` (in GMT).", "type": "string", "format": "date", "example": null } }, "type": "object" }, "IncompleteJobReport": { "title": "Incomplete Job report", "properties": { "message": { "nullable": true, "description": "Report message as entered by the `reporter`.", "type": "string", "example": "Review images associated with report for more details." }, "reporter": { "$ref": "#/components/schemas/ReporterUserObject" }, "submitted": { "description": "Indicates if this report was submitted or not.", "type": "boolean", "example": true }, "file_urls": { "description": "List of files uploaded in association with this report by the `reporter`.", "type": "array", "items": { "type": "string" }, "maxItems": 5, "minItems": 1, "example": [ "https://cigotracker.com/api/v1/jobs/id/?filename=", "https://cigotracker.com/api/v1/jobs/id/?filename=" ] }, "coordinates": { "nullable": true, "description": "GPS coordinates of the report location.", "type": "array", "items": { "properties": { "latitude": { "description": "GPS Coordinate where report was sent.", "type": "string" }, "longitude": { "description": "GPS Coordinate where report was sent.", "type": "string" } }, "type": "object" } }, "datetime": { "nullable": true, "description": "Datetime the report was submitted by the `reporter` (in GMT).", "type": "string", "format": "date", "example": null }, "reason_approved": { "description": "Indicates the approval status of the `message` value by platform users. A `false` value signifies that the `message` has been reviewed and rejected by users within the platform, while `true` implies it has received approval. By default, when an incomplete report is submitted, this value is `true`.", "type": "boolean", "example": true }, "revised_reason": { "nullable": true, "description": "Provides the justification for the disapproval of the `message` value. This property is relevant and populated only when `reason_approved` is `false`. It contains a detailed explanation or feedback regarding why the report's `message` value did not secure approval from the platform users.", "type": "string", "example": null } }, "type": "object" }, "ReviewInformation": { "title": "Review information", "properties": { "score": { "description": "Customer review score from 1 to 5", "type": "number", "example": 4 }, "comment": { "description": "Customer review comment", "type": "string", "example": "Had a great experience, friendly staff!" }, "datetime": { "description": "Datetime the review was submitted by the customer (in GMT).", "type": "string", "format": "date", "example": "2019-04-25 20:01:56" }, "sales_score": { "description": "Customer review score from 1 to 5 for sales", "type": "number", "example": 5 } }, "type": "object" }, "BasicJobModel": { "title": "Basic Job", "properties": { "job_id": { "description": "Job ID", "type": "string", "example": "97867f09fca1a2614f4d52615c13ded7" }, "stop_type": { "description": "Stop Type: Potential types are `job`, `pickup`, and `dropoff`", "type": "string", "example": "job" }, "job_type": { "description": "Job Type: Potential job types are `delivery`, `return`, `exchange`, `installation`, `service`, `pick up`, and `custom`\n\n **Note**: This property is only there if the `stop_type` is equal to `job`.", "type": "string", "example": "delivery" }, "position": { "description": "Position", "type": "integer", "example": 1 }, "branch_id": { "description": "Branch ID (corresponding to the Location Ref. ID)", "type": "string", "example": "S10" }, "branch_api_id": { "description": "Branch API ID (corresponding to the Location API ID)", "type": "string", "example": "73de8cb492d22423a2a5a56f142b76b5" }, "distribution_center_id": { "description": "Distribution Center ID (corresponding to the Location Ref. ID)", "type": "string", "example": "DC12" }, "distribution_center_api_id": { "description": "Distribution Center API ID (corresponding to the Location API ID)", "type": "string", "example": "ba7ba295e3525fc61a4222d3674428db" }, "status": { "description": "Status: Potential statuses are `new`, `in progress`, `damaged`, `completed`, `resolved`, `incomplete`, `cancelled` and `partially completed`\n\n **Note**: Once assigned to an itinerary, the status can never be `staging`.", "type": "string", "example": "completed" }, "address": { "description": "Address", "type": "string", "example": "275 Notre-Dame St. East, Montreal, QC, H2Y 1C6" }, "apartment": { "description": "Apartment", "type": "string", "example": "Suite 101" }, "postal_code": { "description": "Postal code or ZIP code", "type": "string", "example": "H2Y 1C6" }, "coordinates": { "description": "Coordinates in GeoJSON format: `[latitude, longitude]` (both values are of type `float`)", "type": "array", "items": { "type": "number", "format": "float" }, "maxItems": 2, "minItems": 2, "example": [ 46.7727384, -71.3180309 ] }, "quick_desc": { "description": "Quick Description\n\n **Note**: This property is only there if the `stop_type` is equal to `job`.", "type": "string", "example": "SAMPLE" }, "route_metrics": { "$ref": "#/components/schemas/StopRouteMetrics" }, "progress": { "$ref": "#/components/schemas/ProgressInformation" }, "related_jobs": { "description": "Related Jobs\n\n **Note**: This property is only there if the `stop_type` is equal to `pickup` or `dropoff`.", "type": "array", "items": { "type": "string", "example": "f4e922d54b98a878488d2754fd4cfc0e" } } }, "type": "object" }, "BasicStopModel": { "title": "Basic Stop", "properties": { "id": { "type": "string", "example": "stop0123" }, "stop_type": { "description": "Stop Type: Potential types are `job`, `pickup`, and `dropoff`", "type": "string", "example": "job" }, "locked": { "type": "boolean", "example": false }, "name": { "type": "string", "example": "deliver box" }, "coordinates": { "type": "array", "items": { "type": "number", "format": "float" }, "maxItems": 2, "minItems": 2, "example": [ 46.7727384, -71.3180309 ] }, "address": { "type": "string", "example": "275 Notre-Dame St. East, Montreal, QC" }, "position": { "type": "integer", "example": 1 }, "road_time": { "description": "Road Time in minutes", "type": "integer", "example": 439 }, "road_distance": { "description": "Road Distance in meters", "type": "number", "example": 439 }, "eta": { "description": "Estimated time for operators to be on Customer site.", "type": "string", "format": "time", "example": "09:30 AM" }, "handle_time": { "type": "integer", "example": 10 }, "value": { "type": "number", "format": "float", "example": 1149.96 }, "weight": { "type": "number", "format": "float", "example": 120.5 }, "volume": { "type": "number", "format": "float", "example": 2.75 }, "piece_count": { "type": "integer", "example": 1 }, "quantity": { "type": "integer", "example": 2 }, "time_preference": { "type": "string", "enum": [ "AM", "PM", "morning", "midday", "afternoon", "evening", "night", "none" ], "example": "AM" }, "time_frame": { "properties": { "start": { "type": "string", "example": "09:00 AM" }, "end": { "type": "string", "example": "11:00 AM" } }, "type": "object" }, "related_jobs": { "description": "Related Jobs\n\n **Note**: This property is only there if the `stop_type` is equal to `pickup` or `dropoff`.", "type": "array", "items": { "type": "string", "example": "f4e922d54b98a878488d2754fd4cfc0e" } } }, "type": "object" }, "ItineraryModel": { "title": "Itinerary", "properties": { "itinerary_id": { "description": "Itinerary ID", "type": "string", "example": "b53387df22645251aa9b22d24b7ec4a6" }, "numeric_id": { "description": "Numeric ID", "type": "integer", "example": 984753 }, "date": { "description": "Date", "type": "string", "format": "date", "example": "2024-08-01" }, "planned_departure_datetime": { "description": "Planned Departure Datetime", "type": "string", "format": "date", "example": "2024-08-01 08:15:00" }, "time": { "$ref": "#/components/schemas/ItineraryTime" }, "time_frame_size": { "description": "Time Frame Size (if applicable)", "type": "number", "format": "float", "example": 2.5 }, "start_location": { "$ref": "#/components/schemas/ItineraryLocation" }, "end_location": { "$ref": "#/components/schemas/ItineraryLocation" }, "route_status_code": { "description": "Route calculation Status code", "type": "integer", "example": 200 }, "route_error_message": { "description": "Route calculation error message", "type": "string", "example": 200 }, "round_trip": { "description": "Round Trip indicator", "type": "boolean", "example": true }, "route_metrics": { "$ref": "#/components/schemas/ItineraryRouteMetrics" }, "route_options": { "$ref": "#/components/schemas/ItineraryRouteOptions" }, "vehicle": { "$ref": "#/components/schemas/ItineraryVehicleModel" }, "operators": { "description": "Operators", "type": "array", "items": { "$ref": "#/components/schemas/ItineraryOperator" } }, "stops_count": { "description": "Stops Count", "type": "integer", "example": 1 }, "stops": { "description": "Stops", "type": "array", "items": { "$ref": "#/components/schemas/BasicJobModel" } }, "options": { "$ref": "#/components/schemas/ItineraryOptionsResponseModel" } }, "type": "object" }, "PreviewItineraryModel": { "title": "Itinerary", "properties": { "itinerary_id": { "description": "Itinerary ID", "type": "string", "example": "b53387df22645251aa9b22d24b7ec4a6" }, "date": { "description": "Date", "type": "string", "format": "date", "example": "2024-08-01" }, "time": { "$ref": "#/components/schemas/ItineraryTime" }, "time_frame_size": { "description": "Time Frame Size (if applicable)", "type": "number", "format": "float", "example": 2.5 }, "start_location": { "$ref": "#/components/schemas/ItineraryLocation" }, "end_location": { "$ref": "#/components/schemas/ItineraryLocation" }, "route_status_code": { "description": "Route calculation Status code", "type": "integer", "example": 200 }, "route_error_message": { "description": "Route calculation error message", "type": "string", "example": 200 }, "round_trip": { "description": "Round Trip indicator", "type": "boolean", "example": true }, "route_metrics": { "$ref": "#/components/schemas/ItineraryRouteMetrics" }, "route_options": { "$ref": "#/components/schemas/ItineraryRouteOptions" }, "vehicle": { "$ref": "#/components/schemas/ItineraryVehicleModel" }, "operators": { "description": "Operators", "type": "array", "items": { "$ref": "#/components/schemas/ItineraryOperator" } }, "stops_count": { "description": "Stops Count", "type": "integer", "example": 1 }, "stops": { "description": "Stops", "type": "array", "items": { "$ref": "#/components/schemas/BasicStopModel" } }, "warnings": { "description": "Warnings", "type": "array", "items": { "$ref": "#/components/schemas/PreviewItineraryWarnings" } } }, "type": "object" }, "LocationModel": { "title": "Location", "properties": { "id": { "description": "Location ID", "type": "string", "example": "b53387df22645251aa9b22d24b7ec4a6" }, "type": { "description": "Location Type: `branch`, `warehouse`", "type": "string", "example": "branch" }, "name": { "description": "Location Name", "type": "string", "example": "Main Distribution Center" }, "reference_id": { "description": "Location Reference ID", "type": "string", "example": "001" }, "address": { "description": "Location Address", "type": "string", "example": "1455 Boulevard de Maisonneuve O, Montréal, QC H3G 1M8" }, "postal_code": { "description": "Location's postal or ZIP code", "type": "string", "example": "H3G 1M8" }, "coordinates": { "description": "Coordinates in GeoJSON format: `[latitude, longitude]` (both values are of type `float`)", "type": "array", "items": { "type": "number", "format": "float" }, "maxItems": 2, "minItems": 2, "example": [ 46.7727384, -71.3180309 ] }, "activated": { "description": "Access status. When `activated` is `true`, the location can be assigned as start and/or end of itineraries, as well as the default location for vehicles and certain dispatchers.", "type": "boolean", "example": true } }, "type": "object" }, "VehicleModel": { "title": "Vehicle", "properties": { "id": { "description": "Vehicle ID", "type": "string", "example": "b53387df22645251aa9b22d24b7ec4a6" }, "name": { "description": "Vehicle Name", "type": "string", "example": "HINO 00765" }, "reference_id": { "description": "Vehicle Reference ID", "type": "string", "example": "001" }, "type": { "description": "Vehicle Type", "type": "string", "example": "small_truck" }, "weight_capacity": { "description": "Vehicle Weight Capacity (METRIC UNIT)", "type": "number", "example": "19500" }, "volume_capacity": { "description": "Vehicle Volume Capacity (METRIC UNIT)", "type": "number", "example": "800" }, "license_plate": { "description": "License Plate", "type": "string", "example": "C1G 0TR" }, "start_time": { "description": "Default Start Time", "type": "string", "example": "08:00 AM" }, "start_location": { "$ref": "#/components/schemas/LocationModel" }, "end_location": { "$ref": "#/components/schemas/LocationModel" }, "activated": { "description": "Access status. When `activated` is `true`, the vehicle can be assigned to itineraries.", "type": "boolean", "example": true }, "breaks": { "description": "List of configured break windows for this vehicle.", "type": "array", "items": { "$ref": "#/components/schemas/VehicleBreakResource" } } }, "type": "object" }, "ItineraryVehicleModel": { "title": "Vehicle", "properties": { "id": { "description": "Vehicle ID", "type": "string", "example": "b53387df22645251aa9b22d24b7ec4a6" }, "name": { "description": "Vehicle Name", "type": "string", "example": "HINO 00765" }, "reference_id": { "description": "Vehicle Reference ID", "type": "string", "example": "001" }, "type": { "description": "Vehicle Type", "type": "string", "example": "small_truck" }, "weight_capacity": { "description": "Vehicle Weight Capacity (METRIC UNIT)", "type": "number", "example": "19500" }, "volume_capacity": { "description": "Vehicle Volume Capacity (METRIC UNIT)", "type": "number", "example": "800" }, "license_plate": { "description": "License Plate", "type": "string", "example": "C1G 0TR" }, "breaks": { "description": "List of configured break windows for this vehicle.", "type": "array", "items": { "$ref": "#/components/schemas/ScheduleVehicleBreakResource" } } }, "type": "object" }, "OperatorModel": { "title": "Operator", "properties": { "id": { "description": "Operator's API ID", "type": "string", "example": "b53387df22645251aa9b22d24b7ec4a6" }, "name": { "description": "Operator's full name.", "type": "string", "example": "John Doe" }, "reference_id": { "description": "Operator's reference ID.", "type": "string", "example": "95874-CA" }, "username": { "description": "Operator's login username.", "type": "string", "example": "example@domain.com" }, "phone_number": { "description": "Operator's phone number.", "type": "string", "example": "+1347XXXXXXX" }, "language": { "description": "Operator's selected in-app language (returned as ISO 639-1 code).", "type": "string", "example": "en" }, "timezone": { "description": "Operator's time zone.", "type": "string", "example": "America/New_York" }, "last_active": { "description": "Last active datetime in GMT. This is based on the last action taken by the operator.", "type": "string", "format": "date", "example": "2024-08-01 08:54:48" }, "avg_rate": { "description": "Average rating based on customer reviews.", "type": "number", "example": "4.95" }, "activated": { "description": "Access status. When `activated` is `true`, the operator has access to the platform.", "type": "boolean", "example": true } }, "type": "object" }, "ItineraryOperator": { "title": "Operator", "properties": { "id": { "description": "Operator ID", "type": "string", "example": "b53387df22645251aa9b22d24b7ec4a6" }, "name": { "description": "Operator name", "type": "string", "example": "John Doe" }, "reference_id": { "description": "Operator Reference ID", "type": "string", "example": "95874-CA" }, "username": { "description": "Operator Login Username", "type": "string", "example": "example@domain.com" }, "last_active": { "description": "Last Active Datetime", "type": "string", "format": "date", "example": "2024-08-01 08:54:48" }, "avg_rate": { "description": "Average Rate", "type": "number", "example": "4.95" }, "seat": { "description": "Seat no.", "type": "integer", "maximum": 4, "minimum": 1, "example": 1 }, "shifts": { "title": "Shift(s) data", "description": "Shift(s) data associated with this operator for the given itinerary.", "type": "array", "items": { "$ref": "#/components/schemas/ItineraryOperatorShiftSamples" } } }, "type": "object" }, "ItineraryOperatorShiftSamples": { "title": "Operator shift for itinerary samples", "anyOf": [ { "$ref": "#/components/schemas/ItineraryOperatorShiftSample01" }, { "$ref": "#/components/schemas/ItineraryOperatorShiftSample02" } ] }, "ItineraryOperatorShiftSample01": { "title": "First shift for itinerary", "properties": { "start_time": { "description": "Shift start time (in the operator's local timezone).", "type": "string", "example": "2024-08-01 08:15:58" }, "end_time": { "description": "Shift end time (in the operator's local timezone).", "type": "string", "example": "2024-08-01 14:35:12" } }, "type": "object" }, "ItineraryOperatorShiftSample02": { "title": "Second shift for itinerary", "properties": { "start_time": { "description": "Shift start time (in the operator's local timezone).", "type": "string", "example": "2024-08-01 15:00:02" }, "end_time": { "description": "Shift end time (in the operator's local timezone).", "type": "string", "example": "2024-08-01 17:20:54" } }, "type": "object" }, "ItineraryOptionsRequestModel": { "title": "Options", "properties": { "label": { "description": "Itinerary Label", "type": "string", "maximum": 30, "example": "Morning Route" }, "color": { "description": "Itinerary Color (Hex Code)", "type": "string", "example": "#0000FF" }, "note": { "description": "Itinerary Note", "type": "string", "maximum": 255, "example": "Track the weather and extreme weather situations along your route, whether it's sunny, rainy, or snowing." } }, "type": "object" }, "ItineraryOptionsResponseModel": { "title": "Options", "properties": { "label": { "description": "Itinerary Label", "type": "string", "example": "Morning Route" }, "color": { "description": "Itinerary Color (Hex Code)", "type": "string", "example": "#0000FF" }, "note": { "$ref": "#/components/schemas/ItineraryOptionsNoteResponseModel" } }, "type": "object" }, "ItineraryOptionsNoteResponseModel": { "title": "Note", "properties": { "text": { "description": "Itinerary Note", "type": "string", "example": "Track the weather and extreme weather situations along your route, whether it's sunny, rainy, or snowing." }, "create_user": { "description": "Create User", "type": "string", "example": "John Doe" }, "create_time": { "description": "Create Time (GMT)", "type": "string", "format": "date", "example": "2021-04-14 14:52:04" }, "update_user": { "description": "Update User", "type": "string", "example": "Jane Doe" }, "update_time": { "description": "Update Time (GMT)", "type": "string", "format": "date", "example": "2021-04-14 15:52:04" } }, "type": "object" }, "ItineraryRoutingInfoModel": { "title": "Options", "description": "Routing Information.", "properties": { "avoid_tolls": { "description": "Avoid Tolls.", "type": "boolean", "default": false, "example": false }, "avoid_highways": { "description": "Avoid Highways.", "type": "boolean", "example": false }, "avoid_ferries": { "description": "Avoid Ferries.", "type": "boolean", "default": false, "example": false }, "consider_traffic": { "description": "Indicates whether historical traffic information should be considered.", "type": "boolean", "default": false, "example": false }, "street_side": { "description": "For all stops in this itinerary, this option specifies the preferred side of the street the Vehicle should arrive on relative to each of its planned stops.\n\n**Note**: If set to `left` or `right`, u-turns will be avoided.", "type": "string", "default": "any", "enum": [ "any", "left", "right" ] }, "optimized_route": { "description": "Optimize Route to solve VRP (Vehicle Routing Problem)\n\n **Note**: In order to apply optimization settings some of the following properties must equal to `true`, otherwise they will be ignored.", "type": "boolean", "default": false, "example": true }, "ignore_min_jobs": { "description": "Ignore the `min_jobs` limitation.\n\n **Note**: In order to apply the following property, `optimized_route` property must equal to `true`, otherwise it will be ignored.", "type": "boolean", "default": true, "example": false }, "ignore_max_jobs": { "description": "Ignore the `max_jobs` limitation.\n\n **Note**: In order to apply the following property, `optimized_route` property must equal to `true`, otherwise it will be ignored.", "type": "boolean", "default": true, "example": false }, "ignore_max_driving_time": { "description": "Ignore the `ignore_max_driving_time` limitation.\n\n **Note**: In order to apply the following property, `optimized_route` property must equal to `true`, otherwise it will be ignored.", "type": "boolean", "default": true, "example": false }, "ignore_max_distance": { "description": "Ignore the `ignore_max_distance` limitation.\n\n **Note**: In order to apply the following property, `optimized_route` property must equal to `true`, otherwise it will be ignored.", "type": "boolean", "default": true, "example": false }, "ignore_max_volume": { "description": "Ignore the volume limitation of the assigned vehicle `{vehicle_id}`.\n\n **Note**: In order to apply the following property, `optimized_route` property must equal to `true`, otherwise it will be ignored.", "type": "boolean", "default": true, "example": false }, "ignore_max_weight": { "description": "Ignore the weight limitation of the assigned vehicle `{vehicle_id}`.\n\n **Note**: In order to apply the following property, `optimized_route` property must equal to `true`, otherwise it will be ignored.", "type": "boolean", "default": true, "example": false }, "min_jobs": { "description": "Minimum number of Jobs that the assigned vehicle `{vehicle_id}` should load. This is a soft constraint, i.e. if it is not possible to fulfill `min_jobs`, we will still try to get as close as possible to this constraint.\n\n **Note**: In order to apply the following property, `optimized_route` property must equal to `true`, otherwise it will be ignored.", "type": "integer", "default": 0, "minimum": 0, "example": 10 }, "max_jobs": { "description": "Maximum number of Jobs that the assigned vehicle `{vehicle_id}` can load.\n\n **Note**: In order to apply the following property, `optimized_route` property must equal to `true`, otherwise it will be ignored.", "type": "integer", "default": 150, "maximum": 150, "example": 40 }, "max_driving_time": { "description": "Maximum drive time (in seconds) that the assigned vehicle `{vehicle_id}` can go.\n\n **Note**: In order to apply the following property, `optimized_route` property must equal to `true`, otherwise it will be ignored.", "type": "integer", "minimum": 1800, "example": 40000 }, "max_distance": { "description": "Maximum distance (in meters) that the assigned vehicle `{vehicle_id}` can go.\n\n **Note**: In order to apply the following property, `optimized_route` property must equal to `true`, otherwise it will be ignored.", "type": "integer", "minimum": 500, "example": 40000 }, "time_windows_type": { "description": "Type of the Time Windows of `Jobs`.\n\n **Note**: In order to apply the following property, `optimized_route` property must equal to `true`, otherwise it will be ignored.", "type": "string", "default": "none", "enum": [ "none", "preference", "slot" ], "example": "preference" } }, "type": "object" }, "CreateItineraryWarnings": { "title": "Create Itinerary Warnings", "anyOf": [ { "$ref": "#/components/schemas/ItineraryWarningRoutingInfoConsiderTrafficModel" }, { "$ref": "#/components/schemas/ItineraryWarningRoutingInfoModel" }, { "$ref": "#/components/schemas/ItineraryWarningRoutingInfoOptimizationModel" }, { "$ref": "#/components/schemas/ItineraryWarningTimeFrameSizeModel1" }, { "$ref": "#/components/schemas/ItineraryWarningTimeFrameSizeModel2" }, { "$ref": "#/components/schemas/ItineraryWarningTimeFrameSizeModel3" }, { "$ref": "#/components/schemas/ItineraryWarningAddJobIDs" } ] }, "PreviewItineraryWarnings": { "title": "Preview Itinerary Warnings", "anyOf": [ { "$ref": "#/components/schemas/ItineraryWarningRoutingInfoConsiderTrafficModel" }, { "$ref": "#/components/schemas/ItineraryWarningRoutingInfoModel" }, { "$ref": "#/components/schemas/ItineraryWarningRoutingInfoOptimizationModel" }, { "$ref": "#/components/schemas/ItineraryWarningTimeFrameSizeModel1" }, { "$ref": "#/components/schemas/ItineraryWarningTimeFrameSizeModel2" }, { "$ref": "#/components/schemas/ItineraryWarningTimeFrameSizeModel3" }, { "$ref": "#/components/schemas/ItineraryWarningJobIDs" } ] }, "UpdateItineraryWarnings": { "title": "Update Itinerary Warnings", "anyOf": [ { "$ref": "#/components/schemas/ItineraryWarningRoutingInfoConsiderTrafficModel" }, { "$ref": "#/components/schemas/ItineraryWarningRoutingInfoModel" }, { "$ref": "#/components/schemas/ItineraryWarningRoutingInfoOptimizationModel" }, { "$ref": "#/components/schemas/ItineraryWarningTimeFrameSizeModel1" }, { "$ref": "#/components/schemas/ItineraryWarningTimeFrameSizeModel2" }, { "$ref": "#/components/schemas/ItineraryWarningTimeFrameSizeModel3" }, { "$ref": "#/components/schemas/ItineraryWarningAddJobIDs" }, { "$ref": "#/components/schemas/ItineraryWarningDeleteJobIDs" } ] }, "ItineraryWarningRoutingInfoConsiderTrafficModel": { "title": "Routing Error (Consider Traffic)", "description": "No route could be calculated with requested 'Consider Traffic' option.", "properties": { "warning_code": { "type": "integer", "enum": [ 904901 ] }, "field": { "type": "string", "enum": [ "consider_traffic" ] }, "message": { "type": "string", "enum": [ "No route could be calculated with requested 'Consider Traffic' option." ] }, "details": { "$ref": "#/components/schemas/ItineraryWarningDetailsBoolean" } }, "type": "object" }, "ItineraryWarningRoutingInfoModel": { "title": "Routing Error (Incomplete Optimization)", "description": "Optimization completed, but `{itinerary}` could not be fully optimized due to the limitations applied.", "properties": { "warning_code": { "type": "integer", "enum": [ 904902 ] }, "field": { "type": "string", "enum": [ "optimization_settings" ] }, "message": { "type": "string", "enum": [ "Optimization completed, but `{itinerary}` could not be fully optimized due to the limitations applied." ] }, "details": { "type": "array", "items": { "$ref": "#/components/schemas/ItineraryWarningRoutingInfoOptimizations" } } }, "type": "object" }, "ItineraryWarningRoutingInfoOptimizations": { "title": "Itinerary Warning Routing Info Optimizations", "anyOf": [ { "$ref": "#/components/schemas/ItineraryWarningRoutingInfoOptimization01" }, { "$ref": "#/components/schemas/ItineraryWarningRoutingInfoOptimization02" }, { "$ref": "#/components/schemas/ItineraryWarningRoutingInfoOptimization03" }, { "$ref": "#/components/schemas/ItineraryWarningRoutingInfoOptimization04" }, { "$ref": "#/components/schemas/ItineraryWarningRoutingInfoOptimization21" }, { "$ref": "#/components/schemas/ItineraryWarningRoutingInfoOptimization22" }, { "$ref": "#/components/schemas/ItineraryWarningRoutingInfoOptimization23" }, { "$ref": "#/components/schemas/ItineraryWarningRoutingInfoOptimization24" }, { "$ref": "#/components/schemas/ItineraryWarningRoutingInfoOptimization25" }, { "$ref": "#/components/schemas/ItineraryWarningRoutingInfoOptimization26" }, { "$ref": "#/components/schemas/ItineraryWarningRoutingInfoOptimization27" }, { "$ref": "#/components/schemas/ItineraryWarningRoutingInfoOptimization28" }, { "$ref": "#/components/schemas/ItineraryWarningRoutingInfoOptimization29" }, { "$ref": "#/components/schemas/ItineraryWarningRoutingInfoOptimization50" } ] }, "ItineraryWarningRoutingInfoOptimization01": { "title": "Failed optimization (required skills)", "description": "Failed optimization due to required skills.", "properties": { "id": { "description": "Job ID", "type": "string", "example": "99345a1c5e1ad9fd64785abf42e63701" }, "reason": { "description": "Reason", "type": "string", "enum": [ "Failed optimization due to required skills." ] }, "code": { "description": "Code", "type": "integer", "enum": [ 1 ] } }, "type": "object" }, "ItineraryWarningRoutingInfoOptimization02": { "title": "Failed optimization (time window)", "description": "Failed optimization due to invalid time window.", "properties": { "id": { "description": "Job ID", "type": "string", "example": "99345a1c5e1ad9fd64785abf42e63702" }, "reason": { "description": "Reason", "type": "string", "enum": [ "Failed optimization due to invalid time window." ] }, "code": { "description": "Code", "type": "integer", "enum": [ 2 ] } }, "type": "object" }, "ItineraryWarningRoutingInfoOptimization03": { "title": "Failed optimization (over capacity)", "description": "Failed optimization due to defined metric restrictions.", "properties": { "id": { "description": "Job ID", "type": "string", "example": "99345a1c5e1ad9fd64785abf42e63703" }, "reason": { "description": "Reason", "type": "string", "enum": [ "Failed optimization due to defined metric restrictions." ] }, "code": { "description": "Code", "type": "integer", "enum": [ 3 ] } }, "type": "object" }, "ItineraryWarningRoutingInfoOptimization04": { "title": "Failed optimization (distance exceeded)", "description": "Failed optimization due to long distance.", "properties": { "id": { "description": "Job ID", "type": "string", "example": "99345a1c5e1ad9fd64785abf42e63704" }, "reason": { "description": "Reason", "type": "string", "enum": [ "Failed optimization due to long distance." ] }, "code": { "description": "Code", "type": "integer", "enum": [ 4 ] } }, "type": "object" }, "ItineraryWarningRoutingInfoOptimization21": { "title": "Failed optimization (relation constraint)", "description": "Failed optimization due to relation constraint", "properties": { "id": { "description": "Job ID", "type": "string", "example": "99345a1c5e1ad9fd64785abf42e63721" }, "reason": { "description": "Reason", "type": "string", "enum": [ "Failed optimization due to relation constraint" ] }, "code": { "description": "Code", "type": "integer", "enum": [ 21 ] } }, "type": "object" }, "ItineraryWarningRoutingInfoOptimization22": { "title": "Failed optimization (invalid type for vehicle)", "description": "Failed optimization due to invalid type for the allowed vehicle constraint.", "properties": { "id": { "description": "Job ID", "type": "string", "example": "99345a1c5e1ad9fd64785abf42e63722" }, "reason": { "description": "Reason", "type": "string", "enum": [ "Failed optimization due to invalid type for the allowed vehicle constraint." ] }, "code": { "description": "Code", "type": "integer", "enum": [ 22 ] } }, "type": "object" }, "ItineraryWarningRoutingInfoOptimization23": { "title": "Failed optimization (expiry time)", "description": "Failed optimization due to expiry time.", "properties": { "id": { "description": "Job ID", "type": "string", "example": "99345a1c5e1ad9fd64785abf42e63723" }, "reason": { "description": "Reason", "type": "string", "enum": [ "Failed optimization due to expiry time." ] }, "code": { "description": "Code", "type": "integer", "enum": [ 23 ] } }, "type": "object" }, "ItineraryWarningRoutingInfoOptimization24": { "title": "Failed optimization (operator break)", "description": "Operator does not need a break.", "properties": { "id": { "description": "Job ID", "type": "string", "example": "99345a1c5e1ad9fd64785abf42e63724" }, "reason": { "description": "Reason", "type": "string", "enum": [ "Operator does not need a break." ] }, "code": { "description": "Code", "type": "integer", "enum": [ 24 ] } }, "type": "object" }, "ItineraryWarningRoutingInfoOptimization25": { "title": "Failed optimization (invalid vehicle type)", "description": "Failed optimization due to invalid type for the vehicle.", "properties": { "id": { "description": "Job ID", "type": "string", "example": "99345a1c5e1ad9fd64785abf42e63725" }, "reason": { "description": "Reason", "type": "string", "enum": [ "Failed optimization due to invalid type for the vehicle." ] }, "code": { "description": "Code", "type": "integer", "enum": [ 25 ] } }, "type": "object" }, "ItineraryWarningRoutingInfoOptimization26": { "title": "Failed optimization (long road time)", "description": "Failed optimization due to long road time.", "properties": { "id": { "description": "Job ID", "type": "string", "example": "99345a1c5e1ad9fd64785abf42e63726" }, "reason": { "description": "Reason", "type": "string", "enum": [ "Failed optimization due to long road time." ] }, "code": { "description": "Code", "type": "integer", "enum": [ 26 ] } }, "type": "object" }, "ItineraryWarningRoutingInfoOptimization27": { "title": "Failed optimization (max job constraint)", "description": "Failed optimization due to max job constraint.", "properties": { "id": { "description": "Job ID", "type": "string", "example": "99345a1c5e1ad9fd64785abf42e63727" }, "reason": { "description": "Reason", "type": "string", "enum": [ "Failed optimization due to max job constraint." ] }, "code": { "description": "Code", "type": "integer", "enum": [ 27 ] } }, "type": "object" }, "ItineraryWarningRoutingInfoOptimization28": { "title": "Failed optimization (max activity constraint)", "description": "Failed optimization due to max activity constraint.", "properties": { "id": { "description": "Job ID", "type": "string", "example": "99345a1c5e1ad9fd64785abf42e63728" }, "reason": { "description": "Reason", "type": "string", "enum": [ "Failed optimization due to max activity constraint." ] }, "code": { "description": "Code", "type": "integer", "enum": [ 28 ] } }, "type": "object" }, "ItineraryWarningRoutingInfoOptimization29": { "title": "Failed optimization (group relation constraint)", "description": "Failed optimization due to group relation constraint.", "properties": { "id": { "description": "Job ID", "type": "string", "example": "99345a1c5e1ad9fd64785abf42e63729" }, "reason": { "description": "Reason", "type": "string", "enum": [ "Failed optimization due to group relation constraint." ] }, "code": { "description": "Code", "type": "integer", "enum": [ 29 ] } }, "type": "object" }, "ItineraryWarningRoutingInfoOptimization50": { "title": "Failed optimization (location unaccessible)", "description": "Underlying location cannot be accessed over the road network by at least one vehicle.", "properties": { "id": { "description": "Job ID", "type": "string", "example": "99345a1c5e1ad9fd64785abf42e63750" }, "reason": { "description": "Reason", "type": "string", "enum": [ "Underlying location cannot be accessed over the road network by at least one vehicle." ] }, "code": { "description": "Code", "type": "integer", "enum": [ 50 ] } }, "type": "object" }, "ItineraryWarningRoutingInfoOptimizationModel": { "title": "Routing Error (Optimization Failed)", "description": "Route Optimization failed due to unsupported areas.", "properties": { "warning_code": { "type": "integer", "enum": [ 904903 ] }, "field": { "type": "string", "enum": [ "optimization" ] }, "message": { "type": "string", "enum": [ "Route Optimization failed due to unsupported areas." ] } }, "type": "object" }, "ItineraryWarningTimeFrameSizeModel1": { "title": "Time Frame Warning 1", "description": "Time Frame is not enabled.", "properties": { "warning_code": { "type": "integer", "enum": [ 904905 ] }, "field": { "type": "string", "enum": [ "time_frame_size" ] }, "message": { "type": "string", "enum": [ "Time Frame is not enabled." ] } }, "type": "object" }, "ItineraryWarningTimeFrameSizeModel2": { "title": "Time Frame Warning 2", "description": "Invalid Time Frame Size.", "properties": { "warning_code": { "type": "integer", "enum": [ 904906 ] }, "field": { "type": "string", "enum": [ "time_frame_size" ] }, "message": { "type": "string", "enum": [ "Invalid Time Frame Size." ] } }, "type": "object" }, "ItineraryWarningTimeFrameSizeModel3": { "title": "Time Frame Warning 3", "description": "Cannot modify time frame because {itinerary Name} has already been started.", "properties": { "warning_code": { "type": "integer", "enum": [ 904908 ] }, "field": { "type": "string", "enum": [ "time_frame_size" ] }, "message": { "type": "string", "enum": [ "Cannot modify time frame because {itinerary Name} has already been started." ] }, "details": { "$ref": "#/components/schemas/ItineraryWarningDetailsFloat" } }, "type": "object" }, "ItineraryWarningAddJobIDs": { "title": "Add Jobs", "description": "", "properties": { "warning_code": { "type": "integer", "enum": [ 904910 ] }, "field": { "type": "string", "enum": [ "add_ids" ] }, "message": { "type": "string", "enum": [ "Review the jobs you attempted to add to this itinerary. Potential reasons for this warning: the jobs do not exist (they were deleted from the system), are assigned to a date that differs from the itinerary date, are already assigned to an itinerary, have a non-new status, or have access restrictions." ] }, "details": { "title": "job ids", "properties": { "ids": { "description": "list of job ids", "type": "array", "items": { "type": "string", "example": "f4e922d54b98a878488d2754fd4cfc0e" }, "uniqueItems": true } }, "type": "object" } }, "type": "object" }, "ItineraryWarningDeleteJobIDs": { "title": "Delete Jobs", "description": "", "properties": { "warning_code": { "type": "integer", "enum": [ 904911 ] }, "field": { "type": "string", "enum": [ "delete_ids" ] }, "message": { "type": "string", "enum": [ "Review the jobs you attempted to delete from this itinerary. Potential reasons for this warning: the jobs do not exist (they were deleted from the system), are assigned to a date that differs from the itinerary date, are already assigned to an itinerary, have a non-new status, or have access restrictions." ] }, "details": { "title": "job ids", "properties": { "ids": { "description": "list of job ids", "type": "array", "items": { "type": "string", "example": "f4e922d54b98a878488d2754fd4cfc0e" }, "uniqueItems": true } }, "type": "object" } }, "type": "object" }, "ItineraryWarningJobIDs": { "title": "Jobs", "description": "", "properties": { "warning_code": { "type": "integer", "enum": [ 904912 ] }, "field": { "type": "string", "enum": [ "job_ids" ] }, "message": { "type": "string", "enum": [ "Review the jobs you attempted to review on this itinerary. Potential reasons for this warning: the jobs do not exist (they were deleted from the system), are assigned to a date that differs from the itinerary date, are already assigned to an itinerary, have a non-new status, or have access restrictions." ] }, "details": { "title": "job ids", "properties": { "ids": { "description": "list of job ids", "type": "array", "items": { "type": "string", "example": "f4e922d54b98a878488d2754fd4cfc0e" }, "uniqueItems": true } }, "type": "object" } }, "type": "object" }, "ItineraryWarningDetailsBoolean": { "title": "optimization", "properties": { "original_value": { "description": "Existing Value", "type": "boolean", "example": true }, "value": { "description": "New Value", "type": "boolean", "example": false } }, "type": "object" }, "ItineraryWarningDetailsFloat": { "title": "optimization", "properties": { "original_value": { "description": "Existing Value", "type": "number", "example": 4 }, "value": { "description": "New Value", "type": "number", "example": 2.5 } }, "type": "object" }, "JobLocationModel": { "title": "Job location info", "properties": { "job_id": { "description": "Job ID", "type": "string", "example": "f4e922d54b98a878488d2754fd4cfc0e" }, "status": { "description": "Status: Potential statuses are `new`, `in progress`, `damaged`, `completed`, `resolved`, `incomplete`, `cancelled` and `partially completed`", "type": "string", "example": "in progress" }, "progress": { "$ref": "#/components/schemas/InProgressInformation" }, "coordinates": { "description": "Coordinates in GeoJSON format: `[latitude, longitude]` (both values are of type `float`)", "type": "array", "items": { "type": "number", "format": "float" }, "maxItems": 2, "minItems": 2, "example": [ 46.7727384, -71.3180309 ] }, "geocoding": { "$ref": "#/components/schemas/GeocodingInformation" }, "vehicle_tracking": { "$ref": "#/components/schemas/VehicleTrackingInformation" } }, "type": "object" }, "AvailableSlotsModel": { "title": "Available Slots", "description": "Information about available slots based on date and geolocation.", "properties": { "slot_id": { "description": "Slot ID", "type": "string", "example": "slot12345" }, "date": { "description": "The date for the available slot. Expected format: YYYY-MM-DD.", "type": "string", "format": "date", "example": "2023-10-15" }, "start_time": { "description": "Start time of the slot.", "type": "string", "format": "time", "example": "09:00:00" }, "end_time": { "description": "End time of the slot.", "type": "string", "format": "time", "example": "11:00:00" }, "geolocation": { "description": "Geolocation coordinates in the format `latitude, longitude` (both values are of type `float`).", "type": "array", "items": { "type": "number", "format": "float" }, "maxItems": 2, "minItems": 2, "example": [ 37.7749, -122.4194 ] }, "status": { "description": "Status of the slot. Possible values are `available`, `booked`, `unavailable`.", "type": "string", "example": "available" } }, "type": "object" }, "AvailableBookingDatesModel": { "title": "Available Booking Dates", "description": "Information about available booking dates based on geolocation, address, month, days ahead, weight, volume, and days offset.", "properties": { "date": { "description": "The date for the available booking. Expected format: YYYY-MM-DD.", "type": "string", "format": "date", "example": "2023-10-15" }, "geolocation": { "description": "Geolocation coordinates in the format `latitude, longitude` (both values are of type `float`).", "type": "array", "items": { "type": "number", "format": "float" }, "maxItems": 2, "minItems": 2, "example": [ 37.7749, -122.4194 ] }, "address": { "description": "The address for the available booking.", "type": "string", "example": "123 Main St, San Francisco, CA" }, "month": { "description": "The month for the available booking. Expected format: YYYY-MM.", "type": "string", "example": "2023-10" }, "days_ahead": { "description": "The number of days ahead for which the booking is available.", "type": "integer", "example": 90 }, "weight": { "description": "The weight of the job for the available booking.", "type": "number", "format": "float", "example": 10.5 }, "volume": { "description": "The volume of the job for the available booking.", "type": "number", "format": "float", "example": 2.5 }, "days_offset": { "description": "The minimum number of days ahead for available booking dates.", "type": "integer", "example": 5 }, "status": { "description": "Status of the booking date. Possible values are `available`, `booked`, `unavailable`.", "type": "string", "example": "available" } }, "type": "object" }, "NoAvailableDatesResponse": { "description": "Response schema for no available dates found", "properties": { "error": { "description": "Error message", "type": "string" } }, "type": "object" }, "GeoJsonSchema": { "title": "Geo Json info", "properties": { "type": { "description": "GeoJSon geometry", "type": "string", "enum": [ "Point", "LineString", "Polygon", "MultiPoint", "MultiLineString", "MultiPolygon" ], "example": "LineString" }, "coordinates": { "description": "Coordinates in GeoJSON format: `[latitude, longitude]` (both values are of type `float`)", "type": "array", "items": { "type": "number", "format": "float" }, "maxItems": 2, "minItems": 2, "example": [ 46.7727384, -71.3180309 ] } }, "type": "object" }, "GeofenceEvent": { "title": "Geofence Event", "properties": { "operator_full_Name": { "description": "Name of Operator related to event.", "type": "string", "example": "John Doe" }, "arrival": { "description": "Time when Operator entered Geofence radius.", "type": "string", "example": "08:00:00 AM" }, "departure": { "description": "Time when Operator left Geofence radius.", "type": "string", "example": "10:00:00 AM" } }, "type": "object" }, "CustomerSearchModel": { "title": "Customer Search Model", "description": "Details of a matching customer returned from the search API.", "properties": { "customer_id": { "description": "Unique API identifier for the customer.", "type": "string", "example": "8c7e5825f440f48d284e9fd497acd8b2" }, "full_name": { "description": "Full name of the customer.", "type": "string", "example": "John Doe" }, "reference_id": { "description": "Customer reference ID.", "type": "string", "example": "C-WJG178262" }, "phone_number": { "description": "Phone number of the customer.", "type": "string", "example": "+15062345678" }, "mobile_number": { "description": "Mobile number of the customer.", "type": "string", "example": "+15062345678" }, "email": { "description": "Email address of the customer.", "type": "string", "example": "john.doe@example.com" } }, "type": "object" }, "VehicleBreakTiming": { "description": "When the break should happen.\n\n- `custom_time`: Requires both `window_start` and `window_end`. Defines a custom break period during the route\n - Aligns with 15-minute intervals (allowed minutes: 00, 15, 30, 45).\n - Example: `window_start = '10:15'`, `window_end = '10:30'`.\n\n- `before_departure`: Defines a break that occurs before departure, such as rest or preparation time before the itinerary begins.\n - Example: 15 (for a 15-minute break before departure).\n\n- `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.\n - Example: 20 (for a 20-minute break after the route ends).", "type": "string", "enum": [ "before_departure", "custom_time", "after_itinerary_end" ] }, "VehicleBreakResource": { "properties": { "break_api_id": { "description": "Unique break API identifier.", "type": "string", "example": "brk_fisdoa6h3472cio7823hxcb7f8" }, "vehicle_api_id": { "description": "Vehicle API identifier linked to this break.", "type": "string", "example": "veh_5e6bdf4bg923hx7f8io2" }, "window_start": { "description": "Earliest time of day when the break can start. This field is required only when `break_timing` is set to **custom_time**. Must be before `window_end`, follow a 12-hour AM/PM format and must be aligned with 15-minute intervals (allowed minutes: 00, 15, 30, 45).", "type": "string", "example": "01:30 PM" }, "window_end": { "description": "Latest time of day by which the break must end. This field is required only when `break_timing` is set to **custom_time**. Must be after `window_start`, follow a 12-hour AM/PM format and must be aligned with 15-minute intervals (allowed minutes: 00, 15, 30, 45).", "type": "string", "example": "03:15 PM" }, "break_timing": { "$ref": "#/components/schemas/VehicleBreakTiming" }, "duration": { "description": "Break duration in minutes.", "type": "integer", "example": 30 }, "created_at": { "description": "Datetime in 'YYYY-MM-DD HH:mm:ss' format representing when the break was created.", "type": "string", "format": "date-time", "example": "2025-11-07 12:00:00" } }, "type": "object" }, "ScheduleVehicleBreakResource": { "properties": { "break_api_id": { "description": "Unique break API identifier.", "type": "string", "example": "brk_fisdoa6h3472cio7823hxcb7f8" }, "vehicle_api_id": { "description": "Vehicle API identifier.", "type": "string", "example": "veh_5e6bdf4bg923hx7f8io2" }, "schedule_id": { "description": "Itinerary/route API identifier.", "type": "string", "example": "itn_8h3472cio78_f6b8f2c" }, "window_start": { "description": "Time in 'HH:mm AM/PM' aligned with 15-minute intervals (allowed minutes: 00, 15, 30, 45).", "type": "string", "example": "08:15 AM" }, "window_end": { "description": "Time in 'HH:mm AM/PM' aligned with 15-minute intervals (allowed minutes: 00, 15, 30, 45).", "type": "string", "example": "10:30 AM" }, "start_time": { "nullable": true, "description": "Optional concrete start time, if assigned. I must be aligned with 15-minute intervals (allowed minutes: 00, 15, 30, 45).", "type": "string", "example": "08:15 AM" }, "end_time": { "nullable": true, "description": "Optional concrete end time, if assigned. I must be aligned with 15-minute intervals (allowed minutes: 00, 15, 30, 45).", "type": "string", "example": "10:00 AM" }, "break_timing": { "$ref": "#/components/schemas/VehicleBreakTiming" }, "duration": { "description": "Duration of the break in minutes. Once started, the break lasts this long.", "type": "integer", "example": 30 }, "active": { "description": "0 or 1.", "type": "integer", "example": 1 }, "position": { "nullable": true, "description": "Optional display order between the itinerary stops when `break_timing` is **custom_time**.", "type": "integer", "example": 4 }, "created_at": { "description": "Datetime in 'YYYY-MM-DD HH:mm:ss'.", "type": "string", "format": "date-time", "example": "2025-11-07 12:00:00" } }, "type": "object" }, "VehicleBreaksAPIModel": { "required": [ "duration", "break_timing" ], "properties": { "window_start": { "description": "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).", "type": "string", "example": "12:15 PM" }, "window_end": { "description": "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).", "type": "string", "example": "2:00 PM" }, "duration": { "description": "Duration of the break in minutes. Once started, the break lasts this long.", "type": "integer", "example": 30 }, "break_timing": { "$ref": "#/components/schemas/VehicleBreakTiming" } }, "type": "object", "example": { "window_start": "12:00 PM", "window_end": "2:00 PM", "duration": 30, "break_timing": "custom_time" } }, "PostJobRequestBody": { "title": "Job model", "description": "Job model", "required": [ "first_name", "phone_number", "date", "address" ], "properties": { "type": { "description": "Type of Job. If not set, the Job type will be `delivery`.", "type": "string", "default": "delivery", "enum": [ "delivery", "return", "pickup", "installation", "service", "exchange", "custom" ], "example": "delivery" }, "quick_desc": { "description": "A short description regarding the Job that is visible throughout the platform for Dispatchers and Operators alike.", "type": "string", "maxLength": 10, "example": "SAMPLE" }, "date": { "description": "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).\n\n - Format: Year-Month-Day (YYYY-MM-DD)\n - Optional: Timezone offset:\n - If a timezone is included, it requires time to specify exact date\n - 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)\n **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.", "type": "string", "format": "date", "example": "2024-08-01" }, "original_date": { "description": "ISO-8601 date format indicating the Original Job Date.\n\n - Format: Year-Month-Day (YYYY-MM-DD)\n - Optional: Timezone offset:\n - If a timezone is included, it requires time to specify exact date\n - 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)", "type": "string", "format": "date", "example": "2019-03-29" }, "confirmation_status": { "description": "Specify the confirmation status of a Job.\n\n **Note**: If Confirmation module is enabled- Then the following values are available: `awaiting_confirmation`, `confirmed_by_customer`, `reschedule_requested`.", "type": "string", "enum": [ "confirmed", "pending", "awaiting_confirmation", "confirmed_by_customer", "reschedule_requested" ], "example": "confirmed" }, "first_name": { "description": "First name of the Customer associated with the Job.\n\n **Note**: Use this field if it is a business name (without a last name).", "type": "string", "maxLength": 255, "example": "John" }, "last_name": { "description": "Last name of the Customer associated with the Job.", "type": "string", "maxLength": 255, "example": "Doe" }, "phone_number": { "description": "Phone number associated with the Job.\n\nWe accept formatted phone numbers as well as non-formatted, i.e.:\n\n- +15062345678\n- +1-506-234-5678\n- +1 (506) 234-5678\n\n **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 '+'.", "type": "string", "example": "+15062345678" }, "mobile_number": { "description": "Mobile number associated with the Job (the tracking information will be sent to this number via SMS).\n *\n* We accept formatted phone numbers as well as non-formatted, i.e.:\n *\n* - +15062345678\n* - +1-506-234-5678\n* - +1 (506) 234-5678\n **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 '+'.", "type": "string", "example": "+15062345678" }, "email": { "description": "Email address of the customer (the tracking information will be sent to this email).", "type": "string", "format": "email", "maxLength": 255, "example": "john.doe@example.com" }, "address": { "description": "Address associated with the Job. Within this field, include the following (**delimited by commas**):\n* - Civic number\n* - Street name\n* - Street Type (Blvd, Street, Ave, etc.)\n* - City\n* - Province or State\n* - Postal Code or ZIP Code", "type": "string", "maxLength": 250, "example": "275 Notre-Dame St. East, Montreal, QC, H2Y 1C6" }, "coordinates": { "description": "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.", "type": "array", "items": { "type": "number", "format": "float" }, "maxItems": 2, "minItems": 2, "example": [ 46.7727384, -71.3180309 ] }, "apartment": { "description": "Apartment associated with the address. It should be separated from the address itself to prevent geocoding errors when determining the location's geographical coordinates.", "type": "string", "maxLength": 100, "example": "Suite 101" }, "postal_code": { "description": "Postal Code or ZIP code associated with the address.", "type": "string", "maxLength": 7, "minLength": 5, "example": "H2Y 1C6" }, "time_preference": { "description": "Defines the Customer's time preference for the Job's arrival at their door.\n\n **Note**: There are two _Time Preference modes_ available in the [Company Settings](/provider/company-settings) within the platform:\n *\n* - _Basic:_ Used for simple time preferences; `AM` and `PM`.\n* - _Advanced:_ Used for more granular time preferences; `morning`, `midday`, `afternoon`, `evening`, `night`.\n *\n* 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`.\n *\n* 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`.\n* ", "type": "string", "enum": [ "AM", "PM", "morning", "midday", "afternoon", "evening", "night", null ], "example": "AM" }, "balance_owed": { "description": "Balance owed associated with the Job (positive number with up to 2 decimal points).", "type": "number", "format": "float", "minimum": 0, "example": 265.89 }, "comment": { "description": "Any comment or note associated with the Job. Line breaks are supported using (`\\n`) (newline) or (`
`) (HTML line break) characters.", "type": "string", "maxLength": 2500, "example": "A sample comment regarding the job for John Doe.
Please leave at the front door. \\n\\n Tips will be considered." }, "signature_agreement": { "description": "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`. ", "type": "string", "maxLength": 2500, "example": "Sample signature agreement shared with customer." }, "branch_id": { "description": "Branch or Store ID associated with this Job. Ensure this ID is associated to an existing Branch in our platform.", "type": "string", "maxLength": 30, "example": "S10" }, "distribution_center_id": { "description": "Distribution Center or Warehouse ID associated with this Job. Ensure this ID is associated to an existing Distribution Center in our platform.", "type": "string", "maxLength": 30, "example": "DC12" }, "time_frame": { "description": "Set the approximate Time Frame within which the Job should be started and operators should be on Customer site.\n\n **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.", "properties": { "start": { "description": "Start time value has to be before End time value.", "type": "string", "maxLength": 8, "minLength": 7, "example": "9:00 AM" }, "end": { "description": "End time value has to be after Start time value.", "type": "string", "maxLength": 8, "minLength": 7, "example": "11:00 AM" } }, "type": "object" }, "invoices": { "description": "List of Invoice numbers associated with this Job", "type": "array", "items": { "type": "string", "maxLength": 60, "example": "17823657812563" }, "uniqueItems": true }, "barcodes": { "description": "List of barcodes associated with this Job", "type": "array", "items": { "type": "string", "maxLength": 60, "example": "17823657812563" } }, "label_count": { "description": "The number of labels associated with this Job.\n\n**Note**: This variable is used exclusively with our label printing integration. Do not set this if it is not enabled.", "type": "integer", "minimum": 1, "example": 3 }, "reference_id": { "description": "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.", "type": "string", "maxLength": 25, "example": "J-WJG318322" }, "customer_reference_id": { "description": "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).", "type": "string", "maxLength": 25, "example": "C-WJG178262" }, "skip_staging": { "description": "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.", "type": "boolean", "example": false }, "actions": { "description": "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](#tag/action/paths/~1jobs~1id~1{jobID}~1actions/post). For actions that are the same, we recommend grouping them together under one action and setting its quantity accordingly.", "type": "array", "items": { "$ref": "#/components/schemas/PostJobActionRequestBody" } }, "ignore_geo_zone_warnings": { "description": "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", "type": "boolean", "example": "false" }, "bypass_zone_capacity_rules": { "description": "If `true`, Zone Capacity limit validation will not run.", "type": "boolean", "example": "false" } }, "type": "object" }, "PatchJobRequestBody": { "title": "Job model", "description": "Job model", "properties": { "type": { "description": "Type of Job. If not set, the Job type will be `delivery`.", "type": "string", "default": "delivery", "enum": [ "delivery", "return", "pickup", "installation", "service", "exchange", "custom" ], "example": "delivery" }, "quick_desc": { "description": "A short description regarding the Job that is visible throughout the platform for Dispatchers and Operators alike.", "type": "string", "maxLength": 10, "example": "SAMPLE" }, "date": { "description": "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).\n\n- Format: Year-Month-Day (YYYY-MM-DD)\n- Optional: Timezone offset:\n- If a timezone is included, it requires time to specify exact date\n- 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)\n **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.", "type": "string", "format": "date", "example": "2024-08-01" }, "confirmation_status": { "description": "Specify the confirmation status of a Job.\n\n **Note**: If Confirmation module is enabled- Then the following values are available: `awaiting_confirmation`, `confirmed_by_customer`, `reschedule_requested`.", "type": "string", "enum": [ "confirmed", "pending", "awaiting_confirmation", "confirmed_by_customer", "reschedule_requested" ], "example": "confirmed" }, "first_name": { "description": "First name of the Customer associated with the Job.\n\n **Note**: Use this field if it is a business name (without a last name).", "type": "string", "maxLength": 255, "example": "John" }, "last_name": { "description": "Last name of the Customer associated with the Job.", "type": "string", "maxLength": 255, "example": "Doe" }, "phone_number": { "description": "Phone number associated with the Job.\n\nWe accept formatted phone numbers as well as non-formatted, i.e.:\n\n- +15062345678\n- +1-506-234-5678\n- +1 (506) 234-5678\n\n **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 '+'.", "type": "string", "example": "+15062345678" }, "mobile_number": { "description": "Mobile number associated with the Job (the tracking information will be sent to this number via SMS).\n *\n * We accept formatted phone numbers as well as non-formatted, i.e.:\n *\n * - +15062345678\n * - +1-506-234-5678\n * - +1 (506) 234-5678\n **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 '+'.", "type": "string", "example": "+15062345678" }, "email": { "description": "Email address of the customer (the tracking information will be sent to this email).", "type": "string", "format": "email", "maxLength": 255, "example": "john.doe@example.com" }, "address": { "description": "Address associated with the Job. Within this field, include the following (**delimited by commas**):\n * - Civic number\n * - Street name\n * - Street Type (Blvd, Street, Ave, etc.)\n * - City\n * - Province or State\n * - Postal Code or ZIP Code", "type": "string", "maxLength": 250, "example": "275 Notre-Dame St. East, Montreal, QC, H2Y 1C6" }, "apartment": { "description": "Apartment associated with the address. It should be separated from the address itself to prevent geocoding errors when determining the location's geographical coordinates.", "type": "string", "maxLength": 100, "example": "Suite 101" }, "postal_code": { "description": "Postal Code or ZIP code associated with the address.", "type": "string", "maxLength": 7, "minLength": 5, "example": "H2Y 1C6" }, "time_preference": { "description": "Defines the Customer's time preference for the Job's arrival at their door.\n\n **Note**: There are two _Time Preference modes_ available in the [Company Settings](/provider/company-settings) within the platform:\n *\n * - _Basic:_ Used for simple time preferences; `AM` and `PM`.\n * - _Advanced:_ Used for more granular time preferences; `morning`, `midday`, `afternoon`, `evening`, `night`.\n *\n * 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`.\n *\n * 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`.\n * ", "type": "string", "enum": [ "AM", "PM", "morning", "midday", "afternoon", "evening", "night", null ], "example": "AM" }, "balance_owed": { "description": "Balance owed associated with the Job (positive number with up to 2 decimal points).", "type": "number", "format": "float", "minimum": 0, "example": 265.89 }, "comment": { "description": "Any comment or note associated with the Job. Line breaks are supported using (`\\n`) (newline) or (`
`) (HTML line break) characters.", "type": "string", "maxLength": 2500, "example": "A sample comment regarding the job for John Doe.
Please leave at the front door. \\n\\n Tips will be considered." }, "signature_agreement": { "description": "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`. ", "type": "string", "maxLength": 2500, "example": "Sample signature agreement shared with customer." }, "branch_id": { "description": "Branch or Store ID associated with this Job. Ensure this ID is associated to an existing Branch in our platform.", "type": "string", "maxLength": 30, "example": "S10" }, "distribution_center_id": { "description": "Distribution Center or Warehouse ID associated with this Job. Ensure this ID is associated to an existing Distribution Center in our platform.", "type": "string", "maxLength": 30, "example": "DC12" }, "time_frame": { "description": "Set the approximate Time Frame within which the Job should be started and operators should be on Customer site.\n\n **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.", "properties": { "start": { "description": "Start time value has to be before End time value.", "type": "string", "maxLength": 8, "minLength": 7, "example": "9:00 AM" }, "end": { "description": "End time value has to be after Start time value.", "type": "string", "maxLength": 8, "minLength": 7, "example": "11:00 AM" } }, "type": "object" }, "invoices": { "description": "List of Invoice numbers associated with this Job", "type": "array", "items": { "type": "string", "maxLength": 60, "example": "17823657812563" }, "uniqueItems": true }, "label_count": { "description": "The number of labels associated with this Job.\n\n **Note**: This variable is used exclusively with our label printing integration. Do not set this if it is not enabled.", "type": "integer", "minimum": 1, "example": 3 }, "reference_id": { "description": "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.", "type": "string", "maxLength": 25, "example": "J-WJG318322" }, "ignore_geo_zone_warnings": { "description": "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", "type": "boolean", "example": "false" }, "bypass_zone_capacity_rules": { "description": "If `true`, Zone Capacity limit validation will not run.", "type": "boolean", "example": "false" } }, "type": "object" }, "PostJobActionRequestBody": { "title": "Job Action model", "description": "Job Action model", "required": [ "id", "type", "description", "address" ], "properties": { "id": { "description": "ID associated with the Action (i.e. SKU, Serial Number, etc.).", "type": "string", "maxLength": 30, "example": "73165560" }, "type": { "description": "Type of Action.", "type": "string", "enum": [ "delivery", "return", "pickup", "installation", "service", "exchange" ], "example": "delivery" }, "description": { "description": "Description of the Action.", "type": "string", "maxLength": 100, "example": "Astin Sofa - Grey" }, "value": { "description": "Value of the Action as a positive number with up to 2 decimal points.\n\n**Note**: This is representative of the total value associated with the action (it is **NOT** multiplied by the `quantity`).", "type": "number", "format": "float", "minimum": 0, "example": 1149.96 }, "unit_weight": { "description": "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.\n **Note**: The `total_weight` is automatically calculated by multiplying the `unit_weight` set by the `quantity`.\n* You can retrieve the `total_weight` value via the GET endpoints:\n* - [GET Retrieve all Actions for a Job](#tag/action/paths/~1jobs~1id~1{jobID}~1actions/get)\n* - [GET Retrieve an Action for a Job](#tag/action/paths/~1jobs~1id~1{jobID}~1actions~1{actionID}/get)", "type": "number", "format": "float", "minimum": 0, "example": 120.5 }, "unit_volume": { "description": "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.\n **Note**: The `total_volume` is automatically calculated by multiplying the `unit_volume` set by the `quantity`.\n* You can retrieve the `total_volume` value via the GET endpoints:\n* - [GET Retrieve all Actions for a Job](#tag/action/paths/~1jobs~1id~1{jobID}~1actions/get)\n* - [GET Retrieve an Action for a Job](#tag/action/paths/~1jobs~1id~1{jobID}~1actions~1{actionID}/get)", "type": "number", "format": "float", "minimum": 0, "example": 2.75 }, "piece_count": { "description": "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).", "type": "integer", "minimum": 0, "example": 1 }, "piece_count_unit": { "description": "The (optional) unit of the piece count.\n **Note**: In order to be able to use custom units, the relevant toggle in the _Job Creation Options_ section of the [Company Settings](/provider/company-settings) must be enabled.", "type": "string", "maxLength": 15, "example": "boxes" }, "quantity": { "description": "Quantity of the Action as a positive integer.", "type": "integer", "minimum": 1, "example": 2 }, "quantity_unit": { "description": "The (optional) unit of the quantity.\n **Note**: In order to be able to use custom units, the relevant toggle in the _Job Creation Options_ section of the [Company Settings](/provider/company-settings) must be enabled.", "type": "string", "maxLength": 15, "example": "bundles" }, "handle_time": { "description": "Estimated time to complete the Action (in minutes) as a positive integer.\n **Note**: This is representative of the total handle time associated with the Action (it is **NOT** multiplied by the `quantity`).", "type": "integer", "minimum": 0, "example": 10 }, "stop_location_id": { "description": "Stop Location ID (this value will only be saved if the Action type is `pickup`, `return` or `exchange`)", "type": "string", "maxLength": 30, "example": "B12" }, "stop_location": { "$ref": "#/components/schemas/StopLocationRequestBody" }, "invoice_number": { "description": "Invoice Number associated specifically with this Action", "type": "string", "maxLength": 60, "example": "9871236WE127836" }, "shipping_barcode": { "description": "Shipping label barcode", "type": "string", "maxLength": 128, "example": "1234567890" }, "external_reference_id": { "description": "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.", "type": "string", "maxLength": 255, "example": "CJA20121105TBA69420" }, "bypass_zone_capacity_rules": { "description": "Flag to bypass Zone Capacity limit validation. This flag will only work if the Users have permission to bypass Capacity Management validations.", "type": "boolean", "example": "false" }, "require_barcode": { "description": "Flag used to enforce the barcode scan when completing the Action.", "type": "boolean", "example": "false" } }, "type": "object" }, "PatchJobActionRequestBody": { "title": "Job Action model", "description": "Job Action model", "properties": { "id": { "description": "ID associated with the Action (i.e. SKU, Serial Number, etc.).", "type": "string", "maxLength": 30, "example": "73165560" }, "type": { "description": "Type of Action.", "type": "string", "enum": [ "delivery", "return", "pickup", "installation", "service", "exchange" ], "example": "delivery" }, "description": { "description": "Description of the Action.", "type": "string", "maxLength": 100, "example": "Astin Sofa - Grey" }, "value": { "description": "Value of the Action as a positive number with up to 2 decimal points.\n\n **Note**: This is representative of the total value associated with the action (it is **NOT** multiplied by the `quantity`).", "type": "number", "format": "float", "minimum": 0, "example": 1149.96 }, "unit_weight": { "description": "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.\n **Note**: The `total_weight` is automatically calculated by multiplying the `unit_weight` set by the `quantity`.\n* You can retrieve the `total_weight` value via the GET endpoints:\n* - [GET Retrieve all Actions for a Job](#tag/action/paths/~1jobs~1id~1{jobID}~1actions/get)\n* - [GET Retrieve an Action for a Job](#tag/action/paths/~1jobs~1id~1{jobID}~1actions~1{actionID}/get)", "type": "number", "format": "float", "minimum": 0, "example": 120.5 }, "unit_volume": { "description": "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.\n **Note**: The `total_volume` is automatically calculated by multiplying the `unit_volume` set by the `quantity`.\n* You can retrieve the `total_volume` value via the GET endpoints:\n* - [GET Retrieve all Actions for a Job](#tag/action/paths/~1jobs~1id~1{jobID}~1actions/get)\n* - [GET Retrieve an Action for a Job](#tag/action/paths/~1jobs~1id~1{jobID}~1actions~1{actionID}/get)", "type": "number", "format": "float", "minimum": 0, "example": 2.75 }, "piece_count": { "description": "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).", "type": "integer", "minimum": 0, "example": 1 }, "piece_count_unit": { "description": "The (optional) unit of the piece count.\n **Note**: In order to be able to use custom units, the relevant toggle in the _Job Creation Options_ section of the [Company Settings](/provider/company-settings) must be enabled.", "type": "string", "maxLength": 15, "example": "boxes" }, "quantity": { "description": "Quantity of the Action as a positive integer.", "type": "integer", "minimum": 1, "example": 2 }, "quantity_unit": { "description": "The (optional) unit of the quantity.\n **Note**: In order to be able to use custom units, the relevant toggle in the _Job Creation Options_ section of the [Company Settings](/provider/company-settings) must be enabled.", "type": "string", "maxLength": 15, "example": "bundles" }, "handle_time": { "description": "Estimated time to complete the Action (in minutes) as a positive integer.\n **Note**: This is representative of the total handle time associated with the Action (it is **NOT** multiplied by the `quantity`).", "type": "integer", "minimum": 0, "example": 10 }, "stop_location_id": { "description": "Stop Location ID (this value will only be saved if the Action type is `pickup`, `return` or `exchange`)", "type": "string", "maxLength": 30, "example": "B12" }, "stop_location": { "$ref": "#/components/schemas/StopLocationRequestBody" }, "invoice_number": { "description": "Invoice Number associated specifically with this Action", "type": "string", "maxLength": 60, "example": "9871236WE127836" }, "shipping_barcode": { "description": "Shipping label barcode", "type": "string", "maxLength": 128, "example": "1234567890" }, "external_reference_id": { "description": "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.", "type": "string", "maxLength": 255, "example": "CJA20121105TBA69420" }, "bypass_zone_capacity_rules": { "description": "Flag to bypass Zone Capacity limit validation. This flag will only work if the Users have permission to bypass Capacity Management validations.", "type": "boolean", "example": "false" }, "require_barcode": { "description": "Flag used to enforce the barcode scan when completing the Action.", "type": "boolean", "example": "false" } }, "type": "object" }, "PostSearchJobsRequestBody": { "title": "Search Jobs request", "description": "Search Jobs request", "required": [ "start_date" ], "properties": { "start_date": { "description": "Start date in ISO-8601 date format.\n\n - Format: Year-Month-Day (YYYY-MM-DD)\n - Optional: Timezone offset:\n - If a timezone is included, it requires time to specify exact date\n - 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)\n\n **Note**: If you want to find Jobs where the date has not yet been determined, set this value to `tbd`.", "type": "string", "format": "date", "example": "2020-01-01" }, "end_date": { "description": "End Date in ISO-8601 date format.\n\n - Format: Year-Month-Day (YYYY-MM-DD)\n - Optional: Timezone offset:\n - If a timezone is included, it requires time to specify exact date\n - 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)\n\n **Note**:\n- This date should be greater or equal to the `start_date`.\n- If you've set `start_date` to `tbd`, this value will be ignored.", "type": "string", "format": "date", "example": "2020-01-31" }, "status": { "description": "Filter by status of Jobs", "type": "string", "enum": [ "staging", "new", "in progress", "damaged", "completed", "resolved", "incomplete", "partially completed", "cancelled" ], "example": "completed" }, "first_name": { "description": "Filter by first name that may have been set on one or many Jobs", "type": "string", "maxLength": 255, "example": "John" }, "last_name": { "description": "Filter by last name that may have been set on one or many Jobs", "type": "string", "maxLength": 255, "example": "Doe" }, "phone_number": { "description": "Filter by phone number that may have been set on one or many Jobs", "type": "string", "maxLength": 255, "example": "5147894560" }, "quick_desc": { "description": "Filter by quick description that may have been set on one or many Jobs", "type": "string", "maxLength": 10, "example": "SAMPLE" }, "invoice_number": { "description": "Filter by invoice number that may have been set on one or many Jobs", "type": "string", "maxLength": 255, "example": "818362" }, "shipping_barcode": { "description": "Filter by barcode that may have been set on one or many Jobs actions and returns Job ID", "type": "string", "maxLength": 128, "example": "8182258639" }, "reference_id": { "description": "Filter by job system reference ID that may have been set on one or many Jobs", "type": "string", "maxLength": 255, "example": "J-WJG318322" }, "confirmation_status": { "description": "Filter by confirmation status of Jobs", "type": "string", "enum": [ "confirmed", "pending", "awaiting_confirmation", "confirmed_by_customer", "reschedule_requested" ], "example": "confirmed" }, "branch_id": { "description": "Branch or Store ID associated with one or many Jobs. Ensure this ID is associated to an existing Branch in our platform.", "type": "string", "maxLength": 30, "example": "S10" }, "distribution_center_id": { "description": "Distribution Center or Warehouse ID associated with one or many Jobs. Ensure this ID is associated to an existing Distribution Center in our platform.", "type": "string", "maxLength": 30, "example": "DC12" }, "job_type": { "description": "Filter by type of Jobs", "type": "string", "enum": [ "Delivery", "Return", "Pick", "Installation", "Service", "Custom", "Exchange" ], "example": "Delivery" }, "creation_source": { "description": "Filter by creation source of Jobs", "type": "string", "enum": [ "CSV", "DIRECT", "API", "STAGING", "CLONE", "RESCHEDULE" ], "example": "DIRECT" }, "on_itinerary": { "description": "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.", "type": "boolean", "example": false } }, "type": "object" }, "PostItineraryPreviewRequestBody": { "title": "Itinerary model", "description": "Itinerary model", "required": [ "date", "start_time", "vehicle_id", "start_point", "end_point" ], "properties": { "date": { "description": "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).\n\n - Format: Year-Month-Day (YYYY-MM-DD)\n - Optional: Timezone offset:\n - If a timezone is included, it requires time to specify exact date\n - 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)", "type": "string", "format": "date", "example": "2024-08-01" }, "start_time": { "description": "Start Time.", "type": "string", "format": "time", "enum": [ "12:00 AM", "12:30 AM", "8:00 AM", "11:45 PM" ], "example": "08:30 AM" }, "time_frame_size": { "description": "Set the approximate Time Frame on each Job (hour).\n **Note**: In order to be able to use this property, the relevant toggle in the General Options section of the [Company Settings](/provider/company-settings) must be enabled.", "type": "number", "enum": [ 0, 1, 1.5, 2, 2.5, 3, 3.5, 4, 4.5, 5, 5.5, 6 ], "example": 1.5 }, "vehicle_id": { "description": "Vehicle ID.", "type": "string", "example": "b53387df22645251aa9b22d24b7ec4a6" }, "vehicle_breaks": { "description": "List of Schedule Vehicle Breaks configuration for this itinerary.", "type": "array", "items": { "$ref": "#/components/schemas/VehicleBreaksAPIModel" }, "maximum": 3 }, "start_point": { "description": "Start Location.", "oneOf": [ { "$ref": "#/components/schemas/ItineraryPayloadLocationId" }, { "$ref": "#/components/schemas/ItineraryPayloadLocationCoordinates" }, { "$ref": "#/components/schemas/ItineraryPayloadLocationAddress" } ] }, "bypass_zone_capacity_rules": { "description": "If 'true', Zone Capacity limit validation will not run. This flag will only work if the Users have permission to bypass Capacity Management validations.", "type": "boolean", "example": "false" }, "end_point": { "description": "End Location.", "oneOf": [ { "$ref": "#/components/schemas/ItineraryPayloadLocationId" }, { "$ref": "#/components/schemas/ItineraryPayloadLocationCoordinates" }, { "$ref": "#/components/schemas/ItineraryPayloadLocationAddress" } ] }, "routing_info": { "$ref": "#/components/schemas/ItineraryRoutingInfoModel" }, "job_ids": { "description": "List of Job IDs to be reviewed (maximum 150 Jobs including potential on route stops).\n **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.", "type": "array", "items": { "type": "string", "example": "f4e922d54b98a878488d2754fd4cfc0e" }, "maximum": 150 }, "stops": { "description": "List of Stops (Non-Cigo Jobs).\n **Note**: If the request contains the `job_ids` array that is not empty, the `stops` array of objects will be ignored.", "type": "array", "items": { "$ref": "#/components/schemas/PostPreviewItineraryStopRequestBody" }, "maximum": 150 } }, "type": "object" }, "PostItineraryCreateRequestBody": { "title": "Itinerary model", "description": "Itinerary model", "required": [ "date", "start_time", "vehicle_id", "start_point", "end_point", "add_ids" ], "properties": { "date": { "description": "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).\n\n - Format: Year-Month-Day (YYYY-MM-DD)\n - Optional: Timezone offset:\n - If a timezone is included, it requires time to specify exact date\n - 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)", "type": "string", "format": "date", "example": "2024-08-01" }, "start_time": { "description": "Start Time.", "type": "string", "format": "time", "enum": [ "12:00 AM", "12:30 AM", "8:00 AM", "11:45 PM" ], "example": "08:30 AM" }, "bypass_zone_capacity_rules": { "description": "If 'true', Zone Capacity limit validation will not run. This flag will only work if the Users have permission to bypass Capacity Management validations.", "type": "boolean", "example": "false" }, "time_frame_size": { "description": "Set the approximate Time Frame on each Job (hour).\n **Note**: In order to be able to use this property, the relevant toggle in the General Options section of the [Company Settings](/provider/company-settings) must be enabled.", "type": "number", "enum": [ 0, 1, 1.5, 2, 2.5, 3, 3.5, 4, 4.5, 5, 5.5, 6 ], "example": 1.5 }, "vehicle_id": { "description": "Vehicle ID.", "type": "string", "example": "b53387df22645251aa9b22d24b7ec4a6" }, "vehicle_breaks": { "description": "List of Schedule Vehicle Breaks configuration for this itinerary.", "type": "array", "items": { "$ref": "#/components/schemas/VehicleBreaksAPIModel" }, "maximum": 3 }, "start_point": { "description": "Start Location.", "oneOf": [ { "$ref": "#/components/schemas/ItineraryPayloadLocationId" }, { "$ref": "#/components/schemas/ItineraryPayloadLocationCoordinates" }, { "$ref": "#/components/schemas/ItineraryPayloadLocationAddress" } ] }, "end_point": { "description": "End Location.", "oneOf": [ { "$ref": "#/components/schemas/ItineraryPayloadLocationId" }, { "$ref": "#/components/schemas/ItineraryPayloadLocationCoordinates" }, { "$ref": "#/components/schemas/ItineraryPayloadLocationAddress" } ] }, "routing_info": { "$ref": "#/components/schemas/ItineraryRoutingInfoModel" }, "operators": { "description": "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.", "type": "array", "items": { "$ref": "#/components/schemas/PostItineraryBuildOperatorRequestBody" }, "maximum": 4 }, "options": { "$ref": "#/components/schemas/ItineraryOptionsRequestModel" }, "add_ids": { "description": "List of Job IDs to be assigned to the Itinerary (maximum 150 Jobs including potential on route stops).\n **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.", "type": "array", "items": { "type": "string", "example": "f4e922d54b98a878488d2754fd4cfc0e" }, "maximum": 150 }, "include_stops_sequence": { "description": "If set to `true`, the response will include the ordered list of stops of this itinerary as an array of Job IDs.", "type": "boolean", "default": false, "example": false } }, "type": "object" }, "PostLocationCreateRequestBody": { "title": "Create a new Location.", "description": "Create a new Location", "required": [ "type", "name", "geolocation" ], "properties": { "type": { "description": "The type of the location.", "type": "string", "enum": [ "branch", "warehouse" ], "example": "branch" }, "name": { "description": "Location name.", "type": "string", "maximum": 256, "example": "Main branch" }, "ref_no": { "description": "The reference number of the location. This is usually an identifier from an external system.", "type": "string", "maximum": 60, "example": "1abd2l5k8" }, "geolocation": { "description": "The geolocation of this Location.", "oneOf": [ { "$ref": "#/components/schemas/ItineraryPayloadLocationCoordinates" }, { "$ref": "#/components/schemas/ItineraryPayloadLocationAddress" } ] } }, "type": "object" }, "PatchLocationUpdateRequestBody": { "title": "Update Location.", "description": "Update Location", "properties": { "active": { "description": "Choose false to deactivate the location and true for activation.", "type": "boolean", "enum": [ true, false ], "example": true }, "type": { "description": "The type of the location.", "type": "string", "enum": [ "branch", "warehouse" ], "example": "warehouse" }, "name": { "description": "Location name.", "type": "string", "maximum": 256, "example": "New warehouse" }, "ref_no": { "description": "The reference number of the location. This is usually an identifier from an external system.", "type": "string", "maximum": 60, "example": "1abd2l5k8" }, "geolocation": { "description": "The geolocation of this Location.", "oneOf": [ { "$ref": "#/components/schemas/ItineraryPayloadLocationCoordinates" }, { "$ref": "#/components/schemas/ItineraryPayloadLocationAddress" } ] } }, "type": "object" }, "PostItineraryUpdateRequestBody": { "title": "Itinerary model", "description": "Itinerary model", "properties": { "start_time": { "description": "Start Time.", "type": "string", "format": "time", "enum": [ "12:00 AM", "12:30 AM", "8:00 AM", "11:45 PM" ], "example": "08:30 AM" }, "time_frame_size": { "description": "Set the approximate Time Frame on each Job (hour).\n\n **Note**: In order to be able to use this property, the relevant toggle in the General Options section of the [Company Settings](/provider/company-settings) must be enabled.", "type": "number", "enum": [ 0, 1, 1.5, 2, 2.5, 3, 3.5, 4, 4.5, 5, 5.5, 6 ], "example": 1.5 }, "vehicle_id": { "description": "Vehicle ID.", "type": "string", "example": "b53387df22645251aa9b22d24b7ec4a6" }, "bypass_zone_capacity_rules": { "description": "If 'true', Zone Capacity limit validation will not run. This flag will only work if the Users have permission to bypass Capacity Management validations.", "type": "boolean", "example": "false" }, "vehicle_breaks": { "description": "List of Schedule Vehicle Breaks configuration for this itinerary.", "type": "array", "items": { "$ref": "#/components/schemas/VehicleBreaksAPIModel" }, "maximum": 3 }, "start_point": { "description": "Start Location.", "oneOf": [ { "$ref": "#/components/schemas/ItineraryPayloadLocationId" }, { "$ref": "#/components/schemas/ItineraryPayloadLocationCoordinates" }, { "$ref": "#/components/schemas/ItineraryPayloadLocationAddress" } ] }, "end_point": { "description": "End Location.", "oneOf": [ { "$ref": "#/components/schemas/ItineraryPayloadLocationId" }, { "$ref": "#/components/schemas/ItineraryPayloadLocationCoordinates" }, { "$ref": "#/components/schemas/ItineraryPayloadLocationAddress" } ] }, "routing_info": { "$ref": "#/components/schemas/ItineraryRoutingInfoModel" }, "operators": { "description": "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.", "type": "array", "items": { "$ref": "#/components/schemas/PostItineraryBuildOperatorRequestBody" }, "maximum": 4 }, "options": { "$ref": "#/components/schemas/ItineraryOptionsRequestModel" }, "add_ids": { "description": "List of Job IDs to be assigned to the Itinerary.\n\n**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.", "type": "array", "items": { "type": "string", "example": "f4e922d54b98a878488d2754fd4cfc0e" } }, "delete_ids": { "description": "List of Job IDs (`stop_type` is equal to `job`) to be removed from the Itinerary.\n **Notes**:\n* - 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, include all the associated Job IDs from the `related_jobs` property;\n* - `status` must be equal to `new`.", "type": "array", "items": { "type": "string", "example": "0347f675958fb0c0208d5d928c7b28c3" } }, "include_stops_sequence": { "description": "If set to `true`, the response will include the ordered list of stops of this itinerary as an array of Job IDs.", "type": "boolean", "default": false, "example": false } }, "type": "object" }, "PostItineraryBuildOperatorRequestBody": { "title": "Operator model", "description": "Operator model", "required": [ "id", "seat" ], "properties": { "id": { "description": "Operator ID.", "type": "string", "example": "b53387df22645251aa9b22d24b7ec4a6" }, "seat": { "description": "Seat no.", "type": "integer", "maximum": 4, "minimum": 1, "example": 1 } }, "type": "object" }, "PostPreviewItineraryStopRequestBody": { "title": "Stop model", "description": "Stop", "required": [ "id" ], "properties": { "id": { "description": "Specifies the id of the Stop. Ids need to be unique so there must not be two stops with the same id.", "type": "string", "maximum": 128, "example": "stop0123" }, "coordinates": { "description": "Coordinates in GeoJSON format: `[latitude, longitude]` (both values are of type `float`)\n\n **Note**: This is `required` if there is no address associated with the Stop.", "type": "array", "items": { "type": "number", "format": "float" }, "maxItems": 2, "minItems": 2, "example": [ 45.5449878, -73.6603738 ] }, "address": { "description": "Address associated with the Stop. Within this field, include the following (**delimited by commas**):\n- Civic number\n- Street name\n- Street Type (Blvd, Street, Ave, etc.)\n- City\n- Province or State\n\n\n **Note**: This is `required` if there are no coordinates associated with the Stop.", "type": "string", "example": "9850 rue Saint-Urbain Montréal, QC" }, "name": { "description": "Meaningful name for the Stop", "type": "string", "maximum": 255, "example": "deliver box" }, "locked": { "description": "If `true`, the Stop will remain in its position.", "type": "boolean", "example": false }, "handle_time": { "description": "Estimated time to complete the Stop (in minutes) as a positive integer.", "type": "number", "format": "integer", "maximum": 9999, "minimum": 0, "example": 10 }, "value": { "description": "Value of the Stop as a positive number with up to 2 decimal points.", "type": "number", "format": "float", "maximum": 99999.99, "minimum": 0, "example": 1149.96 }, "weight": { "description": "Weight of the Stop in kg or ft (depending on the account settings) as a positive number with up to 2 decimal points.", "type": "number", "format": "float", "maximum": 99999.99, "minimum": 0, "example": 120.5 }, "volume": { "description": "Volume of the Stop in kg or ft (depending on the account settings) as a positive number with up to 2 decimal points.", "type": "number", "format": "float", "maximum": 99999.99, "minimum": 0, "example": 2.75 }, "piece_count": { "description": "Piece count of the Stop as a positive integer (i.e. quantity of 1 for a table, that comes in 3 boxes has a piece count of 3).", "type": "integer", "maximum": 9999, "minimum": 0, "example": 1 }, "quantity": { "description": "Quantity of the Stop as a positive integer.", "type": "integer", "maximum": 9999, "minimum": 0, "example": 2 }, "time_preference": { "description": "Defines the Customer's time preference for the Stop's arrival at their door.\n\n **Note**: There are two Time Preference modes available in the [Company Settings](/provider/company-settings) within the platform:\n\n- _Basic:_ Used for simple time preferences; `AM` and `PM`.\n- _Advanced:_ Used for more granular time preferences; `morning`, `midday`, `afternoon`, `evening`, `night`.\n", "type": "string", "enum": [ "AM", "PM", "morning", "midday", "afternoon", "evening", "night", "none", null ], "example": "AM" }, "time_frame": { "description": "Set the approximate Time Frame within which the Stop should be started and operators should be on Customer site.\n\n **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.", "properties": { "start": { "description": "Start time value has to be before End time value.", "type": "string", "example": "09:00 AM" }, "end": { "description": "End time value has to be after Start time value.", "type": "string", "example": "11:00 AM" } }, "type": "object" } }, "type": "object" }, "PostItineraryUpdateOperatorsRequestBody": { "title": "Update Operators", "description": "Array of Operators", "required": [ "operators" ], "properties": { "operators": { "description": "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.\n **Note**: This action will remove existing Operators that have been assigned to specified Itinerary.", "type": "array", "items": { "$ref": "#/components/schemas/PostItineraryBuildOperatorRequestBody" } } }, "type": "object" }, "PostItineraryUpdatePositionsRequestBody": { "title": "Update Positions of all Stops", "description": "Array of Jobs", "required": [ "stops" ], "properties": { "stops": { "description": "list of Job IDs in order of new Positions.\n\n**Note**: Position of Started and/or Completed Stops cannot be changed.", "type": "array", "items": { "type": "string", "example": "f4e922d54b98a878488d2754fd4cfc0e" }, "uniqueItems": true } }, "type": "object" }, "ItineraryPayloadLocationId": { "title": "ID", "properties": { "id": { "description": "Location ID.", "type": "string", "example": "b53387df22645251aa9b22d24b7ec4a6" } }, "type": "object" }, "ItineraryPayloadLocationCoordinates": { "title": "Coordinates", "properties": { "coordinates": { "description": "Coordinates in GeoJSON format: `[latitude, longitude]` (both values are of type `float`)", "type": "array", "items": { "type": "number", "format": "float" }, "maxItems": 2, "minItems": 2, "example": [ 46.7727384, -71.3180309 ] } }, "type": "object" }, "ItineraryPayloadLocationAddress": { "title": "Address", "properties": { "address": { "description": "Custom End Location Address. Within this field, include the following (**delimited by commas**):\n- Civic number\n- Street name\n- Street Type (Blvd, Street, Ave, etc.)\n- City\n- Province or State\n- Postal Code or ZIP Code", "type": "string", "maximum": 250, "example": "275 Notre-Dame St. East, Montreal, QC, H2Y 1C6" } }, "type": "object" }, "PostOperatorCreateRequestBody": { "title": "Create a new Operator.", "description": "Create a new Operator", "required": [ "full_name", "email", "password" ], "properties": { "full_name": { "description": "Operator first and last name.", "type": "string", "maximum": 256, "example": "John Doe" }, "email": { "description": "The operator's email address.", "type": "string", "format": "email", "maximum": 128, "example": "john_doe@business.com" }, "password": { "description": "The operator's login password.", "type": "string", "minimum": 10, "example": "9g125ak141l9a" }, "reference_id": { "description": "Employee ID from an external system.", "type": "string", "maximum": 30, "example": "1ABD2l5K8" } }, "type": "object" }, "PatchOperatorUpdateRequestBody": { "title": "Update Operator data fields and access to the platform.", "description": "Update Operator", "properties": { "active": { "description": "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.", "type": "boolean", "enum": [ true, false ], "example": true }, "full_name": { "description": "Operator first and last name.", "type": "string", "maximum": 256, "example": "John Doe" }, "email": { "description": "The operator's email address.", "type": "string", "format": "email", "maximum": 128, "example": "john_doe@business.com" }, "password": { "description": "The operator's login new password.", "type": "string", "example": "9ka68f1mb3a" }, "reference_id": { "description": "Employee ID from an external system.", "type": "string", "maximum": 30, "example": "1ABD2l5K8" } }, "type": "object" }, "StopLocationRequestBody": { "title": "Stop Location.", "description": "Stop Location (this object will only be saved if `stop_location_id` is not set and the Action type is `pickup`, `return` or `exchange`)", "required": [ "name", "geolocation" ], "properties": { "name": { "description": "Stop Location name.", "type": "string", "maximum": 32, "example": "Stop Location A" }, "geolocation": { "description": "The geolocation of this Stop Location.", "oneOf": [ { "$ref": "#/components/schemas/ItineraryPayloadLocationCoordinates" }, { "$ref": "#/components/schemas/ItineraryPayloadLocationAddress" } ] }, "time_frame": { "description": "Set the approximate Time Frame within which the Action should be started and operators should be on Stop Location.\n\n **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.", "properties": { "start": { "description": "Start time value has to be before End time value.", "type": "string", "maxLength": 8, "minLength": 7, "example": "9:00 AM" }, "end": { "description": "End time value has to be after Start time value.", "type": "string", "maxLength": 8, "minLength": 7, "example": "11:00 AM" } }, "type": "object" } }, "type": "object" }, "PostSearchCustomersRequestBody": { "title": "Search Customers request", "description": "Search Customers request", "properties": { "name": { "description": "Customer name (supports partial matches)", "type": "string", "maxLength": 255, "example": "John Doe" }, "phone_number": { "description": "Customer phone number", "type": "string", "maxLength": 20, "example": "+15062345678" }, "mobile_number": { "description": "Customer mobile number", "type": "string", "maxLength": 20, "example": "+15062345679" }, "email": { "description": "Customer email", "type": "string", "format": "email", "maxLength": 255, "example": "john.doe@example.com" }, "invoice": { "description": "Invoice ID associated with a customer's job", "type": "string", "maxLength": 255, "example": "INV123456" }, "customer_reference_id": { "description": "Customer Reference ID", "type": "string", "maxLength": 255, "example": "C-WJG178262" }, "job_reference_id": { "description": "Job Reference API ID related to the customer", "type": "string", "maxLength": 255, "example": "78522cd9b5f4cf0892da8e4744e8f48d" } }, "type": "object" }, "AvailableSlotsRequestBody": { "title": "Available Slots Request Body", "description": "Request body for retrieving available slots based on date and geolocation.", "required": [ "date", "geolocation" ], "properties": { "date": { "description": "The date for which to retrieve available slots. Expected format: YYYY-MM-DD.", "type": "string", "format": "date", "example": "2023-10-15" }, "geolocation": { "description": "The geolocation coordinates in the format 'latitude,longitude'.", "type": "string", "example": "37.7749,-122.4194" } }, "type": "object" }, "AvailableBookingDatesRequestBody": { "title": "Available Booking Dates Request Body", "description": "Request body for retrieving available booking dates based on geolocation, address, month, days ahead, weight, volume, and days offset.", "required": [ "geolocation", "address", "month", "days_ahead", "job_weight", "job_volume" ], "properties": { "geolocation": { "description": "The geolocation coordinates in the format 'latitude,longitude'. If no address is given, this is required.", "type": "string", "example": "37.7749,-122.4194" }, "address": { "description": "The address for which to retrieve available booking dates. If no geolocation is given, this is required.", "type": "string", "example": "123 Main St, San Francisco, CA" }, "month": { "description": "The month for which to retrieve available booking dates. Expected format: YYYY-MM.", "type": "string", "example": "2023-10" }, "days_ahead": { "description": "The number of days ahead for which to retrieve available booking dates. Default is 90 days, maximum is 365 days.", "type": "integer", "example": 90 }, "job_weight": { "description": "The weight of the job for which to retrieve available booking dates.", "type": "number", "format": "float", "example": 10.5 }, "job_volume": { "description": "The volume of the job for which to retrieve available booking dates.", "type": "number", "format": "float", "example": 2.5 }, "days_offset": { "description": "The minimum number of days ahead for available booking dates.", "type": "integer", "example": 5 } }, "type": "object" }, "PostJobChatRequestBody": { "title": "Job Chat Message model", "description": "Job Chat Message model", "required": [ "message" ], "properties": { "message": { "description": "The message content to be added to the job's chat. Line-breaks are supported via the newline (`\\n`) character.", "type": "string", "maxLength": 2500, "example": "Items must be dropped off from side entrance." } }, "type": "object" }, "PutJobChatRequestBody": { "title": "Update Job Chat Message model", "description": "Update Job Chat Message model", "required": [ "message" ], "properties": { "message": { "description": "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.", "type": "string", "maxLength": 2500, "example": "Items must be dropped off at front door!" } }, "type": "object" }, "VehicleBreakCreateRequest": { "required": [ "duration", "break_timing" ], "properties": { "window_start": { "description": "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.\nThis 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).", "type": "string" }, "window_end": { "description": "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.\nThis 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).", "type": "string" }, "duration": { "description": "Duration of the break in minutes. Once started, the break lasts this long", "type": "integer", "maximum": 120, "minimum": 1 }, "break_timing": { "$ref": "#/components/schemas/VehicleBreakTiming" } }, "type": "object", "example": { "window_start": "12:00 PM", "window_end": "02:30 PM", "duration": 30, "break_timing": "custom_time" } }, "VehicleBreakUpdateRequest": { "properties": { "window_start": { "description": "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.\nThis 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).", "type": "string" }, "window_end": { "description": "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.\nThis 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).", "type": "string" }, "duration": { "description": "Duration of the break in minutes. Once started, the break lasts this long", "type": "integer", "maximum": 120, "minimum": 1 }, "break_timing": { "$ref": "#/components/schemas/VehicleBreakTiming" } }, "type": "object", "example": { "duration": 30, "break_timing": "before_departure" } }, "PingResponse": { "title": "Ping Request Response", "properties": { "statusCode": { "description": "HTTP response status code", "type": "integer", "example": 200 }, "status": { "description": "HTTP response status", "type": "string", "example": "OK" }, "message": { "description": "Simple welcome message to our API.", "type": "string", "example": "Welcome to the Cigo Tracker API!" }, "details": { "$ref": "#/components/schemas/PingDetails" } }, "type": "object" }, "RetrieveJobResponse": { "title": "Job, Actions, and Related On-Route Stops", "properties": { "statusCode": { "description": "HTTP response status code", "type": "integer", "example": 200 }, "status": { "description": "HTTP response status", "type": "string", "example": "OK" }, "job": { "$ref": "#/components/schemas/JobModel" }, "actions": { "description": "Actions", "type": "array", "items": { "$ref": "#/components/schemas/JobActionModel" } }, "related_on_route_stops": { "description": "Related On-Route Stops", "type": "array", "items": { "$ref": "#/components/schemas/JobRelatedOnRouteStopsModel" } } }, "type": "object" }, "RetrieveCustomerResponse": { "title": "Customer, default configuration and related jobs", "properties": { "statusCode": { "description": "HTTP response status code", "type": "integer", "example": 200 }, "status": { "description": "HTTP response status", "type": "string", "example": "OK" }, "customer": { "$ref": "#/components/schemas/CustomerModel" } }, "type": "object" }, "RetrieveJobReportsResponse": { "title": "Job's reports", "properties": { "statusCode": { "description": "HTTP response status code", "type": "integer", "example": 200 }, "status": { "description": "HTTP response status", "type": "string", "example": "OK" }, "reports": { "$ref": "#/components/schemas/JobReportsModel" } }, "type": "object" }, "RetrieveJobChatResponse": { "title": "Job's chat", "properties": { "statusCode": { "description": "HTTP response status code", "type": "integer", "example": 200 }, "status": { "description": "HTTP response status", "type": "string", "example": "OK" }, "chat": { "description": "Job's chat data", "type": "array", "items": { "$ref": "#/components/schemas/JobChatModel" } } }, "type": "object" }, "RetrieveJobChatMessageByIDResponse": { "title": "Job's chat message", "properties": { "statusCode": { "description": "HTTP response status code", "type": "integer", "example": 200 }, "status": { "description": "HTTP response status", "type": "string", "example": "OK" }, "message_id": { "description": "Current message API ID", "type": "string", "example": "aa9b22d24b7ec4a6b53387df22645251" }, "job_id": { "description": "Associated Job API ID", "type": "string", "example": "aa9b22d24b7ec4a6b53387df22645251" }, "message": { "description": "Message", "type": "string", "example": "Just a message" }, "sent_on": { "format": "date-time", "example": "2022-10-11 22:47:58" }, "is_read": { "description": "Is message already read", "type": "boolean", "example": "true" } }, "type": "object" }, "RetrieveJobLocationResponse": { "title": "Job location info", "properties": { "statusCode": { "description": "HTTP response status code", "type": "integer", "example": 200 }, "status": { "description": "HTTP response status", "type": "string", "example": "OK" }, "job": { "$ref": "#/components/schemas/JobLocationModel" } }, "type": "object" }, "RetrieveJobActionResponse": { "title": "Action", "properties": { "statusCode": { "description": "HTTP response status code", "type": "integer", "example": 200 }, "status": { "description": "HTTP response status", "type": "string", "example": "OK" }, "action": { "$ref": "#/components/schemas/JobActionModel" } }, "type": "object" }, "RetrieveItinerariesResponse": { "title": "Retrieve an Itinerary basic details", "properties": { "statusCode": { "description": "HTTP response status code", "type": "integer", "example": 200 }, "status": { "description": "HTTP response status", "type": "string", "example": "OK" }, "date": { "description": "Date (GMT)", "type": "string", "format": "date", "example": "2024-08-01" }, "itineraries": { "description": "Itineraries", "type": "array", "items": { "$ref": "#/components/schemas/ItineraryModel" } } }, "type": "object" }, "RetrieveItinerariesResponse2": { "title": "Retrieve an Itinerary basic details", "properties": { "statusCode": { "description": "HTTP response status code", "type": "integer", "example": 200 }, "status": { "description": "HTTP response status", "type": "string", "example": "OK" }, "date": { "description": "Date range", "properties": { "start_date": { "description": "Start date (GMT)", "type": "string", "format": "date", "example": "2024-08-01" }, "end_date": { "description": "End date (GMT)", "type": "string", "format": "date", "example": "2024-09-15" } }, "type": "object" }, "itineraries": { "description": "Itineraries", "type": "array", "items": { "$ref": "#/components/schemas/ItineraryModel" } } }, "type": "object" }, "RetrieveItineraryResponse": { "title": "Retrieve an Itinerary basic details", "properties": { "statusCode": { "description": "HTTP response status code", "type": "integer", "example": 200 }, "status": { "description": "HTTP response status", "type": "string", "example": "OK" }, "itinerary": { "$ref": "#/components/schemas/ItineraryModel" } }, "type": "object" }, "RetrieveItineraryPolylineResponse": { "title": "Itinerary’s Polyline GeoJSON", "properties": { "statusCode": { "description": "HTTP response status code", "type": "integer", "example": 200 }, "status": { "description": "HTTP response status", "type": "string", "example": "OK" }, "geojson": { "$ref": "#/components/schemas/GeoJsonSchema" } }, "type": "object" }, "PreviewItineraryResponse": { "title": "Preview a route basic details", "properties": { "statusCode": { "description": "HTTP response status code", "type": "integer", "example": 200 }, "status": { "description": "HTTP response status", "type": "string", "example": "OK" }, "itinerary": { "$ref": "#/components/schemas/PreviewItineraryModel" } }, "type": "object" }, "RetrieveJobActionsResponse": { "title": "Retrieve all Job Actions", "properties": { "statusCode": { "description": "HTTP response status code", "type": "integer", "example": 200 }, "status": { "description": "HTTP response status", "type": "string", "example": "OK" }, "actions": { "description": "Actions", "type": "array", "items": { "$ref": "#/components/schemas/JobActionModel" } } }, "type": "object" }, "UpdateJobResponse": { "title": "Update Job Response", "properties": { "statusCode": { "description": "HTTP response status code", "type": "integer", "example": 200 }, "status": { "description": "HTTP response status", "type": "string", "example": "OK" }, "job_id": { "description": "Job ID", "type": "string", "example": "75bf34f9dd1c325a4542fcda7eb05794" }, "message": { "description": "Message", "type": "string", "example": "Updated Job resource for specified `jobID` successfully." } }, "type": "object" }, "UpdateJobActionResponse": { "title": "Update Job Action Response", "properties": { "statusCode": { "description": "HTTP response status code", "type": "integer", "example": 200 }, "status": { "description": "HTTP response status", "type": "string", "example": "OK" }, "job_id": { "description": "Job ID", "type": "string", "example": "75bf34f9dd1c325a4542fcda7eb05794" }, "action_id": { "description": "Action ID", "type": "string", "example": "2bda0e305cfaa7010a697b99fd51a809" }, "message": { "description": "Message", "type": "string", "example": "Updated Job Action resource for specified `actionID` successfully." } }, "type": "object" }, "UnauthorizedResponse": { "title": "Unauthorized Request Response", "properties": { "statusCode": { "description": "HTTP response status code", "type": "integer", "example": 401 }, "status": { "description": "HTTP response status", "type": "string", "example": "Unauthorized" }, "error": { "description": "Error message", "type": "string", "example": "Unauthorized authentication credentials." } }, "type": "object" }, "ForbiddenResponseCapacityManagement": { "title": "Forbidden Request Response", "properties": { "statusCode": { "description": "HTTP response status code", "type": "integer", "example": 403 }, "status": { "description": "HTTP response status", "type": "string", "example": "Forbidden" }, "error": { "description": "Error message", "type": "string", "example": "Access to the requested resource is forbidden. Please turn on Capacity Management to access this resource." } }, "type": "object" }, "ForbiddenHTTPRequest": { "title": "The resource doesn't support the specified HTTP verb.", "properties": { "statusCode": { "description": "HTTP response status code", "type": "integer", "example": 405 }, "status": { "description": "HTTP response status", "type": "string", "example": "Method Not Allowed" }, "error": { "description": "Error message", "type": "string", "example": "The resource doesn't support the specified HTTP verb." } }, "type": "object" }, "ForbiddenResponse": { "title": "Forbidden Request Response", "properties": { "statusCode": { "description": "HTTP response status code", "type": "integer", "example": 403 }, "status": { "description": "HTTP response status", "type": "string", "example": "Forbidden" }, "error": { "description": "Error message", "type": "string", "example": "Access to the requested resource is forbidden." } }, "type": "object" }, "ForbiddenDisabledResponse": { "title": "Forbidden or Disabled Request Response", "properties": { "statusCode": { "description": "HTTP response status code", "type": "integer", "example": 403 }, "status": { "description": "HTTP response status", "type": "string", "example": "Unauthorized" }, "error": { "description": "Error message", "type": "string", "example": "Access to the requested resource is forbidden. This feature is not currently enabled on your account. For more information, please contact your account manager." } }, "type": "object" }, "JobStateForbiddenResponse": { "title": "Job State Forbidden Response", "properties": { "statusCode": { "description": "HTTP response status code", "type": "integer", "example": 403 }, "status": { "description": "HTTP response status", "type": "string", "example": "Forbidden" }, "error": { "description": "Error", "type": "string", "example": "The status of the Job associated with this request prevents it and its Actions from being modified or removed." }, "details": { "description": "Job Status and Itinerary Assignment", "properties": { "status": { "description": "HTTP response status", "type": "string", "example": "In Progress" }, "in_itinerary": { "description": "In Itinerary", "type": "boolean", "example": true } }, "type": "object" } }, "type": "object" }, "ApiDisabledResponse": { "title": "API Disabled Response", "properties": { "statusCode": { "description": "HTTP response status code", "type": "integer", "example": 409 }, "status": { "description": "HTTP response status", "type": "string", "example": "Conflict" }, "error": { "description": "Error message", "type": "string", "example": "API Access is disabled." } }, "type": "object" }, "JobCreateResponse": { "title": "Job Create Response", "properties": { "statusCode": { "description": "HTTP response status code", "type": "integer", "example": 201 }, "status": { "description": "HTTP response status", "type": "string", "example": "Created" }, "message": { "description": "Message", "type": "string", "example": "Successfully created a job for staging. Save 'job_id' to refer to this job in other operations." }, "job_id": { "description": "Job ID", "type": "string", "example": "75bf34f9dd1c325a4542fcda7eb05794" }, "actions": { "description": "List containing dictionaries of action IDs and the external_reference_id of the action", "type": "array", "items": { "properties": { "action_id": { "description": "Action ID", "type": "string", "example": "4658447740ea46059239b7184d374ff1" }, "external_reference_id": { "description": "External Reference ID", "type": "string", "example": "external_ref_12345" } }, "type": "object" } } }, "type": "object" }, "SearchJobsResponse": { "title": "Search Jobs Response", "properties": { "statusCode": { "description": "HTTP response status code", "type": "integer", "example": 200 }, "status": { "description": "HTTP response status", "type": "string", "example": "OK" }, "in_staging": { "description": "Matching count and list of Job API IDs that are in status `staging`", "properties": { "count": { "description": "Count of Job API IDs corresponding to the search request", "type": "integer", "example": 1 }, "ids": { "description": "List of Job API IDs corresponding to the search request", "type": "array", "items": { "description": "Job API ID", "type": "string", "example": "37703edb3ce4532bc70e8b19b1989c52" } } }, "type": "object" }, "post_staging": { "description": "Matching count and list of Job API IDs that are in statuses after `staging`, i.e. `new`, `completed`, etc.", "properties": { "count": { "description": "Count of Job API IDs corresponding to the search request", "type": "integer", "example": 1 }, "ids": { "description": "List of Job API IDs corresponding to the search request", "type": "array", "items": { "description": "Job API ID", "type": "string", "example": "864c4cb6402655563ed30fb5db298e90" } } }, "type": "object" } }, "type": "object" }, "RequiredFieldsSearchJobResponse": { "title": "Missing required fields or invalid value in request body.", "properties": { "statusCode": { "description": "HTTP response status code", "type": "integer", "example": 400 }, "status": { "description": "HTTP response status", "type": "string", "example": "Bad Request" }, "error": { "description": "Error message", "type": "string", "example": "One or more required fields were not set." }, "details": { "description": "Error details", "type": "array", "items": { "description": "Error message", "type": "string", "example": "Required: 'start_date' is not set." } } }, "type": "object" }, "JobActionCreateResponse": { "title": "Job ACtion Create Response", "properties": { "statusCode": { "description": "HTTP response status code", "type": "integer", "example": 201 }, "status": { "description": "HTTP response status", "type": "string", "example": "Created" }, "job_id": { "description": "Job ID", "type": "string", "example": "75bf34f9dd1c325a4542fcda7eb05794" }, "job_status": { "description": "Job Status", "type": "string", "example": "staging" }, "message": { "description": "Message", "type": "string", "example": "Successfully created an action for staged job '75bf34f9dd1c325a4542fcda7eb05794'. Save 'action_id' to refer to this action in other operations." }, "action_id": { "description": "Action ID", "type": "string", "example": "97a7f7052349acb9db2fb28b19df3ba5" } }, "type": "object" }, "JobNotFoundResponse": { "title": "Job Not Found Response", "properties": { "statusCode": { "description": "HTTP response status code", "type": "integer", "example": 404 }, "status": { "description": "HTTP response status", "type": "string", "example": "Not Found" }, "error": { "description": "Error message", "type": "string", "example": "No Job found for given `jobID`." } }, "type": "object" }, "JobOrActionNotFoundResponse": { "title": "Job or Action Not Found Response", "properties": { "statusCode": { "description": "HTTP response status code", "type": "integer", "example": 404 }, "status": { "description": "HTTP response status", "type": "string", "example": "Not Found" }, "error": { "description": "Error message", "type": "string", "example": "Either the Job for the given `jobID` or the Job Action for the given `actionID` could not be found." } }, "type": "object" }, "CustomerNotFoundResponse": { "title": "Customer Not Found Response", "properties": { "statusCode": { "description": "HTTP response status code", "type": "integer", "example": 404 }, "status": { "description": "HTTP response status", "type": "string", "example": "Not Found" }, "error": { "description": "Error message", "type": "string", "example": "No Customer found for the given `CustomerID`." } }, "type": "object" }, "ItineraryNotFoundResponse": { "title": "Itinerary Not Found Response", "properties": { "statusCode": { "description": "HTTP response status code", "type": "integer", "example": 404 }, "status": { "description": "HTTP response status", "type": "string", "example": "Not Found" }, "error": { "description": "Error message", "type": "string", "example": "No Itinerary found for given `itineraryID`." } }, "type": "object" }, "ItineraryCreateResponse": { "title": "Itinerary Create Response", "properties": { "statusCode": { "description": "HTTP response status code", "type": "integer", "example": 201 }, "status": { "description": "HTTP response status", "type": "string", "example": "Created" }, "message": { "description": "Message", "type": "string", "example": "Successfully created an Itinerary. Save 'itinerary_id' to refer to this Itinerary in other operations." }, "itinerary_id": { "description": "Itinerary ID", "type": "string", "example": "75bf34f9dd1c325a4542fcda7eb05794" }, "warnings": { "description": "Warnings", "type": "array", "items": { "$ref": "#/components/schemas/CreateItineraryWarnings" } } }, "type": "object" }, "ItineraryUpdateResponse": { "title": "Update Itinerary Response", "properties": { "statusCode": { "description": "HTTP response status code", "type": "integer", "example": 200 }, "status": { "description": "HTTP response status", "type": "string", "example": "OK" }, "itinerary_id": { "description": "Itinerary ID", "type": "string", "example": "75bf34f9dd1c325a4542fcda7eb05794" }, "message": { "description": "Message", "type": "string", "example": "Updated Itinerary resource for specified `itineraryID` successfully." }, "warnings": { "description": "Warnings", "type": "array", "items": { "$ref": "#/components/schemas/UpdateItineraryWarnings" } } }, "type": "object" }, "ItineraryUpdateOperatorsResponse": { "title": "Update Itinerary Operators", "properties": { "statusCode": { "description": "HTTP response status code", "type": "integer", "example": 200 }, "status": { "description": "HTTP response status", "type": "string", "example": "OK" }, "message": { "description": "Message", "type": "string", "example": "Updated Operators resource for specified `itineraryID` successfully." } }, "type": "object" }, "ItineraryUpdateOperatorsBadRequestResponse": { "title": "Invalid operator IDs", "properties": { "statusCode": { "description": "HTTP response status code", "type": "integer", "example": 404 }, "status": { "description": "HTTP response status", "type": "string", "example": "Bad Request" }, "error": { "description": "Error message", "type": "string", "example": "Invalid or missing operator IDs." }, "error_code": { "description": "Application error code", "type": "integer", "example": 917509 }, "details": { "description": "Additional error details, when available", "type": "array", "items": { "type": "object" } } }, "type": "object" }, "ItineraryChangePositionResponse": { "title": "Change position of a single Stop", "properties": { "statusCode": { "description": "HTTP response status code", "type": "integer", "example": 200 }, "status": { "description": "HTTP response status", "type": "string", "example": "OK" }, "message": { "description": "Message", "type": "string", "example": "Changed Stop position for specified `itineraryID` successfully." } }, "type": "object" }, "ItineraryChangePositionsResponse": { "title": "Change positions of all Stops", "properties": { "statusCode": { "description": "HTTP response status code", "type": "integer", "example": 200 }, "status": { "description": "HTTP response status", "type": "string", "example": "OK" }, "message": { "description": "Message", "type": "string", "example": "Changed Stops positions for specified `itineraryID` successfully." } }, "type": "object" }, "ItineraryReversePositionsResponse": { "title": "Reverse order of Stops (not Started/Completed) of an existing itinerary.", "properties": { "statusCode": { "description": "HTTP response status code", "type": "integer", "example": 200 }, "status": { "description": "HTTP response status", "type": "string", "example": "OK" }, "message": { "description": "Error message", "type": "string", "example": "Reversed Stops for specified `itineraryID` successfully." } }, "type": "object" }, "InvalidParametersResponse": { "title": "Invalid request parameters.", "properties": { "statusCode": { "description": "HTTP response status code", "type": "integer", "example": 422 }, "status": { "description": "HTTP response status", "type": "string", "example": "Bad Request" }, "error": { "description": "Error details (if there are any)", "type": "array", "items": { "type": "object" } } }, "type": "object" }, "ItineraryInvalidParametersResponse": { "title": "Invalid request parameters.", "properties": { "statusCode": { "description": "HTTP response status code", "type": "integer", "example": 422 }, "status": { "description": "HTTP response status", "type": "string", "example": "Unprocessable Entity" }, "error": { "description": "Error message", "type": "string", "example": "The request parameters are invalid." }, "error_code": { "description": "Unique Error code", "type": "integer", "example": 917951 }, "details": { "description": "Error details (if there are any)", "type": "array", "items": { "type": "object" } } }, "type": "object" }, "InvalidDateResponse": { "title": "Invalid Date Response", "properties": { "statusCode": { "description": "HTTP response status code", "type": "integer", "example": 422 }, "status": { "description": "HTTP response status", "type": "string", "example": "Bad Request" }, "error": { "description": "Error message", "type": "string", "example": "The request parameters are invalid." }, "details": { "description": "Error details", "type": "array", "items": { "description": "Error message", "type": "string", "example": "Invalid date value. Supported format date format YYYY-MM-DD (as per ISO-8601: https://www.iso.org/iso-8601-date-and-time-format.html)" } } }, "type": "object" }, "RequiredFieldsJobResponse": { "title": "Missing Required Fields in Create a new Job", "properties": { "statusCode": { "description": "HTTP response status code", "type": "integer", "example": 400 }, "status": { "description": "HTTP response status", "type": "string", "example": "Bad Request" }, "error": { "description": "Error message", "type": "string", "example": "One or more required fields were not set." }, "details": { "description": "Error details", "type": "array", "items": { "description": "Error message", "type": "string", "example": "Required: 'first_name' is not set." } } }, "type": "object" }, "RequiredFieldsJobActionResponse": { "title": "Missing Required Fields in Create a new Job Action", "properties": { "statusCode": { "description": "HTTP response status code", "type": "integer", "example": 400 }, "status": { "description": "HTTP response status", "type": "string", "example": "Bad Request" }, "error": { "description": "Error message", "type": "string", "example": "One or more required fields were not set." }, "details": { "description": "Error details", "type": "array", "items": { "description": "Error message", "type": "string", "example": "Required: 'description' is not set." } } }, "type": "object" }, "RetrieveLocationsResponse": { "title": "Retrieve Locations basic details", "properties": { "statusCode": { "description": "HTTP response status code", "type": "integer", "example": 200 }, "status": { "description": "HTTP response status", "type": "string", "example": "OK" }, "locations": { "description": "Locations", "type": "array", "items": { "$ref": "#/components/schemas/LocationModel" } } }, "type": "object" }, "RetrieveLocationResponse": { "title": "Retrieve a Location basic details", "properties": { "statusCode": { "description": "HTTP response status code", "type": "integer", "example": 200 }, "status": { "description": "HTTP response status", "type": "string", "example": "OK" }, "location": { "$ref": "#/components/schemas/LocationModel" } }, "type": "object" }, "LocationsNotFoundResponse": { "title": "Location Not Found Response", "properties": { "statusCode": { "description": "HTTP response status code", "type": "integer", "example": 404 }, "status": { "description": "HTTP response status", "type": "string", "example": "Not Found" }, "error": { "description": "Error message", "type": "string", "example": "No Location found." } }, "type": "object" }, "LocationNotFoundResponse": { "title": "Location Not Found Response", "properties": { "statusCode": { "description": "HTTP response status code", "type": "integer", "example": 404 }, "status": { "description": "HTTP response status", "type": "string", "example": "Not Found" }, "error": { "description": "Error message", "type": "string", "example": "No Location found for given location id." } }, "type": "object" }, "LocationCreateResponse": { "title": "Location Create Response", "properties": { "statusCode": { "description": "HTTP response status code", "type": "integer", "example": 201 }, "status": { "description": "HTTP response status", "type": "string", "example": "Created" }, "location_id": { "description": "Location ID", "type": "string", "example": "75bf34f9dd1c325a4542fcda7eb05794" } }, "type": "object" }, "LocationUnknownPropertyResponse": { "title": "Location Unknown Property Response", "properties": { "statusCode": { "description": "HTTP response status code", "type": "integer", "example": 400 }, "status": { "description": "HTTP response status", "type": "string", "example": "Bad Request" }, "error": { "description": "Error message", "type": "string", "example": "Unknown property {property}." } }, "type": "object" }, "LocationPropertyRequiredResponse": { "title": "Location Property is Required Response", "properties": { "statusCode": { "description": "HTTP response status code", "type": "integer", "example": 400 }, "status": { "description": "HTTP response status", "type": "string", "example": "Bad Request" }, "error": { "description": "Error message", "type": "string", "example": "{property} is required." } }, "type": "object" }, "LocationInvalidCoordinatesFormatResponse": { "title": "Location coordinates format is invalid", "properties": { "statusCode": { "description": "HTTP response status code", "type": "integer", "example": 400 }, "status": { "description": "HTTP response status", "type": "string", "example": "Bad Request" }, "error": { "description": "Error message", "type": "string", "example": "Coordinates property value must be [latitude, longitude] in GeoJSON format." } }, "type": "object" }, "LocationInvalidCoordinatesResponse": { "title": "Location provided latitude and longitude values are invalid", "properties": { "statusCode": { "description": "HTTP response status code", "type": "integer", "example": 400 }, "status": { "description": "HTTP response status", "type": "string", "example": "Bad Request" }, "error": { "description": "Error message", "type": "string", "example": "Invalid latitude and longitude pair for the provided coordinate." } }, "type": "object" }, "LocationInvalidCoordinatesAddressResponse": { "title": "Invalid address for the location provided coordinates", "properties": { "statusCode": { "description": "HTTP response status code", "type": "integer", "example": 400 }, "status": { "description": "HTTP response status", "type": "string", "example": "Bad Request" }, "error": { "description": "Error message", "type": "string", "example": "Couldn't find a valid address for the provided coordinates." } }, "type": "object" }, "LocationNotAllowedAttribute": { "title": "Location setting attribute is not allowed", "properties": { "statusCode": { "description": "HTTP response status code", "type": "integer", "example": 405 }, "status": { "description": "HTTP response status", "type": "string", "example": "Not Allowed" }, "error": { "description": "Error message", "type": "string", "example": "Setting property {property} is not allowed." } }, "type": "object" }, "LocationUnknownType": { "title": "Unknown location_type {location_type}", "properties": { "statusCode": { "description": "HTTP response status code", "type": "integer", "example": 400 }, "status": { "description": "HTTP response status", "type": "string", "example": "Bad Request" }, "error": { "description": "Error message", "type": "string", "example": "Unknown location_type {location_type}. Valid locations types are {valid_types}" } }, "type": "object" }, "LocationDataMissing": { "title": "Location data is missing.", "properties": { "statusCode": { "description": "HTTP response status code", "type": "integer", "example": 400 }, "status": { "description": "HTTP response status", "type": "string", "example": "Bad Request" }, "error": { "description": "Error message", "type": "string", "example": "Location data is missing." } }, "type": "object" }, "LocationAddressDataMissing": { "title": "Location address/coordinates data is missing", "properties": { "statusCode": { "description": "HTTP response status code", "type": "integer", "example": 400 }, "status": { "description": "HTTP response status", "type": "string", "example": "Bad Request" }, "error": { "description": "Error message", "type": "string", "example": "Location property should include either an address or coordinates." } }, "type": "object" }, "LocationUpdateResponse": { "title": "Location Update Response", "properties": { "statusCode": { "description": "HTTP response status code", "type": "integer", "example": 200 }, "status": { "description": "HTTP response status", "type": "string", "example": "Ok" }, "message": { "description": "Message", "type": "string", "example": "Updated Location resource for specified location id successfully." } }, "type": "object" }, "LocationInvalidStateIdResponse": { "title": "Location Invalid active Response", "properties": { "statusCode": { "description": "HTTP response status code", "type": "integer", "example": 400 }, "status": { "description": "HTTP response status", "type": "string", "example": "Bad Request" }, "error": { "description": "Error message", "type": "string", "example": "`active` value is not valid. Only valid boolean values of `true` or `false` can be used activating/deactivating a Location." } }, "type": "object" }, "LocationDeactivateDefaultVehicleResponse": { "title": "location must not be assigned as vehicle default", "properties": { "statusCode": { "description": "HTTP response status code", "type": "integer", "example": 405 }, "status": { "description": "HTTP response status", "type": "string", "example": "Not Allowed" }, "error": { "description": "Error message", "type": "string", "example": "Cannot deactivate this location because it is already assigned to a Vehicle as a default location." } }, "type": "object" }, "LocationDeactivateFutureItineraryResponse": { "title": "Location must not be assigned to a future Itinerary", "properties": { "statusCode": { "description": "HTTP response status code", "type": "integer", "example": 405 }, "status": { "description": "HTTP response status", "type": "string", "example": "Not Allowed" }, "error": { "description": "Error message", "type": "string", "example": "Cannot deactivate this location because it is already assigned to a future Itinerary." } }, "type": "object" }, "RetrieveVehiclesResponse": { "title": "Retrieve Vehicles basic details", "properties": { "statusCode": { "description": "HTTP response status code", "type": "integer", "example": 200 }, "status": { "description": "HTTP response status", "type": "string", "example": "OK" }, "vehicles": { "description": "Vehicles", "type": "array", "items": { "$ref": "#/components/schemas/VehicleModel" } } }, "type": "object" }, "RetrieveVehicleResponse": { "title": "Retrieve a vehicle basic details", "properties": { "statusCode": { "description": "HTTP response status code", "type": "integer", "example": 200 }, "status": { "description": "HTTP response status", "type": "string", "example": "OK" }, "vehicle": { "$ref": "#/components/schemas/VehicleModel" } }, "type": "object" }, "VehiclesNotFoundResponse": { "title": "Vehicle Not Found Response", "properties": { "statusCode": { "description": "HTTP response status code", "type": "integer", "example": 404 }, "status": { "description": "HTTP response status", "type": "string", "example": "Not Found" }, "error": { "description": "Error message", "type": "string", "example": "No Vehicle found." } }, "type": "object" }, "VehicleNotFoundResponse": { "title": "Vehicle Not Found Response", "properties": { "statusCode": { "description": "HTTP response status code", "type": "integer", "example": 404 }, "status": { "description": "HTTP response status", "type": "string", "example": "Not Found" }, "error": { "description": "Error message", "type": "string", "example": "No Vehicle found for given `VehicleID`." } }, "type": "object" }, "RetrieveOperatorsResponse": { "title": "Retrieve Operators basic details", "properties": { "statusCode": { "description": "HTTP response status code", "type": "integer", "example": 200 }, "status": { "description": "HTTP response status", "type": "string", "example": "OK" }, "operators": { "description": "Operators", "type": "array", "items": { "$ref": "#/components/schemas/OperatorModel" } } }, "type": "object" }, "RetrieveOperatorResponse": { "title": "Retrieve an operator basic details", "properties": { "statusCode": { "description": "HTTP response status code", "type": "integer", "example": 200 }, "status": { "description": "HTTP response status", "type": "string", "example": "OK" }, "operator": { "$ref": "#/components/schemas/OperatorModel" } }, "type": "object" }, "OperatorsNotFoundResponse": { "title": "Operator Not Found Response", "properties": { "statusCode": { "description": "HTTP response status code", "type": "integer", "example": 404 }, "status": { "description": "HTTP response status", "type": "string", "example": "Not Found" }, "error": { "description": "Error message", "type": "string", "example": "No Operator found." } }, "type": "object" }, "OperatorNotFoundResponse": { "title": "Operator Not Found Response", "properties": { "statusCode": { "description": "HTTP response status code", "type": "integer", "example": 404 }, "status": { "description": "HTTP response status", "type": "string", "example": "Not Found" }, "error": { "description": "Error message", "type": "string", "example": "No Operator found for given `OperatorID`." } }, "type": "object" }, "OperatorCreateResponse": { "title": "Operator Create Response", "properties": { "statusCode": { "description": "HTTP response status code", "type": "integer", "example": 201 }, "status": { "description": "HTTP response status", "type": "string", "example": "Created" }, "operator_id": { "description": "Operator ID", "type": "string", "example": "6c89f32048f964a88f3da6b16abc43d4" } }, "type": "object" }, "OperatorUnknownPropertyResponse": { "title": "Operator Unknown Property Response", "properties": { "statusCode": { "description": "HTTP response status code", "type": "integer", "example": 400 }, "status": { "description": "HTTP response status", "type": "string", "example": "Bad Request" }, "error": { "description": "Error message", "type": "string", "example": "Unknown property {property}." } }, "type": "object" }, "OperatorPropertyRequiredResponse": { "title": "Operator Property is Required Response", "properties": { "statusCode": { "description": "HTTP response status code", "type": "integer", "example": 400 }, "status": { "description": "HTTP response status", "type": "string", "example": "Bad Request" }, "error": { "description": "Error message", "type": "string", "example": "{property} is required." } }, "type": "object" }, "OperatorNotAllowedAttribute": { "title": "Operator setting attribute is not allowed", "properties": { "statusCode": { "description": "HTTP response status code", "type": "integer", "example": 405 }, "status": { "description": "HTTP response status", "type": "string", "example": "Not allowed" }, "error": { "description": "Error message", "type": "string", "example": "Setting property {property} is not allowed." } }, "type": "object" }, "OperatorDataMissing": { "title": "Operator data is missing.", "properties": { "statusCode": { "description": "HTTP response status code", "type": "integer", "example": 400 }, "status": { "description": "HTTP response status", "type": "string", "example": "Bad Request" }, "error": { "description": "Error message", "type": "string", "example": "Operator data is missing." } }, "type": "object" }, "OperatorUpdateResponse": { "title": "Operator Update Response", "properties": { "statusCode": { "description": "HTTP response status code", "type": "integer", "example": 200 }, "status": { "description": "HTTP response status", "type": "string", "example": "Ok" }, "message": { "description": "Message", "type": "string", "example": "Updated Operator resource for specified Operator API ID successfully." } }, "type": "object" }, "OperatorInvalidStateIdResponse": { "title": "Operator Invalid active Response", "properties": { "statusCode": { "description": "HTTP response status code", "type": "integer", "example": 400 }, "status": { "description": "HTTP response status", "type": "string", "example": "Bad Request" }, "error": { "description": "Error message", "type": "string", "example": "`active` value is not valid. Only valid boolean values of `true` or `false` can be used activating/deactivating an Operator." } }, "type": "object" }, "OperatorDeactivateFutureItineraryResponse": { "title": "Operator must not be assigned to a future Itinerary", "properties": { "statusCode": { "description": "HTTP response status code", "type": "integer", "example": 405 }, "status": { "description": "HTTP response status", "type": "string", "example": "Not Allowed" }, "error": { "description": "Error message", "type": "string", "example": "Cannot deactivate this Operator because they have been assigned to a future Itinerary." } }, "type": "object" }, "AvailableSlotsResponse": { "title": "Available Slots Response", "description": "Response schema for available slots.", "properties": { "max_jobs": { "description": "Maximum number of jobs allowed. Only sent if zone has max slots settings enabled.", "type": "integer", "example": 10 }, "available_jobs_slots": { "description": "Number of available job slots. In case the maximum number has been exceeded, a negative value will be sent. Only sent if zone has max slots settings enabled.", "type": "integer", "example": 5 }, "max_weight": { "description": "Maximum weight capacity. Only sent if zone has max weight settings enabled.", "type": "number", "format": "float", "example": 200 }, "available_weight_slots": { "description": "Available weight capacity. In case the maximum number has been exceeded, a negative value will be sent. Only sent if zone has max weight settings enabled.", "type": "number", "format": "float", "example": 150.5 }, "max_volume": { "description": "Maximum volume capacity. Only sent if zone has max volume settings enabled.", "type": "number", "format": "float", "example": 100 }, "available_volume_slots": { "description": "Available volume capacity. In case the maximum number has been exceeded, a negative value will be sent. Only sent if zone has max volume settings enabled.", "type": "number", "format": "float", "example": 75.3 }, "max_handle_time": { "description": "Maximum handle time capacity. Only sent if zone has max handle time (working time) settings enabled.", "type": "number", "format": "float", "example": 100 }, "available_handle_time": { "description": "Available handle time capacity. In case the maximum number has been exceeded, a negative value will be sent. Only sent if zone has max handle time settings enabled.", "type": "number", "format": "float", "example": 75.3 } }, "type": "object" }, "AvailableBookingDatesResponse": { "title": "Available Booking Dates Response", "description": "Response schema for available booking dates.", "properties": { "statusCode": { "description": "HTTP response status code", "type": "integer", "example": 200 }, "status": { "description": "HTTP response status", "type": "string", "example": "OK" }, "available_booking_dates": { "description": "List of available booking dates.", "type": "array", "items": { "type": "string", "format": "date", "example": "2023-10-15" } } }, "type": "object" }, "GeofencingGetAllResponse": { "title": "List of all Geofencing events.", "properties": { "statusCode": { "description": "HTTP response status code", "type": "integer", "example": 200 }, "status": { "description": "HTTP response status", "type": "string", "example": "OK" }, "geofence_events": { "description": "Geofencing events", "type": "array", "items": { "$ref": "#/components/schemas/GeofenceEvent" } }, "first_geofence_entry": { "description": "First Geofencing event arrival time", "type": "string", "example": "03:00:00 AM" }, "last_geofence_exit": { "description": "Last Geofencing events departure time", "type": "string", "example": "03:10:00 AM" } }, "type": "object" }, "GeofencingInvalidIDResponse": { "title": "Operator must not be assigned to a future Itinerary", "properties": { "statusCode": { "description": "HTTP response status code", "type": "integer", "example": 400 }, "status": { "description": "HTTP response status", "type": "string", "example": "Bad Request" }, "error": { "description": "Error message", "type": "string", "example": "Invalid ID type." } }, "type": "object" }, "GeofencingJobNotFoundResponse": { "title": "Operator must not be assigned to a future Itinerary", "properties": { "statusCode": { "description": "HTTP response status code", "type": "integer", "example": 404 }, "status": { "description": "HTTP response status", "type": "string", "example": "Not Found" }, "error": { "description": "Error message", "type": "string", "example": "Job not found." } }, "type": "object" }, "GeofencingMethodNotAllowedResponse": { "title": "Operator must not be assigned to a future Itinerary", "properties": { "statusCode": { "description": "HTTP response status code", "type": "integer", "example": 405 }, "status": { "description": "HTTP response status", "type": "string", "example": "Method Not Allowed" }, "error": { "description": "Error message", "type": "string", "example": "Method not allowed." } }, "type": "object" }, "SearchCustomersResponse": { "title": "Search Customers Response", "properties": { "statusCode": { "description": "HTTP response status code", "type": "integer", "example": 200 }, "status": { "description": "HTTP response status", "type": "string", "example": "OK" }, "customers": { "description": "List of matching customers", "type": "array", "items": { "$ref": "#/components/schemas/CustomerSearchModel" } } }, "type": "object" }, "RequiredFieldsSearchCustomerResponse": { "title": "Missing Required Fields in Search for Customers", "properties": { "statusCode": { "description": "HTTP response status code", "type": "integer", "example": 422 }, "status": { "description": "HTTP response status", "type": "string", "example": "Unprocessable Entity" }, "error": { "description": "Error message", "type": "string", "example": "The request body is invalid." }, "details": { "description": "Error details", "type": "array", "items": { "description": "Specific details about missing or invalid fields.", "type": "string", "example": "name: Value cannot be null or empty." } } }, "type": "object" }, "JobChatCreateResponse": { "title": "Job Chat Creation Response", "description": "Response when successfully creating a job chat message", "properties": { "statusCode": { "description": "HTTP response status code", "type": "integer", "example": 201 }, "status": { "description": "HTTP response status", "type": "string", "example": "Created" }, "job_id": { "description": "Associated Job API ID", "type": "string", "example": "f22645251aa9b22d24b7ec4a6b53387d" }, "message_id": { "description": "Associated Message API ID", "type": "string", "example": "75bf34f9dd1c325a4542fcda7eb05794" }, "message": { "description": "HTTP response message", "type": "string", "example": "Successfully created a job message." } }, "type": "object" }, "JobChatUpdateResponse": { "title": "Job Chat Update Response", "description": "Response when successfully updating a job chat message", "properties": { "statusCode": { "description": "HTTP response status code", "type": "integer", "example": 200 }, "status": { "description": "HTTP response status", "type": "string", "example": "OK" }, "job_id": { "description": "Associated Job API ID", "type": "string", "example": "f22645251aa9b22d24b7ec4a6b53387d" }, "message_id": { "description": "Associated Message API ID", "type": "string", "example": "75bf34f9dd1c325a4542fcda7eb05794" }, "update_time": { "format": "date-time", "example": "2022-10-11 22:47:58" }, "message": { "description": "Message", "type": "string", "example": "Successfully updated the job message." } }, "type": "object" }, "RetrieveJobChatMessageResponse": { "title": "Job Chat Message Response", "description": "Response when retrieving a single job chat message", "properties": { "statusCode": { "description": "HTTP response status code", "type": "integer", "example": 200 }, "status": { "description": "HTTP response status", "type": "string", "example": "OK" }, "api_id": { "description": "Associated Message API ID", "type": "string", "example": "aa9b22d24b7ec4a6b53387df22645251" }, "message": { "type": "string", "example": "Items must be dropped off at front door!" }, "file_url": { "type": "string", "example": "https://cigo.local/api/v1/jobs/id/?filename=" }, "user": { "$ref": "#/components/schemas/ChatUser" }, "job_status": { "type": "string", "example": "in progress" }, "sent_on": { "type": "string", "format": "date-time", "example": "2022-10-11 22:47:58" }, "read_on": { "nullable": true, "type": "string", "format": "date-time", "example": null }, "read_status": { "type": "boolean", "example": false }, "update_time": { "nullable": true, "type": "string", "format": "date-time", "example": null } }, "type": "object" }, "MessageNotFoundResponse": { "title": "Message Not Found Response", "properties": { "statusCode": { "type": "integer", "example": 404 }, "status": { "type": "string", "example": "Not Found" }, "error": { "type": "string", "example": "Message not found" } }, "type": "object" }, "RequiredFieldsJobChatResponse": { "title": "Missing Chat Fields Response", "properties": { "statusCode": { "type": "integer", "example": 400 }, "status": { "type": "string", "example": "Bad Request" }, "error": { "type": "string", "example": "Missing required field: message" } }, "type": "object" }, "ChatEditForbiddenResponse": { "title": "Chat Edit Forbidden Response", "properties": { "statusCode": { "type": "integer", "example": 403 }, "status": { "type": "string", "example": "Forbidden" }, "error": { "type": "string", "example": "Only API-created messages can be edited" } }, "type": "object" }, "ChatUser": { "title": "Chat User Model", "properties": { "api_id": { "type": "string", "example": "b53387df22645251aa9b22d24b7ec4a6" }, "username": { "type": "string", "example": "operator@example.com" }, "name": { "type": "string", "example": "John Doe" }, "role": { "type": "string", "example": "Operator" } }, "type": "object" }, "BreakNotFoundResponse": { "properties": { "error": { "type": "string", "example": "not_found" }, "message": { "type": "string", "example": "Break not found for given `breakID` and `vehicleID`." } }, "type": "object" }, "MaxBreaksResponse": { "description": "Returned when a vehicle already has the maximum number of break windows.", "properties": { "error": { "type": "string", "example": "validation_error" }, "message": { "type": "string", "example": "A vehicle cannot have more than 3 break windows." }, "max": { "type": "integer", "example": 3 }, "current": { "type": "integer", "example": 3 } }, "type": "object" }, "VehicleBreakListResponse": { "properties": { "breaks": { "description": "List of configured break windows for the vehicle.", "type": "array", "items": { "$ref": "#/components/schemas/VehicleBreakResource" } } }, "type": "object", "example": { "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" } ] } }, "ScheduleVehicleBreakListResponse": { "properties": { "breaks": { "type": "array", "items": { "$ref": "#/components/schemas/ScheduleVehicleBreakResource" } } }, "type": "object", "example": { "breaks": [ { "break_api_id": "brk_fisdoa6h3472cio7823hxcb7f8", "vehicle_api_id": "veh_5e6bdf4bg923hx7f8io2", "schedule_id": "itn_8h3472cio78_f6b8f2c", "window_start": "03:00 PM", "window_end": "04:00 PM", "break_timing": "custom_time", "duration": 30, "active": 1, "position": 3, "created_at": "2025-11-07 12:00:00" } ] } } }, "securitySchemes": { "BasicAuth": { "type": "http", "description": "From the API credentials, use the generated Account ID and Auth Key values to authenticate with our API.\n### Getting your Account ID and Auth Key\n\nTo retrieve your Account ID and API Auth Key:\n1. Log in to Cigo Tracker as the account administrator\n2. From the left menu sidebar, navigate to [Integrations > API](/public-api/settings)\n3. If the API access is not enabled, enable it\n4. Once enabled, you can copy the Auth Key by clicking on the Clipboard icon adjacent to it. The same applies for the Auth Key after un-hiding it\n5. The **Account ID** serves as the `username` and the **Auth Key** serves as the `password` combination for your Basic Auth headers.\n\n![API Credentials Sample](/reference/public-api-credentials-example.png)\n\nOnce you're on the API settings page, you can copy the Auth Key by clicking on the Clipboard icon adjacent to it. The same applies for the Auth Key after un-hiding it.\n\n ### Troubleshooting\n- Validate that your API credentials are valid with the [ping GET request](#tag/auth/paths/~1ping/get)\n- Ensure that you are using the correct Account ID and Auth Key\n- Check that your [API Access is enabled](/public-api/settings)\n", "scheme": "basic" } } }, "tags": [ { "name": "auth", "x-displayName": "Credentials Validation" }, { "name": "job", "x-displayName": "Job" }, { "name": "action", "x-displayName": "Job Action" }, { "name": "customer", "x-displayName": "Customer" }, { "name": "itinerary", "x-displayName": "Itinerary" }, { "name": "location", "x-displayName": "Location" }, { "name": "vehicle", "x-displayName": "Vehicle" }, { "name": "operator", "x-displayName": "Operator" }, { "name": "geofencing", "x-displayName": "Geofencing" }, { "name": "capacity_management", "x-displayName": "Capacity Management" } ] }