Docs › Getting started

Quickstart (5 minutes)

Sandbox key, first order, first status read.

This walkthrough takes you from nothing to a tracked order in about five minutes, using the sandbox. Sandbox orders run through a simulated lifecycle. No driver moves, and nothing is billed.

1. Get a sandbox API key

bash

curl -s https://api.trydragonfly.com/v1/signup \
  -H 'content-type: application/json' \
  -d '{
    "sandbox": true,
    "businessName": "Acme Test Kitchen",
    "contactName": "Sam Lee",
    "email": "[email protected]",
    "vertical": "catering"
  }'

The response contains your key once. Store it now.

json

{
  "data": {
    "sandbox": true,
    "status": "APPROVED",
    "merchantId": "cm…",
    "apiKey": "dfk_test_…",
    "signingSecret": "…",
    "keyPrefix": "dfk_test_3339"
  }
}

bash

export DRAGONFLY_API_KEY=dfk_test_…

2. Create an order

bash

curl -s https://api.trydragonfly.com/v1/orders \
  -H "Authorization: Bearer $DRAGONFLY_API_KEY" \
  -H 'content-type: application/json' \
  -d '{
    "externalId": "order-1001",
    "pickup":  { "address": "100 W Randolph St, Chicago, IL 60601", "contactName": "Kitchen", "contactPhone": "+13125550100" },
    "dropoff": { "address": "445 N Michigan Ave, Chicago, IL 60611", "contactName": "Reception", "contactPhone": "+13125550111",
                 "windowStart": "2026-10-09T11:30:00-05:00", "windowEnd": "2026-10-09T12:00:00-05:00" },
    "subtotalCents": 42500,
    "tipCents": 5000
  }'

json

{ "data": { "orderId": "cm…", "externalId": "order-1001", "status": "PENDING", "dropoffs": 1, "dispatchedTo": "sandbox", "trackingUrl": null, "idempotentReplay": false } }

3. Watch it move

bash

curl -s https://api.trydragonfly.com/v1/orders/order-1001 -H "Authorization: Bearer $DRAGONFLY_API_KEY"

Sandbox orders move PENDING → ASSIGNED (about 30 s) → PICKED_UP (about 90 s) → DELIVERED (about 3 minutes).

4. Get pushed updates instead of polling

bash

curl -s https://api.trydragonfly.com/v1/webhooks \
  -H "Authorization: Bearer $DRAGONFLY_API_KEY" -H 'content-type: application/json' \
  -d '{ "url": "https://your-app.example.com/dragonfly", "events": ["delivery.*"] }'

Then create another order. Your endpoint receives signed delivery.* events as the sandbox simulates the delivery. See Verifying signatures.

5. Go live

When your integration works in sandbox, follow Getting access to get a dfk_live_ key and the Go-live checklist. The API is identical; only the key changes.

← PreviousIntroduction Next →Getting access & approval

Something unclear or missing? Tell us.