Agent Playbook

How an AI agent, script or automation creates and maintains listings on OZFINDA, Australia's business directory. This page is meant to be read by agents: every rule is explicit, every error is machine-readable, and you don't need a browser, CAPTCHA or human in the loop for anything except one email confirmation.

One rule shapes everything else: OZFINDA lists Australian businesses only. Every listing needs an Australian state or territory, and every submission is moderated, including by an AI model that checks the business is real and operates in Australia. Submissions that fail are refused or held for a human. They are never published silently.

Quick start

# 1. Register an account and get an API key (shown once)
curl -X POST https://ozfinda.com.au/api/v1/agents/register \
  -H "Content-Type: application/json" \
  -d '{"name":"Sam Citizen","email":"[email protected]","password":"a-long-password"}'

# 2. Create a listing (published once the email is confirmed)
curl -X POST https://ozfinda.com.au/api/v1/listings \
  -H "Authorization: Bearer ozf_..." \
  -H "Content-Type: application/json" \
  -d '{
    "business_name": "Bondi Plumbing Co",
    "categories": ["trades"],
    "tagline": "Licensed plumbers for the Eastern Suburbs",
    "description": "Family-run plumbing business servicing Bondi, Randwick and Coogee since 2004.",
    "phone": "0412 345 678",
    "website": "https://bondiplumbing.com.au",
    "suburb": "Bondi",
    "state": "NSW",
    "postcode": "2026",
    "service_area": "Eastern Suburbs, Sydney"
  }'

# 3. After the human clicks the confirmation email, publish it
curl -X PATCH https://ozfinda.com.au/api/v1/listings/bondi-plumbing-co \
  -H "Authorization: Bearer ozf_..." \
  -H "Content-Type: application/json" \
  -d '{"published": true}'

Who should use this

• Business owners' assistants: an agent listing the business it works for.
• Agencies and automations: maintaining listings for Australian clients. Each account's plan caps how many listings it can own. The Free plan includes 1, and paid plans include more (see https://ozfinda.com.au/#pricing).
• Search and recommendation agents: read-only search needs no key.

Don't use it to bulk-import scraped business data, to list businesses you don't represent, or to list anything outside Australia. Those listings are refused, and repeated attempts get the account removed.

Basics

1. Get an API key

New account: POST /agents/register

{ "name": "Sam Citizen", "email": "[email protected]", "password": "a-long-password", "key_name": "Claude agent" }

Returns 201 with account, api_key.key (shown once, so store it) and next_actions. The account is a normal OZFINDA account. A human can log in at https://ozfinda.com.au/login with the same email and password and see everything the agent did.

We email a confirmation link to the address. Nothing can be published until a human clicks it. This is our main defence against throwaway-account spam. Use a real inbox the business controls.

Existing account: POST /api-keys

{ "email": "[email protected]", "password": "a-long-password", "name": "Zapier" }

Or, with an existing key in the Authorization header, just { "name": "..." }. Owners can also mint and revoke keys in the dashboard under Account → API keys.

• GET /api-keys lists live keys (prefix only).
• DELETE /api-keys/{id} revokes one.
• An account can hold up to 10 live keys.

2. Create a listing: POST /listings

Unknown fields are rejected with 400, so typos surface instead of being silently dropped.

Response 201:

{
  "listing": {
    "username": "bondi-plumbing-co",
    "url": "https://ozfinda.com.au/bondi-plumbing-co",
    "status": "live",
    "moderation": { "status": "clear", "reason": null },
    "...": "every field above, plus id, dashboard_url, created_at, updated_at"
  },
  "next_actions": []
}

Always read status and next_actions. next_actions tells you exactly what's blocking a listing from going live.

Listing status

3. Read, update, delete

• GET /listings/{username}: anyone can read a live listing. With your key you also see your drafts plus status and moderation.
• PATCH /listings/{username}: send only the fields you're changing. Use {"published": false} to unpublish. username can't be changed over the API.
• DELETE /listings/{username}: permanent. Removes the listing and everything attached to it.
• GET /me: your account, plan, listing quota (listings_used / listings_limit) and all your listings with status.

Content edits re-run moderation. A live listing that's edited into something that fails is unpublished and held for review.

4. Search (no key needed)

GET /listings?q=emergency+plumber&state=NSW&category=trades&limit=20&offset=0

Returns results[] (username, url, business_name, category, tagline, suburb, state, service_area, phone, website, featured) and next_offset. Search combines full-text and semantic matching over live listings. Featured (paid) listings rank first when there's no q.

GET /categories returns every category slug and label.

Moderation and spam rules

Every create and content edit goes through, in order:

1. Structure. state must be an Australian state or territory, and postcode must be a 4-digit Australian postcode. Anything else gets 422.
2. One listing per website. A website already on OZFINDA gets 409 conflict. If it's an unclaimed listing for your business, the response includes a claim link. If it's yours, it tells you which username to PATCH.
3. Restricted content. Adult services, drugs, weapons, unlicensed gambling, counterfeit goods and scams are held for review (pending_review).
4. AI review. A decision model checks that the listing is a genuine business operating in Australia. Confident failures (overseas business, SEO/link spam, gibberish, not a business) are refused with 422 content_policy and nothing is saved. Borderline cases are saved but held for a human (pending_review).
5. Email confirmation. Nothing goes live until the account's email is confirmed.

What passes easily: a real Australian business described in plain, specific language, with a real suburb, state, postcode, Australian phone number and its own website.

What fails: keyword lists, city-name stuffing, links in the description, businesses based overseas, placeholder text, and listings for businesses you don't represent.

Rate limits

Over the limit you get 429 rate_limited with a Retry-After header in seconds. Back off and retry. Don't hammer.

Errors

Every error has the same shape:

{ "error": "human-readable message", "code": "content_policy", "field": "state", "docs_url": "https://ozfinda.com.au/docs/agents" }

Recommended agent loop

1. GET /me. Check can_add_listing and existing listings, so you update rather than duplicate.
2. POST /listings with the fullest, most specific details you have.
3. If 422 content_policy, read error. Don't retry the same content. Fix the underlying problem or stop.
4. If status is draft with verify_email, tell your human to click the email, then PATCH {"published": true}.
5. If pending_review, tell your human it's waiting for a moderator. Don't resubmit duplicates.
6. Keep the listing current with PATCH when hours, phone or services change.

Discovery

• https://ozfinda.com.au/llms.txt: site summary for language models
• https://ozfinda.com.au/llms-full.txt: everything in one file
• https://ozfinda.com.au/openapi.json: OpenAPI 3.1 spec
• https://ozfinda.com.au/.well-known/api-catalog: RFC 9727 API catalog
• https://ozfinda.com.au/docs/agents.md: this playbook as markdown