API Documentation

Everything you need to integrate contractor license verification into your application.

✓ Now covering QLD, NSW & VIC• 333,840 licenses

State Coverage

WorkClear provides license verification for contractors across multiple Australian states. Each state has different data sources and update frequencies.

State	Records	Source	Status
QLD	107,268	QBCC Licensed Contractors Register	Live
NSW	178,901	NSW Fair Trading	Live
VIC	47,671	VBA Building Practitioner Register	Live
SA, WA, TAS, NT, ACT	—	—	Coming Soon

View real-time data freshness on our Status Page.

Getting Started

Try the API instantly with our demo endpoint, or sign up for full access.

Try Without Signing Up

Use our /api/demo endpoint for up to 5 free requests per day:

Demo Endpoint

# Try the demo endpoint without an API key (5 requests/day limit)
curl "https://workclear.vercel.app/api/demo?licence_number=54898"

# Specify a state to search only that state
curl "https://workclear.vercel.app/api/demo?licence_number=236638C&state=NSW"

Get an API Key

Sign up for an account — Contact us at api@workclear.com.au
Receive your API key — We'll send you a key starting with wc_live_ or wc_test_
Start making requests — Include your API key in the x-api-key header

Free Tier: All accounts start with 100 free API requests per month. No credit card required.

Authentication

All API requests (except /api/demo and /api/health) require authentication via an API key.

Request Headers

Header	Value
x-api-key	Your API key

Example Request

curl -X GET "https://workclear.vercel.app/api/verify?licence_number=54898" \
  -H "x-api-key: wc_live_your_api_key_here"

Endpoints

GET/api/verify

Verify a contractor's license by their license number. Searches across all states or a specific state if provided.

Query Parameters

Parameter	Type	Description
licence_number	string	The contractor's license number (required)
state	string	State code: `QLD`, `NSW`, or `VIC` (optional, searches all if omitted)

Response Examples

QLD License

{
  "status": "active",
  "state": "QLD",
  "licence_number": "54898",
  "licensee_name": "CRAIG MAXWELL NIXON",
  "abn": "52 286 440 148",
  "licence_type": "Individual",
  "financial_category": "Self Certification - Trade",
  "licence_classes": [
    {
      "grade": "Trade Contractor Licence",
      "class": "Gasfitting"
    },
    {
      "grade": "Trade Contractor Licence",
      "class": "Plumbing and Drainage"
    }
  ],
  "data_date": "2026-01-30",
  "source": "QBCC Licensed Contractors Register"
}

NSW License

{
  "status": "active",
  "state": "NSW",
  "licence_number": "236638C",
  "licensee_name": "Blake Robert Burrows",
  "abn": null,
  "licence_type": "Individual",
  "issue_date": "2011-05-30",
  "expiry_date": "2028-05-29",
  "licence_classes": [
    { "class": "Electrician" }
  ],
  "source": "NSW Fair Trading"
}

VIC License

{
  "status": "active",
  "state": "VIC",
  "licence_number": "DB-U 101781",
  "licensee_name": "Individual (name withheld)",
  "abn": null,
  "licence_type": "Person",
  "issue_date": "2025-10-31",
  "expiry_date": "2030-10-31",
  "licence_classes": [
    { "class": "Domestic Builder - Unlimited" }
  ],
  "source": "VBA Building Practitioner Register"
}

POST/api/verify/bulkNew

Verify multiple contractor licenses in a single request. Ideal for batch processing, onboarding workflows, or periodic compliance checks.

Request Body

Field	Type	Description
licences	string[]	Array of license numbers (required, max 100)
state	string	State code: `QLD`, `NSW`, or `VIC` (optional, searches all if omitted)

Response Fields

Field	Description
summary.total	Total licenses requested
summary.found	Licenses found in database
summary.not_found	Licenses not found
summary.errors	Lookup failures (invalid format, etc.)
summary.processing_time_ms	Total processing time in milliseconds
results[]	Array of results, one per requested license

Billing Note: Each license in the bulk request counts as 1 API call for billing purposes. A request with 50 licenses uses 50 API calls from your quota.

Example Request

curl -X POST "https://workclear.vercel.app/api/verify/bulk" \
  -H "x-api-key: wc_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "licences": ["54898", "236638C", "DB-U 101781"],
    "state": null
  }'

200 OK

{
  "summary": {
    "total": 3,
    "found": 3,
    "not_found": 0,
    "errors": 0,
    "processing_time_ms": 245
  },
  "results": [
    {
      "licence_number": "54898",
      "status": "found",
      "data": {
        "status": "active",
        "state": "QLD",
        "licence_number": "54898",
        "licensee_name": "CRAIG MAXWELL NIXON",
        ...
      }
    },
    {
      "licence_number": "236638C",
      "status": "found",
      "data": {
        "status": "active",
        "state": "NSW",
        ...
      }
    },
    {
      "licence_number": "DB-U 101781",
      "status": "found",
      "data": {
        "status": "active",
        "state": "VIC",
        ...
      }
    }
  ]
}

GET/api/search

Search for contractors by name or ABN across all states or a specific state.

Query Parameters

Parameter	Type	Description
q	string	Search query (required)
type	string	`name` or `abn` (default: name)
state	string	State code: `QLD`, `NSW`, or `VIC` (optional)
limit	number	Max results (default: 10, max: 100)

Example Request

curl -X GET "https://workclear.vercel.app/api/search?q=NIXON&type=name&limit=5" \
  -H "x-api-key: wc_live_your_api_key_here"

200 OK

{
  "count": 3,
  "results": [
    {
      "state": "QLD",
      "licence_number": "54898",
      "licensee_name": "CRAIG MAXWELL NIXON",
      "licence_type": "Individual",
      "abn": "52 286 440 148"
    },
    {
      "state": "NSW",
      "licence_number": "123456C",
      "licensee_name": "NIXON ELECTRICAL",
      "licence_type": "Business",
      "expiry_date": "2027-03-15"
    }
  ]
}

GET/api/demo

Free demo endpoint for testing. Same as /api/verify but rate-limited to 5 requests per day per IP. No authentication required.

GET/api/health

Health check endpoint. No authentication required. Use for monitoring.

GET/api/status

API status including database connectivity and record counts. No authentication required.

Error Handling

The API uses standard HTTP status codes. All errors return a JSON object with an error field.

Status	Meaning
200	Success (even if no results found)
400	Invalid request parameters
401	Missing or invalid API key
429	Rate limit exceeded
500	Internal server error

Note: A 200 response with "status": "not_found" means no license was found, not that there was an error.

Rate Limits

Tier	Rate Limit	Price
Demo	5 requests/day	Free
Free	100 requests/month	Free
Starter	1,000 requests/month	$49/mo
Pro	10,000 requests/month	$149/mo
Enterprise	Unlimited	Contact us

Rate limit information is included in response headers: X-RateLimit-Remaining.