{ "openapi": "3.1.0", "info": { "title": "Qvoo CRM Public API Reference", "version": "1.1.0", "description": "Welcome to the Qvoo CRM Developer Platform. These APIs allow external systems to fetch, push, and sync Leads, Properties, Contacts, Customers, Tasks, Team Members, and WhatsApp Messages. Scoped endpoints require a valid API Key or OAuth 2.0 access token.\n\n## 🚀 Getting Started\n\nTo get started with the Qvoo CRM Public API, follow these steps:\n\n1. **Get Workspace ID**: Obtain your workspace identifier from the workspace settings in the Qvoo CRM dashboard.\n2. **Generate API Key**: Navigate to the Developer Settings in your Qvoo CRM portal to generate an active API Key.\n3. **Verify API Access**: Perform a quick API call to the `/api/v1/health` endpoint to verify connectivity.\n\n---\n\n## 🔒 Authentication\n\n> [!IMPORTANT]\n> **OAuth 2.0 Security Enforcement:** Workspaces can optionally enable \"OAuth 2.0 Security Enforcement\" under Developer Settings. When enabled, direct API Key authentication (`X-API-Key`) is blocked, and all API requests must use a Bearer token generated via the Client Credentials flow.\n\nWe support two authentication methods depending on your integration scenario:\n\n### 1. API Key Authentication (Recommended for simple server-to-server calls)\nInclude your API Key in the `X-API-Key` HTTP header for all requests:\n```bash\ncurl --request GET \\\n --url http://localhost:5010/api/v1/workspaces/YOUR_WORKSPACE_ID/leads \\\n --header 'X-API-Key: YOUR_API_KEY'\n```\n\n### 2. OAuth 2.0 Client Credentials (Recommended for third-party integrations)\nFirst, exchange your client credentials for an access token:\n```bash\ncurl --request POST \\\n --url http://localhost:5010/api/v1/oauth/token \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"client_id\": \"YOUR_CLIENT_ID\",\n \"client_secret\": \"YOUR_CLIENT_SECRET\",\n \"grant_type\": \"client_credentials\"\n }'\n```\nThen, use the returned `access_token` in the `Authorization` header as a Bearer token:\n```bash\ncurl --request GET \\\n --url http://localhost:5010/api/v1/workspaces/YOUR_WORKSPACE_ID/leads \\\n --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'\n```\n\n---\n\n## 📬 Postman Collection\n\nYou can download our pre-configured Postman Collection to start testing endpoints immediately:\n\n👉 **[Download Postman Collection](/api/postman_collection.json)**\n\n---\n\n---\n\n## 🔑 API Scopes\n\nAPI keys and OAuth tokens use granular scopes. The deprecated `admin` scope has been **removed** — keys bearing it are rejected with `403`.\n\n| Scope | Grants access to |\n|-------|------------------|\n| `lead.read` / `lead.write` | Leads endpoints |\n| `property.read` / `property.write` | Properties endpoints |\n| `contact.read` / `contact.write` | Contacts endpoints |\n| `customer.read` / `customer.write` | Customers endpoints |\n| `task.read` / `task.write` | Tasks endpoints |\n| `webhook.manage` | Webhook subscription management |\n| `metadata.read` | Workspace info, schema, metadata lookups |\n| `team.read` | `/team` and `/users` endpoints |\n\n**Default scopes** when creating a key without specifying scopes: `lead.read`, `lead.write`, `metadata.read`.\n\n---\n\n## 🚫 Data Retention — No DELETE\n\nThe Public API does **not** support `DELETE` for CRM entities (leads, properties, contacts, customers, tasks). Any `DELETE` request returns **405 Method Not Allowed**. Use archive endpoints where available (e.g. `POST /leads/{id}/archive`) or manage deletions in the CRM UI.\n\n---\n\n## ⚡ Rate Limits\n\nRequests are rate-limited per workspace and API key using Redis-backed counters with per-minute and hourly caps. Exceeding limits returns **429** with `Retry-After`.\n\n---\n\n## 📜 API Changelog\n\n### v1.1.0 (2026-06-13)\n* **API_CLIENT auth**: Public API requests run under a dedicated API_CLIENT principal instead of synthetic admin.\n* **Scope hardening**: Removed deprecated `admin` scope; added `metadata.read` and `team.read`; default key scopes are `lead.read`, `lead.write`, `metadata.read`.\n* **No DELETE**: All `DELETE` requests on the Public API return 405; CRM records cannot be deleted via API.\n* **Custom fields**: Custom `fields` are optional on create when workspace required-field rules allow it.\n* **Idempotency-Key**: Optional header on POST create endpoints prevents duplicate records on retries (24h TTL).\n* **Bulk leads**: `POST /leads/bulk` returns a per-row `results` array with status for each input row.\n* **Rate limits**: Redis-backed per-minute and hourly caps replace in-memory counters.\n* **ETag caching**: GET-by-id responses include an `ETag` header; send `If-None-Match` to receive **304 Not Modified**.\n* **Webhook redaction**: Webhook subscription secrets are redacted from Public API list/get responses; delivery payloads omit sensitive fields.\n\n### v1.0.0 (2026-06-12)\n* **Initial Release**: Launched Qvoo CRM Developer Platform APIs.\n* **OAuth 2.0 & Keys**: Implemented client credentials grant and JWT refresh token rotation alongside Workspace API Keys.\n* **Webhooks**: Added subscriptions management APIs and real-time delivery payload logs for leads, properties, contacts, customers, and tasks events.", "contact": { "name": "Qvoo Developer Support", "email": "support@qvoo.io" } }, "servers": [ { "url": "{custom_domain}", "description": "Custom Domain Server", "variables": { "custom_domain": { "default": "https://api.qvoo.io", "description": "Enter your custom domain here" } } }, { "url": "http://localhost:5000", "description": "Local Development Server" } ], "paths": { "/api/v1/oauth/token": { "post": { "summary": "Generate OAuth 2.0 Access Token", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "client_id": { "type": "string" }, "client_secret": { "type": "string" }, "grant_type": { "type": "string", "default": "client_credentials" } }, "required": [ "client_id", "client_secret", "grant_type" ] } } } }, "responses": { "200": { "description": "Token generated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "tags": [ "OAuth 2.0" ] } }, "/api/v1/oauth/revoke": { "post": { "summary": "Revoke OAuth 2.0 Credentials", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "client_id": { "type": "string" }, "client_secret": { "type": "string" } }, "required": [ "client_id", "client_secret" ] } } } }, "responses": { "200": { "description": "Credentials revoked successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionSuccessResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "tags": [ "OAuth 2.0" ] } }, "/api/v1/oauth/refresh": { "post": { "summary": "Refresh OAuth 2.0 Access Token", "description": "Exchange a refresh token for a new access token and a new refresh token.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "refresh_token": { "type": "string" } }, "required": [ "refresh_token" ] } } } }, "responses": { "200": { "description": "Token refreshed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "access_token": { "type": "string", "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." }, "refresh_token": { "type": "string", "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." }, "expires_in": { "type": "integer", "example": 3600 } }, "required": [ "access_token", "refresh_token", "expires_in" ] } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "tags": [ "OAuth 2.0" ] } }, "/api/v1/health": { "get": { "summary": "API Health Endpoint", "description": "Get the health status, version, and server timestamp of the API.", "responses": { "200": { "description": "API is healthy", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "healthy" }, "version": { "type": "string", "example": "1.0.0" }, "timestamp": { "type": "string", "format": "date-time", "example": "2026-06-12T08:00:00Z" } }, "required": [ "status", "version", "timestamp" ] } } } }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "tags": [ "API Health" ] } }, "/api/v1/workspaces/{workspaceId}/leads": { "get": { "summary": "List Leads", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 10 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of leads", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedLeadResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "ApiKeyAuth": [] }, { "OAuth2Bearer": [] } ], "tags": [ "Leads" ] }, "post": { "summary": "Create Lead", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKeyHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeadInput" } } } }, "responses": { "201": { "description": "Lead created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeadResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "409": { "$ref": "#/components/responses/ConflictError" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "ApiKeyAuth": [] }, { "OAuth2Bearer": [] } ], "tags": [ "Leads" ] } }, "/api/v1/workspaces/{workspaceId}/leads/{leadId}": { "get": { "summary": "Get Lead Details", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "leadId", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IfNoneMatchHeader" } ], "responses": { "200": { "description": "Lead details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeadResponse" } } }, "headers": { "ETag": { "description": "Weak entity tag for cache validation (W/\"-\")", "schema": { "type": "string" } } } }, "304": { "$ref": "#/components/responses/NotModified" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "ApiKeyAuth": [] }, { "OAuth2Bearer": [] } ], "tags": [ "Leads" ], "description": "Supports conditional GET via If-None-Match. Response includes an ETag header derived from updatedAt." }, "put": { "summary": "Update Lead", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "leadId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeadInput" } } } }, "responses": { "200": { "description": "Lead updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeadResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "ApiKeyAuth": [] }, { "OAuth2Bearer": [] } ], "tags": [ "Leads" ] } }, "/api/v1/workspaces/{workspaceId}/leads/sync": { "get": { "summary": "Incremental Leads Synchronization", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "updated_since", "in": "query", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Chronological sync list of leads", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedLeadResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "ApiKeyAuth": [] }, { "OAuth2Bearer": [] } ], "tags": [ "Leads" ] } }, "/api/v1/workspaces/{workspaceId}/leads/recent": { "get": { "summary": "Recent Leads", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "hours", "in": "query", "schema": { "type": "integer", "default": 12 } } ], "responses": { "200": { "description": "Recent leads list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedLeadResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "ApiKeyAuth": [] }, { "OAuth2Bearer": [] } ], "tags": [ "Leads" ] } }, "/api/v1/workspaces/{workspaceId}/leads/bulk": { "post": { "summary": "Bulk Lead Import", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKeyHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "leads": { "type": "array", "items": { "$ref": "#/components/schemas/LeadInput" } } }, "required": [ "leads" ] } } } }, "responses": { "201": { "description": "Leads imported successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkImportResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "ApiKeyAuth": [] }, { "OAuth2Bearer": [] } ], "tags": [ "Leads" ] } }, "/api/v1/workspaces/{workspaceId}/leads/{leadId}/comments": { "get": { "summary": "Get Lead Comments", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "leadId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Comments list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommentListResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "ApiKeyAuth": [] }, { "OAuth2Bearer": [] } ], "tags": [ "Leads" ] }, "post": { "summary": "Add Lead Comment", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "leadId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string" } }, "required": [ "content" ] } } } }, "responses": { "201": { "description": "Comment added successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommentResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "ApiKeyAuth": [] }, { "OAuth2Bearer": [] } ], "tags": [ "Leads" ] } }, "/api/v1/workspaces/{workspaceId}/leads/{leadId}/archive": { "post": { "summary": "Archive Lead", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "leadId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Lead archived successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionSuccessResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "ApiKeyAuth": [] }, { "OAuth2Bearer": [] } ], "tags": [ "Leads" ] } }, "/api/v1/workspaces/{workspaceId}/properties": { "get": { "summary": "List Properties", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 10 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of properties", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedPropertyResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "ApiKeyAuth": [] }, { "OAuth2Bearer": [] } ], "tags": [ "Properties" ] }, "post": { "summary": "Create Property", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKeyHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PropertyInput" } } } }, "responses": { "201": { "description": "Property created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PropertyResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "ApiKeyAuth": [] }, { "OAuth2Bearer": [] } ], "tags": [ "Properties" ] } }, "/api/v1/workspaces/{workspaceId}/properties/{propertyId}": { "get": { "summary": "Get Property Details", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "propertyId", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IfNoneMatchHeader" } ], "responses": { "200": { "description": "Property details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PropertyResponse" } } }, "headers": { "ETag": { "description": "Weak entity tag for cache validation (W/\"-\")", "schema": { "type": "string" } } } }, "304": { "$ref": "#/components/responses/NotModified" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "ApiKeyAuth": [] }, { "OAuth2Bearer": [] } ], "tags": [ "Properties" ], "description": "Supports conditional GET via If-None-Match. Response includes an ETag header derived from updatedAt." }, "put": { "summary": "Update Property", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "propertyId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PropertyInput" } } } }, "responses": { "200": { "description": "Property updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PropertyResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "ApiKeyAuth": [] }, { "OAuth2Bearer": [] } ], "tags": [ "Properties" ] } }, "/api/v1/workspaces/{workspaceId}/properties/inventory": { "get": { "summary": "Property Inventory List", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Inventory details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PropertyInventoryResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "ApiKeyAuth": [] }, { "OAuth2Bearer": [] } ], "tags": [ "Properties" ] } }, "/api/v1/workspaces/{workspaceId}/properties/availability": { "get": { "summary": "Property Availability List", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Availability details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PropertyAvailabilityResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "ApiKeyAuth": [] }, { "OAuth2Bearer": [] } ], "tags": [ "Properties" ] } }, "/api/v1/workspaces/{workspaceId}/properties/{propertyId}/units": { "get": { "summary": "List Property Units", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "propertyId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Units list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnitListResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "ApiKeyAuth": [] }, { "OAuth2Bearer": [] } ], "tags": [ "Properties" ] } }, "/api/v1/workspaces/{workspaceId}/properties/{propertyId}/towers": { "get": { "summary": "List Property Towers", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "propertyId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Towers list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TowerListResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "ApiKeyAuth": [] }, { "OAuth2Bearer": [] } ], "tags": [ "Properties" ] } }, "/api/v1/workspaces/{workspaceId}/properties/sync": { "get": { "summary": "Incremental Property Sync", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sync list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedPropertyResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "ApiKeyAuth": [] }, { "OAuth2Bearer": [] } ], "tags": [ "Properties" ] } }, "/api/v1/workspaces/{workspaceId}/contacts": { "get": { "summary": "List Contacts", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 10 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of contacts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedContactResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "ApiKeyAuth": [] }, { "OAuth2Bearer": [] } ], "tags": [ "Contacts" ] }, "post": { "summary": "Create Contact", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKeyHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactInput" } } } }, "responses": { "201": { "description": "Contact created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "409": { "$ref": "#/components/responses/ConflictError" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "ApiKeyAuth": [] }, { "OAuth2Bearer": [] } ], "tags": [ "Contacts" ] } }, "/api/v1/workspaces/{workspaceId}/contacts/{id}": { "get": { "summary": "Get Contact Details", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IfNoneMatchHeader" } ], "responses": { "200": { "description": "Contact details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactResponse" } } }, "headers": { "ETag": { "description": "Weak entity tag for cache validation (W/\"-\")", "schema": { "type": "string" } } } }, "304": { "$ref": "#/components/responses/NotModified" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "ApiKeyAuth": [] }, { "OAuth2Bearer": [] } ], "tags": [ "Contacts" ], "description": "Supports conditional GET via If-None-Match. Response includes an ETag header derived from updatedAt." }, "put": { "summary": "Update Contact", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactInput" } } } }, "responses": { "200": { "description": "Contact updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "ApiKeyAuth": [] }, { "OAuth2Bearer": [] } ], "tags": [ "Contacts" ] } }, "/api/v1/workspaces/{workspaceId}/contacts/sync": { "get": { "summary": "Sync Contacts", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sync list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedContactResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "ApiKeyAuth": [] }, { "OAuth2Bearer": [] } ], "tags": [ "Contacts" ] } }, "/api/v1/workspaces/{workspaceId}/contacts/recent": { "get": { "summary": "Recent Contacts", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Recent list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedContactResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "ApiKeyAuth": [] }, { "OAuth2Bearer": [] } ], "tags": [ "Contacts" ] } }, "/api/v1/workspaces/{workspaceId}/contacts/bulk": { "post": { "summary": "Bulk Contact Import", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "contacts": { "type": "array", "items": { "$ref": "#/components/schemas/ContactInput" } } }, "required": [ "contacts" ] } } } }, "responses": { "201": { "description": "Bulk success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkImportResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "ApiKeyAuth": [] }, { "OAuth2Bearer": [] } ], "tags": [ "Contacts" ] } }, "/api/v1/workspaces/{workspaceId}/contacts/{id}/archive": { "post": { "summary": "Archive Contact", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Contact archived successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionSuccessResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "ApiKeyAuth": [] }, { "OAuth2Bearer": [] } ], "tags": [ "Contacts" ] } }, "/api/v1/workspaces/{workspaceId}/customers": { "get": { "summary": "List Customers", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 10 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of customers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedCustomerResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "ApiKeyAuth": [] }, { "OAuth2Bearer": [] } ], "tags": [ "Customers" ] }, "post": { "summary": "Create Customer", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKeyHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerInput" } } } }, "responses": { "201": { "description": "Customer created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "409": { "$ref": "#/components/responses/ConflictError" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "ApiKeyAuth": [] }, { "OAuth2Bearer": [] } ], "tags": [ "Customers" ] } }, "/api/v1/workspaces/{workspaceId}/customers/{id}": { "get": { "summary": "Get Customer Details", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IfNoneMatchHeader" } ], "responses": { "200": { "description": "Customer details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerResponse" } } }, "headers": { "ETag": { "description": "Weak entity tag for cache validation (W/\"-\")", "schema": { "type": "string" } } } }, "304": { "$ref": "#/components/responses/NotModified" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "ApiKeyAuth": [] }, { "OAuth2Bearer": [] } ], "tags": [ "Customers" ], "description": "Supports conditional GET via If-None-Match. Response includes an ETag header derived from updatedAt." }, "put": { "summary": "Update Customer", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactInput" } } } }, "responses": { "200": { "description": "Customer updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "ApiKeyAuth": [] }, { "OAuth2Bearer": [] } ], "tags": [ "Customers" ] } }, "/api/v1/workspaces/{workspaceId}/customers/sync": { "get": { "summary": "Sync Customers", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sync list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedCustomerResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "ApiKeyAuth": [] }, { "OAuth2Bearer": [] } ], "tags": [ "Customers" ] } }, "/api/v1/workspaces/{workspaceId}/customers/recent": { "get": { "summary": "Recent Customers", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Recent list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedCustomerResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "ApiKeyAuth": [] }, { "OAuth2Bearer": [] } ], "tags": [ "Customers" ] } }, "/api/v1/workspaces/{workspaceId}/customers/bulk": { "post": { "summary": "Bulk Customer Import", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customers": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerInput" } } }, "required": [ "customers" ] } } } }, "responses": { "201": { "description": "Bulk success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkImportResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "ApiKeyAuth": [] }, { "OAuth2Bearer": [] } ], "tags": [ "Customers" ] } }, "/api/v1/workspaces/{workspaceId}/customers/{id}/archive": { "post": { "summary": "Archive Customer", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Customer archived successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionSuccessResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "ApiKeyAuth": [] }, { "OAuth2Bearer": [] } ], "tags": [ "Customers" ] } }, "/api/v1/workspaces/{workspaceId}/tasks": { "get": { "summary": "List Tasks", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 10 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of tasks", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedTaskResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "ApiKeyAuth": [] }, { "OAuth2Bearer": [] } ], "tags": [ "Tasks" ] }, "post": { "summary": "Create Task", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKeyHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskInput" } } } }, "responses": { "201": { "description": "Task created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "ApiKeyAuth": [] }, { "OAuth2Bearer": [] } ], "tags": [ "Tasks" ] } }, "/api/v1/workspaces/{workspaceId}/tasks/{id}": { "get": { "summary": "Get Task Details", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IfNoneMatchHeader" } ], "responses": { "200": { "description": "Task details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskResponse" } } }, "headers": { "ETag": { "description": "Weak entity tag for cache validation (W/\"-\")", "schema": { "type": "string" } } } }, "304": { "$ref": "#/components/responses/NotModified" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "ApiKeyAuth": [] }, { "OAuth2Bearer": [] } ], "tags": [ "Tasks" ], "description": "Supports conditional GET via If-None-Match. Response includes an ETag header derived from updatedAt." }, "put": { "summary": "Update Task", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskInput" } } } }, "responses": { "200": { "description": "Task updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "ApiKeyAuth": [] }, { "OAuth2Bearer": [] } ], "tags": [ "Tasks" ] } }, "/api/v1/workspaces/{workspaceId}/tasks/sync": { "get": { "summary": "Sync Tasks", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sync list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedTaskResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "ApiKeyAuth": [] }, { "OAuth2Bearer": [] } ], "tags": [ "Tasks" ] } }, "/api/v1/workspaces/{workspaceId}/tasks/recent": { "get": { "summary": "Recent Tasks", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Recent list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedTaskResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "ApiKeyAuth": [] }, { "OAuth2Bearer": [] } ], "tags": [ "Tasks" ] } }, "/api/v1/workspaces/{workspaceId}/tasks/{id}/complete": { "post": { "summary": "Complete Task", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Task completed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "ApiKeyAuth": [] }, { "OAuth2Bearer": [] } ], "tags": [ "Tasks" ] } }, "/api/v1/workspaces/{workspaceId}/tasks/{id}/reopen": { "post": { "summary": "Reopen Task", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Task reopened successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "ApiKeyAuth": [] }, { "OAuth2Bearer": [] } ], "tags": [ "Tasks" ] } }, "/api/v1/workspaces/{workspaceId}/tasks/{id}/archive": { "post": { "summary": "Archive Task", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Task archived successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionSuccessResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "ApiKeyAuth": [] }, { "OAuth2Bearer": [] } ], "tags": [ "Tasks" ] } }, "/api/v1/workspaces/{workspaceId}/team": { "get": { "summary": "Get Team Members", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of team members", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamMemberListResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "ApiKeyAuth": [] }, { "OAuth2Bearer": [] } ], "tags": [ "General" ] } }, "/api/v1/workspaces/{workspaceId}/inbound/leads": { "post": { "summary": "Inbound Lead Intake", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKeyHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeadInput" } } } }, "responses": { "201": { "description": "Lead captured successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionSuccessResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "ApiKeyAuth": [] }, { "OAuth2Bearer": [] } ], "tags": [ "Leads" ] } }, "/api/v1/workspaces/{workspaceId}/inbound/properties": { "post": { "summary": "Inbound Property Intake", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKeyHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PropertyInput" } } } }, "responses": { "201": { "description": "Property captured successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionSuccessResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "ApiKeyAuth": [] }, { "OAuth2Bearer": [] } ], "tags": [ "Properties" ] } }, "/api/v1/workspaces/{workspaceId}/inbound/contacts": { "post": { "summary": "Inbound Contact Intake", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKeyHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactInput" } } } }, "responses": { "201": { "description": "Contact captured successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionSuccessResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "ApiKeyAuth": [] }, { "OAuth2Bearer": [] } ], "tags": [ "Contacts" ] } }, "/api/v1/workspaces/{workspaceId}/webhooks": { "post": { "summary": "Create Webhook Subscription", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } } }, "required": [ "name", "url", "events" ] } } } }, "responses": { "201": { "description": "Webhook created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscriptionResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "ApiKeyAuth": [] }, { "OAuth2Bearer": [] } ], "tags": [ "Webhooks" ] }, "get": { "summary": "List Webhook Subscriptions", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of webhooks", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "_id": { "type": "string" }, "name": { "type": "string" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "isActive": { "type": "boolean" }, "createdAt": { "type": "string" } } } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "ApiKeyAuth": [] }, { "OAuth2Bearer": [] } ], "tags": [ "Webhooks" ] } }, "/api/v1/workspaces/{workspaceId}/webhooks/{id}": { "get": { "summary": "Get Webhook Details", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Webhook details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscriptionResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "ApiKeyAuth": [] }, { "OAuth2Bearer": [] } ], "tags": [ "Webhooks" ] }, "put": { "summary": "Update Webhook Subscription", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } } } } } } }, "responses": { "200": { "description": "Webhook updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscriptionResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "ApiKeyAuth": [] }, { "OAuth2Bearer": [] } ], "tags": [ "Webhooks" ] } }, "/api/v1/workspaces/{workspaceId}/webhooks/{id}/enable": { "post": { "summary": "Enable Webhook Subscription", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Webhook enabled successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionSuccessResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "ApiKeyAuth": [] }, { "OAuth2Bearer": [] } ], "tags": [ "Webhooks" ] } }, "/api/v1/workspaces/{workspaceId}/webhooks/{id}/disable": { "post": { "summary": "Disable Webhook Subscription", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Webhook disabled successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionSuccessResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "ApiKeyAuth": [] }, { "OAuth2Bearer": [] } ], "tags": [ "Webhooks" ] } }, "/api/v1/workspaces/{workspaceId}/webhooks/{id}/test": { "post": { "summary": "Send Test Webhook Event", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Test event dispatched", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionSuccessResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "ApiKeyAuth": [] }, { "OAuth2Bearer": [] } ], "tags": [ "Webhooks" ] } }, "/api/v1/workspaces/{workspaceId}/webhooks/{id}/deliveries": { "get": { "summary": "Get Webhook Delivery Logs", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20 } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } } ], "responses": { "200": { "description": "Delivery logs paginated list", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "_id": { "type": "string" }, "subscriptionId": { "type": "string" }, "event": { "type": "string" }, "payload": { "type": "object" }, "statusCode": { "type": "integer" }, "responseBody": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } } } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "ApiKeyAuth": [] }, { "OAuth2Bearer": [] } ], "tags": [ "Webhooks" ] } }, "/api/v1/workspaces/{workspaceId}/metadata/lead-statuses": { "get": { "summary": "Get Lead Statuses", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of lead status keys", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "type": "string" }, "example": [ "new", "contacted", "interested", "lost", "won" ] } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "ApiKeyAuth": [] }, { "OAuth2Bearer": [] } ], "tags": [ "Sync & Metadata" ] } }, "/api/v1/workspaces/{workspaceId}/metadata/lead-stages": { "get": { "summary": "Get Lead Stages", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of active lead stages with layout properties", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "stageKey": { "type": "string" }, "displayName": { "type": "string" }, "color": { "type": "string" }, "position": { "type": "integer" } } } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "ApiKeyAuth": [] }, { "OAuth2Bearer": [] } ], "tags": [ "Sync & Metadata" ] } }, "/api/v1/workspaces/{workspaceId}/metadata/sources": { "get": { "summary": "Get Lead Sources", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of configured lead sources", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "type": "string" }, "example": [ "website", "referral", "manual" ] } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "ApiKeyAuth": [] }, { "OAuth2Bearer": [] } ], "tags": [ "Sync & Metadata" ] } }, "/api/v1/workspaces/{workspaceId}/metadata/tags": { "get": { "summary": "Get Lead Tags", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of active tags in the workspace", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "type": "string" } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "ApiKeyAuth": [] }, { "OAuth2Bearer": [] } ], "tags": [ "Sync & Metadata" ] } }, "/api/v1/workspaces/{workspaceId}/metadata/property-types": { "get": { "summary": "Get Property Types", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of configured property types", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "type": "string" }, "example": [ "Apartment", "Villa", "Plot" ] } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "ApiKeyAuth": [] }, { "OAuth2Bearer": [] } ], "tags": [ "Sync & Metadata" ] } }, "/api/v1/workspaces/{workspaceId}": { "get": { "summary": "Get Workspace Info", "description": "Fetch details about the workspace including active modules and configurations.", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Workspace settings", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "workspaceId": { "type": "string" }, "workspaceName": { "type": "string" }, "timezone": { "type": "string" }, "currency": { "type": "string" }, "modules": { "type": "array", "items": { "type": "string" } } } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "ApiKeyAuth": [] }, { "OAuth2Bearer": [] } ], "tags": [ "Workspace" ] } }, "/api/v1/workspaces/{workspaceId}/leads/check-duplicate": { "post": { "summary": "Check Duplicate Lead", "description": "Verify if a lead with the same phone number already exists in this workspace.", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "type": "string", "example": "+919876543210" } }, "required": [ "phone" ] } } } }, "responses": { "200": { "description": "Duplicate check result", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "exists": { "type": "boolean", "example": true }, "leadId": { "type": "string", "nullable": true } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "ApiKeyAuth": [] }, { "OAuth2Bearer": [] } ], "tags": [ "Leads" ] } }, "/api/v1/workspaces/{workspaceId}/schema": { "get": { "summary": "Workspace Schema Discovery", "description": "Returns definitions of standard and custom fields for leads, contacts, and customers in the workspace.", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Workspace field schemas", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "leadFields": { "type": "array", "items": { "type": "object", "properties": { "fieldKey": { "type": "string", "example": "customField_123" }, "displayName": { "type": "string", "example": "Secondary Phone" }, "type": { "type": "string", "example": "text" }, "required": { "type": "boolean", "example": false }, "isCustom": { "type": "boolean", "example": true }, "options": { "type": "array", "items": { "type": "string" } } } } }, "contactFields": { "type": "array", "items": { "type": "object", "properties": { "fieldKey": { "type": "string", "example": "company_name" }, "displayName": { "type": "string", "example": "Company" }, "type": { "type": "string", "example": "text" }, "required": { "type": "boolean", "example": false }, "isCustom": { "type": "boolean", "example": false }, "options": { "type": "array", "items": { "type": "string" } } } } }, "customerFields": { "type": "array", "items": { "type": "object", "properties": { "fieldKey": { "type": "string", "example": "customField_123" }, "displayName": { "type": "string", "example": "Secondary Phone" }, "type": { "type": "string", "example": "text" }, "required": { "type": "boolean", "example": false }, "isCustom": { "type": "boolean", "example": true }, "options": { "type": "array", "items": { "type": "string" } } } } } } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "ApiKeyAuth": [] }, { "OAuth2Bearer": [] } ], "tags": [ "Sync & Metadata" ] } }, "/api/workspaces/{workspaceId}/developer/api-keys": { "get": { "summary": "List API Keys", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "API key list", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "_id": { "type": "string" }, "name": { "type": "string" }, "clientId": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string" }, "createdAt": { "type": "string" } } } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "SessionAuth": [] } ], "tags": [ "Developer Portal" ] }, "post": { "summary": "Create API Key", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "Granular scopes. Defaults to lead.read, lead.write, metadata.read if omitted. admin scope is not permitted." } }, "required": [ "name" ] } } } }, "responses": { "201": { "description": "API key created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string" }, "data": { "type": "object", "properties": { "_id": { "type": "string" }, "name": { "type": "string" }, "clientId": { "type": "string" }, "clientSecret": { "type": "string" }, "apiKey": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } } } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "SessionAuth": [] } ], "tags": [ "Developer Portal" ] } }, "/api/workspaces/{workspaceId}/developer/api-keys/{id}/rotate": { "post": { "summary": "Rotate API Key Credentials", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "API key credentials rotated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string" }, "data": { "type": "object", "properties": { "_id": { "type": "string" }, "clientId": { "type": "string" }, "clientSecret": { "type": "string" }, "apiKey": { "type": "string" } } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "SessionAuth": [] } ], "tags": [ "Developer Portal" ] } }, "/api/workspaces/{workspaceId}/developer/api-keys/{id}": { "delete": { "summary": "Delete API Key", "description": "Permanently deletes (revokes) an API key. Requires workspace admin session authentication.", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "API key deleted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionSuccessResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "SessionAuth": [] } ], "tags": [ "Developer Portal" ] } }, "/api/v1/workspaces/{workspaceId}/whatsapp/send/text": { "post": { "summary": "Send WhatsApp Text Message", "tags": [ "WhatsApp" ], "security": [ { "ApiKeyAuth": [] }, { "OAuth2Bearer": [] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "to": { "type": "string" }, "body": { "type": "string" } }, "required": [ "to", "body" ] } } } }, "responses": { "200": { "description": "Message sent successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "wamid": { "type": "string", "example": "wamid.HBg..." }, "message": { "type": "object", "properties": { "workspaceId": { "type": "string" }, "conversationId": { "type": "string" }, "direction": { "type": "string", "example": "outbound" }, "from": { "type": "string" }, "to": { "type": "string" }, "type": { "type": "string" }, "body": { "type": "string" }, "status": { "type": "string", "example": "accepted" }, "timestamp": { "type": "string", "format": "date-time" } } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/workspaces/{workspaceId}/whatsapp/send/template": { "post": { "summary": "Send WhatsApp Template Message", "tags": [ "WhatsApp" ], "security": [ { "ApiKeyAuth": [] }, { "OAuth2Bearer": [] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "to": { "type": "string" }, "name": { "type": "string" }, "language": { "type": "string" }, "components": { "type": "array", "items": { "type": "object" } }, "variables": { "type": "array", "items": { "type": "string" } } }, "required": [ "to", "name", "language" ] } } } }, "responses": { "200": { "description": "Template message sent successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "wamid": { "type": "string", "example": "wamid.HBg..." }, "message": { "type": "object", "properties": { "workspaceId": { "type": "string" }, "conversationId": { "type": "string" }, "direction": { "type": "string", "example": "outbound" }, "from": { "type": "string" }, "to": { "type": "string" }, "type": { "type": "string" }, "body": { "type": "string" }, "status": { "type": "string", "example": "accepted" }, "timestamp": { "type": "string", "format": "date-time" } } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/workspaces/{workspaceId}/whatsapp/conversations": { "get": { "summary": "Get WhatsApp Conversations", "tags": [ "WhatsApp" ], "security": [ { "ApiKeyAuth": [] }, { "OAuth2Bearer": [] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer" } }, { "name": "search", "in": "query", "schema": { "type": "string" } }, { "name": "status", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of conversations", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "conversations": { "type": "array", "items": { "type": "object", "properties": { "_id": { "type": "string" }, "customerWaId": { "type": "string" }, "customerName": { "type": "string" }, "customerPhone": { "type": "string" }, "lastMessagePreview": { "type": "string" }, "lastMessageDirection": { "type": "string", "example": "inbound" } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/workspaces/{workspaceId}/whatsapp/templates/sync": { "post": { "summary": "Sync WhatsApp Templates", "tags": [ "WhatsApp" ], "security": [ { "ApiKeyAuth": [] }, { "OAuth2Bearer": [] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Templates synchronized successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Templates synchronized" }, "data": { "type": "array", "items": { "type": "object", "properties": { "_id": { "type": "string" }, "name": { "type": "string", "example": "qvoo_hello" }, "language": { "type": "string", "example": "en" }, "category": { "type": "string", "example": "MARKETING" }, "components": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "text": { "type": "string" } } } } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/workspaces/{workspaceId}/whatsapp/templates": { "get": { "summary": "List WhatsApp Templates", "tags": [ "WhatsApp" ], "security": [ { "ApiKeyAuth": [] }, { "OAuth2Bearer": [] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of WhatsApp templates", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "_id": { "type": "string" }, "name": { "type": "string", "example": "qvoo_hello" }, "language": { "type": "string", "example": "en" }, "category": { "type": "string", "example": "MARKETING" }, "components": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "text": { "type": "string" } } } } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } } }, "webhooks": { "lead.created": { "post": { "summary": "Lead Created Event", "description": "Triggered when a new lead is created in the workspace.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Lead" } } } }, "responses": { "200": { "description": "Event received successfully" } } } }, "lead.updated": { "post": { "summary": "Lead Updated Event", "description": "Triggered when any field on an existing lead is modified.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Lead" } } } }, "responses": { "200": { "description": "Event received successfully" } } } }, "contact.created": { "post": { "summary": "Contact Created Event", "description": "Triggered when a new contact is added to the workspace.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Contact" } } } }, "responses": { "200": { "description": "Event received successfully" } } } }, "contact.updated": { "post": { "summary": "Contact Updated Event", "description": "Triggered when an existing contact details are updated.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Contact" } } } }, "responses": { "200": { "description": "Event received successfully" } } } }, "customer.created": { "post": { "summary": "Customer Created Event", "description": "Triggered when a lead is converted to a successful customer.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" } } } }, "responses": { "200": { "description": "Event received successfully" } } } }, "customer.updated": { "post": { "summary": "Customer Updated Event", "description": "Triggered when an existing customer details are updated.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" } } } }, "responses": { "200": { "description": "Event received successfully" } } } }, "property.created": { "post": { "summary": "Property Created Event", "description": "Triggered when a new property listed in inventory.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Property" } } } }, "responses": { "200": { "description": "Event received successfully" } } } }, "property.updated": { "post": { "summary": "Property Updated Event", "description": "Triggered when details of a property listed in inventory are modified.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Property" } } } }, "responses": { "200": { "description": "Event received successfully" } } } }, "task.created": { "post": { "summary": "Task Created Event", "description": "Triggered when a new task is created and assigned.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Task" } } } }, "responses": { "200": { "description": "Event received successfully" } } } }, "task.completed": { "post": { "summary": "Task Completed Event", "description": "Triggered when a task status is changed to completed.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Task" } } } }, "responses": { "200": { "description": "Event received successfully" } } } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key" }, "OAuth2Bearer": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" }, "SessionAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "CRM session JWT obtained via login. Workspace admin role required. Used for Developer Portal routes only — not for Public API (X-API-Key / OAuth)." } }, "responses": { "UnauthorizedError": { "description": "401 Unauthorized - Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "ForbiddenError": { "description": "403 Forbidden - Access denied or developer module disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "NotFoundError": { "description": "404 Not Found - Requested resource was not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "ValidationError": { "description": "422 Validation Error - Request body failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "RateLimitError": { "description": "429 Rate Limit - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "InternalServerError": { "description": "500 Internal Server Error - An unexpected error occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "BadRequestError": { "description": "400 Bad Request - Missing required parameters or invalid formatting", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "ConflictError": { "description": "409 Conflict - Resource already exists / Duplicate check failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictResponse" } } } }, "MethodNotAllowedError": { "description": "405 Method Not Allowed — DELETE is not supported on the Public API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "success": false, "error": "DELETE is not supported on the Public API. Records cannot be deleted via this API." } } } }, "NotModified": { "description": "304 Not Modified — resource unchanged since If-None-Match ETag" } }, "schemas": { "CustomFields": { "type": "object", "description": "Dynamic custom fields configured by the workspace admin. This includes conditional fields, hierarchical fields, and standard primitives.", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "items": { "type": "string" } }, { "type": "object", "description": "Used for hierarchical fields (e.g., location tree: country -> state -> city)" } ] } }, "LeadInput": { "type": "object", "properties": { "name": { "type": "string" }, "status": { "type": "string" }, "leadStage": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "description": { "type": "string" }, "fields": { "$ref": "#/components/schemas/CustomFields", "description": "Optional on create when workspace required-field rules do not mandate specific custom fields." }, "mobileNumber": { "type": "string", "description": "Primary mobile number of the lead (triggers duplicate check)", "example": "+919876543210" } }, "required": [ "name", "mobileNumber" ] }, "Lead": { "allOf": [ { "$ref": "#/components/schemas/LeadInput" }, { "type": "object", "properties": { "_id": { "type": "string" }, "workspaceId": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } } } ] }, "PropertyInput": { "type": "object", "description": "Properties in Qvoo support strict:false in MongoDB, meaning custom fields are stored directly at the root of the document.", "properties": { "title": { "type": "string", "example": "Ocean Breeze Apartments - Unit 402" }, "price": { "type": "number", "minimum": 0, "example": 12500000 }, "currency": { "type": "string", "example": "INR" }, "propertyType": { "type": "string", "example": "Apartment" }, "salesType": { "type": "array", "items": { "type": "string" }, "example": [ "sale" ] }, "subtype": { "type": "string", "example": "3BHK" }, "city": { "type": "string", "example": "Mumbai" }, "state": { "type": "string", "example": "Maharashtra" }, "country": { "type": "string", "example": "India" }, "area": { "type": "string", "example": "Worli" }, "assignedTo": { "type": "string", "description": "User ID of the assigned team member (24-char hex)", "example": "65b8c47f4e2cfc1df3a75222" } }, "additionalProperties": true, "required": [ "title", "price", "currency", "propertyType", "salesType", "subtype", "city", "state", "country", "area" ] }, "Property": { "allOf": [ { "$ref": "#/components/schemas/PropertyInput" }, { "type": "object", "properties": { "_id": { "type": "string" }, "workspaceId": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } } } ] }, "ContactInput": { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "fields": { "$ref": "#/components/schemas/CustomFields" }, "mobileNumber": { "type": "string", "description": "Primary mobile number of the contact (triggers duplicate check)", "example": "+919876543210" } }, "required": [ "name", "mobileNumber" ] }, "Contact": { "allOf": [ { "$ref": "#/components/schemas/ContactInput" }, { "type": "object", "properties": { "_id": { "type": "string" }, "workspaceId": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } } } ] }, "Customer": { "allOf": [ { "$ref": "#/components/schemas/CustomerInput" }, { "type": "object", "properties": { "_id": { "type": "string" }, "workspaceId": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } } } ] }, "TaskInput": { "type": "object", "properties": { "title": { "type": "string" }, "description": { "type": "string" }, "dueDate": { "type": "string", "format": "date-time" }, "status": { "type": "string", "enum": [ "TODO", "Active", "In Progress", "Completed" ], "example": "TODO" }, "priority": { "type": "string", "enum": [ "Low", "Medium", "High", "Urgent" ], "example": "Medium" }, "assignedTo": { "type": "string", "description": "User ID of the assigned team member (24-char hex)", "example": "65b8c47f4e2cfc1df3a75222" } }, "required": [ "title", "assignedTo" ] }, "Task": { "allOf": [ { "$ref": "#/components/schemas/TaskInput" }, { "type": "object", "properties": { "_id": { "type": "string" }, "workspaceId": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } } } ] }, "TeamMember": { "type": "object", "properties": { "_id": { "type": "string" }, "userId": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "role": { "type": "string" }, "phone": { "type": "string" }, "workspaceId": { "type": "string" }, "createdAt": { "type": "string" } } }, "Activity": { "type": "object", "properties": { "_id": { "type": "string" }, "workspaceId": { "type": "string" }, "userId": { "type": "string" }, "leadId": { "type": "string" }, "type": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "createdAt": { "type": "string" } } }, "Note": { "type": "object", "properties": { "_id": { "type": "string" }, "workspaceId": { "type": "string" }, "leadId": { "type": "string" }, "content": { "type": "string" }, "createdBy": { "type": "string" }, "createdAt": { "type": "string" } } }, "Comment": { "type": "object", "properties": { "_id": { "type": "string" }, "workspaceId": { "type": "string" }, "leadId": { "type": "string" }, "content": { "type": "string" }, "createdBy": { "type": "string" }, "createdAt": { "type": "string" } } }, "ErrorResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "Error description" } }, "required": [ "success", "error" ] }, "ValidationErrorResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "Validation failed" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "success", "error" ] }, "TokenResponse": { "type": "object", "properties": { "access_token": { "type": "string", "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." }, "refresh_token": { "type": "string", "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." }, "token_type": { "type": "string", "example": "Bearer" }, "expires_in": { "type": "integer", "example": 3600 }, "scope": { "type": "string", "example": "read write" } }, "required": [ "access_token", "refresh_token", "token_type", "expires_in" ] }, "ActionSuccessResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Operation completed successfully" } }, "required": [ "success", "message" ] }, "BulkImportResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "count": { "type": "integer", "example": 5, "description": "Number of leads successfully created" }, "skippedDuplicates": { "type": "integer", "example": 2, "description": "Rows skipped (duplicate or validation failure)" }, "data": { "type": "array", "items": { "type": "object" }, "description": "Created lead documents" }, "results": { "type": "array", "description": "Per-row outcome for each input lead (index matches request array order)", "items": { "type": "object", "properties": { "index": { "type": "integer", "example": 0 }, "status": { "type": "string", "enum": [ "created", "skipped", "error" ], "example": "created" }, "leadId": { "type": "string", "nullable": true, "example": "607f1f77bcf86cd799439011" }, "error": { "type": "string", "nullable": true, "example": "Duplicate mobile number" } }, "required": [ "index", "status" ] } } }, "required": [ "success", "count", "results" ] }, "PaginatedLeadResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Lead" } }, "nextCursor": { "type": "string", "nullable": true, "example": "eyJ1IjoiMjAyNi0wNi0xMlQxMzowOTowM1oiLCJpIjoiNjA3ZjRmOGEzYzMzIn0" } }, "required": [ "success", "data" ] }, "LeadResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Lead" } }, "required": [ "success", "data" ] }, "PaginatedPropertyResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Property" } }, "nextCursor": { "type": "string", "nullable": true, "example": "eyJ1IjoiMjAyNi0wNi0xMlQxMzowOTowM1oiLCJpIjoiNjA3ZjRmOGEzYzMzIn0" } }, "required": [ "success", "data" ] }, "PropertyResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Property" } }, "required": [ "success", "data" ] }, "PaginatedContactResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Contact" } }, "nextCursor": { "type": "string", "nullable": true, "example": "eyJ1IjoiMjAyNi0wNi0xMlQxMzowOTowM1oiLCJpIjoiNjA3ZjRmOGEzYzMzIn0" } }, "required": [ "success", "data" ] }, "ContactResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Contact" } }, "required": [ "success", "data" ] }, "PaginatedCustomerResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Customer" } }, "nextCursor": { "type": "string", "nullable": true, "example": "eyJ1IjoiMjAyNi0wNi0xMlQxMzowOTowM1oiLCJpIjoiNjA3ZjRmOGEzYzMzIn0" } }, "required": [ "success", "data" ] }, "CustomerResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Customer" } }, "required": [ "success", "data" ] }, "PaginatedTaskResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Task" } }, "nextCursor": { "type": "string", "nullable": true, "example": "eyJ1IjoiMjAyNi0wNi0xMlQxMzowOTowM1oiLCJpIjoiNjA3ZjRmOGEzYzMzIn0" } }, "required": [ "success", "data" ] }, "TaskResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Task" } }, "required": [ "success", "data" ] }, "NoteResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Note" } }, "required": [ "success", "data" ] }, "CommentResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Comment" } }, "required": [ "success", "data" ] }, "PropertyInventoryResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "type": "object" } } }, "required": [ "success", "data" ] }, "PropertyAvailabilityResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "type": "object" } } }, "required": [ "success", "data" ] }, "UnitListResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "type": "object" } } }, "required": [ "success", "data" ] }, "TowerListResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "type": "object" } } }, "required": [ "success", "data" ] }, "TeamMemberListResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "count": { "type": "integer", "example": 3 }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/TeamMember" } } }, "required": [ "success", "count", "data" ] }, "WebhookSubscriptionResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "_id": { "type": "string" }, "name": { "type": "string" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "workspaceId": { "type": "string" }, "createdAt": { "type": "string" } } } }, "required": [ "success", "data" ] }, "CustomerInput": { "type": "object", "properties": { "leadId": { "type": "string", "description": "The 24-character hex ID of the Lead associated with this customer", "example": "65b8c47f4e2cfc1df3a75111" }, "name": { "type": "string", "description": "Full name of the customer", "example": "Rahul Sharma" }, "assignedTo": { "oneOf": [ { "type": "string", "description": "User ID of the assigned team member" }, { "type": "array", "items": { "type": "string" }, "description": "Array of User IDs of the assigned team members" } ] }, "fields": { "$ref": "#/components/schemas/CustomFields" }, "selectedPropertyId": { "type": "string", "description": "ID of the property selected/purchased by the customer" }, "customPropertyName": { "type": "string", "description": "Custom name of the property if not in inventory" }, "dealDate": { "type": "string", "format": "date-time" }, "dealAmount": { "type": "number" }, "commissionAmount": { "type": "number" }, "successNotes": { "type": "string" } }, "required": [ "leadId", "name" ] }, "ConflictResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "Duplicate lead found" }, "duplicate": { "type": "object", "properties": { "leadId": { "type": "string", "example": "65b8c47f4e2cfc1df3a75111" }, "name": { "type": "string", "example": "Rahul Sharma" }, "createdAt": { "type": "string", "example": "2026-06-12T10:00:00.000Z" } } } }, "required": [ "success", "error" ] }, "AllowedApiScopes": { "type": "string", "enum": [ "lead.read", "lead.write", "property.read", "property.write", "contact.read", "contact.write", "customer.read", "customer.write", "task.read", "task.write", "webhook.manage", "metadata.read", "team.read" ] } }, "parameters": { "IdempotencyKeyHeader": { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (max 128 chars) for safe POST retries. Duplicate requests within 24 hours return the original response without creating a second record.", "schema": { "type": "string", "maxLength": 128, "example": "lead-create-abc123" } }, "IfNoneMatchHeader": { "name": "If-None-Match", "in": "header", "required": false, "description": "ETag from a prior GET response. When unchanged, server returns 304 Not Modified.", "schema": { "type": "string", "example": "W/\"2026-06-13T10:00:00.000Z-607f1f77bcf86cd799439011\"" } } } }, "tags": [ { "name": "API Health", "description": "Ensure the Qvoo CRM API services are online, responsive, and functioning correctly. The Health API provides lightweight, public endpoints to perform heartbeat checks and verify connectivity from your integration environments. It is recommended to use these endpoints to perform initial diagnostic checks before configuring credentials or testing core business logic." }, { "name": "OAuth 2.0", "description": "Manage access tokens, credentials, and authentication sessions for Qvoo CRM API integrations. Qvoo supports the Standard OAuth 2.0 Client Credentials Grant flow for secure, scoped server-to-server authorization. Use these endpoints to programmatically exchange client credentials for short-lived access tokens, refresh expired sessions, or revoke credentials to maintain robust API security." }, { "name": "Leads", "description": "Create, query, update, and archive sales leads. Supports bulk import with per-row results, duplicate checking, sync workflows, and inbound intake gateways. Custom fields are optional on create when workspace rules allow." }, { "name": "Properties", "description": "Access and manage Qvoo CRM's property inventory, units, towers, and real estate availability data. Properties represent physical assets, residential units, or commercial spaces tracked within the CRM. These endpoints allow you to search current listings, query units by tower, verify reservation status, and sync inventory changes with external property portals or MLS (Multiple Listing Services) networks." }, { "name": "Contacts", "description": "Manage individual contact records, communication preferences, and profiles. Contacts represent real people—such as leads, customers, partners, or vendors—associated with your workspace. Use these endpoints to associate contacts with customer accounts, manage touchpoints, update contact details, and synchronize address book lists with external email clients and marketing automation platforms." }, { "name": "Customers", "description": "Create and manage customer accounts, business entities, and organizations. Customers represent signed clients or active accounts that have transitioned from the lead stage. Use this API to track customer lifetime values, update billing addresses, manage organizational hierarchies, and coordinate account-management tasks across your success team." }, { "name": "Tasks", "description": "Track, assign, and manage actionable tasks, follow-up events, and sales goals. The Tasks API helps developers automate daily team workflows by programmatically creating tasks, scheduling deadlines, assigning owners, and updating completion statuses. Keep your team aligned and ensure no lead or customer relationship is neglected." }, { "name": "Users", "description": "Query team members and user profiles. Requires team.read scope. Adding or removing users is not available on the Public API." }, { "name": "Developer Portal", "description": "Workspace admin session-authenticated routes for API key lifecycle management. Base path: /api/workspaces/{workspaceId}/developer (no /v1). Not callable with X-API-Key — use CRM login session Bearer token." }, { "name": "Webhooks", "description": "Configure real-time event subscriptions to receive instant HTTP POST payloads when data changes in Qvoo CRM. Instead of polling our APIs, subscribe to webhook events for leads, properties, contacts, tasks, or customers. These endpoints let you register endpoint URLs, manage active subscriptions, and view delivery history to guarantee event-driven synchronization with your external systems." }, { "name": "Sync & Metadata", "description": "Inspect schema metadata, pipeline status mappings, custom field configurations, and lookup tables defined in your workspace. Because Qvoo CRM supports customizable sales stages, property types, and system tags, you should use these discovery endpoints to fetch active configurations programmatically, ensuring your data sync layers map fields correctly without hardcoded values." }, { "name": "Workspace", "description": "Retrieve general configuration settings, subscription details, and profile information for the active Qvoo CRM workspace. The Workspace API provides metadata about your organization, default localized currencies, timezones, and feature flags. This information is vital for configuring localized date formatting and currency handling in your external integrations." } ] }