API Reference

Getting Started with the Sparqle API

This Documentation page will help you get started with the Sparqle API.

Authentication

All API requests processed through the Sparqle platform are authenticated with an API credential linked to your company account, which can be found in the Sparqle Dashboard > Settings page.

Authenticate your request by sending an API key in the api-key HTTP request header.

POST /orders
Host: https://v2.sparqle.com/1
Content-Type: application/json
api-key: YOUR_API_KEY

Rate limits

The Sparqle API has a general rate limit of 120 calls per minute.


Orders

Create delivery orders directly on the Sparqle API.

{
  "orderRef": "12345",
  "deliveryDate": "2023-11-27",
  "name": "Package",
  "description": "ABC",
  "sizeWidth": "2 cm",
  "sizeLength": "15 cm",
  "sizeHeight": "20 cm",
  "weight": "2 kg",
  "deliveryName": "Sparqle HQ",
  "deliveryEmail": "[email protected]",
  "deliveryPhone": "+31932780701",
  "deliveryAddress": "IJsbaanpad 2, 1076 CV Amsterdam",
  "deliveryTimeStart": "15:00",
  "deliveryTimeEnd": "21:00",
  "locationId": "8ABC9NJF7O",
  "load": 1,
  "deliveryNote": "it's at the second floor"
}

The locationId is a reference to your location's address. Please contact Support to request your location id.

Labels

For your created order you can retrieve a label with a GET to /orders/label/{orderId}?orientation=portrait. The result is a base64 encoded value that can be converted to a PDF. For each of the collo there's a separate page in the PDF. Specify query parameter orientation with value portrait to get the labels in portrait mode.

{
    "label": "JVBERi0xLjM....lRU9GCg=="
}

Returns

Create pickup only orders (returns).

{
  "name": "Return",
  "description": "Pickup",
  "orderRef": "Return-12345",
  "deliveryDate": "2024-01-01",
  "pickupEmail": "[email protected]",
  "pickupPhone": "+31612345678",
  "pickupNote": "This is a pickup note.",
  "pickupName": "Tim",
  "pickupAddress": "Leidseplein 25, 1017PS Amsterdam",
  "locationId": "S1GXHIQM3PL",
  "isReturn": true
}

Webhooks

Sparqle sends webhooks for every order update. In each webhook the body contains the full order object. Provide your webhook url and preferred events to our support team.

🚧

The following statuses are supported:

ERROR, DRAFT, UNASSIGNED, ASSIGNED, PICKUP_ARRIVED, PICKUP_FAILED, COLLECTED, IN_TRANSIT, DELIVERY_ARRIVED, DELIVERY_FAILED, COMPLETED, REJECTED, EXPECTED, CANCELLED, RETURNED

{
    "labels": [],
    "id": 581,
    "createdAt": "2023-12-01T09:02:48.031Z",
    "updatedAt": "2023-12-01T09:02:48.031Z",
    "orderId": "AB5B6DOP2",
    "orderRef": "12345",
    "orderType": "SAME_DAY",
    "status": "DRAFT",
    "invoiceId": null,
    "invoiceLineItemId": null,
    "createdBy": null,
    "attempt": 0,
    "name": “Package",
    "description": "ABC",
    "sizeLength": "15 cm",
    "sizeWidth": "2 cm",
    "sizeHeight": "20 cm",
    "weight": "2 kg",
    "deliveryDate": "2023-11-27T00:00:00.000Z",
    "pickupName": “Rituals - Spuistraat”,
    "pickupAddress": "Spuistraat 13, 2511 BC Den Haag, Netherlands",
    "pickupAddressLat": "52.0771428",
    "pickupAddressLng": "4.3115002",
    "pickupPhone": null,
    "pickupTimeStart": "14:00",
    "pickupTimeEnd": "18:00",
    "pickupDuration": 2,
    "pickupNote": null,
    "deliveryName": "Sparqle HQ",
    "deliveryEmail": "[email protected]",
    "deliveryAddress": "IJsbaanpad 2, 1076 CV Amsterdam",
    "deliveryAddressLat": 52.3413986,
    "deliveryAddressLng": 4.8538871,
    "deliveryPhone": "+31932780701",
    "deliveryTimeStart": "15:00",
    "deliveryTimeEnd": "21:00",
    "deliveryDuration": 2,
    "deliveryNote": null,
    "region": "Amsterdam",
    "isDispatch": false,
    "load": 1,
    "types": [],
    "pickupEta": null,
    "deliveryEta": null,
    "unscheduledReason": null,
    "packageWas": null,
    "neighbourAddress": null,
    "pods": [],
    "signature": null,
    "riderNote": null,
    "failedReason": null,
    "pickupStatus": "DRAFT",
    "deliveryStatus": "DRAFT",
    "arrivedAt": null,
    "completedAt": null,
    "failedAt": null,
    "locationId": "8ABC19NJF7O",
    "riderId": null,
    "routePlanId": null,
    "companyId": 61
}

Delivery Lifecycle

Learn about delivery statuses and how you can track them.

Draft

Default status in which an order gets created on the Sparqle platform. This is the only status an order is able to either get unassigned/assigned to a Sparqle route plan or is able to get cancelled by the merchant.

Error

This order status means something happened with the order for which Sparqle is not able to process further.

Rejected

The order is received but is not matching one of the configured delivery areas on the Sparqle platform.

Expected

Specific order status for orders with no delivery date that requires a planning step from the customer, such as choosing a delivery date and time window outside of the regular order creation flow.

Unassigned

Order status where the order is added to a Sparqle route plan but not yet assigned to a rider.

Assigned

Order status where the order is assigned to a rider on a Sparqle route plan.

Cancelled

The order is actively cancelled by either the merchant or Sparqle in case of a specific issue with the order.

Pickup Arrived

The rider arrived to the location of pickup and the order is about to get collected or pickup failed status.

Pickup Failed

The rider was not able to pick up the order at the location due to issues with/absence of the order.

Collected

The rider collected the order at location.

In Transit

The rider is on its way to the customer.

Completed

The rider completed the delivery successfully. This is a final status.

Delivery Failed

The rider failed the delivery. This may not be an end state, as there can be more delivery attempts on this order. The order will possibly move back to Draft and increment the attempts field. In case the maximum number of attempts are met, the order will move to the Cancelled status, which will be the final status.

Returned

The order has reached its maximum number of attempts and is sent back to the sender.