REST API · v1

WasteBolt API

Create and manage Waste Transfer Notes programmatically. Integrate WasteBolt into your weighbridge software, ERP, or custom workflow.

4 Endpoints

API Key Auth

60 req/min

HTTPS only

Base URL

https://vfhjhirnyulkvkmukpbj.supabase.co/functions/v1

Authentication

All API requests require an x-api-key header containing your WasteBolt API key. Keys are generated from your account under Settings → Integrations. Keys are prefixed with wbsync_.

Example request header

x-api-key: wbsync_AbCdEfGhIjKlMnOpQrStUvWxYz012345

Keep your API key secret. Do not expose it in client-side code or public repositories. If a key is compromised, disable it immediately from the Integrations page and create a new one.

Rate Limiting

Each API key is limited to 60 requests per minute. Limits are tracked per key using a fixed 1-minute window. All responses include rate limit headers so you can monitor usage.

X-RateLimit-Limit

Max requests per window

60

X-RateLimit-Remaining

Requests left this window

47

X-RateLimit-Reset

Window reset timestamp (ISO)

2026-03-02T09:02:00Z

When the limit is exceeded you will receive a 429 response with a Retry-After header indicating seconds until reset.

429 Response

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 2026-03-02T09:02:00.000Z
Retry-After: 23

{
  "success": false,
  "error": "Rate limit exceeded. 60 requests per minute allowed. Retry in 23s.",
  "code": "RATE_LIMIT_EXCEEDED"
}

Error Codes

All error responses share the same shape. The code field is stable and safe to use in your error handling logic.

Error response shape

{
  "success": false,
  "error": "Human readable message",
  "code": "MACHINE_READABLE_CODE"
}

Code	HTTP	Description
`NO_API_KEY`	401	x-api-key header missing from request
`INVALID_KEY_FORMAT`	401	Key does not start with wbsync_
`INVALID_KEY`	401	Key not found in WasteBolt
`KEY_DISABLED`	401	Key has been manually disabled
`KEY_EXPIRED`	401	Key has passed its expiry date
`SUBSCRIPTION_INACTIVE`	403	WasteBolt subscription has expired
`RATE_LIMIT_EXCEEDED`	429	60 req/min limit reached — see Retry-After header
`VALIDATION_ERROR`	422	Required field missing or invalid
`INVALID_STATUS`	422	Status value not allowed via API
`NOT_FOUND`	404	WTN not found or not accessible by this key
`WTN_LOCKED`	409	WTN is signed and cannot be updated
`INVALID_JSON`	400	Request body is not valid JSON
`DATABASE_ERROR`	500	Internal database error — retry after a moment

POST/create-wtn-api

Create a Waste Transfer Note

Creates a new WTN under your account. Returns the full note including the auto-generated note number.

Required Fields

producer_details.namestringName of the waste producer

producer_details.addressstringFull address of the producer

waste_details.ewc_codestringEWC code e.g. "20 03 01"

waste_details.descriptionstringDescription of the waste

waste_details.quantitystringQuantity e.g. "5 tonnes"

transfer_details.transfer_datestringISO date e.g. "2026-03-02"

Optional Fields

carrier_detailsobjectCarrier name, address, vehicle reg

consignee_detailsobjectReceiving site name, address, permit number

note_typestring"standard" (default) | "hazardous" | "season_ticket"

statusstring"draft" (default) | "complete"

curl -X POST https://vfhjhirnyulkvkmukpbj.supabase.co/functions/v1/create-wtn-api \
  -H "x-api-key: wbsync_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "producer_details": {
      "name": "Acme Waste Ltd",
      "address": "123 Industrial Estate, Birmingham, B1 1AA",
      "registration_number": "123456"
    },
    "carrier_details": {
      "name": "Fast Carriers Ltd",
      "address": "456 Transport Road, Coventry, CV1 2BB",
      "vehicle_reg": "AB12 CDE"
    },
    "consignee_details": {
      "name": "Green Recycling Ltd",
      "address": "789 Waste Park, Wolverhampton, WV1 3CC",
      "permit_number": "EPR/AB1234CD/A001"
    },
    "waste_details": {
      "ewc_code": "20 03 01",
      "description": "Mixed municipal waste",
      "quantity": "5 tonnes",
      "quantity_unit": "tonnes"
    },
    "transfer_details": {
      "transfer_date": "2026-03-02"
    },
    "note_type": "standard",
    "status": "draft"
  }'

201 Response

{
  "success": true,
  "message": "Waste Transfer Note created successfully",
  "data": {
    "id": 1042,
    "note_number": "ACM-1042",
    "status": "draft",
    "note_type": "standard",
    "created_at": "2026-03-02T09:15:32.000Z",
    "producer_details": { ... },
    "carrier_details": { ... },
    "consignee_details": { ... },
    "waste_details": { ... },
    "transfer_details": { ... }
  }
}

GET/wtn-api

List Waste Transfer Notes

Returns a paginated list of WTNs for your account, newest first. Supports filtering by status, date range, note type, DWT status, and note number search.

Query Parameters

statusstringFilter by status: draft | complete | signed

note_typestringFilter: standard | hazardous | season_ticket

dwt_statusstringFilter: pending | submitted | failed

fromdateStart date (inclusive) e.g. 2026-01-01

todateEnd date (inclusive) e.g. 2026-12-31

searchstringSearch note_number (partial match)

pageintegerPage number, default 1

limitintegerResults per page, default 20, max 100

cURL

curl "https://vfhjhirnyulkvkmukpbj.supabase.co/functions/v1/wtn-api?status=complete&from=2026-01-01&limit=20&page=1" \
  -H "x-api-key: wbsync_YOUR_KEY_HERE"

200 Response

{
  "success": true,
  "data": [ { ... }, { ... } ],
  "pagination": {
    "total": 84,
    "page": 1,
    "limit": 20,
    "total_pages": 5,
    "has_next": true,
    "has_prev": false
  },
  "filters_applied": {
    "status": "complete",
    "from": "2026-01-01"
  }
}

GET/wtn-api/:id

Get a Single WTN

Returns a single WTN by its numeric ID. Only returns WTNs belonging to your account.

idintegerThe numeric WTN ID returned when creating or listing WTNs

cURL

curl "https://vfhjhirnyulkvkmukpbj.supabase.co/functions/v1/wtn-api/1042" \
  -H "x-api-key: wbsync_YOUR_KEY_HERE"

200 Response

{
  "success": true,
  "data": {
    "id": 1042,
    "note_number": "ACM-1042",
    "status": "complete",
    "note_type": "standard",
    "created_at": "2026-03-02T09:15:32.000Z",
    "dwt_status": "pending",
    "producer_details": { ... },
    "carrier_details": { ... },
    "consignee_details": { ... },
    "waste_details": { ... },
    "transfer_details": { ... }
  }
}

PATCH/wtn-api/:id

Update WTN Status

Updates the status of a WTN. Signed WTNs are locked and cannot be modified via the API.

Body Fields

statusstring"draft" | "complete" — signed WTNs return 409 WTN_LOCKED

cURL

curl -X PATCH "https://vfhjhirnyulkvkmukpbj.supabase.co/functions/v1/wtn-api/1042" \
  -H "x-api-key: wbsync_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{"status": "complete"}'

200 Response

{
  "success": true,
  "message": "WTN updated successfully",
  "data": {
    "id": 1042,
    "note_number": "ACM-1042",
    "status": "complete",
    ...
  }
}

WasteBolt API

Authentication

Rate Limiting

Error Codes

Create a Waste Transfer Note

Required Fields

Optional Fields

List Waste Transfer Notes

Query Parameters

Get a Single WTN

Update WTN Status

Body Fields

Ready to integrate?