Developer API

WTNcloud REST API

Create waste transfer notes and check their status programmatically. Integrate WTNcloud with Google Sheets, your own CRM, or any system that can make HTTP requests.

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

POST/wtn/create

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).

Field	Type	Required	Description
name	string	Required	Customer name
address	string	Required	Customer address
email	string	Optional	Customer email
phone	string	Optional	Customer phone number
driverEmail	string	Optional	Assign to a driver by their email address
dateOfTransfer	string	Optional	ISO date (e.g. 2026-04-15). Defaults to today
ewcCode	string	Optional	European Waste Catalogue code
wasteDescription	string	Optional	Description of the waste
quantity	number	Optional	Amount of waste
unit	string	Optional	Unit of measurement (kg, tonnes, litres, etc.)
containmentType	string	Optional	How the waste is contained (bags, skip, drums, etc.)
saveCustomer	boolean	Optional	Save the customer for reuse in future WTNs

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.

GET/wtn/status

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

Query Parameters

Field	Type	Required	Description
references	string	Optional	Comma-separated WTN references (e.g. WTN-00042,WTN-00043)
since	string	Optional	ISO date — returns WTNs created on or after this date (max 100 results)

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"
    }
  ]
}

Error Codes

Status	Meaning	What to do
400	Bad Request	Check your request body matches the schema above. The response includes validation details.
401	Unauthorized	Your API key is missing or invalid. Check the Authorization header.
403	Forbidden	Your account has been suspended. Contact [email protected].
500	Server Error	Something went wrong on our end. Retry after a few seconds. If it persists, contact support.

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].

Ready to integrate?

Get Started Questions? Email [email protected]