Listing API

Programmatically manage your listings on hires.nz

Unlock API Access

Automate your listings with our powerful API. Create, update, and manage listings programmatically.

Upgrade to Business - $49/mo

Business Plan Required

API access is a premium feature included with the Business plan ($49/month). View all plans

Authentication

All API requests require an API key. Include your key in the request header:

X-API-Key: hires_your_api_key_here

Or use Bearer token authentication:

Authorization: Bearer hires_your_api_key_here

You'll need to upgrade to Business to generate an API key and use these endpoints.

Endpoints

GET /api/v1/listings

List all your active listings.

Response

{
  "listings": [
    {
      "id": 123,
      "title": "iPhone 15 Pro",
      "content": "Brand new in box...",
      "type": "product",
      "category": "electronics",
      "images": ["https://..."],
      "price": 1999.00,
      "price_type": "fixed",
      "location": "Auckland",
      "region": "Auckland",
      "is_active": true,
      "view_count": 45,
      "created_at": "2024-01-15 10:30:00",
      "updated_at": "2024-01-15 10:30:00"
    }
  ]
}
POST /api/v1/listings

Create a new listing.

Request Body

{
  "title": "iPhone 15 Pro",
  "content": "Brand new in box, 256GB, Natural Titanium",
  "type": "product",
  "category": "electronics",
  "images": ["https://example.com/photo1.jpg"],
  "price": 1999.00,
  "price_type": "fixed",
  "location": "Auckland CBD",
  "region": "Auckland",
  "district": "Central",
  "latitude": -36.8485,
  "longitude": 174.7633
}

Required Fields

  • title - Listing title
  • content - Description

Optional Fields

  • type - product, service, rental, job (default: product)
  • category - Subcategory
  • images - Array of image URLs
  • price - Price in NZD
  • price_type - fixed, negotiable, per_hour, per_night
  • location, region, district - Location info
  • latitude, longitude - GPS coordinates

Response (201 Created)

{
  "id": 456,
  "message": "listing created"
}
GET /api/v1/listings/{id}

Get a single listing by ID. Returns the same fields as the list endpoint.

PUT/PATCH /api/v1/listings/{id}

Update a listing. Only include fields you want to change.

Request Body

{
  "price": 1799.00,
  "is_active": false
}

Response

{
  "message": "listing updated"
}
DELETE /api/v1/listings/{id}

Delete (close) a listing. This performs a soft delete.

Response

{
  "message": "listing deleted"
}

Error Responses

All errors return JSON with an error field:

{
  "error": "API key required"
}
Status Meaning
401 Missing or invalid API key
403 Business plan expired or not your listing
404 Listing not found
400 Invalid request (missing required fields, bad JSON)

Example: cURL

# List all listings
curl -H "X-API-Key: hires_your_key" https://hires.nz/api/v1/listings

# Create a listing
curl -X POST https://hires.nz/api/v1/listings \
  -H "X-API-Key: hires_your_key" \
  -H "Content-Type: application/json" \
  -d '{"title":"Test Product","content":"Description here","price":99.99}'

# Update a listing
curl -X PUT https://hires.nz/api/v1/listings/123 \
  -H "X-API-Key: hires_your_key" \
  -H "Content-Type: application/json" \
  -d '{"price":89.99}'

# Delete a listing
curl -X DELETE https://hires.nz/api/v1/listings/123 \
  -H "X-API-Key: hires_your_key"

Rate Limits

API requests are limited to 1000 requests per hour per API key. Contact us if you need higher limits.

Ready to automate your listings?

Join businesses across New Zealand using our API to manage their marketplace presence efficiently.

Get Business Plan - $49/mo Contact Sales

Complete Subscription

Loading payment form...