Gazetted API Reference

Overview

The Gazetted API lets law firms, councils, probate registries, and case management platforms place statutory notices in UK local newspapers and the London Gazette without using the web portal. It is designed for integrations where notices are generated programmatically from structured case data.

All requests are made to https://gazetted.co.uk/api/v1. The API accepts JSON request bodies and returns JSON responses. All monetary values are integers in pence (GBP).

Supported notice types

The following notice types are supported via the API. Additional types available in the portal (including Premises Licence) require custom wording and are not yet template-driven — they will be added in a future version.

Rate limits

Each API key is limited to 120 requests per minute. Exceeding this returns a 429 Too Many Requests response with a Retry-After header indicating how many seconds to wait.

SLA

The API targets 99.9% uptime. For status updates, see Status. Orders placed via the API are processed with the same SLA as portal orders.

Quickstart

This guide walks through placing an HGV Operator Licence notice end-to-end in under five minutes.

export GAZETTED_API_KEY=gz_live_xxxx

curl -X POST https://gazetted.co.uk/api/v1/quote \
  -H "Authorization: Bearer $GAZETTED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "hgv",
    "postcode": "SW1A 1AA"
  }'

{
  "type": "hgv",
  "postcode": "SW1A 1AA",
  "newspaper": {
    "name": "Evening Standard",
    "rateGbpPence": 1200,
    "frequency": "daily"
  },
  "pricing": {
    "subtotalGbpPence": 11900,
    "platformFeeGbpPence": 3500,
    "gazetteFeeGbpPence": 0,
    "vatGbpPence": 2400,
    "totalGbpPence": 14400
  },
  "compliance": {
    "minColumnsRequired": 1,
    "publicationDaysRequired": 1
  }
}

curl -X POST https://gazetted.co.uk/api/v1/orders \
  -H "Authorization: Bearer $GAZETTED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "hgv",
    "postcode": "SW1A 1AA",
    "applicantName": "Acme Haulage Ltd",
    "applicantAddress": "1 Logistics Park, London SW1A 1AA",
    "contactEmail": "transport@acmehaulage.co.uk",
    "publicationDate": "2026-05-15",
    "licenceType": "new",
    "vehicleCount": 10,
    "trailerCount": 5,
    "operatingCentreAddress": "Depot Road, London SW1",
    "operatingCentrePostcode": "SW1A 1AA",
    "trafficArea": "London"
  }'

{
  "id": "ord_01hwx3n8k2z9m",
  "reference": "GZ-2605-0042",
  "status": "pending_payment",
  "type": "hgv",
  "quotedPriceGbpPence": 14400,
  "noticeText": "Acme Haulage Ltd of 1 Logistics Park...",
  "checkoutUrl": "https://checkout.stripe.com/c/pay/cs_live_...",
  "paymentMethod": "stripe_checkout",
  "createdAt": "2026-05-01T10:30:00.000Z"
}

Authentication

All endpoints except POST /v1/quote require authentication via a Bearer token in the Authorization header.

curl https://gazetted.co.uk/api/v1/orders \
  -H "Authorization: Bearer $GAZETTED_API_KEY"

Managing API keys

Keys are created and revoked from Settings → API Access. Keys are scoped to your organisation — all members of the org share the same key pool. You can create multiple keys (e.g. one per integration) and revoke individual keys without affecting others.

Key rotation

To rotate a key, generate a new one from the Settings page and update your integration before revoking the old key. There is no automated rotation — you control the lifecycle entirely.

Versioning

The current version is v1, indicated by the /v1/ path prefix. We follow a conservative versioning policy:

• —Non-breaking additions (new optional fields, new endpoints) are made within v1 without notice.
• —Breaking changes (removed fields, changed semantics, new required fields) are introduced as v2 with a deprecation notice and migration period.
• —The v1 base URL will remain available for at least 12 months after v2 ships.

Rate Limits

Each API key is limited to 120 requests per minute. Exceeding this limit returns an HTTP 429 response:

HTTP/1.1 429 Too Many Requests
Retry-After: 23
Content-Type: application/json

{
  "error": "Rate limit exceeded. Please try again shortly.",
  "code": "rate_limit_exceeded"
}

The Retry-After header contains the number of seconds until the rate limit window resets. We recommend exponential backoff with jitter:

Errors

All error responses use a consistent shape:

{
  "error": "The requested order was not found.",
  "code": "order_not_found",
  "details": {
    "id": "ord_01hwx3n8k2z9m"
  }
}

Error codes

Endpoint Reference

All endpoints accept and return application/json. Monetary values are integers in pence (GBP). Dates are ISO 8601 strings.

Get an instant price estimate for a notice type and postcode. No authentication required. Rate-limited to 20 requests/min per IP.

curl -X POST https://gazetted.co.uk/api/v1/quote \
  -H "Authorization: Bearer $GAZETTED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "probate",
    "postcode": "EC2A 1AA",
    "wordCount": 120
  }'

Create a new notice order. Scope required: orders:write.

The API generates notice wording from structured fields — you do not supply pre-formatted text. The response includes a checkoutUrl (card billing), invoiceUrl (invoice terms), or neither (purchase order).

Shared fields (all types)

curl -X POST https://gazetted.co.uk/api/v1/orders \
  -H "Authorization: Bearer $GAZETTED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "hgv",
    "postcode": "SW1A 1AA",
    "applicantName": "Acme Haulage Ltd",
    "applicantAddress": "1 Logistics Park, London SW1A 1AA",
    "contactEmail": "transport@acmehaulage.co.uk",
    "publicationDate": "2026-05-15",
    "licenceType": "new",
    "vehicleCount": 10,
    "trailerCount": 5,
    "operatingCentreAddress": "Depot Road, London SW1",
    "operatingCentrePostcode": "SW1A 1AA",
    "trafficArea": "London"
  }'

List orders for your organisation. Scope required: orders:read. Results are paginated using cursor pagination.

curl "https://gazetted.co.uk/api/v1/orders?limit=10&status=published" \
  -H "Authorization: Bearer $GAZETTED_API_KEY"

Get full detail for a single order. Scope required: orders:read. Returns 404 order_not_found for orders that don't exist or belong to another organisation (the two cases are intentionally indistinguishable).

Request cancellation of an order. Scope required: orders:write. Triggers a Stripe refund if the order has been paid. Not all statuses are cancellable — orders after urn_received cannot be cancelled.

curl -X POST https://gazetted.co.uk/api/v1/orders/ord_01hwx3n8k2z9m/cancel \
  -H "Authorization: Bearer $GAZETTED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Client withdrew instruction" }'

Amend the details of a pending or booked order. Scope required: orders:write. Notice text and pricing are recomputed. If the amendment increases the notice size, the request will fail with 409 size_growth_not_allowed unless you pass acceptPriceChange: true.

Download the proof PDF for an order. Scope required: orders:read. Returns application/pdf with a Content-Disposition: attachment header.

Webhooks

Webhooks deliver real-time notifications to your server when order statuses change. They are more reliable than polling — polling the orders list frequently may trigger rate limits.

Registering a webhook

Add a webhook URL from Settings → Webhooks. Each webhook has a signing secret shown once at creation — store it securely. You can register multiple webhooks for different event types.

Event types

Every event uses the same envelope — see Payload format for the full schema. The data.object field contains the serialized order at the time the event fired.

Payload format

POST https://your-server.com/webhooks/gazetted HTTP/1.1
Content-Type: application/json
X-Gazetted-Signature: t=1714561234,v1=3d5e2b1...
X-Gazetted-Event: order.published

{
  "id": "evt_01hwx4ab2c3d",
  "event": "order.published",
  "createdAt": "2026-05-15T09:00:00.000Z",
  "data": {
    "orderId": "ord_01hwx3n8k2z9m",
    "reference": "GZ-2605-0042",
    "status": "published",
    "type": "hgv",
    "publishedAt": "2026-05-15T09:00:00.000Z",
    "certificateUrl": "https://gazetted.co.uk/api/v1/orders/ord_01hwx3n8k2z9m/certificate"
  }
}

Signature verification

Every webhook request includes an X-Gazetted-Signature header. Verify this to confirm the payload came from Gazetted and was not tampered with.

The signature is t=<timestamp>,v1=<hmac-sha256>. The HMAC is computed over <timestamp>.<rawRequestBody>using your webhook's signing secret.

import crypto from "crypto";

function verifyGazettedWebhook(
  rawBody: string,
  signature: string,
  secret: string
): boolean {
  const parts = Object.fromEntries(
    signature.split(",").map((p) => p.split("="))
  );
  const timestamp = parts["t"];
  const expectedSig = parts["v1"];

  // Reject if timestamp older than 5 minutes
  const age = Date.now() / 1000 - parseInt(timestamp, 10);
  if (age > 300) return false;

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

  return crypto.timingSafeEqual(
    Buffer.from(computed),
    Buffer.from(expectedSig)
  );
}

Retry policy

If your endpoint returns a non-2xx status or times out, Gazetted retries up to 5 times with the following schedule:

Failed deliveries after all retries are stored as a dead-letter queue entry visible in your webhook settings. You can replay individual events from there.

Best practices

• —Respond with a 2xx status within 3 seconds. Offload processing to a background job.
• —Only return 2xx once you have persisted the event — not before.
• —Handle events idempotently. The same event may arrive multiple times.
• —Filter events by type before processing — ignore events you don't need.

SDKs & Libraries

Official SDKs are on the roadmap. For v1, the curl, Node.js, and Python examples in this reference are the recommended starting point. The API is simple enough that a thin wrapper around fetch or httpx is all you need.

Changelog

Status

Live uptime and incident history are available at status.gazetted.co.uk.

For incident alerts, subscribe to updates on the status page. Critical incidents affecting order processing are also communicated by email to affected organisations.

Support

For API integration support, contact support@gazetted.co.uk. Include your organisation name and a description of the issue.

For order-related queries (newspaper deadlines, publication dates, certificates), contact notices@gazetted.co.uk.