WTNcloud REST API

Authentication

All API requests require a Bearer token in the Authorization header. Your API key is available on the Integrations page in your dashboard (Business plan only).

Authorization: Bearer YOUR_API_KEY

Keep your API key secret. Do not expose it in client-side code or public repositories.

Base URL

https://wtncloud.co.uk/api/external

Create one or more waste transfer notes in bulk. Each WTN is linked to a customer (matched by name and address, or created automatically). Optionally assign to a driver by email.

Request Body

Send a JSON object with a wtns array (1–100 items).

Example Request

curl -X POST https://wtncloud.co.uk/api/external/wtn/create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "wtns": [
      {
        "name": "Acme Construction Ltd",
        "address": "12 High Street, Bristol, BS1 2AB",
        "email": "[email protected]",
        "driverEmail": "[email protected]",
        "ewcCode": "17 01 01",
        "wasteDescription": "Concrete rubble",
        "quantity": 500,
        "unit": "kg",
        "containmentType": "Skip",
        "saveCustomer": true
      }
    ]
  }'

Response

{
  "created": [
    {
      "wtnReference": "WTN-00042",
      "wtnId": "a1b2c3d4e5f6...",
      "driverEmail": "[email protected]",
      "status": "ASSIGNED"
    }
  ]
}

Status will be "ASSIGNED" if a matching active driver was found, or "DRAFT" if no driver was specified or matched.

Check the status of your waste transfer notes. Query by WTN reference numbers or fetch all WTNs created since a given date.

Query Parameters

Provide either references or since, not both.

Example Request

curl "https://wtncloud.co.uk/api/external/wtn/status?references=WTN-00042" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "wtns": [
    {
      "wtnReference": "WTN-00042",
      "wtnId": "a1b2c3d4e5f6...",
      "status": "COMPLETED",
      "assignmentStatus": "COMPLETED",
      "driverName": "John Smith",
      "driverEmail": "[email protected]",
      "pdfUrl": true,
      "createdAt": "2026-04-15T10:30:00.000Z",
      "updatedAt": "2026-04-15T14:22:00.000Z"
    }
  ]
}

HWCN endpoints

Hazardous Waste Consignment Notes (HWCNs) for England (SI 2005/894) and Wales (WSI 2005/1806). The endpoints follow the same shape as the WTN ones above — Bearer-token auth, bulk envelope, ApiLog tracking — but differ in two important ways:

• Drafts are free. POST /hwcn/create lands rows as DRAFT with no charge. The free-WTN quota / PAYG balance is only touched when a dashboard user (or driver app) signs Part D and completes the note. This matches the dashboard HWCN flow — see the FAQ on /tools/hwcn-generator.
• Country-specific format checks. Each item is validated against the same Schedule 4 rules the dashboard form applies — England rejects premises codes (abolished 2016), Wales requires either a registered NRW premises code or theEXEMPT sentinel, SIC 2003 only accepted on Welsh notes, etc.
• Scotland and Northern Ireland aren't supported via the API today. Those use regulator-issued consignment codes (SEPA, NIEA) that the producer can't generate locally.

Bulk-create HWCN drafts. Each item gets a unique producer-generated consignment code on creation; the row stays in DRAFT until an operator completes Part D from the dashboard.No billing on this endpoint.

Request Body

Send a JSON object with an hwcns array (1–100 items). Each item is the same Parts A–C shape the dashboard form collects, minus the signed declaration (which is added when the operator completes the draft).

Example Request

curl -X POST https://wtncloud.co.uk/api/external/hwcn/create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "hwcns": [
      {
        "country": "england",
        "consignor": {
          "companyName": "Acme Waste Ltd",
          "contactName": "Jane Operator",
          "address": { "line1": "1 High Street", "city": "London", "postcode": "SW1A 1AA" },
          "email": "[email protected]",
          "sicCode": "38120",
          "sicVersion": "SIC_2007"
        },
        "consignee": {
          "companyName": "Disposal Site PLC",
          "address": { "line1": "10 Industrial Way", "city": "Reading", "postcode": "RG1 1AA" },
          "permitOrLicenceNumber": "EPR/AB1234CD",
          "operatesUnderExemption": false
        },
        "waste": {
          "processGivingRiseToWaste": "Vehicle workshop oil change",
          "description": "Used engine oil",
          "ewcCode": "13 02 05*",
          "physicalForm": "liquid",
          "quantityKg": 200,
          "hpCodes": ["HP3", "HP14"],
          "containerType": "drum",
          "containerCount": 1
        },
        "carrier": {
          "companyName": "Hauliers Ltd",
          "address": { "line1": "Yard 4", "city": "Slough", "postcode": "SL1 1AA" },
          "registrationNumber": "CB/AB1234",
          "vehicleRegistration": "AB12 CDE",
          "collectionDate": "2026-04-30",
          "carrierCertificateAccepted": true
        }
      }
    ]
  }'

Response

{
  "created": [
    {
      "consignmentCode": "ACMEWA/AB23F",
      "hwcnId": "a1b2c3d4e5f6...",
      "status": "DRAFT",
      "customerId": null
    }
  ]
}

Code format. England returns XXXXXX/YYYYY (six chars from your company name, padded with Q; five-char suffix). Wales registered: AAAnnn/XXXXX. Wales exempt: EXE/XXXXXXXX. Codes use a confusable-free alphabet (no 0/O/1/I/L/5/S) so they read aloud cleanly.

customerId is populated when we find an existing saved customer matching the consignor by name+address (case-insensitive) or by email. We never overwrite saved customer details from API payloads.

Look up HWCNs by consignment code or fetch all HWCNs created since a given date. Soft-deleted rows are excluded.

Query Parameters

Provide either references or since, not both.

Example Request

curl "https://wtncloud.co.uk/api/external/hwcn/status?references=ACMEWA%2FAB23F" \
  -H "Authorization: Bearer YOUR_API_KEY"

Note the URL-encoded slash (%2F) inside the consignment code — every HWCN code contains a slash separator.

Response

{
  "hwcns": [
    {
      "consignmentCode": "ACMEWA/AB23F",
      "hwcnId": "a1b2c3d4e5f6...",
      "jurisdiction": "england",
      "status": "COMPLETED",
      "pdfUrl": true,
      "completedAt": "2026-04-30T10:15:00.000Z",
      "createdAt": "2026-04-26T22:00:00.000Z",
      "updatedAt": "2026-04-30T10:15:00.000Z"
    }
  ]
}

status is one of DRAFT, COMPLETED, CANCELLED.pdfUrl is a boolean indicating whether a PDF has been generated for this HWCN; the actual PDF is only fetchable from the dashboard (a public download URL is intentionally not exposed via this API).

Error Codes

Rate Limits

API requests are rate limited to prevent abuse. Each request can include up to 100 WTNs in a single batch. If you need higher limits, contact us at [email protected].