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://staging-v2.sparqle.tech/1
Content-Type: application/json
api-key: YOUR_API_KEY
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.
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=="
}
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, RETURN_TO_SENDER
{
"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.
![](https://files.readme.io/afd04d9-Screenshot_2024-08-14_at_18.10.57.png)
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.
Return to Sender
The order has reached its maximum number of attempts and is sent back to the sender.