post

/partner/jobs

Create a new Job in a pending state.

This job is not live yet and does not show on our system, nor will be processed by anyone until it is submitted by you (see the Submit a Job session).

Billing identifier

As an option for a partner to create jobs on behalf of another venue, Quiqup supports the billing identifier. This is useful in cases where a partner is an aggregator or a marketplace and want to have their clients on the final customer’s bill.

For this to be used, you have to:

  1. Get in contact with us so we can create an unique identifier to be used by you to create jobs on behalf of another venue;
  2. Pass the field billing_identifier on the root of the request giving the new billing identifier as the its value. Example:
{
  "billing_identifier": "another-venue-uid",
  "pickups": [...],
  "dropoffs": [...]
}

Contact phone

The contact phone in the pickups and dropoffs must follow the MSISDN format, which means that it has to include the international identifier + the national code + the customer’s number. It can include the + signal at the beginning but it is not mandatory. For example, both +971599999998 and 971599999998 are valid.

Courier app

As an example of how your data is going to be seen by the courier, consider the following payload for the waypoints (pickup and dropoff):

{
  "needs_return": true,
  "transport_mode": "scooter",
  "pickups": [
    {
      "contact_name": "Rafael Soares",
      "contact_phone": "+971599999999",
      "partner_order_id": "XYZ123456",
			"notes": "Go directly to the kitchen on the first floor",
      "location": {
        "address1": "1st Road",
        "address2": "104G",
        "coords": [
          55.1631158,
          25.0559987
        ],
        "country":"UAE",
        "town":"Dubai"
      },
      "items": [
        {
          "name": "Chelo Kebab",
          "quantity": 2
        },
        {
          "name": "Slice of Margherita pizza",
          "quantity": 3
        }
      ]
    }
  ],
  "dropoffs": [
    {
      "contact_name": "Tim Linssen",
      "contact_phone": "+971599999998",
			"payment_mode": "pre_paid",
      "payment_amount": 0,
      "location": {
        "address1": "Emirattes Hills",
        "address2": "1006 B",
        "coords": [
          55.1599898,
          25.0616772
        ],
        "country":"UAE",
        "town":"Dubai"
      }
    }
  ]
}

It will result in the data being displayed to the courier as follows:

Locations

Within each waypoint (pickup and dropoff) there is the location field. You can choose one of the following options to determine the specific location:

By Postcode

If you have the postcode of the place, you can give the address1, address2 (optional) and postcode fields, and this will be enough for us to determine the location.

By Full Address

In case there is no postcode to give, you can give all the other informations: address1, address2 (optional), town and country. Eg:

  "address1":"Blue bay tower, office 1, Al Abraaj Street Steigenberger hotel",
  "country":"UAE",
  "town":"Dubai"

By Coordinates

The most accurate way to give a location is by sending the coordinates. In case you have it, you can give it in the following array format: [longitude, latitude], along with the address1 field, so we can present it to the courier. As an example:

  "address1": "1st Road",
  "address2": "104G",
  "coords": [
    55.1631158, # longitude
    25.0559987  # latitude
  ]

Partner Order ID

Most of the times, the venue checks the order’s items along with the courier by using their own identifier. For example, when a courier goes to the venue to get a meal, they will ask for the order XYZ-123, being this order id something that the venue can recognize.

For this to be possible, you have to pass the field partner_order_id: "PARTNER-ORDER-ID-HERE" in the pickup field. Example:

{
  "pickups": [
    {
      "contact_name": "Rafael Soares",
      "contact_phone": "+971599999999",
      "partner_order_id": "XYZ-123-456", # this ID can be anything
			... # other fields here
		}
	],
	"dropoffs": [...]
}

Payment mode

This is going to define how the courier is going to charge the customer at the drop-off waypoint. Which means you must set this value within the dropoff object.

If the payment_mode is set as paid_on_delivery, the courier is going to require a payment before deliverying the goods. In this case, the payment_amount value must be set as bigger than 1.0.

It the payment_mode is set as pre_paid, then the courier is not going to charge anything and will assume the payment has been made already. In this case, the payment_amount value must be set as 0.

In case no payment_mode is provided, the default value will be pre_paid with payment_amount as 0.

Return waypoint

If you need the courier to return something to the pickup location after the drop-off waypoint, you can set the field needs_return: true. If not, you can just ignore this field.

Scheduled jobs

It is also possible to create a job now to be delivered at a specific time in the future. In this case you have to give two params on the root of the request: "kind": "partner_scheduled" and scheduled_for containing the datetime in iso8601 format. Example:

{
  "kind": "partner_scheduled",
  "scheduled_for": "2019-10-08T16:50:00.816Z",
  "pickups": [...],
  "dropoffs": [...]
}

Tracking URLs and Tokens

After creating a job, every waypoint will be assigned to a tracking token, and a tracking URL will be generated using them.

These can be sent to your customers so that they can use our Track App to follow their delivery. In order to make it happen, you have to send a field share_tracking: true within the waypoint you want to enable this. For example, if you want the final customer to receive the tracking notification, you can send a dropoff like this:

"dropoffs": [
    {
      "contact_name": "Tim Linssen",
      "contact_phone": "+971599999998",
      "share_tracking": true,
      "location": {
        "address1": "Emirattes Hills",
        "country":"UAE",
        "town":"Dubai"
      }
    }
  ]

The customer will only be able to track their own delivery. This means that the app will be disabled until the job is active and a Quiqee is going to that particular waypoint.

By default, all jobs are delivered on demand. If you want to schedule a job, you don’t need to pass any of these two fields.

Transport mode

Unless you want to set an specific transport mode, the recomendation is to not send this field, which is going to make Quiqup determine the best available option for that region.

Authorization

oauth2 - clientCredentials

Request Body

Schema
object
needs_return
boolean
transport_mode
string
billing_identifier
string
scheduled_for
string
kind
string
1 validation
pickups
array[object]
dropoffs
array[object]

Responses

When the job has been created successfully

Schema
object
transport_mode
string
allowed_transport_modes
array[string]
id
string
billing_identifier
null or string
state
string
state_updated_at
string
kind
string
scheduled_for
null or string
earliest_collection_at
string
metadata
object
courier
null
created_at
string
submitted_at
null
known_costs
object
feedback_given
boolean
estimated_costs
object
quiqee_accepted_at
null
delivery_window_minutes
null
state_transitions
object
courier_route
null
cancelled_by
null
package_detail
null
orders
array[object]
summary
null

Send a Test Request

Send requests directly from the browser (CORS must be enabled)
$$.env
1 variable not set
oauth_access_token