API v1 reference

This page covers the conventions shared by every /api/v1/* endpoint. Deep-dive pages for the most commonly integrated resources — Contacts, Properties, Deals, and Inquiries & leads — follow this one. For every other resource, the tables below list the exact routes; the full machine-readable spec is always at GET /api/v1/openapi.json.

Base URL

https://api.avensa.bg/api/v1

Requests are versioned at the path level (/api/v1). All endpoints require authentication — see Authentication and API keys.

Pagination

List endpoints share four query parameters:

List response envelope:

{
  "data": [ { "...": "..." } ],
  "meta": {
    "count": 25,
    "total": 340,
    "has_more": true,
    "next_cursor": "eyJpZCI6Ii4uLiJ9"
  }
}

A single-resource response wraps the object in data: { "data": { "...": "..." } }.

Idempotency

POST endpoints that create a resource accept an optional Idempotency-Key header (any string, up to 255 characters). Retrying the same request with the same key (scoped to account + method + path) replays the original response instead of creating a duplicate — the replay carries X-Idempotency-Replay: true. A concurrent retry that's still in flight returns 409 Conflict. Recommended for anything wired through Zapier or a retrying job queue.

Idempotency-Key: a1b2c3d4-1234-5678-9abc-def012345678

Optimistic locking

Deals (and some other mutable resources) carry a version integer. Updates must include the version you last read; a stale version returns 409 Conflict so you can re-fetch and retry instead of silently overwriting a concurrent change.

Resource groups

For request/response schemas of any endpoint not covered by a deep-dive page, fetch GET /api/v1/openapi.json — it is generated from the same route definitions the app runs against, so it never drifts from this reference.

Errors

Errors and rate limiting share one shape across every endpoint — see Rate limits and errors.