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/
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": "example@gmail.com",
  "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": "tim.cook@test.com",
  "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": "example@gmail.com",
    "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
}