WTNcloud REST API

Authentication

All API requests require a Bearer token in the Authorization header. Your API key is available on the API Settings page in your dashboard (Enterprise 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 filed under one of your saved customers — the one you name with customerId, or one matched from the name and address you send, saved for you if nothing matches (see “Matching notes to customers” below). Optionally assign to a driver by email.

Request Body

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

Matching notes to customers

Every note is filed under one of your saved customers, so a customer’s notes stay together in the dashboard, the customer portal and your reports. For each item, the first of these that finds a customer wins:

1. customerId — the saved customer with that id. An id that isn’t one of your customers refuses the whole batch with 400 CUSTOMER_NOT_FOUND (listing the ids in customerIds) and creates nothing.
2. Name and address. The name ignoring case and punctuation (Acme Ltd and ACME-LTD. are one name); the address ignoring case, spacing and punctuation, with or without the postcode on the end. So 12 High Street, Bristol, BS1 2AB finds a customer saved in the dashboard as 12 High Street, Bristol with the postcode BS1 2AB.
3. Name and postcode, when your address line has a postcode in it. The same customer with the street spelled differently (High St) is still the same customer.
4. Email, compared ignoring case.
5. Nothing matched — a new customer is saved from the item: the postcode found at the end of the address line as their postcode, and the rest of the line as their address, the way a customer added in the dashboard is saved.

The API never changes a saved customer’s name or address. When a note is filed by customerId or by name and postcode, and the name or address you sent differs from the saved one, the note records what you sent — it prints on that note’s PDF and the driver is sent there — and the saved customer stays as it was. A note matched by email alone prints the saved customer’s details.

Every item in the response carries the customerId it was filed under. Keep it against the customer in your own system and send it with their next note: matching then has nothing to guess, and a change of address on your side can’t save them a second time.

Name and postcode are treated as one customer’s identity, the same rule the dashboard uses when it offers to save a one-off customer. Two different customers with the same name at the same postcode are rare, but if you have them, send customerId to keep them apart.

Signatures

You only ever send the producer’s signature. The carrier half of a note your account raises is your own signature, which WTNcloud already holds — the one you saved under Settings → Notes, and the one the dashboard’s “Apply My Signature” button uses. It is resolved server-side from your account, so the API neither needs nor accepts a carrier signature image: nobody can upload one on your behalf.

What an item carries decides where the note lands:

• Neither field — DRAFT or ASSIGNED, unsigned, for the driver to complete on site. This is the original behaviour and is unchanged.
• transferorSignature — both halves signed, COMPLETE. The PDF is rendered and the customer is sent their copy if you have auto-send on.
• applyCarrierSignature: true on its own — carrier-signed and AWAITING_TRANSFEROR_SIGNATURE; WTNcloud emails or texts the producer a signing link, and the note completes when they sign it.

Every signature is written to the note’s immutable audit trail with how it was captured: the image you push is recorded as API (drawn in your software, attested by your key), your carrier signature as SAVED_SIGNATURE.

Two guards worth knowing before you wire this up. A producer signature over a shell — no EWC code, no description, zero quantity, no unit — is refused with a 400: the unsigned path exists for shells, and a signed note has to say what was transferred. unit is in that list for a reason. Everywhere else an omitted unit falls back to kilograms and the driver corrects it on site; on a note the producer has already signed there is no on-site correction, so a bare 4 meant as tonnes would stand as 4 kg on a duty-of-care record. For the same reason a signed note’s unit has to be one we can weigh — tonnes, kg, litres or m3, common spellings accepted — because an unrecognised one is treated as kilograms downstream, which is the same mistake in a different hat. And asking for a carrier signature your account has never saved refuses the whole batch with CARRIER_SIGNATURE_NOT_SAVED rather than creating half-signed notes.

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",
        "transferorSignature": "data:image/png;base64,iVBORw0KGgo...",
        "transferorSignerName": "Jane Doe",
        "transferorSignerCompany": "Acme Construction Ltd",
        "additionalWasteLines": [
          {
            "ewcCode": "17 04 07",
            "wasteDescription": "Mixed metals",
            "quantity": 300,
            "unit": "kg",
            "containmentType": "Skip",
            "physicalForm": "Solid",
            "numberOfContainers": 1,
            "containsPops": false
          }
        ],
        "saveCustomer": true
      }
    ]
  }'

Response

{
  "created": [
    {
      "wtnReference": "WTN-00042",
      "wtnId": "a1b2c3d4e5f6...",
      "driverEmail": "[email protected]",
      "status": "COMPLETE",
      "signatures": { "transferor": true, "carrier": true },
      "pdf": "https://wtncloud.co.uk/api/external/wtn/a1b2c3d4e5f6/pdf",
      "publicPdf": "https://wtncloud.co.uk/s/Ab3dEf7h",
      "customerId": "cmtyitafh0003c5pbq5nhn900"
    }
  ]
}

On an unsigned item, status is "ASSIGNED" if a matching active driver was found, or "DRAFT" if no driver was specified or matched. Send signatures and it is "COMPLETE", "AWAITING_TRANSFEROR_SIGNATURE" or "AWAITING_TRANSFEREE_SIGNATURE" instead — the signatures object says which halves landed.

signatures, pdf, publicPdf and customerId are on every item, always — on an unsigned draft as much as a finished note, and on an idempotent replay of a batch created before any of them existed. You do not need to code defensively around their absence. driverEmail is the one field that comes and goes: it is echoed back only when you sent one.

pdf is the note’s permanent address, not a promise that a document is waiting there. The PDF is rendered once the note is signed, so the link answers 404 PDF_NOT_READY for a few seconds after a signed create, and for as long as an unsigned draft stays unsigned. See GET /wtn/{id}/pdf below.

publicPdf is the link to give your customer. It needs no API key and opens in any browser — it is the same short link WTNcloud texts a customer when a note completes. Until the PDF exists it shows a “not ready yet” page, and once the note is signed the same link opens the document, so you can send it straight after the create. Treat it like the document itself: anyone who has the link can read the note. It stops working while the note is deleted, and works again if the note is restored.

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. Soft-deleted notes are excluded, the same as /hwcn/status: a note in your deleted items is not a record that stands, and its pdf link would not resolve.

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,
      "pdf": "https://wtncloud.co.uk/api/external/wtn/a1b2c3d4e5f6/pdf",
      "publicPdf": "https://wtncloud.co.uk/s/Ab3dEf7h",
      "createdAt": "2026-04-15T10:30:00.000Z",
      "updatedAt": "2026-04-15T14:22:00.000Z"
    }
  ]
}

pdfUrl is a boolean, despite the name — whether a document has been rendered yet. The link is pdf, and it is the same address whether or not the render has happened. Poll pdfUrl and fetch when it turns true, or just fetch and honour Retry-After on a 404 PDF_NOT_READY. publicPdf is the no-key link to the same document, as on POST /wtn/create; a note created before public links existed is given one the first time you look it up here.

Downloads the PDF of one of your own transfer notes — the document itself (application/pdf), streamed back through the API. Every download re-checks the key asking for it, so this is for your own systems; to give someone the document without your key, hand them publicPdf instead. Takes the wtnId from a create or status response, and needs only the read scope every key already carries.

curl "https://wtncloud.co.uk/api/external/wtn/a1b2c3d4e5f6/pdf" \
  -H "Authorization: Bearer YOUR_API_KEY" -o WTN-00042.pdf

A PDF is rendered once a note is signed, so a poll that beats the render gets 404 PDF_NOT_READY with a Retry-After header — retry rather than treating it as missing. An unsigned draft answers the same way until someone signs it. A load you logged from a paper note answers 404 NO_PDF_FOR_CAPTURE: nothing rendered one and nothing will, and the retained original is the record. A note belonging to another account is a plain 404, the same answer an id that doesn’t exist gets.

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 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. A batch holding one is refused whole with 400 COUNTRY_NOT_SUPPORTED and nothing in it is created: remove the items the response lists and resend.

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,
      "pdf": "https://wtncloud.co.uk/api/external/hwcn/a1b2c3d4e5f6/pdf",
      "publicPdf": "https://wtncloud.co.uk/s/Hw4Cn5Xy"
    }
  ]
}

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 the saved customer the consignment is linked to, so it shows in that customer’s history and portal. It is the one you named with customerId, or else one matched from the consignor the way /wtn/create matches a note (“Matching notes to customers” above): the company name with the address first, then the name with the postcode, then the email. The address is read as line 1, line 2, city and postcode, and finds a customer saved with or without the postcode, or saved with line 1 alone. It is null when nothing matches: this endpoint never saves a customer, and never changes one. The consignor block you send is what the consignment records, whichever customer it is linked to. Once a consignment or a note comes back with a customerId, send it with that consignor’s next consignment, and there is nothing to match.

pdf is where the consignment note will be downloadable from. Everything created here is a DRAFT and an HWCN is only rendered when Part D is signed, so expect 404 PDF_NOT_READY from it until that happens — see GET /hwcn/{id}/pdf below.

publicPdf is a link to the same document that needs no API key — the one to send the consignor, or anyone else who should have a copy. It shows a “not ready yet” page while the note is a draft and opens the PDF once Part D is signed, without the link changing. Anyone who has it can read the note; it stops working while the HWCN is deleted, and works again if it is restored.

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,
      "pdf": "https://wtncloud.co.uk/api/external/hwcn/a1b2c3d4e5f6/pdf",
      "publicPdf": "https://wtncloud.co.uk/s/Hw4Cn5Xy",
      "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, and pdf is where to fetch it with your API key. publicPdf is the no-key link to the same document, as on POST /hwcn/create; an HWCN created before public links existed is given one the first time you look it up here.

The hazardous twin of /wtn/{id}/pdf: downloads the consignment note for one of your own HWCNs, using the hwcnId from a create or status response. read scope; the file comes back as application/pdf.

curl "https://wtncloud.co.uk/api/external/hwcn/a1b2c3d4e5f6/pdf" \
  -H "Authorization: Bearer YOUR_API_KEY" -o consignment.pdf

An HWCN is rendered when Part D is signed, so a note still sitting as a DRAFT answers 404 PDF_NOT_READY — which is the normal state of anything POST /hwcn/create has just made. Poll /hwcn/status for status: "COMPLETED" rather than hammering this endpoint.

For permitted receiving sites that want their own software to see what is arriving. One API key addresses exactly one permitted site — a multi-site operator runs one account and one key per site, which is what keeps DEFRA reporting unambiguous.

WTNcloud is the registered Digital Waste Tracking software supplier and files every receipt with DEFRA on your behalf, so your integration never needs its own DEFRA registration or credentials. These endpoints require the receiver:read and receiver:write scopes, which you switch on yourself under Settings → API in your dashboard. Your account also needs the receiver role and its site permit — both your own settings too, and the API names whichever is missing.

Transfer notes carriers have fired to your site on arrival, and hazardous consignment notes addressed to it — the latter are raised by the producer and travel with the load rather than being fired. Defaults to whatever is still awaiting a decision: an accept or reject for a transfer note, a Part E for a consignment. Your to-do list.

Ordering: the pending worklist and any since query return oldest first, so you can work through a backlog larger than one page and advance a since cursor. Browsing resolved or all without a since returns newest first.

Example Request

curl "https://wtncloud.co.uk/api/external/receiver/inbound?status=pending" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "inbound": [
    {
      "wtnId": "a1b2c3d4e5f6...",
      "wtnReference": "WTN-00042",
      "firedByCompany": "Acme Haulage Ltd",
      "carrierCompany": null,
      "producerCompany": "Riverside Joinery",
      "vehicleRegistration": "AB12 CDE",
      "siteName": "Northside Transfer Station",
      "firedAt": "2026-07-24T09:12:00.000Z",
      "dateOfTransfer": "2026-07-24T00:00:00.000Z",
      "batchId": null,
      "resolution": "pending",
      "receivedAt": null,
      "waste": { "ewcCode": "17 09 04", "description": "Mixed C&D waste", "quantity": 12.5, "unit": "tonnes" },
      "acceptedQuantity": null,
      "additionalWasteLines": [],
      "recoveryDisposalCode": null,
      "hasPdf": true
    }
  ],
  "consignments": [
    {
      "hwcnId": "b2c3d4e5f6a1...",
      "consignmentCode": "ACMEWA/AB23F",
      "consignmentCodeMissingReason": null,
      "jurisdiction": "england",
      "raisedByCompany": "Acme Waste Ltd",
      "consignorCompany": "Riverside Joinery",
      "carrierCompany": "Hauliers Ltd",
      "vehicleRegistration": "AB12 CDE",
      "siteName": "Northside Transfer Station",
      "createdAt": "2026-07-24T09:00:00.000Z",
      "resolution": "pending",
      "partE": "awaiting",
      "receivedAt": null,
      "acceptedQuantityKg": null,
      "recoveryDisposalCode": null,
      "containsPops": false,
      "waste": {
        "ewcCode": "13 02 05*",
        "description": "Used engine oil",
        "quantityKg": 200,
        "physicalForm": "liquid",
        "hpCodes": ["HP_3", "HP_14"],
        "containerType": "drum",
        "containerCount": 1,
        "specialHandling": null
      },
      "additionalWasteLines": [],
      "hasPdf": true
    }
  ]
}

A transfer note carrying several waste lines lists the ones after the first (which is waste) in additionalWasteLines, each with its ewcCode, description, declared quantity and unit, and the acceptedQuantity you recorded for that line once it is resolved (0 on a rejection, null while pending). The same list comes back on /receiver/movements.

consignments are hazardous loads awaiting your Part E. status filters them the same way (pending = Part E not yet signed), and since reads the note's creation — nobody "fires" a consignment note, the producer raises it and the load turns up with it. limit applies to each list independently, so one kind can never hide behind the other. A consignment carrying several EWC-coded streams under one code lists the extras in additionalWasteLines, each with its own hazard codes and weight.

Loads you have actually taken in — both notes fired to you and your own captures of paper or emailed notes — with their DEFRA tracking state.

Provide either references or since. More than 100 references is rejected rather than truncated, so a reconciliation run can never mistake a trimmed response for a complete one. Ordering: a since sync returns oldest first so you can page the whole window; reference lookups return newest first.

Response

{
  "movements": [
    {
      "wtnId": "a1b2c3d4e5f6...",
      "wtnReference": "WTN-00042",
      "firedByCompany": "Acme Haulage Ltd",
      "siteName": "Northside Transfer Station",
      "dateOfTransfer": "2026-07-24T00:00:00.000Z",
      "receivedAt": "2026-07-24T10:02:00.000Z",
      "resolution": "accepted",
      "origin": "fired",
      "source": "DIGITAL",
      "waste": { "ewcCode": "17 09 04", "description": "Mixed C&D waste", "quantity": 12.5, "unit": "tonnes" },
      "acceptedQuantity": 12.1,
      "additionalWasteLines": [],
      "recoveryDisposalCode": "R13",
      "hasPdf": true,
      "dwt": {
        "wasteTrackingId": "2026ABC123",
        "status": "SUBMITTED",
        "env": "production",
        "submittedAt": "2026-07-24T10:02:05.000Z",
        "lastError": null
      }
    }
  ],
  "consignments": [
    {
      "hwcnId": "b2c3d4e5f6a1...",
      "consignmentCode": "ACMEWA/AB23F",
      "jurisdiction": "england",
      "raisedByCompany": "Acme Waste Ltd",
      "carrierCompany": "Hauliers Ltd",
      "siteName": "Northside Transfer Station",
      "origin": "consigned",
      "receivedAt": "2026-07-25",
      "receivedTime": "10:02",
      "resolution": "accepted",
      "acceptedQuantityKg": 195,
      "recoveryDisposalCode": "D10",
      "containsPops": false,
      "waste": { "ewcCode": "13 02 05*", "description": "Used engine oil", "quantityKg": 200 },
      "additionalWasteLines": [],
      "hasPdf": true,
      "dwt": {
        "wasteTrackingId": "2026DEF456",
        "status": "SUBMITTED",
        "env": "production",
        "submittedAt": "2026-07-25T10:02:09.000Z",
        "lastError": null
      }
    }
  ]
}

Hazardous receipts carry the same dwt block, because a hazardous receive is filed with DEFRA exactly like a non-hazardous one — that is what makes them reconcilable. references matches consignment codes, and since filters on when the receipt completed. origin is consigned (a note raised by someone else and receipted here) or capture (your own log of a paper note that arrived with a load).

dwt.status is one of PENDING, SUBMITTED, FAILED, AMENDED, NOT_REQUIRED, or null when no submission has been attempted. Filing happens asynchronously after receipt, so a movement read immediately may still show PENDING. origin is fired (a note sent to you digitally) or capture (your own scan of a paper or emailed note).

Downloads the PDF for a transfer note at your site. Returns the file itself (application/pdf), not a URL. For a hazardous consignment note, use /receiver/hwcn/{id}/pdf below.

curl "https://wtncloud.co.uk/api/external/receiver/wtn/a1b2c3d4e5f6/pdf" \
  -H "Authorization: Bearer YOUR_API_KEY" -o consignment.pdf

A PDF is rendered shortly after a note is finalised, so polling too quickly can return 404 PDF_NOT_READY with a Retry-After header — retry rather than treating it as missing. A load you logged yourself from a paper note answers 404 NO_PDF_FOR_CAPTURE instead: nothing generated a PDF and nothing will, so stop polling. A transfer note that is not addressed to your site returns a plain 404.

Record Part E — the consignee receipt — on a hazardous consignment addressed to your site. This is the hazardous equivalent of accepting a fired transfer note: what a receiving site does with a consignment note is declare what it actually took in and what it did with it, and that declaration is what DEFRA's receive is built from. Needs the receiver:write scope.

Example Request

curl -X POST "https://wtncloud.co.uk/api/external/receiver/hwcn/b2c3d4e5f6a1/receipt" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "dateReceived": "2026-07-25",
    "timeReceived": "10:02",
    "quantityReceivedIsEstimate": false,
    "rdCode": "D10",
    "receivedLines": [
      { "ewcCode": "13 02 05*", "quantityReceivedKg": 195, "accepted": "accepted" },
      { "ewcCode": "16 01 07*", "quantityReceivedKg": 40, "accepted": "rejected" }
    ],
    "vehicleRegistration": "AB12 CDE",
    "rejectionDetails": "Oil filters in a split drum.",
    "certificateConfirmed": true
  }'

Response

{
  "ok": true,
  "hwcnId": "b2c3d4e5f6a1...",
  "consignmentCode": "ACMEWA/AB23F",
  "partE": "signed",
  "dwt": {
    "filed": true,
    "reason": "A DEFRA receive was triggered. Poll /receiver/movements for its status and wasteTrackingId."
  }
}

No signature image, and no Idempotency-Key. There is no canvas over an API, so the authenticated call is the signature — the same reading the transfer-note accept endpoint takes. The consignment id is a natural key, so a second call is refused with 409 and a retry after a lost response is safe. A consignment not addressed to your site returns a plain 404.

Downloads the consignment note itself (application/pdf), for a consignment at your site.

curl "https://wtncloud.co.uk/api/external/receiver/hwcn/b2c3d4e5f6a1/pdf" \
  -H "Authorization: Bearer YOUR_API_KEY" -o consignment-note.pdf

The PDF is re-rendered on each signature, so a note still being signed can return 404 PDF_NOT_READY — honour Retry-After. A consignment you logged yourself from a paper note returns 404 NO_PDF_FOR_CAPTURE: WTNcloud generated no document for it, because the original that arrived with the load is the legal record and is held in your dashboard.

These endpoints record what happened to a load at your site, and are what cause a Digital Waste Tracking receipt to be filed with DEFRA on your behalf. They need the receiver:write scope.

Filing happens in the background once the receipt is recorded, so the response tells you whether a submission was triggered, not its outcome. Poll /receiver/movements for the wasteTrackingId.

Accept a transfer note fired to your site, in full or in part. The hazardous equivalent is Part E — see /receiver/hwcn/{id}/receipt.

Example Request

curl -X POST "https://wtncloud.co.uk/api/external/receiver/inbound/a1b2c3d4e5f6/accept" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "recoveryDisposalCode": "R13", "acceptedQuantity": 12.1 }'

Response

{
  "ok": true,
  "wtnId": "a1b2c3d4e5f6...",
  "status": "ACCEPTED",
  "dwt": {
    "filed": true,
    "reason": "A DEFRA receive was triggered. Poll /receiver/movements for its status and wasteTrackingId."
  }
}

A transfer note can only be resolved once — accepting or rejecting an already-processed one returns 409, which makes a retry after a lost response safe. A note listing several waste lines (its additionalWasteLines in /receiver/inbound) is one receipt with a figure per line: send "lineQuantities": [6, 1.5] for a 6 t + 2 t load of which 1.5 t of the second line was taken. A weighbridge weighs the lorry as a whole, so split its net across the lines rather than sending it as the first line's figure. Send every line you read beside the figures as lineKeys, and a note the carrier has edited since is refused with 409 LINES_CHANGED instead of your figures landing on different waste: read it again from /receiver/inbound and resend.

Reject a transfer note. Nothing is filed with DEFRA — no waste was received at your site, so there is no receive movement to report.

Record a load that never came through WTNcloud — a paper note handed over at the gate. Creates the movement and files its DEFRA receive.

Hazardous loads go here too. If the EWC code is hazardous, supply hazardousDetails and the load is kept as a consignment note rather than a transfer note — the record an operator and an EA inspection look for, in your HWCN register, list and CSV. The response says which you got in kind. Which one it is is decided from the EWC catalogue server-side, never from a flag you send, so the record kept can never disagree with the code declared.

wasteDescription is required for a hazardous load — a consignment note has to describe the waste.

A delivery carrying several EWC codes of the same kind is one receipt with several lines — put them in additionalWasteLines rather than sending a receipt each. That holds for both kinds: a transfer note may list several non-hazardous wastes, and a consignment note several hazardous ones. A delivery carrying both is two receipts, because the two move under different documents — send the hazardous part on its own and it comes back as kind: “hwcn”.

An Idempotency-Key header is required: this creates a brand-new record with no natural unique key, so without one a retry after a lost response would file a second DEFRA receive for the same physical load.

Example Request

curl -X POST "https://wtncloud.co.uk/api/external/receiver/receipts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: gate-ticket-88213" \
  -H "Content-Type: application/json" \
  -d '{
    "carrierId": "clx123carrier",
    "ewcCode": "17 09 04",
    "quantity": 8.4,
    "unit": "tonnes",
    "recoveryDisposalCode": "R13",
    "producerName": "Riverside Joinery",
    "vehicleReg": "AB12 CDE"
  }'

Response

{
  "ok": true,
  "wtnId": "b2c3d4e5f6a1...",
  "wtnReference": "WTN-00187",
  "kind": "wtn",
  "dwt": {
    "filed": true,
    "reason": "A DEFRA receive was triggered. Poll /receiver/movements for its status and wasteTrackingId."
  }
}

Example — a hazardous load

curl -X POST "https://wtncloud.co.uk/api/external/receiver/receipts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: gate-ticket-88214" \
  -H "Content-Type: application/json" \
  -d '{
    "carrierId": "clx123carrier",
    "ewcCode": "13 02 05*",
    "wasteDescription": "Used engine oil",
    "quantity": 200,
    "unit": "kg",
    "recoveryDisposalCode": "D10",
    "producerName": "Riverside Joinery",
    "vehicleReg": "AB12 CDE",
    "hazardousDetails": {
      "consignmentCode": "ACMEWA/AB23F",
      "hpCodes": ["HP_3", "HP_14"],
      "sourceOfComponents": "OWN_TESTING",
      "components": [{ "name": "Mineral oil", "concentration": 900 }]
    }
  }'

{
  "ok": true,
  "kind": "hwcn",
  "hwcnId": "b2c3d4e5f6a1...",
  "consignmentCode": "ACMEWA/AB23F",
  "dwt": {
    "filed": true,
    "reason": "A DEFRA receive was triggered. Poll /receiver/movements for its status and wasteTrackingId."
  }
}

A load that arrived with no note at all is logged with consignmentCodeMissingReason instead of a code; we store a placeholder that could not be mistaken for a real consignment code, and DEFRA is sent the reason rather than the placeholder. Logging the same consignment code twice returns 409 CONSIGNMENT_ALREADY_LOGGED with the id of the note you already have — one physical movement, one record.

Rather than polling, you can have us POST an event to your server as things happen. Add up to three endpoints under Settings → API in your dashboard, choose which events each one receives, and send yourself a test delivery before going live.

Endpoints must be https and publicly reachable. Redirects are not followed — point the webhook at its final URL.

Events

Events reach every party to the movement that has subscribed — so a carrier and a receiving site can each run their own integration against the same consignment.

Which kind of note an event is about. A hazardous event carries data.hwcnId and data.consignmentCode where a transfer note carries data.wtnId; the dwt.* events additionally carry data.kind of "wtn" or "hwcn". Every event also carries data.reference — the WTN number or the consignment code — so a consumer that only needs to identify the movement can read one field for both.

Payload

Every delivery has the same envelope. Route on event, dedupe on id — that value is constant across retries of the same event, so a redelivery is easy to spot.

{
  "id": "0f2c9f4a-4f4e-4c1a-9f3e-7b2d9c4a1e55",
  "event": "movement.received",
  "createdAt": "2026-07-25T09:14:22.418Z",
  "data": {
    "wtnId": "a1b2c3d4e5f6...",
    "reference": "WTN-00187",
    "receivingSitePermit": "EPR/AB1234CD",
    "receivedAt": "2026-07-25T09:14:00.000Z",
    "acceptanceStatus": "ACCEPTED",
    "acceptedQuantity": 12.1,
    "recoveryDisposalCode": "R13",
    "rejectionReason": null,
    "signatoryName": "Acme Recycling Ltd",
    "dwtFiling": true
  }
}

On a transfer note of several waste lines, acceptedQuantity is the first line's and additionalLines lists what was accepted of each of the others, each with its ewcCode, unit and acceptedQuantity. It is absent when the receipt took one figure for the load, and then every other line was received as declared. A line the site added at receipt, a waste the note doesn't list, carries added: true, a quantity of 0 and what was received of it in acceptedQuantity.

Headers

Verifying a delivery

Sign the raw request body, byte for byte. Parsing the JSON and re-serialising it produces a different string and the signature will not match.

import { createHmac, timingSafeEqual } from "crypto";

// `rawBody` must be the unparsed request body (e.g. express.raw()).
function verify(rawBody, headers, secret) {
  const timestamp = headers["x-wtncloud-timestamp"];
  const signature = headers["x-wtncloud-signature"];
  if (!timestamp || !signature) return false;

  // Replay guard: the timestamp is inside the signed string, so an attacker
  // can't re-date a captured delivery without breaking the signature.
  const age = Math.abs(Date.now() / 1000 - Number(timestamp));
  if (!Number.isFinite(age) || age > 300) return false;

  const expected = createHmac("sha256", secret)
    .update(`${timestamp}.${rawBody}`, "utf8")
    .digest("hex");

  const a = Buffer.from(expected, "utf8");
  const b = Buffer.from(signature, "utf8");
  return a.length === b.length && timingSafeEqual(a, b);
}

Delivery and retries

• Reply 2xx to acknowledge. Anything else — including a redirect — counts as a failure. Reply first and do your processing afterwards; we allow 10 seconds.
• Retries — five attempts in total, spaced 1, 5, 15 and 60 minutes apart, so a delivery survives about 81 minutes of downtime. Each attempt carries a fresh timestamp and signature.
• Ordering isn't guaranteed. A retried movement.received can arrive after the dwt.submitted that followed it. Treat each event as a fact about a point in time, and use the API to read current state.
• Persistent failure switches an endpoint off. After 20 consecutive events that exhaust every retry, we deactivate it and email the account owner. Nothing is lost: accepted movements and DEFRA submissions stay readable through /receiver/movements.

Error Codes

Rate Limits

API requests are rate limited to prevent abuse. Each request can include up to 100 WTNs in a single batch. The PDF download endpoints get their own budget of 60 requests a minute, separate from the JSON reads, because each one streams a file. If you need higher limits, contact us at [email protected].