{ "openapi": "3.0.0", "info": { "title": "Sakneen API", "description": "API for managing leads and other resources in the Sakneen system", "version": "1.0.0", "contact": { "name": "Sakneen Support", "email": "support@sakneen.com" } }, "servers": [ { "url": "https://your-assigned-api-host.invalid", "description": "Replace with the HTTPS origin assigned by Sakneen support. Do not append the API path." } ], "tags": [ { "name": "Health", "description": "API health and status monitoring" }, { "name": "Leads", "description": "Operations related to lead management" }, { "name": "Units", "description": "Operations related to property unit management" }, { "name": "Compounds", "description": "Operations related to compound/project management" }, { "name": "Reservations", "description": "Operations for external reservation upserts and reservation webhook updates" } ], "paths": { "/external/apis/v1.0/healthz": { "get": { "tags": [ "Health" ], "summary": "Health Check", "description": "Public connection check. A successful response verifies API availability and does not validate your API key.", "operationId": "healthCheck", "responses": { "200": { "description": "The API is healthy. No API key is required.", "content": { "application/json": { "schema": { "type": "object", "required": [ "description", "ok", "version" ], "properties": { "description": { "type": "string" }, "ok": { "type": "boolean" }, "version": { "type": "string" } } }, "example": { "description": "Backend APIs for the Sakneen platform", "ok": true, "version": "v1.0" } } } } }, "security": [] } }, "/external/apis/v1.0/leads": { "post": { "tags": [ "Leads" ], "summary": "Create or update lead", "description": "Creates a lead from the old flat payload or the newer data payload. All request body fields are optional. If recordSystemId is supplied, Sakneen upserts by that exact organization-scoped external lead or submission ID. If recordSystemId is omitted, each request creates a new lead. data is accepted without PUBLIC_CREATE_LEAD form validation, and values in data win over duplicate flat fields. additionalData is stored separately from lead data and merged across updates. leadSource is used only when the caller sends data.leadSource. The server validates duplicate phoneNumber and phoneNumber2 values with the same admin/sales rules; duplicate-phone validation is skipped when the organization allows conflict leads and returns 400 otherwise. When project is supplied, Sakneen links existing organization compounds whose translated name matches the project value case-insensitively for the request language. The server does not accept compound IDs and does not create compounds from this endpoint. Successful writes are logged as External Lead Create or External Lead Update with modifier External API and source API.", "operationId": "upsertLead", "parameters": [ { "name": "language", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional language used for translated project-name compound matching. Defaults to en-us.", "example": "en-us" }, { "name": "Content-Type", "in": "header", "required": true, "schema": { "type": "string" }, "example": "application/json" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "recordSystemId": { "type": "string", "description": "Optional stable external lead or submission ID. When supplied, the server uses the exact value for org-scoped upsert and delete. The same value in different organizations maps to different leads. The server never generates or normalizes this value.", "example": "alkarma-website-form-uuid-123" }, "data": { "type": "object", "description": "Optional arbitrary lead fields accepted without PUBLIC_CREATE_LEAD form validation. Values in data override duplicate old flat fields. Send data.leadSource when a lead source should be stored. Send project when compound linking is needed. phoneNumber and phoneNumber2 are checked for duplicates when the organization does not allow conflict leads.", "additionalProperties": true, "example": { "name": "Ahmed Hassan", "phoneNumber": "+201001234567", "email": "ahmed@example.com", "project": "North Coast" } }, "additionalData": { "type": "object", "description": "Optional free-form metadata stored separately from lead data. Sakneen stores this as-is, merges it across updates, and does not use it for client, assignment, or compound logic.", "additionalProperties": true, "example": { "externalScore": 87, "tags": [ "vip", "returning" ] } }, "name": { "type": "string", "description": "Optional old flat lead name field.", "example": "Ahmed Hassan" }, "email": { "type": "string", "format": "email", "description": "Optional old flat email field.", "example": "ahmed@example.com" }, "phoneNumber": { "type": "string", "description": "Optional old flat phone number field.", "example": "+201001234567" }, "project": { "type": "string", "description": "Optional old flat project field. When supplied, Sakneen links existing organization compounds by translated compound name for the request language. The server does not accept compound IDs and does not create compounds.", "example": "North Coast" } } }, "examples": { "oldFlatPayload": { "summary": "Old flat create payload", "value": { "name": "Jane Smith", "phoneNumber": "+201001234567", "email": "jane@example.com", "project": "North Coast" } }, "crmLead": { "summary": "CRM lead ID", "value": { "recordSystemId": "crm-lead-00163EAB688B", "data": { "name": "Jane Smith", "phoneNumber": "+201001234567", "email": "jane@example.com", "leadSource": "CRM", "project": "North Coast" } } }, "directWebsiteSubmission": { "summary": "Direct website submission ID", "value": { "recordSystemId": "alkarma-website-form-018f9f29-4b8a-7c1a", "data": { "name": "Ahmed Hassan", "phoneNumber": "+201001234568", "email": "ahmed@example.com", "project": "North Coast" }, "additionalData": { "providerSubmissionId": "018f9f29-4b8a-7c1a", "campaign": "summer-launch" } } }, "additionalData": { "summary": "Lead with separate additionalData", "value": { "recordSystemId": "website-form-extra-001", "data": { "name": "Extra Data Lead", "phoneNumber": "+201001234599", "status": "new" }, "additionalData": { "externalScore": 87, "tags": [ "vip" ] } } }, "mixedPayload": { "summary": "Mixed old flat and data payload", "value": { "recordSystemId": "website-form-uuid-123", "name": "Fallback Name", "phoneNumber": "+201001234567", "data": { "name": "Dynamic Name", "campaign": "spring-launch" } } } } } } }, "responses": { "201": { "description": "Created or updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "operation": { "type": "string", "enum": [ "create", "update" ] }, "lead": { "type": "object" }, "newLead": { "type": "object", "description": "Compatibility copy of the lead object kept for earlier create-only callers." } } }, "example": { "ok": true, "operation": "create", "lead": { "_id": "64f1234567890abcdef123456", "leadId": 1001, "recordSystemId": "alkarma-website-form-018f9f29-4b8a-7c1a", "compoundsIds": [ "64f1234567890abcdef123450" ], "data": { "name": "Ahmed Hassan", "phoneNumber": "+201001234568", "email": "ahmed@example.com", "project": "North Coast" }, "additionalData": { "providerSubmissionId": "018f9f29-4b8a-7c1a", "campaign": "summer-launch" } }, "newLead": { "_id": "64f1234567890abcdef123456", "leadId": 1001, "recordSystemId": "alkarma-website-form-018f9f29-4b8a-7c1a", "compoundsIds": [ "64f1234567890abcdef123450" ], "data": { "name": "Ahmed Hassan", "phoneNumber": "+201001234568", "email": "ahmed@example.com", "project": "North Coast" }, "additionalData": { "providerSubmissionId": "018f9f29-4b8a-7c1a", "campaign": "summer-launch" } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } }, { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "string" } } } ] }, "error": { "type": "string" }, "statusCode": { "type": "integer" } } }, "examples": { "invalidEmail": { "summary": "Invalid flat email", "value": { "message": [ "email must be an email" ], "error": "Bad Request", "statusCode": 400 } }, "duplicatePhone": { "summary": "Duplicate phone when conflict leads are disabled", "value": { "message": [ "Duplicate Lead: Existing Lead (+201001234567) exists. and is not assigned to anyone." ], "error": "Bad Request", "statusCode": 400 } } } } } }, "401": { "description": "API key missing, invalid, disabled, or not enabled for external access.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "statusCode": { "type": "integer" } } }, "example": { "message": "Access Denied, API key not valid", "statusCode": 401 } } } } } } }, "/external/apis/v1.0/units": { "post": { "tags": [ "Units" ], "summary": "Create or update a unit", "description": "Create a new property unit or update an existing one in the system", "operationId": "createUnit", "parameters": [ { "name": "Content-Type", "in": "header", "required": true, "schema": { "type": "string" }, "example": "application/json" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "recordSystemId", "unitId" ], "properties": { "recordSystemId": { "type": "string", "description": "Unique system identifier for the record" }, "unitId": { "type": "string", "description": "Unique identifier for the unit" }, "price": { "type": "number", "description": "Price of the unit", "minimum": 0 }, "bua": { "type": "number", "description": "Built-up area in square meters", "minimum": 0 }, "propertyType": { "type": "string", "description": "External propertyType value. Confirm your organization’s supported names and mappings with Sakneen support." }, "status": { "type": "string", "description": "External status value. Confirm your organization’s supported names and mappings with Sakneen support." }, "bedrooms": { "type": "integer", "description": "Number of bedrooms", "minimum": 0 }, "bathrooms": { "type": "integer", "description": "Number of bathrooms", "minimum": 0 }, "finishingType": { "type": "string", "description": "External finishingType value. Confirm your organization’s supported names and mappings with Sakneen support." }, "floor": { "type": "string", "example": "2" }, "amenities": { "type": "array", "items": { "type": "string" }, "description": "List of amenities available" }, "features": { "type": "array", "items": { "type": "string" }, "description": "List of unit features" }, "saleType": { "type": "string", "enum": [ "primary", "resale" ], "description": "Type of sale" }, "landArea": { "type": "number", "description": "Land area in square meters", "minimum": 0 }, "gardenArea": { "type": "number", "minimum": 0, "example": 20 } }, "example": { "recordSystemId": "00163EAB688B1EECA9C3E1F963E029CC", "unitId": "VH-12", "price": 12000, "bua": 120, "propertyType": "apartment", "status": "available", "bedrooms": 2, "bathrooms": 2, "landAres": 120, "finishingType": "Fully finished", "deliveryDateType": "months", "deliveryDate": "01-12-2026", "deliveryDateMonths": 25, "floor": "ground", "amenities": [ "wifi", "parking" ], "features": [ "parking" ], "saleType": "primary" } } } } }, "responses": { "201": { "description": "Work accepted for asynchronous processing. This response does not mean processing has completed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok" ], "properties": { "ok": { "type": "boolean" } } }, "example": { "ok": true } } } }, "400": { "description": "Bad Request - Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "array", "items": { "type": "string" } }, "error": { "type": "string" }, "statusCode": { "type": "integer" } } }, "example": { "message": [ "Invalid or missing required fields" ], "error": "Bad Request", "statusCode": 400 } } } }, "401": { "description": "API key missing, invalid, disabled, or not enabled for external access.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "statusCode": { "type": "integer" } } }, "example": { "message": "Access Denied, API key not valid", "statusCode": 401 } } } }, "403": { "description": "Forbidden - Missing required data", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "statusCode": { "type": "integer" } } }, "example": { "message": "Forbidden", "statusCode": 403 } } } } } } }, "/external/apis/v1.0/units/export/all": { "get": { "tags": [ "Units" ], "summary": "Export Units", "description": "Returns all matching units in one response, without pagination. An export can return up to 10,000 units; if more units match, the API returns 400 and no units. Stored unit fields that have no value are omitted.", "operationId": "exportUnits", "parameters": [ { "name": "Accept-Language", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "en-us", "ar-eg" ], "default": "en-us" }, "description": "Language of translated fields such as `name`, `slug`, and `compoundName`. Any other value returns `en-us`. A translated field is omitted when the record has no translation in that language. The `language` header is not used by this endpoint." }, { "name": "statuses", "in": "query", "required": false, "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string" } }, "description": "Unit statuses, case-sensitive (e.g., `Available`). Repeat the parameter for multiple values. Without it, the export returns the same unit statuses as `GET /external/apis/v1.0/units`.", "example": [ "Available" ] }, { "name": "brokerId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Broker organization ID. Returns only units that are visible to brokers and assigned to this broker.", "example": "6aaa653020fd7406492f0554" }, { "name": "dateFilterBy", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "createdAt", "updatedAt" ] }, "description": "Date field to filter on. The date filter applies only when this is sent with `startDate`, `endDate`, or both." }, { "name": "startDate", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Returns units from the start of this day, in Egypt time (Africa/Cairo).", "example": "2026-09-01" }, { "name": "endDate", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Returns units up to the end of this day, in Egypt time (Africa/Cairo).", "example": "2026-09-30" }, { "name": "sortBy", "in": "query", "required": false, "schema": { "type": "string", "default": "defaultSort" }, "description": "Field to sort by. `defaultSort` sorts by `createdAt`." }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc", "ascending", "descending" ], "default": "desc" }, "description": "Sort order" } ], "responses": { "200": { "description": "Matching units", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "_id": { "type": "string", "description": "Unit ID" }, "unitId": { "type": "string", "description": "Unit code" }, "recordSystemId": { "type": "string", "description": "Unit ID in your system" }, "name": { "type": "string", "description": "Unit name in the response language" }, "slug": { "type": "string", "description": "Unit slug in the response language" }, "title": { "type": "string" }, "status": { "type": "string", "example": "Available" }, "saleType": { "type": "string", "enum": [ "primary", "resale" ] }, "price": { "type": "number" }, "priceCurrency": { "type": "string", "example": "EGP" }, "priceByYear": { "type": "object", "description": "Prices by payment plan length. Keys are numbers of years.", "additionalProperties": { "type": "number" } }, "priceOne": { "type": "number", "description": "From `priceByYear`, using prices above 0 for years that match the unit's payment plans. With two or more prices, the second highest; with one price, that price; omitted when there are none." }, "priceTwo": { "type": "number", "nullable": true, "description": "The highest of those prices when there are two or more; otherwise null." }, "buaPricePerSquareMeter": { "type": "number" }, "lanAreaPricePerSquareMeter": { "type": "number" }, "bua": { "type": "number", "description": "Built-up area in square meters. Uses the unit design's bua when the unit has none." }, "coveredTerrace": { "type": "number" }, "totalBua": { "type": "number", "description": "bua + coveredTerrace when coveredTerrace is set (including 0). Otherwise the unit's stored totalBua, then bua, then 0. Not rounded." }, "landArea": { "type": "number" }, "gardenArea": { "type": "number" }, "beds": { "type": "number", "description": "Uses the unit design's bedrooms when the unit has none." }, "bathrooms": { "type": "number" }, "floor": { "type": "object", "properties": { "name": { "type": "string" } } }, "orientation": { "type": "string" }, "deliveryDetails": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "date", "months" ] }, "date": { "type": "string", "format": "date-time" }, "numberOfMonths": { "type": "number" } } }, "mainImageUrl": { "type": "string", "description": "Uses the unit design's image when the unit has none." }, "media": { "type": "array", "description": "The unit's media combined with its unit design's media.", "items": { "type": "object", "properties": { "image": { "type": "string" }, "imageType": { "type": "string" }, "type": { "type": "string" } } } }, "floorPlans": { "type": "array", "description": "Image URLs of the media items whose imageType is floorplan.", "items": { "type": "string" } }, "unitLocationImage": { "type": "string" }, "buildingLocationImageUrl": { "type": "string" }, "locationId": { "type": "string", "description": "ID of the compound or phase the unit belongs to" }, "compound": { "type": "object", "nullable": true, "description": "Null when the unit belongs to a phase.", "properties": { "_id": { "type": "string" }, "type": { "type": "string", "example": "Compound" }, "name": { "type": "string" }, "slug": { "type": "string" }, "description": { "type": "string" } } }, "phase": { "type": "object", "nullable": true, "description": "Null when the unit belongs directly to a compound.", "properties": { "_id": { "type": "string" }, "parentId": { "type": "string", "description": "ID of the phase's compound" }, "type": { "type": "string", "example": "Phase" }, "compound": { "type": "object", "nullable": true, "description": "The phase's compound.", "properties": { "_id": { "type": "string" }, "type": { "type": "string", "example": "Compound" }, "name": { "type": "string" }, "slug": { "type": "string" }, "description": { "type": "string" } } }, "name": { "type": "string" }, "slug": { "type": "string" }, "description": { "type": "string" } } }, "compoundName": { "type": "string", "description": "For a unit in a phase, this is the name of the phase's compound." }, "phaseName": { "type": "string", "description": "Returned only for units that belong to a phase." }, "propertyTypeId": { "type": "string" }, "type": { "type": "object", "description": "Property type. {} when the unit has no property type.", "properties": { "_id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" } } }, "unitDesignId": { "type": "string" }, "unitDesign": { "type": "object", "nullable": true, "properties": { "_id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "bua": { "type": "number" }, "bedrooms": { "type": "number" }, "mainImageUrl": { "type": "string" }, "media": { "type": "array", "items": { "type": "object" } } } }, "amenitiesIds": { "type": "array", "items": { "type": "string" } }, "amenities": { "type": "array", "items": { "type": "object", "properties": { "_id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" } } } }, "featuresIds": { "type": "array", "items": { "type": "string" } }, "finishingTypeId": { "type": "string" }, "paymentPlansIds": { "type": "array", "items": { "type": "string" } }, "paymentPlans": { "type": "array", "items": { "type": "object", "properties": { "_id": { "type": "string" }, "numberOfYears": { "type": "number" }, "name": { "type": "string" } } } }, "brokersIds": { "type": "array", "description": "IDs of the broker organizations the unit is assigned to", "items": { "type": "string" } }, "brokers": { "type": "array", "items": { "type": "object", "properties": { "_id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" } } } }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } } } } } } }, "400": { "description": "Bad Request - More than 10,000 units matched, or a query parameter is invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "error": { "type": "string" }, "statusCode": { "type": "integer" } } }, "examples": { "tooManyUnits": { "summary": "More than 10,000 units matched", "value": { "message": "Export matched 12450 units, which exceeds the maximum of 10000. Narrow the results using status, broker, or date filters.", "error": "Bad Request", "statusCode": 400 } }, "invalidQueryParameter": { "summary": "Invalid query parameter", "value": { "message": [ "brokerId must be a mongodb id" ], "error": "Bad Request", "statusCode": 400 } } } } } }, "401": { "description": "API key missing, invalid, disabled, or not enabled for external access.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "statusCode": { "type": "integer" } } }, "example": { "message": "Access Denied, API key not valid", "statusCode": 401 } } } } } } }, "/external/apis/v1.0/compounds": { "get": { "tags": [ "Compounds" ], "summary": "Get Compounds for Organization", "description": "Retrieves a paginated list of compounds for the organization with optional filtering and search capabilities", "operationId": "getCompounds", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 }, "description": "The page number to retrieve" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 }, "description": "Number of items per page" }, { "name": "all", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ], "default": 0 }, "description": "Return all results without pagination. 0 = paginated, 1 = all results" } ], "responses": { "200": { "description": "Successfully retrieved compounds", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "_id": { "type": "string", "description": "Unique identifier for the compound" }, "isDeleted": { "type": "boolean", "description": "Indicates if the compound has been deleted" }, "organizationId": { "type": "string", "description": "ID of the organization that owns the compound" }, "type": { "type": "string", "description": "Type of the entity" }, "area": { "type": "number", "description": "Total area of the compound in square meters" }, "mainImageUrl": { "type": "string", "description": "URL of the main image" }, "mainBannerUrl": { "type": "string", "description": "URL of the main banner image" }, "media": { "type": "array", "description": "Array of media items", "items": { "type": "object", "properties": { "image": { "type": "string" }, "type": { "type": "string" } } } }, "constructionUpdates": { "type": "array", "description": "Array of construction update media", "items": { "type": "object", "properties": { "image": { "type": "string" }, "type": { "type": "string" } } } }, "showOnMap": { "type": "boolean", "description": "Whether to display compound on map" }, "isPublished": { "type": "boolean", "description": "Whether the compound is published" }, "isPublic": { "type": "boolean", "description": "Whether the compound is publicly accessible" }, "logo": { "type": "string", "description": "URL of the compound logo" }, "saleType": { "type": "string", "description": "Type of sale" }, "mapHealthCheck": { "type": "boolean", "description": "Health check status for map integration" }, "numberOfUnits": { "type": "number", "description": "Total number of units in the compound" }, "mainBrochure": { "type": "object", "properties": { "dateUploaded": { "type": "string", "format": "date-time" }, "name": { "type": "string" }, "url": { "type": "string" } } }, "brochures": { "type": "array", "items": { "type": "object", "properties": { "dateUploaded": { "type": "string", "format": "date-time" }, "name": { "type": "string" }, "url": { "type": "string" } } } }, "isNewLaunch": { "type": "boolean", "description": "Indicates if this is a new launch" }, "EOIUnitTypes": { "type": "array", "description": "Array of EOI unit types" }, "EOIUnitPreferences": { "type": "array", "description": "Array of EOI unit preferences" }, "EOIForm": { "type": "array", "description": "EOI form fields" }, "offerJsons": { "type": "array", "description": "Array of offer configurations" }, "allowPriceRange": { "type": "boolean", "description": "Whether price range filtering is allowed" }, "showInLeadFeedback": { "type": "boolean", "description": "Whether to show in lead feedback" }, "isAdminOnly": { "type": "boolean", "description": "Whether compound is visible only to admins" }, "commercialBuildingsOrder": { "type": "array", "description": "Order of commercial buildings" }, "showInEcommerce": { "type": "boolean", "description": "Whether to show in e-commerce" }, "__v": { "type": "number", "description": "Version key" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" }, "organization": { "type": "object", "properties": { "_id": { "type": "string" }, "name": { "type": "string" }, "logo": { "type": "string" } } }, "description": { "type": "string", "description": "Description of the compound" }, "name": { "type": "string", "description": "Name of the compound" }, "slug": { "type": "string", "description": "URL-friendly identifier" } } } }, "pagination": { "type": "object", "properties": { "count": { "type": "number", "description": "Number of items in current response" }, "limit": { "type": "number", "description": "Maximum items per page" }, "pages": { "type": "number", "description": "Total number of pages" }, "total": { "type": "number", "description": "Total number of compounds" } } } } }, "example": { "data": [ { "_id": "691dc2308d882bd47368661a", "isDeleted": false, "organizationId": "691dc2308d882bd473686611", "type": "Compound", "area": 6115, "mainImageUrl": "https://loremflickr.com/3543/341?lock=8944094847880925", "mainBannerUrl": "https://picsum.photos/seed/eg63G/1357/1356", "media": [ { "image": "https://picsum.photos/seed/EeQ33FNdk/3441/2587", "type": "image" }, { "image": "https://picsum.photos/seed/Bfyrei7U9A/1836/3961", "type": "image" } ], "constructionUpdates": [ { "image": "https://loremflickr.com/714/712?lock=5238549307544312", "type": "image" } ], "showOnMap": true, "isPublished": true, "isPublic": false, "logo": "https://picsum.photos/seed/9GT605R8FG/630/451", "saleType": "primary", "mapHealthCheck": true, "numberOfUnits": 222, "mainBrochure": { "dateUploaded": "2025-11-19T13:12:16.376Z", "name": "Des Moines Main Brochure", "url": "https://loremflickr.com/3194/302?lock=6831798650377823" }, "brochures": [ { "dateUploaded": "2025-11-19T13:12:16.376Z", "name": "Des Moines Brochure", "url": "https://picsum.photos/seed/2Nige/1361/396" } ], "isNewLaunch": false, "EOIUnitTypes": [], "EOIUnitPreferences": [], "EOIForm": [], "offerJsons": [], "allowPriceRange": false, "showInLeadFeedback": false, "isAdminOnly": false, "commercialBuildingsOrder": [], "showInEcommerce": false, "__v": 0, "createdAt": "2025-11-19T13:12:16.378Z", "updatedAt": "2025-11-19T13:12:16.378Z", "organization": { "_id": "691dc2308d882bd473686611", "name": "lasirena", "logo": "https://www.lasirena-egypt.com/wp-content/uploads/2019/07/Lasirena-Logo.png" }, "description": "Alioqui denuo dolores videlicet soleo pecco. Aegre quibusdam quas conicio. Confero ulciscor sol.", "name": "Des Moines", "slug": "des-moines" } ], "pagination": { "count": 1, "limit": 2, "pages": 2, "total": 3 } } } } }, "400": { "description": "Bad Request - Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "message": { "type": "array", "items": { "type": "string" } }, "error": { "type": "string" } } }, "example": { "statusCode": 400, "message": [ "page must be a positive number", "limit must not exceed 100" ], "error": "Bad Request" } } } }, "401": { "description": "API key missing, invalid, disabled, or not enabled for external access.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "statusCode": { "type": "integer" } } }, "example": { "message": "Access Denied, API key not valid", "statusCode": 401 } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "string" } } }, "example": { "statusCode": 500, "message": "Internal server error", "error": "Internal Server Error" } } } } } } }, "/external/apis/v1.0/compounds/{slug}/units": { "get": { "tags": [ "Compounds" ], "summary": "Get Compound Units", "description": "Retrieves all units for a specific compound with detailed information including unit designs, amenities, property types, and phases", "operationId": "getCompoundUnits", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The compound slug identifier", "example": "compound-slug" } ], "responses": { "200": { "description": "Successfully retrieved compound units", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "_id": { "type": "string" }, "isDeleted": { "type": "boolean" }, "organizationId": { "type": "string" }, "locationId": { "type": "string" }, "paymentPlansIds": { "type": "array", "items": { "type": "string" } }, "unitDesignId": { "type": "string" }, "floor": { "type": "object", "properties": { "name": { "type": "string" } } }, "amenitiesIds": { "type": "array", "items": { "type": "string" } }, "bua": { "type": "number" }, "price": { "type": "number" }, "beds": { "type": "number" }, "buildingId": { "type": "string" }, "unitId": { "type": "string" }, "media": { "type": "array", "items": { "type": "object", "properties": { "image": { "type": "string" }, "imageType": { "type": "string", "nullable": true }, "type": { "type": "string" } } } }, "status": { "type": "string" }, "rentalStatus": { "type": "string" }, "propertyTypeId": { "type": "string" }, "saleType": { "type": "string" }, "isAdminOnly": { "type": "boolean" }, "reviews": { "type": "array", "items": { "type": "object" } }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "amenities": { "type": "array", "items": { "type": "object", "properties": { "_id": { "type": "string" }, "name": { "type": "string" }, "icon": { "type": "string" } } } }, "phase": { "type": "object", "properties": { "_id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "description": { "type": "string" } } }, "type": { "type": "object", "properties": { "_id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" } } }, "unitDesign": { "type": "object", "properties": { "_id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "description": { "type": "string" } } }, "name": { "type": "string" }, "slug": { "type": "string" } } } } } }, "example": { "data": [ { "_id": "691dd0f28ebfedf1459d8439", "isDeleted": false, "organizationId": "691dd0f28ebfedf1459d8425", "locationId": "691dd0f28ebfedf1459d842e", "paymentPlansIds": [ "63a2ea2b2b48f4b7190171b4", "63a2ea2b2b48f4b7190171b5" ], "unitDesignId": "691dd0f28ebfedf1459d8434", "floor": { "name": "Ground" }, "amenitiesIds": [ "691dd0f28ebfedf1459d8436", "691dd0f28ebfedf1459d8437" ], "bua": 109, "price": 4960641295871160, "beds": 3, "buildingId": "CH1", "unitId": "CH11", "media": [ { "image": "https://img.sakneen.com//5b6c306b-d792-4321-bc55-fc237889f8c1-attachments/CH---Ground/Floor-Plan/Type-CH.jpeg", "imageType": "floorplan", "type": "image" }, { "image": "https://img.sakneen.com//7c4eae33-075a-4af0-8f70-695405a49017-attachments/CH---Ground/Gallery/a-(1).jpg", "imageType": null, "type": "image" } ], "status": "Available", "rentalStatus": "Unavailable", "propertyTypeId": "691dd0f28ebfedf1459d8432", "saleType": "primary", "isAdminOnly": false, "createdAt": "2025-11-19T14:15:14.120Z", "updatedAt": "2025-11-19T14:15:14.120Z", "amenities": [ { "_id": "691dd0f28ebfedf1459d8436", "name": "lady", "icon": "https://picsum.photos/seed/HtwE9NRMU/2195/2261" } ], "phase": { "_id": "691dd0f28ebfedf1459d842e", "name": "famously cricket", "slug": "denitrify-silently", "description": "Adfero coniecto harum eveniet votum curvo torrens amissio cotidie attero." }, "type": { "_id": "691dd0f28ebfedf1459d8432", "name": "hunt", "slug": "pleasure" }, "unitDesign": { "_id": "691dd0f28ebfedf1459d8434", "name": "effector", "slug": "effector", "description": "finally opposite napkin underneath service as crafty furthermore sardonic aw" }, "name": "CH11", "slug": "ch11" } ] } } } }, "401": { "description": "API key missing, invalid, disabled, or not enabled for external access.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "statusCode": { "type": "integer" } } }, "example": { "message": "Access Denied, API key not valid", "statusCode": 401 } } } }, "404": { "description": "Not Found - Compound not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "string" } } }, "example": { "statusCode": 404, "message": "There is no compound with slug: invalid-slug", "error": "Not Found" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "string" } } }, "example": { "statusCode": 500, "message": "Internal server error", "error": "Internal Server Error" } } } } } } }, "/external/apis/v1.0/reservations": { "post": { "tags": [ "Reservations" ], "summary": "Create or Update Reservation", "description": "Accept a reservation create/update request from an external system and queue it for asynchronous processing. A 201 response with `{ \"ok\": true }` means the request was accepted. If the unit cannot be resolved during processing, Sakneen still creates or updates the reservation without a local unit link. Other processing failures are tracked internally by Sakneen's Google Cloud Tasks-backed queue ledger and operational notifications.", "operationId": "createOrUpdateReservation", "parameters": [ { "name": "Content-Type", "in": "header", "required": true, "schema": { "type": "string" }, "example": "application/json" }, { "name": "language", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional language preference.", "example": "en-us" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "recordSystemId", "unitRecordSystemId", "status" ], "properties": { "recordSystemId": { "type": "string", "description": "Unique reservation identifier from the external system. Used as the upsert key." }, "unitRecordSystemId": { "type": "string", "description": "External unit identifier. Sakneen resolves this against the unit's recordSystemId when the unit exists." }, "status": { "type": "string", "description": "External status string. Organization-specific mappings apply; an unmapped value is retained as supplied." }, "fullName": { "type": "string", "description": "Customer full name" }, "phoneNumber": { "type": "string", "description": "Customer phone number" }, "email": { "type": "string", "format": "email", "description": "Customer email address" }, "nationalID": { "type": "string", "description": "Customer national ID" }, "crmID": { "type": "string", "description": "External CRM identifier" }, "reservationAmount": { "type": "number", "minimum": 0, "description": "Reservation amount" }, "expiryDate": { "type": "string", "format": "date-time", "description": "Reservation expiry date" }, "crmOpportunityId": { "type": "string", "description": "External CRM opportunity identifier" }, "salesPersonEmail": { "type": "string", "format": "email", "description": "Email address of the Sakneen sales person to attach to the reservation" }, "reservationData": { "type": "object", "description": "Additional reservation fields to map into the organization's reservation form when configured", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "items": { "oneOf": [ { "type": "string" }, { "type": "number" } ] } } ] } } }, "example": { "recordSystemId": "RES-001", "unitRecordSystemId": "UNIT-001", "status": "approved", "fullName": "Palm Hills Client", "phoneNumber": "+201001234567", "email": "client@example.com", "reservationAmount": 150000, "crmOpportunityId": "OPP-456", "salesPersonEmail": "sales@example.com", "reservationData": { "paymentPlan": "5 years", "source": "external-crm" } } } } } }, "responses": { "201": { "description": "Work accepted for asynchronous processing. This response does not mean processing has completed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok" ], "properties": { "ok": { "type": "boolean" } } }, "example": { "ok": true } } } }, "400": { "description": "Bad Request - validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "array", "items": { "type": "string" } }, "error": { "type": "string" }, "statusCode": { "type": "integer" } } }, "example": { "message": [ "recordSystemId should not be empty", "unitRecordSystemId should not be empty", "status must be one of the following values: pending, approved, rejected, canceled, expired" ], "error": "Bad Request", "statusCode": 400 } } } }, "401": { "description": "API key missing, invalid, disabled, or not enabled for external access.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "statusCode": { "type": "integer" } } }, "example": { "message": "Access Denied, API key not valid", "statusCode": 401 } } } } } } }, "/external/apis/v1.0/reservations/webhook": { "post": { "tags": [ "Reservations" ], "summary": "Reservation Webhook", "description": "Apply a receipt update to an existing reservation cheque. Receipt status mappings are configured per organization; obtain the supported values from Sakneen support. This changes wallet/receipt data.", "operationId": "reservationsWebhook", "parameters": [ { "name": "Content-Type", "in": "header", "schema": { "type": "string" }, "example": "application/json" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "reservationId", "chequeId", "receiptId", "receiptAmount", "receiptStatus" ], "properties": { "reservationId": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$", "description": "Existing reservation MongoDB ID.", "example": "000000000000000000000001" }, "chequeId": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$", "description": "Existing cheque MongoDB ID.", "example": "000000000000000000000002" }, "receiptId": { "type": "string", "minLength": 1, "maxLength": 120, "example": "sample-receipt-001" }, "receiptAmount": { "type": "number", "minimum": 0, "exclusiveMinimum": true, "example": 100 }, "receiptStatus": { "type": "string", "minLength": 1, "maxLength": 120, "description": "External receipt status mapped for your organization. Replace the sample with a supported value.", "example": "CONFIRMED" } } } } } }, "responses": { "201": { "description": "Receipt update completed. The response body is empty." }, "400": { "description": "Bad Request - validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "array", "items": { "type": "string" } }, "error": { "type": "string" }, "statusCode": { "type": "integer" } } }, "example": { "message": [ "chequeStatus must be a valid enum value" ], "error": "Bad Request", "statusCode": 400 } } } }, "401": { "description": "API key missing, invalid, disabled, or not enabled for external access.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "statusCode": { "type": "integer" } } }, "example": { "message": "Access Denied, API key not valid", "statusCode": 401 } } } }, "404": { "description": "Not Found - reservation, unit, or cheque could not be located", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "string" } } }, "example": { "statusCode": 404, "message": "Reservation not found", "error": "Not Found" } } } }, "422": { "description": "Unprocessable Entity - state transition is not allowed", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "message": { "type": "string" }, "error": { "type": "string" } } }, "example": { "statusCode": 422, "message": "Reservation must be pending cheque collection before OIC approval", "error": "Unprocessable Entity" } } } } } } }, "/external/apis/v1.0/leads/{recordSystemId}": { "delete": { "tags": [ "Leads" ], "summary": "Delete lead", "description": "Soft deletes a non-deleted lead by organization-scoped external lead or submission ID, and soft deletes its linked lead actions. Returns 404 when no matching non-deleted lead exists. Successful deletes are logged as External Lead Delete with modifier External API and source API.", "operationId": "deleteLead", "parameters": [ { "name": "recordSystemId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Stable external lead or submission ID used when upserting the lead.", "example": "alkarma-website-form-018f9f29-4b8a-7c1a" } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } }, "example": { "ok": true } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } }, { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "string" } } } ] }, "error": { "type": "string" }, "statusCode": { "type": "integer" } } }, "example": { "message": "recordSystemId should not be empty", "error": "Bad Request", "statusCode": 400 } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } }, { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "string" } } } ] }, "error": { "type": "string" }, "statusCode": { "type": "integer" } } }, "example": { "message": "Lead not found", "error": "Not Found", "statusCode": 404 } } } }, "401": { "description": "API key missing, invalid, disabled, or not enabled for external access.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "statusCode": { "type": "integer" } } }, "example": { "message": "Access Denied, API key not valid", "statusCode": 401 } } } } } } } }, "components": { "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "api-key", "description": "Issued by Sakneen support for your assigned API host and environment. Never place the key in a URL." } } }, "security": [ { "apiKey": [] } ] }