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