EfiRoute Developer API

keyAPI keys

Keys belong to the company, not to a person, so an integration keeps working when staff change. The raw key is shown once — EfiRoute stores only a hash of it.

1. Sign in and open Settings → API.
2. Create a key, pick the scopes it needs: read, write, optimize.
3. Copy it immediately and store it as a secret in your own system.
4. Send it on every request: Authorization: Bearer efr_live_…
5. Revoke it any time; revoking does not delete the audit trail.

rocket_launchQuick start

Five calls from empty project to optimized routes. Only the last one costs anything — reading is always free.

curl -H "Authorization: Bearer efr_live_…" \
  https://api.efiroute.com/api/v1/account

curl -X POST https://api.efiroute.com/api/v1/projects \
  -H "Authorization: Bearer efr_live_…" \
  -H "Content-Type: application/json" \
  -d '{"name":"Monday deliveries","defaultStartTime":"08:00"}'

curl -X POST https://api.efiroute.com/api/v1/projects/$PID/stops \
  -H "Authorization: Bearer efr_live_…" \
  -H "Content-Type: application/json" \
  -d '{"stops":[
        {"name":"Acme Ltd","address":"Bahnhofstrasse 1, 8001 Zurich","serviceMinutes":"15 min"},
        {"name":"Beta AG","address":"Langstrasse 20, 8004 Zurich","serviceMinutes":"1:30"}
      ]}'

# Required: the optimizer skips stops without coordinates
curl -X POST https://api.efiroute.com/api/v1/projects/$PID/stops/geocode \
  -H "Authorization: Bearer efr_live_…"

curl -X POST https://api.efiroute.com/api/v1/projects/$PID/couriers \
  -H "Authorization: Bearer efr_live_…" \
  -H "Content-Type: application/json" \
  -d '{"courierId":"…","startAddress":"Depot, 8005 Zurich",
       "endAddress":"Depot, 8005 Zurich",
       "workStartTime":"08:00","workEndTime":"17:00",
       "stopDurationMinutes":10,
       "loadLimits":{"weight":800,"count":40}}'

curl -X POST https://api.efiroute.com/api/v1/projects/$PID/optimize \
  -H "Authorization: Bearer efr_live_…" \
  -H "Content-Type: application/json" -d '{}'

# 200 -> routes in the response
# 202 -> { "jobId": "…" }, poll /optimization-jobs/{jobId}
#        or subscribe to the optimization.completed webhook

apiEndpoint reference

Full request and response schemas, including every field and error code, live in the OpenAPI document. Import it into Postman or generate a typed client with openapi-generator.

https://api.efiroute.com/api/v1

report_problemErrors are predictable

Success is always { success: true, data: … }. Failure always carries a stable machine-readable code plus structured details — branch on the code, never on the message text. Validation failures list every offending field in details.issues.

{
  "success": false,
  "message": "Only projects in the \"draft\" status can be deleted. …",
  "code": "PROJECT_NOT_DRAFT",
  "details": {}
}

webhookWebhooks instead of polling

Subscribe to optimization.completed and optimization.failed. Every delivery is signed with HMAC-SHA256 over "<timestamp>.<raw body>", so a captured request cannot be replayed. Failed deliveries retry six times with backoff (1 m, 5 m, 15 m, 1 h, 3 h) and an endpoint that fails 20 times in a row is disabled automatically.

const crypto = require('crypto');

// Use the RAW request body — not the parsed object.
app.post('/efiroute/webhook',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const ts = req.get('X-EfiRoute-Timestamp');
    const sig = (req.get('X-EfiRoute-Signature') || '').replace('sha256=', '');

    // Reject replays: the timestamp is part of the signed payload.
    if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return res.sendStatus(400);

    const expected = crypto
      .createHmac('sha256', process.env.EFIROUTE_WEBHOOK_SECRET)
      .update(ts + '.' + req.body.toString('utf8'))
      .digest('hex');

    const ok = sig.length === expected.length &&
      crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
    if (!ok) return res.sendStatus(401);

    // Deliveries can repeat: key your handling on the delivery id.
    const event = JSON.parse(req.body.toString('utf8'));
    enqueue(event.id, event.event, event.data);

    res.sendStatus(200); // Acknowledge fast, do the work asynchronously.
  });

account_balance_walletWhat it costs

Reading data is free. An optimization run costs $1 per courier, taken from your monthly subscription credit first and the prepaid wallet after. A run that fails, or that produces no routes, is not charged. Stops are never metered. Rate limit: 120 requests per minute per key.