Getting started

Prerequisites

An HGV Traders dealer account with API access
A bearer token (dashboard-minted or via POST /api/v1/auth)
HTTPS client capable of JSON requests and raw file PUT uploads

Base URL: https://hgvtraders.com/api/v1

1. Obtain a bearer token

Recommended: mint a named token from Dashboard → Settings → API Tokens. Tokens are 64-character hex strings shown once at creation.

Alternative: exchange credentials programmatically:

curl -X POST "https://hgvtraders.com/api/v1/auth" \
  -H "Content-Type: application/json" \
  -d '{"email":"dealer@hgvtraders.com","password":"your-password"}'

{
  "data": {
    "token": "a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456"
  }
}

See Authentication for expiry, rotation, and rate limits.

3. Try a public read call (no token)

Marketplace content is available without authentication:

curl "https://hgvtraders.com/api/v1/jobs?limit=5&q=HGV+driver"

{
  "data": {
    "jobs": [ ... ],
    "total": 128,
    "page": 1,
    "pages": 26
  }
}

See Public read for jobs, events, and posts.

5. Create a listing with photos (full walkthrough)

5a. Upload each photo

curl -X POST "https://hgvtraders.com/api/v1/uploads" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@front.jpg" \
  -F "organisationId=clorg123abc"

{
  "data": {
    "key": "orgs/clorg123abc/temp/1717243200123-a1b2c3d4.jpg"
  }
}

Repeat for each image. See Image uploads — including the presigned fallback for files over 4MB.

5b. Create a draft listing

Save the key from each upload response, then create the listing:

KEY="orgs/clorg123abc/temp/1717243200123-a1b2c3d4.jpg"

curl -X POST "https://hgvtraders.com/api/v1/stock" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{
    \"organisationId\": \"clorg123abc\",
    \"assetClass\": \"TRUCK\",
    \"title\": \"2020 DAF XF 530\",
    \"priceType\": \"FIXED\",
    \"pricePence\": 4500000,
    \"locationPostcode\": \"M1 1AA\",
    \"imageKeys\": [\"$KEY\"]
  }"

Note the returned id from the response.

5c. Publish

curl -X POST "https://hgvtraders.com/api/v1/stock/clstk456def/publish" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"organisationId":"clorg123abc"}'

Publishing is subject to plan slot limits — see Stock API.

7. Pull enquiries or register webhooks

Poll:

curl "https://hgvtraders.com/api/v1/enquiries?status=NEW" \
  -H "Authorization: Bearer YOUR_TOKEN"

Push: configure webhook URLs in Dashboard → Settings → Webhooks for enquiry.created. See Webhooks and Enquiries.

8. Browse the reference

Resource	Link
All routes	Endpoint reference
Request/response schemas	API Reference
Status codes	Errors
Limits	Rate limits

Stock imports (alternative to REST)

Feed-based bulk import is available via Dashboard → Imports (scheduled feeds and CSV). For concierge setup, use Dashboard → Integrations → Request setup or see Integrations — Feed import. Use REST when you need programmatic create/update from your DMS; use imports for high-volume feed sync.

Multi-organisation users

Pass organisationId on every write route and on org-scoped reads when the token's user belongs to more than one dealership. The bearer token alone does not imply which organisation is active — see Accounts.