Skip to main content
This guide walks through the full happy path: validate an address, create an order, and fetch a printable label. You’ll use the test environment throughout — nothing here dispatches a real courier.

​
Prerequisites

  • An API key for the test environment
  • A locationId for the pickup location
Both are issued by your Sparqle contact. See Authentication for where the key goes, and Environments for base URLs.
The test base URL is https://staging-v2.sparqle.tech. Replace it with the live URL only once you’re ready to ship real parcels.

​
1. Check the order

Optional but recommended: validate the recipient address and serviceability before you commit. Pass your locationId in the path. 
curl -X POST https://staging-v2.sparqle.tech/orders/check/ABC123 \
  -H "api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "deliveryAddress": {
      "street": "Gustav Mahlerlaan",
      "houseNumber": "320",
      "postalCode": "1082 ME",
      "city": "Amsterdam",
      "countryCode": "NL"
    }
  }'

​
2. Create the order

curl -X POST https://staging-v2.sparqle.tech/orders \
  -H "api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "locationId": "ABC123",
    "orderRef": "PADE3JWEA",
    "deliveryName": "Jane Doe",
    "deliveryEmail": "[email protected]",
    "deliveryPhone": "+31612345678",
    "deliveryAddress": {
      "street": "Gustav Mahlerlaan",
      "houseNumber": "320",
      "postalCode": "1082 ME",
      "city": "Amsterdam",
      "countryCode": "NL"
    }
  }'
A successful response returns the created order, including the fields you’ll need next: 
{
  "orderId": "SPQ-10293",
  "orderRef": "PADE3JWEA",
  "status": "draft",
  "barcode": "3STBXX123456789",
  "trackingUrl": "https://tracking.sparqle.com/barcode/3STBXX123456789"
}
orderRef is your reference for the order. Keep it stable and unique so you can reconcile webhooks and labels against your own system.

​
3. Fetch the label

Use the orderId from the previous step. The label comes back as a base64-encoded PDF. 
curl https://staging-v2.sparqle.tech/orders/label/SPQ-10293 \
  -H "api-key: YOUR_API_KEY"
Decode the base64 string to a .pdf and print it. For multi-parcel shipments, fetch every label in a bundle at once with GET /orders/label/bundle/{orderBundleId}. See Labels.

​
4. Track the delivery

As the parcel moves, Sparqle sends webhooks for each status change, or you can poll the order. Statuses run from draft through to completed — see the order lifecycle.

​
Next steps

Authentication

Keys, headers, and test vs. live.

Order lifecycle

Every status and what it means.

Webhooks

Receive status updates as they happen.

API reference

Full endpoint and schema details.