Appointments
Fetch the available appointment slots, list, view, create, update, reschedule, and cancel appointments in Octopi.

This resource allows clients to fetch the available appointment slots, list, view, create, update, reschedule, and cancel appointments in Octopi.‘

Supported Formats

json
>>>

GET /api/v1/appointments

Returns all the appointments present for a provided date.

Supported Formats

json

Errors

Code Description
404 Not found.
422 Unprocessable Entity.
500 Internal Server Error.

Examples

curl --location --request GET 'https://app.octopi.co/api/v1/appointments'     --header 'Authorization: Token token==ADD TOKEN HERE'     --header 'Content-Type: application/json'     --data-raw '{
  "appointment_date": "2023-08-18"
}'

{
  "appointments": [
    {
      "appointment_number": "OCTOAPPT1104501",
      "appointment_slot_id": 1045,
      "appointment_date": "2023-08-18",
      "appointment_timings": "01:00 PM - 02:00 PM",
      "status": "Pending",
      "truck": "TN01AN1982",
      "truck_driver": {
        "id": 1234,
        "fullname": "John Doe",
        "license_number": "LIDEW9784FY",
        "twic": "",
        "number": "633353",
        "active": true,
        "date_of_birth": null,
        "telephone_number": null,
        "email": null,
        "remarks": null,
        "trucking_company": "TruckingCo1",
        "allowed_until": null,
        "created_at": "2017-09-15T15:47:12Z",
        "updated_at": "2023-09-15T15:47:12Z"
      },
      "truck_visit": null,
      "comment": "",
      "reschedule_reason": null,
      "purposes": [
        {
          "purpose_type": "drop_off",
          "cargo_type": "container",
          "cargo_status": "full",
          "cargo": "CMAU2100410",
          "container_usage": null,
          "booking": "RUNNINGBOOKING",
          "bill_of_lading": "BOL1092719",
          "delivery_order": null
        }
      ]
    }
  ]
}

Params

Param name Description
appointment_date
required

Filter appointments for the provided date. Must be formatted as YYYY-MM-DD.

Validations:

  • Must be a String
appointment_number
optional

Filter appointments for a given appointment. You can pass the appointment Octopi ID or the appointment number.

Validations:

  • Must be a String
terminal
optional

Filter appointments for the provided Terminal Name. You can pass the terminal Octopi ID or the terminal name.

Validations:

  • Must be a String
container
optional

Filter appointments associated with a container. You can pass the container Octopi ID or the container number.

Validations:

  • Must be a String
truck
optional

Filter appointments associated with a truck. You can pass the truck Octopi ID or the truck’s license plate.

Validations:

  • Must be a String
bill_of_lading
optional

Filter appointments associated with a bill of lading. You can pass the bill of lading Octopi ID or the bill_of_lading number

Validations:

  • Must be a String
shipping_line
optional

Filter appointments associated with a shipping line. You can pass the shipping line Octopi ID or the shiping line’s name

Validations:

  • Must be a String
status
optional

Filter appointments for the given status

Validations:

  • Must be one of: pending, completed, cancelled.
booking
optional

Filter appointments associated with a booking. You can pass the booking Octopi ID or the booking number

Validations:

  • Must be a String
purpose
optional

Filter appointments for the provided purpose type

Validations:

  • Must be one of: drop_off, pick_up.
delivery_order
optional

Filter appointments associated with a delivery order. You can pass the delivery orde Octopi ID or the delivery orde number

Validations:

  • Must be a String
truck_driver
optional

Filter appointments associated with a truck driver. You can pass the truck driver Octopi ID or the truck driver’s license number

Validations:

  • Must be a String
page
optional

Specify which page of results to fetch. This value defaults to 1.

Validations:

  • Must be a Integer
per
optional

The number of appointments to be displayed. This value defaults to 10 and accepts a maximum of 100.

Validations:

  • Must be a Integer
>>>

POST /api/v1/appointments

Creates a new appointment.

Supported Formats

json

Errors

Code Description
404 Not found.
422 Unprocessable Entity.
500 Internal Server Error.

Examples

curl --location --request POST 'https://app.octopi.co/api/v1/appointments'     --header 'Authorization: Bearer token_value'     --header 'Content-Type: application/json'     --data-raw '{
  "appointment_date_time": "2023-08-21T07:00:00Z",
  "appointment_number": "APPT1234",
  "truck_license": "TN01CH0010",
  "truck_driver": "LIDEW9784FY",
  "trucking_company": "TruckingCo1",
  "comment": "Pick Up Cargo",
  "purposes": [
    {
      "purpose_type": "pick_up",
      "cargo":{
        "cargo_type": "container",
        "container_number": "CMAU2100446",
        "container_status": "full",
        "container_usage": "export"
      },
      "booking": "RUNNINGBOOKING"
    }
  ]
}'

{
  "appointment_number": "APPT1234",
  "appointment_slot_id": 1078,
  "appointment_date": "2023-08-21",
  "appointment_timings": "12:00 PM - 01:00 PM",
  "status": "Pending",
  "truck": "TN01CH0010",
  "truck_driver": null,
  "truck_driver_license_number": null,
  "trucking_company": "TruckingCo1",
  "truck_visit": null,
  "comment": "Pick Up Cargo",
  "reschedule_reason": null,
  "purposes": [
    {
      "purpose_type": "pick_up",
      "cargo_type": "container",
      "cargo_status": "full",
      "cargo": "CMAU2100446",
      "container_usage": "export",
      "booking": "RUNNINGBOOKING",
      "bill_of_lading": null,
      "delivery_order": null
    }
  ]
}

Params

Param name Description
appointment_slot_id
optional

Specify the appointment slot to which you want to create the appointment. Either appointment_slot_id or appointment_date_time is mandatory for creating an appointment.

Validations:

  • Must be a Integer
appointment_date_time
optional

The date and time at which you want to book the appointment for, in ISO 8601 format (Eg 2023-08-18T14:00:00Z) in UTC. Either appointment_date_time or appointment_slot_id is mandatory for creating an appointment.

Validations:

  • Must be a String
terminal
optional

The name of the terminal to which you want to create the appointment. Terminal is mandatory if there are multiple active terminals present for your organization and you are passing the appointment_date_time instead of appointment_slot_id.

Validations:

  • Must be a String
appointment_number
optional

Unique appointment number. Should be at least 4 characters. Octopi will auto-generate one if not provided.

Validations:

  • Must be a String
truck_license
required

Truck’s license plate number.

Validations:

  • Must be a String
truck_driver_id
optional

Truck driver ID. If this parameter is present, the truck_driver_license parameter will be ignored.

Validations:

  • Must be a String
truck_driver_license
optional

Truck driver’s license number. If the truck_driver_id parameter is present, this will be ignored.

Validations:

  • Must be a String
trucking_company
optional

The trucking company for this appointment. If a truck is present, then the trucking company in this parameter must match it. Similarly, if a truck driver is present, the driver’s company must match this trucking company.

Validations:

  • Must be a String
comment
optional

Comments for this appointment.

Validations:

  • Must be a String
purposes
optional

Truck visit’s purposes (multiple purposes allowed).

Validations:

  • Must be an Array of nested elements
purposes[purpose_type]
required

Purpose type.

Validations:

  • Must be one of: drop_off, pick_up.
purposes[cargo]
optional

Cargo details

Validations:

  • Must be a Hash
purposes[cargo][cargo_type]
required

Type of Cargo.

Validations:

  • Must be one of: chassis, container, general_cargo.
purposes[cargo][container_number]
optional

Container number. Required if cargo_type is ‘container’ and if the purpose is not for pick-up empty.

Validations:

  • Must be a String
purposes[cargo][container_type]
optional

Type of Container (eg 20DV). Required when creating a new container.

Validations:

  • Must be a String
purposes[cargo][container_status]
required

Status of container. Required if cargo_type is ‘container’.

Validations:

  • Must be one of: empty, full.
purposes[cargo][chassis_number]
optional

Active Chassis number. Required if cargo_type is ‘chassis’.

Validations:

  • Must be a String
purposes[cargo][shipping_line]
optional

Shipping line code. Required when creating a new container if the purpose is not for pick-up empty.

Validations:

  • Must be a String
purposes[cargo][goods]
optional

Goods description.

Validations:

  • Must be a String
purposes[cargo][container_usage]
optional

The container’s usage.

Validations:

  • Must be one of: export, import, unknown.
purposes[booking]
optional

A valid booking number to drop off a full container or pick up an empty.

Validations:

  • Must be a String
purposes[bill_of_lading]
optional

A valid Bill of Lading number to pick up a full container if your organization validates BOLs.

Validations:

  • Must be a String
purposes[delivery_order]
optional

A valid delivery order number to pick up general cargo

Validations:

  • Must be a String
>>>

GET /api/v1/appointments/:appointment_number

Returns information about a specific appointment.

Supported Formats

json

Errors

Code Description
404 Not found.
422 Unprocessable Entity.
500 Internal Server Error.

Examples

curl "https://app.octopi.co/api/v1/appointments/OCTOAPPT129903" -X GET -H "Accept: application/json" -H "Content-Type: application/json" -H "Authorization: Token token=ADD TOKEN HERE"'

{
  "appointment_number": "OCTOAPPT129903",
  "appointment_slot_id": 299,
  "appointment_date": "2023-06-02",
  "appointment_timings": "06:30 PM - 07:30 PM",
  "status": "Completed",
  "truck": "TN01CH0007",
  "truck_driver": {
    "id": 1234,
    "fullname": "John Doe",
    "license_number": "N/A",
    "twic": "",
    "number": "633353",
    "active": true,
    "date_of_birth": null,
    "telephone_number": null,
    "email": null,
    "remarks": null,
    "trucking_company": "FAST DELIVERIES, INC",
    "allowed_until": null,
    "created_at": "2017-09-15T15:47:12Z",
    "updated_at": "2023-09-15T15:47:12Z"
  },
  "truck_visit": 24,
  "comment": "",
  "reschedule_reason": null,
  "purposes": [
    {
      "purpose_type": "pick_up",
      "cargo_type": "container",
      "cargo_status": "full",
      "cargo": "ABCZ120E127",
      "container_usage": "export",
      "booking": null,
      "bill_of_lading": null,
      "delivery_order": null
    },
    {
      "purpose_type": "drop_off",
      "cargo_type": "container",
      "cargo_status": "full",
      "cargo": "ABCZ120E385",
      "container_usage": "export",
      "booking": "RUNNINGBOOKING",
      "bill_of_lading": null,
      "delivery_order": null
    }
  ]
}

Params

Param name Description
appointment_number
required

The Appointment’s number.

Validations:

  • Must be a String
>>>

PUT /api/v1/appointments/:appointment_number

Updates the fields of an existing appointment and/or reschedule an appointment.

Supported Formats

json

Errors

Code Description
404 Not found.
422 Unprocessable Entity.
500 Internal Server Error.

Examples

curl --location --request PUT 'https://app.octopi.co/api/v1/appointments/OCTOAPPT1108301'     --header 'Authorization: Bearer token_value'     --header 'Content-Type: application/json'     --data-raw '{
  "appointment_date_time": "2023-08-24T09:30:00Z",
  "terminal": "Main Terminal",
  "reschedule_reason": "Late Arrival.",
  "truck_driver_license": "LIDEW9784FY",
  "comment": "Rescheduled appointment due to delay, changed truck driver, and updated container.",
  "purposes": [
    {
      "purpose_type": "drop_off",
      "cargo": {
        "cargo_type": "container",
        "container_number": "CMAU2101273",
        "container_status": "full"
      },
      "booking": "RUNNINGBOOKING",
      "delivery_order": "dol"
    }
  ]
}'

{
  "appointment_number": "OCTOAPPT1108602",
  "appointment_slot_id": 1096,
  "appointment_date": "2023-08-24",
  "appointment_timings": "03:00 PM - 04:00 PM",
  "status": "Pending",
  "truck": "TN01CH0010",
  "truck_driver": {
    "id": 1234,
    "fullname": "John Doe",
    "license_number": "LIDEW9784FY",
    "twic": "",
    "number": "633353",
    "active": true,
    "date_of_birth": null,
    "telephone_number": null,
    "email": null,
    "remarks": null,
    "trucking_company": "FAST DELIVERIES, INC",
    "allowed_until": null,
    "created_at": "2017-09-15T15:47:12Z",
    "updated_at": "2023-09-15T15:47:12Z"
  },
  "trucking_company": "TruckingCo1",
  "truck_visit": null,
  "comment": "Rescheduled appointment due to delay, changed truck driver, and updated container.",
  "reschedule_reason": "Late Arrival.",
  "purposes": [
    {
      "purpose_type": "drop_off",
      "cargo_type": "container",
      "cargo_status": "full",
      "cargo": "CMAU2101273",
      "container_usage": null,
      "booking": "RUNNINGBOOKING",
      "bill_of_lading": null,
      "delivery_order": "dol"
    }
  ]
}

Params

Param name Description
appointment_number
required

The appointment’s number.

Validations:

  • Must be a String
appointment_slot_id
optional

Specify the new appointment slot to which you want to reschedule the appointment to. Either appointment_slot_id or appointment_date_time is mandatory for rescheduling an appointment.

Validations:

  • Must be a Integer
appointment_date_time
optional

The date and time at which you want to reschedule the appointment for, in ISO 8601 format (Eg 2023-08-18T14:00:00Z) in UTC. Either appointment_date_time or appointment_slot_id is mandatory for rescheduling an appointment.

Validations:

  • Must be a String
terminal
optional

The name of the terminal to which you want to reschedule the appointment. Terminal is mandatory if there are multiple active terminals present for your organization and you are passing the appointment_date_time instead of appointment_slot_id.

Validations:

  • Must be a String
reschedule_reason
optional

The reason for rescheduling the appointment. Required if you want to reschedule the appointment.

Validations:

  • Must be a String
truck_license
optional

Truck’s license plate number.

Validations:

  • Must be a String
truck_driver_id
optional

Truck driver ID. If this parameter is present, the truck_driver_license parameter will be ignored.

Validations:

  • Must be a String
truck_driver_license
optional

Truck driver’s license number. If the truck_driver_id parameter is present, this will be ignored.

Validations:

  • Must be a String
trucking_company
optional

The trucking company for this appointment. If a truck is present, then the trucking company in this parameter must match it. Similarly, if a truck driver is present, the driver’s company must match this trucking company.

Validations:

  • Must be a String
comment
optional

Comments for this appointment.

Validations:

  • Must be a String
purposes
optional

Truck visit’s purposes (multiple purposes allowed). The purposes provided in this API will override the existing purposes in that appointment.

Validations:

  • Must be an Array of nested elements
purposes[cargo]
optional

Cargo details

Validations:

  • Must be a Hash
purposes[cargo][purpose_type]
required

Purpose type.

Validations:

  • Must be one of: drop_off, pick_up.
purposes[cargo][cargo_type]
required

Type of Cargo.

Validations:

  • Must be one of: chassis, container, general_cargo.
purposes[cargo][container_number]
optional

Container number. Required if cargo_type is ‘container’ and if the purpose is not for pick-up empty.

Validations:

  • Must be a String
purposes[cargo][container_type]
optional

Type of Container (eg 20DV). Required when creating a new container.

Validations:

  • Must be a String
purposes[cargo][container_status]
required

Status of container. Required if cargo_type is ‘container’.

Validations:

  • Must be one of: empty, full.
purposes[cargo][chassis_number]
optional

Active Chassis number. Required if cargo_type is ‘chassis’.

Validations:

  • Must be a String
purposes[cargo][shipping_line]
optional

Shipping line code. Required when creating a new container if the purpose is not for pick-up empty.

Validations:

  • Must be a String
purposes[cargo][goods]
optional

Goods description.

Validations:

  • Must be a String
purposes[cargo][container_usage]
optional

The container’s usage.

Validations:

  • Must be one of: export, import, unknown.
purposes[booking]
optional

A valid booking number to drop off a full container or pick up an empty.

Validations:

  • Must be a String
purposes[bill_of_lading]
optional

A valid Bill of Lading number to pick up a full container if your organization validates BOLs.

Validations:

  • Must be a String
purposes[delivery_order]
optional

A valid delivery order number to pick up general cargo

Validations:

  • Must be a String
>>>

PUT /api/v1/appointments/:appointment_number/cancel

Cancels the appointment

Supported Formats

json

Errors

Code Description
404 Not found.
422 Unprocessable Entity.
500 Internal Server Error.

Examples

curl --location --request PUT 'https://app.octopi.co/api/v1/appointments/OCTOAPPT158409/cancel'   --header 'Authorization: Bearer token_value'   --header 'Content-Type: application/json'   --data-raw '{
  "cancellation_reason": "Cancellation from client side"
  }'

{
  "appointment_number": "OCTOAPPT158409",
  "appointment_slot_id": 584,
  "appointment_date": "2023-06-26",
  "appointment_timings": "03:00 PM - 04:00 PM",
  "status": "Cancelled",
  "truck": "TN01AN1982",
  "trucking_company": null,
  "truck_visit": null,
  "comment": null,
  "reschedule_reason": null,
  "cancelled_at": "2023-08-21T13:31:56.191+05:30",
  "cancelled_by": "System",
  "cancellation_reason": "Cancellation from client side",
  "purposes": []
}

Params

Param name Description
appointment_number
required

The appointment’s number

Validations:

  • Must be a String
cancellation_reason
required

The reason for cancelling the appointment

Validations:

  • Must be a String
>>>

GET /api/v1/appointments/appointment_slots

Returns all the appointment slots with availablity for a given date.

Supported Formats

json

Errors

Code Description
404 Not found.
422 Unprocessable Entity.
500 Internal Server Error.

Examples

curl --location --request GET 'https://app.octopi.co/api/v1/appointments/appointment_slots'     --header 'Authorization: Token token==ADD TOKEN HERE'     --header 'Content-Type: application/json'     --data-raw '{
  "appointment_date": "2023-08-21"
}'

{
  "appointment_slots": [
    {
      "appointment_slot_id": 1098,
      "appointment_date": "2023-08-21",
      "slot_timings": "04:00 PM - 05:00 PM",
      "terminal": "Main Terminal",
      "overall_capacity": 10,
      "available_slots": 3
    },
    {
      "appointment_slot_id": 1120,
      "appointment_date": "2023-08-21",
      "slot_timings": "05:00 PM - 06:00 PM",
      "terminal": "Main Terminal",
      "overall_capacity": 10,
      "available_slots": 5
    }
  ]
}

Params

Param name Description
appointment_date
required

Date for which you want the appointment slot details for. Must be formatted as YYYY-MM-DD.

Validations:

  • Must be a String
terminal
optional

The name of the terminal for which you want the appointment slots for. Terminal is mandatory if there are multiple active terminals present for your organization.

Validations:

  • Must be a String