Enquiries API

Pull buyer enquiry records for your organisation via the bearer-authenticated API.

Overview

Use these routes to poll buyer enquiries into your CRM or DMS. For real-time delivery, prefer Webhooks (enquiry.created).

Method	Path	Purpose
`GET`	`/api/v1/enquiries`	Paginated enquiry list
`GET`	`/api/v1/enquiries/{id}`	Single enquiry detail

Both routes require bearer authentication. Pass organisationId when the user belongs to multiple organisations — see Accounts.

Note: Replying to enquiries is not available via REST in v1 — use the dashboard.

Response fields

Each enquiry includes buyer contact details and a linked stock summary:

Field	Type	Description
`id`	string	Enquiry CUID
`stockId`	string	Linked listing ID
`organisationId`	string	Owning dealership
`name`	string	Buyer name
`email`	string	Buyer email
`phone`	string \| null	Buyer phone
`message`	string	Enquiry message
`status`	enum	`NEW`, `CONTACTED`, `NEGOTIATING`, `SOLD`, `LOST`
`readAt`	ISO datetime \| null	When marked read in dashboard
`repliedAt`	ISO datetime \| null	When dealer replied
`firstResponseAt`	ISO datetime \| null	First response timestamp
`createdAt`, `updatedAt`	ISO datetime	Record timestamps
`stock`	object	`{ id, title, slug }` — linked listing summary

Internal dealer notes (dealerNote) are not exposed via the API.

List enquiries

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

Multi-org:

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

{
  "data": {
    "enquiries": [
      {
        "id": "clenq111aaa",
        "stockId": "clstk456def",
        "organisationId": "clorg123abc",
        "name": "Jane Smith",
        "email": "jane@example.com",
        "phone": "+447700900123",
        "message": "Is this still available? Can I arrange a viewing?",
        "status": "NEW",
        "readAt": null,
        "repliedAt": null,
        "firstResponseAt": null,
        "createdAt": "2024-06-01T14:22:00.000Z",
        "updatedAt": "2024-06-01T14:22:00.000Z",
        "stock": {
          "id": "clstk456def",
          "title": "2020 DAF XF 530",
          "slug": "2020-daf-xf-530"
        }
      }
    ],
    "total": 8,
    "page": 1,
    "pages": 1
  }
}

Query parameters

Parameter	Description
`organisationId`	Required when user has multiple org memberships
`status`	Filter: `NEW`, `CONTACTED`, `NEGOTIATING`, `SOLD`, `LOST`
`page`	Page number (default `1`)
`limit`	Items per page (default `20`, max `100`)

Results are ordered by createdAt descending (newest first). See Pagination.

Get a single enquiry

curl "https://hgvtraders.com/api/v1/enquiries/clenq111aaa?organisationId=clorg123abc" \
  -H "Authorization: Bearer YOUR_TOKEN"

{
  "data": {
    "id": "clenq111aaa",
    "stockId": "clstk456def",
    "organisationId": "clorg123abc",
    "name": "Jane Smith",
    "email": "jane@example.com",
    "phone": "+447700900123",
    "message": "Is this still available? Can I arrange a viewing?",
    "status": "NEW",
    "readAt": null,
    "repliedAt": null,
    "firstResponseAt": null,
    "createdAt": "2024-06-01T14:22:00.000Z",
    "updatedAt": "2024-06-01T14:22:00.000Z",
    "stock": {
      "id": "clstk456def",
      "title": "2020 DAF XF 530",
      "slug": "2020-daf-xf-530"
    }
  }
}

Returns 404 if the enquiry does not exist or belongs to another organisation.

Polling vs webhooks

Approach	When to use
Webhooks	Real-time CRM push on `enquiry.created` — see Webhooks
Polling	Batch export, legacy systems, or webhook fallback — poll `GET /api/v1/enquiries?status=NEW` on an interval

Track the highest createdAt or enquiry id you have processed to avoid duplicates.

Typical integration flow

Register a webhook for enquiry.created or poll GET /api/v1/enquiries?status=NEW every few minutes
Fetch detail with GET /api/v1/enquiries/{id} if the list payload is insufficient
Create a lead in your CRM using name, email, phone, message, and stock.title
Mark progress in the HGV Traders dashboard (status changes are not writable via API v1)

Errors

Status	Typical cause
400	Invalid query or missing `organisationId` for multi-org users
401	Invalid or missing bearer token
404	Enquiry not found or wrong organisation
429	Write rate limit exceeded (shared bucket with other bearer write routes)

See Errors.

On this page