{"openapi":"3.1.0","info":{"title":"Datalake API - Public Endpoints","description":"Public API endpoints for the datalake service","version":"v4.418.0"},"servers":[{"url":"https://api.stonal.io/datalake","description":"Production environment"},{"url":"https://api-{stack}.stonal.io/datalake","description":"Custom stack production environment","variables":{"stack":{"description":"Custom stack name","default":"demo"}}},{"url":"https://api.stonal-dev.io/datalake","description":"Development environment"},{"url":"https://api.stonal-test.io/datalake","description":"Test environment"},{"url":"https://api.stonal-staging.io/datalake","description":"Staging environment"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"Assets","description":"Public API to manage and query assets"},{"name":"Selection Sessions","description":"Selection Session Management API"},{"name":"Stakeholders","description":"Public API to manage and query stakeholders"},{"name":"Amendments","description":"V1 API to query amendments"},{"name":"Billing events","description":"V1 API to query billing events"},{"name":"Certificates","description":"V1 API to query certificates"},{"name":"Contracts","description":"V1 API to manage and query contracts"},{"name":"Deposits","description":"V1 API to query deposits"},{"name":"Public asset types","description":"Public API to manage and query asset type"},{"name":"Public properties","description":"Public API to manage and query properties"}],"paths":{"/v1/organizations/{organizationCode}/stakeholders/{uid}":{"get":{"tags":["Stakeholders"],"summary":"Get stakeholder by ID","description":"Retrieves a single stakeholder by its unique identifier. Requires `stonal.contacts.read` permission","operationId":"getStakeholderByUid","parameters":[{"name":"organizationCode","in":"path","description":"Organization code","required":true,"schema":{"type":"string"}},{"name":"uid","in":"path","description":"Unique identifier of the stakeholder","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Successfully retrieved stakeholder","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StakeHolderView"}}}},"403":{"description":"Forbidden - Not authorized to access this organization","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StakeHolderView"}}}},"404":{"description":"Stakeholder not found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StakeHolderView"}}}},"500":{"description":"Internal server error","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StakeHolderView"}}}}}},"put":{"tags":["Stakeholders"],"summary":"Save stakeholder","description":"Creates or updates a stakeholder with a specific UID. Requires `stonal.contact.write` permission","operationId":"saveStakeholder","parameters":[{"name":"organizationCode","in":"path","description":"Organization code","required":true,"schema":{"type":"string"}},{"name":"uid","in":"path","description":"Unique identifier of the stakeholder","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"description":"Stakeholder data to save","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SaveStakeHolderRequestBody"}}},"required":true},"responses":{"200":{"description":"Stakeholder successfully saved","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StakeHolderView"}}}},"400":{"description":"Invalid request body","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StakeHolderView"}}}},"403":{"description":"Forbidden - Not authorized to access this organization","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StakeHolderView"}}}},"500":{"description":"Internal server error during save operation","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StakeHolderView"}}}}}},"delete":{"tags":["Stakeholders"],"summary":"Delete stakeholder","description":"Deletes a stakeholder by its unique identifier. Requires `stonal.contact.delete` permission","operationId":"deleteStakeholder","parameters":[{"name":"organizationCode","in":"path","description":"Organization code","required":true,"schema":{"type":"string"}},{"name":"uid","in":"path","description":"Unique identifier of the stakeholder","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Stakeholder successfully deleted","content":{}},"403":{"description":"Forbidden - Not authorized to access this organization","content":{}},"404":{"description":"Stakeholder not found","content":{}},"500":{"description":"Internal server error during deletion","content":{}}}},"patch":{"tags":["Stakeholders"],"summary":"Update stakeholder","description":"Partially updates an existing stakeholder. Requires `stonal.contact.write` permission","operationId":"updateStakeholder","parameters":[{"name":"organizationCode","in":"path","description":"Organization code","required":true,"schema":{"type":"string"}},{"name":"uid","in":"path","description":"Unique identifier of the stakeholder","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"description":"Stakeholder data to update","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateStakeHolderRequestBody"}}},"required":true},"responses":{"204":{"description":"Stakeholder successfully updated"},"400":{"description":"Invalid request body"},"403":{"description":"Forbidden - Not authorized to access this organization"},"404":{"description":"Stakeholder not found"},"500":{"description":"Internal server error during update"}}}},"/v1/organizations/{organizationCode}/stakeholders/{companyUid}/contacts":{"get":{"tags":["Stakeholders"],"summary":"List a company's contact cards","description":"The persons attached to the company (parentUid), one card each with its primary phone number and email, primary contact first, then in the order of the last PUT, then the persons it did not save by lastName and firstName (case- and accent-insensitive), then by uid. Requires `stonal.contacts.read` permission","operationId":"getContacts","parameters":[{"name":"organizationCode","in":"path","description":"Organization code","required":true,"schema":{"type":"string"}},{"name":"companyUid","in":"path","description":"Uid of the company","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The company's contact cards","content":{"*/*":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/CompanyContactCard"}}}}},"400":{"description":"The stakeholder is not a company (`errors[].code` NOT_A_COMPANY)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden - Not authorized to access this organization (empty body)"},"404":{"description":"Company not found"}}},"put":{"tags":["Stakeholders"],"summary":"Replace a company's contact cards","description":"Makes the persons attached to the company match the list, in one transaction: a card without uid creates a person, a card with uid updates it (a changed name becomes its lastName and clears its firstName; the card's phone number and email replace the ones it showed and become primary, the person's other ones are kept), and an attached person absent from the list is deleted, like DELETE /stakeholders/{uid}, unless it is linked to a contract (409, nothing changed). Each card needs a name and a phone number or an email; at most one card is the primary contact (an omitted isPrimaryContact means false), and no two cards nor another person share an email. Clearing or replacing a card's phone number or email also removes every copy of it from the person's legacy contactsDetails, keeping the entries' other values. Any invalid card rejects the whole list, with every error in one response (errors on `contacts[<index>].<field>`). The list order is stored and returned by the next reads. Returns the saved list. Requires `stonal.contact.write` permission, and also `stonal.contact.delete` when the list leaves out an attached person (403 otherwise, nothing changed)","operationId":"replaceContacts","parameters":[{"name":"organizationCode","in":"path","description":"Organization code","required":true,"schema":{"type":"string"}},{"name":"companyUid","in":"path","description":"Uid of the company","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"description":"The whole list of contact cards of the company","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/CompanyContactCard"}}}},"required":true},"responses":{"200":{"description":"The saved contact cards","content":{"*/*":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/CompanyContactCard"}}}}},"400":{"description":"An invalid card, a uid that is not a contact of this company, or a stakeholder that is not a company. Every error is listed at once; match them on `field`. `errors[].code`: NAME_REQUIRED, EMAIL_OR_PHONE_REQUIRED, EMAIL_INVALID, EMAIL_DUPLICATE, EMAIL_ALREADY_USED, UID_INVALID, UID_DUPLICATE, UID_NOT_A_CONTACT, PRIMARY_CONTACT_DUPLICATE, NOT_A_COMPANY; `errors[].params`: `value`, and `firstIndex` (the card a duplicate repeats)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden - Not authorized to access this organization (empty body), or missing `stonal.contact.delete` for the contacts the list leaves out (ErrorResponse body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Company not found"},"409":{"description":"The list leaves out a contact linked to a contract; the detail names each such contact, and each has an error with `code` CONTACT_HAS_CONTRACTS and `params` `uid`, `name`, `contractCount`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/organizations/{organizationCode}/stakeholders":{"get":{"tags":["Stakeholders"],"summary":"Search stakeholders","description":"Search for stakeholders with various filtering options and pagination. Requires `stonal.contacts.read` permission","operationId":"searchStakeholder","parameters":[{"name":"organizationCode","in":"path","description":"Organization code","required":true,"schema":{"type":"string"}},{"name":"q","in":"query","description":"Search query term","required":false,"schema":{"type":"string"}},{"name":"type","in":"query","description":"Filter by stakeholder type (person or company)","required":false,"schema":{"type":"string"}},{"name":"name","in":"query","description":"Filter by stakeholder name","required":false,"schema":{"type":"string"}},{"name":"siren","in":"query","description":"Filter by the siren","required":false,"schema":{"type":"string"}},{"name":"email","in":"query","description":"Filter by stakeholder email","required":false,"schema":{"type":"string"}},{"name":"include","in":"query","description":"Add objects linked in the response","required":false,"schema":{"type":"array","items":{"type":"string"}}},{"name":"page","in":"query","description":"Page number (zero-based)","required":false,"schema":{"type":"integer","format":"int32","default":0}},{"name":"size","in":"query","description":"Page size","required":false,"schema":{"type":"integer","format":"int32","default":10}},{"name":"sort","in":"query","description":"Sort field. Allowed values: name, creationDate, updatedAt","required":false,"schema":{"type":"string"}},{"name":"direction","in":"query","description":"Sort direction (asc or desc)","required":false,"schema":{"type":"string","default":"asc"}},{"name":"assetIds","in":"query","description":"Filter by asset IDs","required":false,"schema":{"type":"array","items":{"type":"string"}}},{"name":"updatedAtAfter","in":"query","description":"Filter stakeholders updated after this date. Use ISO 8601 format","required":false,"schema":{"type":"string"},"example":"2025-11-10T14:30:00Z"},{"name":"mustHave","in":"query","description":"Filter existing siren","required":false,"schema":{"type":"string"},"example":"SIREN"},{"name":"orphansOnly","in":"query","description":"Only return companies without a parent","required":false,"schema":{"type":"boolean","default":false}},{"name":"parentUid","in":"query","description":"Refers to the STAKEHOLDER hierarchy only, never to the asset perimeter or a contract: return the direct children of this stakeholder (a company's subsidiaries and its attached persons). Use with the hasChildren flag from a previous search to drill into a contact's children. Can be combined with a text query (q) to search within those children; cannot be combined with orphansOnly. The children come primary contact (isPrimaryContact) first, then in the order of the last PUT /stakeholders/{uid}/contacts, then by lastName and firstName (case- and accent-insensitive; a company child by its name), then by uid; without q, an explicit sort replaces this order.","required":false,"schema":{"type":"string"},"example":"030f134a-fb24-4a16-8acb-d29d9ba50077"},{"name":"perimeterMode","in":"query","description":"How to apply the assetIds perimeter filter. INCLUDED (default) returns stakeholders linked to the given asset(s) or an ancestor; EXCLUDED returns the inverse (stakeholders you can still link to the asset). Ignored when assetIds is absent.","required":false,"schema":{"type":"string"},"example":"EXCLUDED"},{"name":"excludeAttachedPersons","in":"query","description":"Hide the persons attached to a company (parentUid), i.e. the companies' contacts. Default false.","required":false,"schema":{"type":"boolean","default":false},"example":true}],"responses":{"200":{"description":"Successfully retrieved stakeholders","content":{"*/*":{"schema":{"$ref":"#/components/schemas/SearchStakeHolderResponseBody"}}}},"400":{"description":"Invalid request parameters","content":{"*/*":{"schema":{"$ref":"#/components/schemas/SearchStakeHolderResponseBody"}}}},"403":{"description":"Forbidden - Not authorized to access this organization","content":{"*/*":{"schema":{"$ref":"#/components/schemas/SearchStakeHolderResponseBody"}}}},"500":{"description":"Internal server error","content":{"*/*":{"schema":{"$ref":"#/components/schemas/SearchStakeHolderResponseBody"}}}}}},"post":{"tags":["Stakeholders"],"summary":"Create stakeholder","description":"Creates a new stakeholder (person or company) for an organization. Requires `stonal.contact.write` permission","operationId":"createStakeholder","parameters":[{"name":"organizationCode","in":"path","description":"Organization code","required":true,"schema":{"type":"string"}}],"requestBody":{"description":"Stakeholder data to create","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateStakeHolderRequestBody"}}},"required":true},"responses":{"201":{"description":"Stakeholder successfully created","content":{"*/*":{"schema":{"$ref":"#/components/schemas/CreateStakeHolderResponseBody"}}}},"400":{"description":"Invalid request body","content":{"*/*":{"schema":{"$ref":"#/components/schemas/CreateStakeHolderResponseBody"}}}},"403":{"description":"Forbidden - Not authorized to access this organization","content":{"*/*":{"schema":{"$ref":"#/components/schemas/CreateStakeHolderResponseBody"}}}},"500":{"description":"Internal server error during creation","content":{"*/*":{"schema":{"$ref":"#/components/schemas/CreateStakeHolderResponseBody"}}}}}}},"/v1/organizations/{organizationCode}/selection-sessions":{"post":{"tags":["Selection Sessions"],"summary":"Create a selection session","description":"Creates a new selection session with selection data and context for the specified organization. Requires `stonal.asset.read` permission","operationId":"createSelectionSession","parameters":[{"name":"organizationCode","in":"path","description":"Organization code identifier","required":true,"schema":{"type":"string"},"example":"DEMO"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSelectionSessionRequest"}}},"required":true},"responses":{"201":{"description":"Selection session successfully created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSelectionSessionResponse"}}}},"400":{"description":"Bad Request - Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSelectionSessionResponse"}}}},"401":{"description":"Unauthorized - Missing or invalid JWT/PAT","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSelectionSessionResponse"}}}},"403":{"description":"Forbidden - User doesn't have permission for this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSelectionSessionResponse"}}}},"404":{"description":"Not Found - Organization code not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSelectionSessionResponse"}}}}}}},"/v1/organizations/{organizationCode}/contracts":{"get":{"tags":["Contracts"],"summary":"Get contracts","description":"List contracts for an organization with cursor pagination, optional filters, and opt-in property data. Requires `stonal.asset.read` permission","operationId":"getContracts","parameters":[{"name":"organizationCode","in":"path","description":"Organization code","required":true,"schema":{"type":"string"}},{"name":"contractCode","in":"query","description":"Contract code","required":false,"schema":{"type":"string"}},{"name":"assetUids","in":"query","description":"Asset UIDs (ex: 11111111-1111-1111-1111-111111111111,22222222-2222-2222-2222-222222222222)","required":false,"schema":{"type":"array","items":{"type":"string"}}},{"name":"stakeholderUids","in":"query","description":"Stakeholder UIDs (ex: 33333333-3333-3333-3333-333333333333,44444444-4444-4444-4444-444444444444)","required":false,"schema":{"type":"array","items":{"type":"string"}}},{"name":"equipmentTypeCodes","in":"query","description":"Equipment type codes (ex: ELEVATOR,HVAC)","required":false,"schema":{"type":"array","items":{"type":"string"}}},{"name":"size","in":"query","description":"Page size (default 50, max 2000)","required":false,"schema":{"type":"integer","format":"int32","default":50}},{"name":"cursor","in":"query","description":"Opaque cursor for pagination; \"0\" starts from the first page","required":false,"schema":{"type":"string","default":"0"}},{"name":"include","in":"query","description":"Optional includes; only \"data\" is recognised. Adds per-contract property values to each contract.","required":false,"schema":{"type":"array","items":{"type":"string"}}}],"responses":{"200":{"description":"Successfully get contracts","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ContractsGetResultResponse"}}}},"400":{"description":"Bad request - invalid pagination parameters","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ContractsGetResultResponse"}}}},"403":{"description":"Forbidden - Not authorized to access this organization","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ContractsGetResultResponse"}}}},"500":{"description":"Internal server error during creation","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ContractsGetResultResponse"}}}}}},"post":{"tags":["Contracts"],"summary":"Create contracts","description":"Create new contracts for an organization with his stakeholders and assets linked. Requires `stonal.asset.write` permission","operationId":"createContract","parameters":[{"name":"organizationCode","in":"path","description":"Organization code","required":true,"schema":{"type":"string"}}],"requestBody":{"description":"Creation contract body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContractCreationRequest"}}},"required":true},"responses":{"201":{"description":"Successfully created contracts"},"403":{"description":"Forbidden - Not authorized to access this organization"},"409":{"description":"Conflict - Contract already exists or has no changes"},"500":{"description":"Internal server error during creation"}}},"patch":{"tags":["Contracts"],"summary":"Update a contract","description":"Update a contracts for an organization with his stakeholders and assets linked. Requires `stonal.asset.write` permission","operationId":"patchContract","parameters":[{"name":"organizationCode","in":"path","description":"Organization code","required":true,"schema":{"type":"string"}}],"requestBody":{"description":"Patch contract body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContractUpdateRequest"}}},"required":true},"responses":{"204":{"description":"Successfully updated the contract"},"400":{"description":"Bad request - invalid body"},"403":{"description":"Forbidden - Not authorized to access this organization"},"409":{"description":"Conflict - Contract already exists or has no changes"},"500":{"description":"Internal server error during creation"}}}},"/v1/organizations/{organizationCode}/assets":{"post":{"tags":["Assets"],"summary":"Ingest assets","description":"Create and update assets by organization. Requires `stonal.asset.write` permission","operationId":"upsertAssets","parameters":[{"name":"organizationCode","in":"path","description":"Organization code","required":true,"schema":{"type":"string"}}],"requestBody":{"description":"Assets to create or update","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpsertAssetsRequest"}}},"required":true},"responses":{"200":{"description":"Successfully ingest assets","content":{"*/*":{"schema":{"oneOf":[{"$ref":"#/components/schemas/IngestAssetsFailResponse"},{"$ref":"#/components/schemas/IngestAssetsSuccessResponse"}]}}}},"403":{"description":"Forbidden - Not authorized to access this organization","content":{"*/*":{"schema":{"oneOf":[{"$ref":"#/components/schemas/IngestAssetsFailResponse"},{"$ref":"#/components/schemas/IngestAssetsSuccessResponse"}]}}}}}}},"/v1/organizations/{organizationCode}/assets/search":{"post":{"tags":["Assets"],"summary":"Search assets","description":"Search assets by organization. Requires `stonal.asset.read` permission","operationId":"searchAssets","parameters":[{"name":"organizationCode","in":"path","description":"Organization code","required":true,"schema":{"type":"string"}}],"requestBody":{"description":"Search criteria","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchAssetsRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/SearchAssetsResponse"}}}}}}},"/v1/organizations/{organizationCode}/selection-sessions/{selectionSessionUid}":{"get":{"tags":["Selection Sessions"],"summary":"Get a selection session","description":"Get a unique selection session with its selection data and context.","operationId":"getSelectionSession","parameters":[{"name":"organizationCode","in":"path","description":"Organization code","required":true,"schema":{"type":"string"}},{"name":"selectionSessionUid","in":"path","description":"Selection Session UID","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Selection session retrieved successfully","content":{"*/*":{"schema":{"$ref":"#/components/schemas/GetSelectionSessionResponse"}}}},"401":{"description":"Unauthorized - Missing or invalid JWT/PAT","content":{"*/*":{"schema":{"$ref":"#/components/schemas/GetSelectionSessionResponse"}}}},"404":{"description":"Not Found - Selection session or organization not found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/GetSelectionSessionResponse"}}}}}},"delete":{"tags":["Selection Sessions"],"summary":"Delete a selection session","description":"Delete a selection session and all its data. Requires `stonal.asset.read` permission","operationId":"deleteSelectionSession","parameters":[{"name":"organizationCode","in":"path","description":"Organization code","required":true,"schema":{"type":"string"}},{"name":"selectionSessionUid","in":"path","description":"Selection Session UID","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Selection session deleted successfully"},"401":{"description":"Unauthorized - Missing or invalid JWT/PAT"},"404":{"description":"Not Found - Selection session or organization not found"}}}},"/v1/organizations/{organizationCode}/selection-sessions/{selectionSessionUid}/structure":{"get":{"tags":["Selection Sessions"],"summary":"Get a structure in function of the selection session","description":"Get a structure of the unique selection session.","operationId":"getSelectionSessionStructure","parameters":[{"name":"organizationCode","in":"path","description":"Organization code","required":true,"schema":{"type":"string"}},{"name":"selectionSessionUid","in":"path","description":"Selection Session UID","required":true,"schema":{"type":"string"}},{"name":"includeExpired","in":"query","description":"If `false` or undefined only returns non expired assets. If `true` also includes expired assets","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"Structure retrieved successfully","content":{"*/*":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/AssetBuildingStructure"}}}}},"404":{"description":"Not Found - Structure from selection session or selection session or organization not found","content":{"*/*":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/AssetBuildingStructure"}}}}}}}},"/v1/organizations/{organizationCode}/selection-sessions/{selectionSessionUid}/assets":{"get":{"tags":["Selection Sessions"],"summary":"Get selected asset details for a selection session","description":"Returns the name and level of each selected asset in the session.","operationId":"getSelectionSessionAssets","parameters":[{"name":"organizationCode","in":"path","description":"Organization code","required":true,"schema":{"type":"string"}},{"name":"selectionSessionUid","in":"path","description":"Selection Session UID","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Selected asset details retrieved successfully","content":{"*/*":{"schema":{"$ref":"#/components/schemas/GetSelectionSessionAssetsResponse"}}}},"404":{"description":"Not Found - Selection session or organization not found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/GetSelectionSessionAssetsResponse"}}}}}}},"/v1/organizations/{organizationCode}/selection-sessions/{selectionSessionUid}/assets/{uid}":{"get":{"tags":["Selection Sessions"],"summary":"Get the plan of the assets base view in selection session","description":"Get the plan of the assets base view in selection session.","operationId":"getSelectionSessionPlan","parameters":[{"name":"organizationCode","in":"path","description":"Organization code","required":true,"schema":{"type":"string"}},{"name":"selectionSessionUid","in":"path","description":"Selection Session UID","required":true,"schema":{"type":"string"}},{"name":"uid","in":"path","description":"Selection asset UID","required":true,"schema":{"type":"string"}},{"name":"includeExpired","in":"query","description":"If `false` or undefined only draws non expired assets. If `true` also includes expired assets","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"Structure retrieved successfully","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PlanRepresentationResponseBody"}}}},"404":{"description":"Not Found - Structure from selection session or selection session or organization not found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PlanRepresentationResponseBody"}}}}}}},"/v1/organizations/{organizationCode}/deposits":{"get":{"tags":["Deposits"],"summary":"Get deposits","description":"List deposits for an organization, paginated with an opaque cursor ordered by ascending id. Requires `stonal.asset.read` permission.","operationId":"getDeposits","parameters":[{"name":"organizationCode","in":"path","description":"Organization code","required":true,"schema":{"type":"string"}},{"name":"contractCode","in":"query","description":"Filter by contract code","required":false,"schema":{"type":"string"}},{"name":"code","in":"query","description":"Filter by deposit code","required":false,"schema":{"type":"string"}},{"name":"size","in":"query","description":"Number of results per page (default 50, max 2000)","required":false,"schema":{"type":"integer","format":"int32","default":50}},{"name":"cursor","in":"query","description":"Opaque cursor returned by a previous call. Use \"0\" to start.","required":false,"schema":{"type":"string","default":"0"}}],"responses":{"200":{"description":"Successfully got deposits","content":{"*/*":{"schema":{"$ref":"#/components/schemas/DepositsGetResultResponse"}}}},"400":{"description":"Invalid query parameter","content":{"*/*":{"schema":{"$ref":"#/components/schemas/DepositsGetResultResponse"}}}},"403":{"description":"Forbidden - Not authorized to access this organization","content":{"*/*":{"schema":{"$ref":"#/components/schemas/DepositsGetResultResponse"}}}},"500":{"description":"Internal server error","content":{"*/*":{"schema":{"$ref":"#/components/schemas/DepositsGetResultResponse"}}}}}}},"/v1/organizations/{organizationCode}/certificates":{"get":{"tags":["Certificates"],"summary":"Get certificates","description":"List certificates for an organization, paginated with an opaque cursor ordered by ascending id. Optionally filtered by asset stonal identifiers. Requires `stonal.asset.read` permission.","operationId":"getCertificates","parameters":[{"name":"organizationCode","in":"path","description":"Organization code","required":true,"schema":{"type":"string"}},{"name":"assetUids","in":"query","description":"Filter by asset stonal identifiers (repeatable, max 2000). When absent, all certificates of the organization are returned.","required":false,"schema":{"type":"array","items":{"type":"string"}}},{"name":"size","in":"query","description":"Number of results per page (default 50, max 2000)","required":false,"schema":{"type":"integer","format":"int32","default":50}},{"name":"cursor","in":"query","description":"Opaque cursor returned by a previous call. Use \"0\" to start.","required":false,"schema":{"type":"string","default":"0"}}],"responses":{"200":{"description":"Successfully got certificates","content":{"*/*":{"schema":{"$ref":"#/components/schemas/CertificatesGetResultResponse"}}}},"400":{"description":"Invalid query parameter","content":{"*/*":{"schema":{"$ref":"#/components/schemas/CertificatesGetResultResponse"}}}},"403":{"description":"Forbidden - Not authorized to access this organization","content":{"*/*":{"schema":{"$ref":"#/components/schemas/CertificatesGetResultResponse"}}}},"500":{"description":"Internal server error","content":{"*/*":{"schema":{"$ref":"#/components/schemas/CertificatesGetResultResponse"}}}}}}},"/v1/organizations/{organizationCode}/billing-events":{"get":{"tags":["Billing events"],"summary":"Get billing events","description":"List billing events for an organization, paginated with an opaque cursor ordered by ascending id. Without `requestedDate` nor `validFrom`/`validUntil`, only the events valid today are returned. Requires `stonal.asset.read` permission.","operationId":"getBillingEvents","parameters":[{"name":"organizationCode","in":"path","description":"Organization code","required":true,"schema":{"type":"string"}},{"name":"contractCodes","in":"query","description":"Filter by contract codes (repeatable, max 2000)","required":false,"schema":{"type":"array","items":{"type":"string"}}},{"name":"eventTypeCodes","in":"query","description":"Filter by billing event type codes (repeatable, max 2000)","required":false,"schema":{"type":"array","items":{"type":"string"}}},{"name":"requestedDate","in":"query","description":"Only events valid at this date, bounds included (yyyy-MM-dd)","required":false,"schema":{"type":"string"}},{"name":"validFrom","in":"query","description":"Only events valid at some point between validFrom and validUntil, bounds included (yyyy-MM-dd). Must be used with validUntil.","required":false,"schema":{"type":"string"}},{"name":"validUntil","in":"query","description":"See validFrom (yyyy-MM-dd). Must be used with validFrom.","required":false,"schema":{"type":"string"}},{"name":"size","in":"query","description":"Number of results per page (default 50, max 2000)","required":false,"schema":{"type":"integer","format":"int32","default":50}},{"name":"cursor","in":"query","description":"Opaque cursor returned by a previous call. Use \"0\" to start.","required":false,"schema":{"type":"string","default":"0"}}],"responses":{"200":{"description":"Successfully got billing events","content":{"*/*":{"schema":{"$ref":"#/components/schemas/BillingEventsGetResultResponse"}}}},"400":{"description":"Invalid query parameter","content":{"*/*":{"schema":{"$ref":"#/components/schemas/BillingEventsGetResultResponse"}}}},"403":{"description":"Forbidden - Not authorized to access this organization","content":{"*/*":{"schema":{"$ref":"#/components/schemas/BillingEventsGetResultResponse"}}}},"500":{"description":"Internal server error","content":{"*/*":{"schema":{"$ref":"#/components/schemas/BillingEventsGetResultResponse"}}}}}}},"/v1/organizations/{organizationCode}/asset-types/all":{"get":{"tags":["Public asset types"],"summary":"Get all asset types","description":"Get all asset types by organization","operationId":"getAllAssetTypes","parameters":[{"name":"organizationCode","in":"path","description":"Organization code","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successfully get all asset types","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicAssetTypesResponse"}}}},"403":{"description":"Forbidden - Not authorized to access this organization","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicAssetTypesResponse"}}}}}}},"/v1/organizations/{organizationCode}/asset-properties/all":{"get":{"tags":["Public properties"],"summary":"Get all asset properties","description":"Get all asset properties by organization","operationId":"getAllProperties","parameters":[{"name":"organizationCode","in":"path","description":"Organization code","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successfully get all asset types","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicPropertiesResponse"}}}},"403":{"description":"Forbidden - Not authorized to access this organization","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PublicPropertiesResponse"}}}}}}},"/v1/organizations/{organizationCode}/amendments":{"get":{"tags":["Amendments"],"summary":"List amendments","description":"Return amendments for an organization, paginated by ascending internal id via opaque cursor. Requires `stonal.asset.read` permission.","operationId":"getAmendments","parameters":[{"name":"organizationCode","in":"path","description":"Organization code","required":true,"schema":{"type":"string"}},{"name":"contractCode","in":"query","description":"Filter by contract business code","required":false,"schema":{"type":"string"}},{"name":"code","in":"query","description":"Filter by amendment business code","required":false,"schema":{"type":"string"}},{"name":"effectiveDateFrom","in":"query","description":"Inclusive lower bound on the amendment effective date (ISO date, e.g. 2024-01-01)","required":false,"schema":{"type":"string","format":"date"}},{"name":"effectiveDateTo","in":"query","description":"Inclusive upper bound on the amendment effective date (ISO date, e.g. 2024-12-31)","required":false,"schema":{"type":"string","format":"date"}},{"name":"size","in":"query","description":"Page size, between 1 and 2000","required":false,"schema":{"type":"integer","format":"int32","default":50}},{"name":"cursor","in":"query","description":"Opaque pagination cursor; '0' starts iteration, null in the response signals completion","required":false,"schema":{"type":"string","default":"0"}}],"responses":{"200":{"description":"Successfully fetched amendments","content":{"*/*":{"schema":{"$ref":"#/components/schemas/AmendmentsGetResultResponse"}}}},"400":{"description":"Invalid query parameter (size out of range, malformed cursor or date, inverted date range)","content":{"*/*":{"schema":{"$ref":"#/components/schemas/AmendmentsGetResultResponse"}}}},"403":{"description":"Forbidden - Not authorized to access this organization","content":{"*/*":{"schema":{"$ref":"#/components/schemas/AmendmentsGetResultResponse"}}}},"500":{"description":"Internal server error","content":{"*/*":{"schema":{"$ref":"#/components/schemas/AmendmentsGetResultResponse"}}}}}}},"/v1/organizations/{organizationCode}/contracts/{contractCode}":{"delete":{"tags":["Contracts"],"summary":"Delete a contract","description":"Delete a contract for an organization. Requires `stonal.asset.delete` permission. If the contract code contains URL-unsafe characters (e.g. `/` in `2021/Z5059`), it MUST be **double percent-encoded** in the path — `2021/Z5059` is sent as `2021%252FZ5059`.","operationId":"deleteContract","parameters":[{"name":"organizationCode","in":"path","description":"Organization code","required":true,"schema":{"type":"string"}},{"name":"contractCode","in":"path","description":"Contract code. Double percent-encode any character that is unsafe in a URL path segment (notably `/` → `%252F`); the server decodes the value twice.","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Successfully deleted the contract"},"403":{"description":"Forbidden - Not authorized to access this organization"},"404":{"description":"Contract not found"},"500":{"description":"Internal server error during deletion"}}}}},"components":{"schemas":{"QualifiedCoordinate":{"type":"object","properties":{"value":{"type":"string","description":"Value of the coordinate (phone number or email)","example":"0611223344"},"type":{"type":"string","description":"Qualifier of the coordinate","example":"Mobile"},"isPrimary":{"type":"boolean","description":"Whether this is the primary coordinate of its type","example":true}},"required":["isPrimary","type","value"]},"SaveContactDetailsResponseBody":{"type":"object","properties":{"email":{"type":"string","description":"Email address of the contact (required of type=person/company)","example":"john.doe@example.com"},"phoneNumber":{"type":["string","null"],"description":"Phone number of the contact (not required)","example":"0123456789"},"additionalInfos":{"type":["string","null"],"description":"Additional infos of the contact (not required)"}},"required":["email"]},"SaveStakeHolderRequestBody":{"type":"object","description":"Request body of creating or updating a stakeholder with a specific UID","properties":{"type":{"type":["string","null"],"description":"Type of stakeholder (person or company)","example":"person"},"uid":{"type":["string","null"],"description":"Unique identifier of the stakeholder (must match the path parameter)","example":"123e4567-e89b-12d3-a456-426614174000"},"firstName":{"type":["string","null"],"description":"First name of the person. Required for type=person, optional for a contact attached to a company (parentUid).","example":"John"},"lastName":{"type":["string","null"],"description":"Last name of the person, required for type=person. The single name (\"Nom du contact\") of a contact attached to a company.","example":"Doe"},"companyName":{"type":["string","null"],"description":"Company name (required of type=company)","example":"Acme Corporation"},"siren":{"type":["string","null"],"description":"SIREN number of the company (required of type=company)","example":"123456789"},"address":{"type":["string","null"],"description":"Address of the company"},"postalCode":{"type":["string","null"],"description":"Postal code of the company"},"city":{"type":["string","null"],"description":"City of the company"},"externalCode":{"type":["string","null"],"description":"External code of the company"},"contactsDetails":{"type":"array","description":"List of contact details of the stakeholder","items":{"$ref":"#/components/schemas/SaveContactDetailsResponseBody"}},"isActive":{"type":"boolean","description":"Active status of the stakeholder"},"fax":{"type":["string","null"],"description":"Fax of the company"},"function":{"type":["string","null"],"description":"Function of the person"},"parentUid":{"type":["string","null"],"description":"Refers to the stakeholder hierarchy only (not the asset perimeter or a contract): uid of this stakeholder's parent company — the mother company for a company, the attachment company for a person","example":"030f134a-fb24-4a16-8acb-d29d9ba50077"},"isPrimaryContact":{"type":["boolean","null"],"description":"Whether this person is the primary contact of its parent company (stakeholder hierarchy, see parentUid). Requires a parentUid; at most one child per parent, so setting true demotes the current primary contact. PUT replaces the stakeholder: absent means false.","example":true},"phoneNumbers":{"type":["array","null"],"description":"Qualified phone numbers of the stakeholder","items":{"$ref":"#/components/schemas/QualifiedCoordinate"}},"emails":{"type":["array","null"],"description":"Qualified emails of the stakeholder. A person needs an email (here or in contactsDetails); a contact attached to a company needs an email or a phone number.","items":{"$ref":"#/components/schemas/QualifiedCoordinate"}},"creationDate":{"type":"string","description":"Date of creation of the stakeholder. Accepts a plain date (yyyy-MM-dd) or an ISO 8601 datetime; the time portion, if present, is ignored.","example":"2021-01-01"}},"required":["contactsDetails","creationDate","isActive","type"]},"ContractLinkedView":{"type":"object","properties":{"id":{"type":"string","description":"Id of the contract"},"type":{"type":"string","description":"Type of the contract","example":"LEASE"},"code":{"type":"string","description":"Code of the contract"},"label":{"type":["string","null"],"description":"Label of the contract"},"startDate":{"type":["string","null"],"format":"date","description":"Date when the contract becomes effective","example":"2024-01-01"},"endDate":{"type":["string","null"],"format":"date","description":"End date of the contract, 3000-01-01 when it is open-ended","example":"2026-12-31"},"assetUids":{"type":["array","null"],"description":"Asset stonal ids linked of the contract","items":{"type":"string"}},"assetChildrenUids":{"type":["array","null"],"description":"Children assets stonal ids linked of the contract","items":{"type":"string"}}},"required":["code","id","type"]},"QualifiedCoordinateView":{"type":"object","properties":{"value":{"type":"string","description":"Value of the coordinate (phone number or email)","example":"0611223344"},"type":{"type":"string","description":"Qualifier of the coordinate","example":"Mobile"},"isPrimary":{"type":"boolean","description":"Whether this is the primary coordinate of its type","example":true}},"required":["isPrimary","type","value"]},"StakeHolderContactDetailView":{"type":"object","properties":{"phoneNumber":{"type":["string","null"],"description":"Phone number of the contact","example":"0123456789"},"additionalInfos":{"type":["string","null"],"description":"Additional infos of the contact","example":"Some additional infos"},"email":{"type":["string","null"],"description":"Email address of the contact, absent for a company's contact that only has a phone number","example":"john.doe@example.com"},"creationDate":{"type":["string","null"],"description":"Date of creation of the contact","example":"2020-01-01"}}},"StakeHolderParentView":{"type":"object","properties":{"uid":{"type":"string","description":"Uid of the parent","example":"030f134a-fb24-4a16-8acb-d29d9ba50077"},"name":{"type":"string","description":"Name of the parent","example":"Acme Corp"},"siren":{"type":["string","null"],"description":"SIREN of the parent","example":"552100554"}},"required":["name","uid"]},"StakeHolderView":{"type":"object","description":"Represents a stakeholder (person or company)","properties":{"uid":{"type":"string","format":"uuid","description":"Unique identifier of the stakeholder","example":"123e4567-e89b-12d3-a456-426614174000"},"type":{"type":"string","description":"Type of stakeholder (person or company)","example":"person"},"firstName":{"type":["string","null"],"description":"First name of the stakeholder (null for companies)","example":"John"},"lastName":{"type":["string","null"],"description":"Last name of the stakeholder (null for companies)","example":"Doe"},"name":{"type":"string","description":"Full name of the stakeholder (null for person, company name required)","example":"Stonal"},"siren":{"type":["string","null"],"description":"SIREN number of the companies (null for persons)","example":"123456789"},"address":{"type":["string","null"],"description":"Address of the company"},"postalCode":{"type":["string","null"],"description":"Postal code of the company"},"city":{"type":["string","null"],"description":"City of the company"},"externalCode":{"type":["string","null"],"description":"External code of the company"},"contactsDetails":{"type":["array","null"],"description":"List of contact details of the stakeholder","items":{"$ref":"#/components/schemas/StakeHolderContactDetailView"}},"phoneNumbers":{"type":["array","null"],"description":"Qualified phone numbers of the stakeholder","items":{"$ref":"#/components/schemas/QualifiedCoordinateView"}},"emails":{"type":["array","null"],"description":"Qualified emails of the stakeholder","items":{"$ref":"#/components/schemas/QualifiedCoordinateView"}},"contracts":{"type":["array","null"],"description":"Stakeholder contracts list","items":{"$ref":"#/components/schemas/ContractLinkedView"}},"contractTypes":{"type":"array","description":"Derived contact sub-type (read-only): the distinct holder-type codes of the stakeholder's active (non-terminated) contracts. Empty when the stakeholder has no active contract.","example":["LEASE","MAINTENANCE"],"items":{"type":"string"}},"isActive":{"type":"boolean","description":"Active status of the stakeholder"},"fax":{"type":["string","null"],"description":"Fax of the company"},"function":{"type":["string","null"],"description":"Function of the person"},"parentUid":{"type":["string","null"],"description":"Refers to the stakeholder hierarchy only (not the asset perimeter or a contract): uid of this stakeholder's parent company — the mother company for a company, the attachment company for a person","example":"030f134a-fb24-4a16-8acb-d29d9ba50077"},"parent":{"description":"Display-ready summary of the parent (same link as parentUid): lets a client render the selected parent (e.g. \"SIREN - name\" in the parent picker) without having paged through the company list to resolve the uid. Absent when the stakeholder has no parent.","oneOf":[{"$ref":"#/components/schemas/StakeHolderParentView"},{"type":"null"}]},"isPrimaryContact":{"type":"boolean","description":"Whether this stakeholder is the primary contact of its parent company (stakeholder hierarchy only, see parentUid). Always false without a parent; at most one child per parent.","example":true},"hasChildren":{"type":"boolean","description":"Refers to the stakeholder hierarchy only (not the asset perimeter or a contract): whether this stakeholder has at least one child — a company's subsidiaries or the persons attached to it. Fetch the children with ?parentUid=<this uid> on the search endpoint.","example":true},"childrenCount":{"type":"integer","format":"int32","description":"Number of direct children — the count behind hasChildren","example":3},"contractCount":{"type":"integer","format":"int32","description":"Number of active (non-terminated) contracts","example":2},"creationDate":{"type":["string","null"],"description":"Date of creation of the stakeholder","example":"2024-01-15"},"updatedAt":{"type":["string","null"],"description":"Date of last update of the stakeholder","example":"2024-11-10T14:30:00"}},"required":["childrenCount","contractCount","contractTypes","hasChildren","isActive","isPrimaryContact","name","type","uid"]},"CompanyContactCard":{"type":"object","description":"One contact card of a company: a person attached to it (parentUid)","properties":{"uid":{"type":["string","null"],"description":"Uid of the person. Absent on PUT for a card to create.","example":"030f134a-fb24-4a16-8acb-d29d9ba50077"},"name":{"type":["string","null"],"description":"Name of the contact (its single \"Nom du contact\"). On PUT a changed name becomes the lastName and clears the firstName.","example":"Mr Smith"},"function":{"type":["string","null"],"description":"Function or service of the contact","example":"Gardien"},"isPrimaryContact":{"type":"boolean","description":"Whether this contact is the company's primary contact. At most one card is true; omitted means false.","example":true},"phoneNumber":{"description":"Primary phone number of the contact, null if none. A card needs a phone number or an email. On PUT, a new value replaces the phone number the card showed and null removes it; the person's other phone numbers are kept, so after a removal the next stored one becomes primary and is shown on the card.","oneOf":[{"$ref":"#/components/schemas/CompanyContactCoordinate"},{"type":"null"}]},"email":{"description":"Primary email of the contact, null if none. A card needs a phone number or an email. On PUT, a new value replaces the email the card showed and null removes it; the person's other emails are kept, so after a removal the next stored one becomes primary and is shown on the card.","oneOf":[{"$ref":"#/components/schemas/CompanyContactCoordinate"},{"type":"null"}]},"contractCount":{"type":"integer","format":"int32","description":"Number of contracts the contact is linked to, terminated ones included. A contact linked to a contract cannot be left out of a PUT (409). Ignored on PUT.","example":0,"readOnly":true}},"required":["name"]},"CompanyContactCoordinate":{"type":"object","properties":{"value":{"type":["string","null"],"description":"Phone number or email. On PUT, a coordinate without value counts as none.","example":"0472000000"},"type":{"type":["string","null"],"description":"Qualifier of the coordinate. On PUT, a null or blank type keeps the type already stored for that value; a new value without type is stored without one.","example":"LANDLINE"}}},"ErrorResponse":{"type":"object","description":"Response for any requested that occurs errors","properties":{"type":{"type":"string","description":"A tag or a link that categorize and explains the issue","example":"tag:InvalidBody"},"title":{"type":"string","description":"A short, human-readable summary of the problem type","example":"Invalid body"},"detail":{"type":["string","null"],"default":"null","description":"A human-readable explanation specific to this occurrence of the problem","example":"The request body is invalid"},"errors":{"type":["array","null"],"default":"null","description":"Errors that occurred during the request on the fields","example":[{"field":"a_field_name","detail":"required"}],"items":{"$ref":"#/components/schemas/FieldError"}},"instance":{"type":["string","null"],"default":"null","description":"A URI reference that identifies the specific occurrence of the problem","example":"https://example.com/errors/invalid-body"}},"required":["title","type"]},"FieldError":{"type":"object","description":"Details of the request error","properties":{"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem"},"field":{"type":"string","description":"The identifier of the field that is causing the issue"},"instance":{"type":["string","null"],"default":"null","description":"A URI reference that identifies the specific occurrence of the problem","example":"https://example.com/errors/invalid-body"},"code":{"type":["string","null"],"description":"Stable machine-readable code of the error, on the endpoints that define one (company contact cards); absent elsewhere","example":"EMAIL_ALREADY_USED"},"params":{"type":["object","null"],"additionalProperties":{"type":"string"},"description":"Values of this occurrence for the code, such as the offending value","example":{"value":"jean@presta.fr"}}},"required":["detail","field"]},"CreateStakeHolderRequestBody":{"type":"object","description":"Request body for creating a new stakeholder","properties":{"type":{"type":"string","description":"Type of stakeholder (person or company)","example":"person"},"firstName":{"type":["string","null"],"description":"First name of the person. Required for type=person, optional for a contact attached to a company (parentUid).","example":"John"},"lastName":{"type":["string","null"],"description":"Last name of the person, required for type=person. The single name (\"Nom du contact\") of a contact attached to a company.","example":"Doe"},"companyName":{"type":["string","null"],"description":"Company name (required for type=company)","example":"Acme Corporation"},"siren":{"type":["string","null"],"description":"SIREN number for company (required for type=company)","example":"123456789"},"address":{"type":["string","null"],"description":"Address of the company"},"postalCode":{"type":["string","null"],"description":"Postal code of the company"},"city":{"type":["string","null"],"description":"City of the company"},"externalCode":{"type":["string","null"],"description":"External code of the company"},"contactsDetails":{"type":["array","null"],"description":"Contact details of the company","items":{"$ref":"#/components/schemas/CreateStakeholderContactDetail"}},"isActive":{"type":"boolean","description":"Contact active status of the company or person"},"fax":{"type":["string","null"],"description":"Fax of the company"},"function":{"type":["string","null"],"description":"Function of the person"},"parentUid":{"type":["string","null"],"description":"Refers to the stakeholder hierarchy only (not the asset perimeter or a contract): uid of this stakeholder's parent company — the mother company for a company, the attachment company for a person","example":"030f134a-fb24-4a16-8acb-d29d9ba50077"},"isPrimaryContact":{"type":["boolean","null"],"description":"Whether this person is the primary contact of its parent company (stakeholder hierarchy, see parentUid). Requires a parentUid; at most one child per parent, so setting true demotes the current primary contact.","example":true},"phoneNumbers":{"type":["array","null"],"description":"Qualified phone numbers of the stakeholder","items":{"$ref":"#/components/schemas/QualifiedCoordinate"}},"emails":{"type":["array","null"],"description":"Qualified emails of the stakeholder. A person needs an email (here or in contactsDetails); a contact attached to a company needs an email or a phone number.","items":{"$ref":"#/components/schemas/QualifiedCoordinate"}}},"required":["isActive","type"]},"CreateStakeholderContactDetail":{"type":"object","properties":{"email":{"type":["string","null"],"description":"Email address of the contact. A person needs one, unless it is a contact attached to a company with a phone number.","example":"john.doe@example.com"},"phoneNumber":{"type":["string","null"],"description":"Phone number of the contact (not required)","example":"0123456789"},"additionalInfos":{"type":["string","null"],"description":"Additional infos of the contact (not required)"}}},"CreateStakeHolderResponseBody":{"type":"object","description":"Response body for stakeholder creation","properties":{"uid":{"type":["string","null"],"format":"uuid","description":"Unique identifier of the created stakeholder (null if creation failed)","example":"123e4567-e89b-12d3-a456-426614174000"},"invalidRequest":{"description":"Invalid request details (present only if there were validation errors)","oneOf":[{"$ref":"#/components/schemas/CreateStakeHolderRequestBody"},{"type":"null"}]},"error":{"type":["string","null"],"description":"Error message (present only if there was an error)","example":"Your request could not be processed. Please try again later or contact support."}}},"CreateSelectionSessionRequest":{"type":"object","description":"Request body for creating a selection session","properties":{"selection":{"$ref":"#/components/schemas/SelectionData"},"context":{"$ref":"#/components/schemas/SelectionContext"}},"required":["context","selection"]},"SelectionContext":{"type":"object","description":"Context information including, among other things, base view, selectable assets, and UI options","properties":{"baseView":{"type":["array","null"],"example":[{"uid":"550e8400-e29b-41d4-a716-446655440000"}],"items":{"$ref":"#/components/schemas/SelectionContextBaseViewItem"}},"selectableAssets":{"type":["array","null"],"example":[{"type":"EQUIPMENT|.*"}],"items":{"type":"object","additionalProperties":{}}},"uiOptions":{"type":["object","null"],"additionalProperties":{},"example":{"viewAssetDetails":true}}}},"SelectionContextBaseViewItem":{"type":"object","properties":{"uid":{"type":["string","null"],"example":"550e8400-e29b-41d4-a716-446655440000"},"externalIds":{"type":["object","null"],"additionalProperties":{"type":"string"},"description":"Only one external identifier, where the key is the source name and the value is the identifier in that source system.","example":{"CODE":"A-0913"}}}},"SelectionData":{"type":"object","properties":{"selectedAssets":{"type":["array","null"],"description":"Selection data containing the list of selected asset UIDs","example":["3d0eab45-e2cc-4b80-addf-5ee0e77a5dcc","a1b2c3d4-e5f6-7890-abcd-ef1234567890"],"items":{"type":"string"}}}},"CreateSelectionSessionResponse":{"type":"object","description":"Response containing the created selection session UID and access URL","example":{"uid":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","url":"https://app.stonal.io/plans/ORGCODE/selection/?sessionId=a1b2c3d4-e5f6-7890-abcd-ef1234567890"},"properties":{"uid":{"type":"string","format":"uuid","description":"Unique identifier of the created selection session","example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"},"url":{"type":"string","description":"URL to access the selection view with the created session","example":"https://app.stonal.io/plans/ORGCODE/selection/?sessionId=a1b2c3d4-e5f6-7890-abcd-ef1234567890"}},"required":["uid","url"]},"ContractCreationRequest":{"type":"object","description":"Request body for creating a new contract","properties":{"label":{"type":["string","null"],"description":"Label of the contract"},"type":{"type":["string","null"],"description":"Type of the contract","example":"LEASE or OTHER"},"code":{"type":["string","null"],"description":"Code of the contract"},"assets":{"type":"array","description":"Assets linked of the contract","items":{"type":"string"},"uniqueItems":true},"stakeholders":{"type":"array","description":"Stakeholders linked of the contract","items":{"type":"string"},"uniqueItems":true},"equipments":{"type":"array","deprecated":true,"description":"Equipments linked of the contract (deprecated, use the V2 `installations` field instead)","items":{"type":"string"},"uniqueItems":true},"effectiveDate":{"type":["string","null"],"description":"Effective date of the contract (accepts yyyy-MM-dd or dd/MM/yyyy)","example":"2023-01-01"},"endDate":{"type":["string","null"],"description":"End date of the contract (accepts yyyy-MM-dd or dd/MM/yyyy)","example":"2023-01-01"}},"required":["assets","equipments","stakeholders"]},"Asset":{"type":"object","properties":{"uid":{"type":["string","null"],"description":"Unique identifier for the asset (typically UUID)","example":"519c00c9-29b1-4e16-8ed2-61bb4a8d6249"},"externalIds":{"type":["object","null"],"additionalProperties":{"type":"string"},"description":"Map of external system identifiers. Values can be null to delete a specific external ID.","example":{"CODE":"001"}},"temporaryId":{"type":["string","null"]},"type":{"type":["string","null"],"description":"Type of asset","example":"BUILDING"},"name":{"type":["string","null"]},"deletedAt":{"type":["string","null"],"description":"Date when the asset was deleted. ISO 8601 format","example":"2025-11-19T16:30:00Z"},"effectiveDate":{"type":["string","null"],"description":"Date when the asset is effective. ISO 8601 format","example":"2024-11-19"},"groupedBy":{"type":["array","null"],"description":"List of all assets grouping the current asset","items":{"$ref":"#/components/schemas/AssetIds"}},"groupingAssetsToAdd":{"type":["array","null"],"description":"List of assets to add to list of assets grouping the current asset","items":{"$ref":"#/components/schemas/AssetIds"}},"groupingAssetsToRemove":{"type":["array","null"],"description":"List of assets to remove from the list of assets grouping the current asset. References that do not currently group the asset are ignored.","items":{"$ref":"#/components/schemas/AssetIds"}},"groups":{"type":["array","null"],"description":"List of all assets grouped by the current asset","items":{"$ref":"#/components/schemas/AssetIds"}},"properties":{"oneOf":[{"$ref":"#/components/schemas/AssetProperties"},{"type":"null"}]},"parent":{"oneOf":[{"$ref":"#/components/schemas/AssetIds"},{"type":"null"}]},"expirationDate":{"type":["string","null"]}}},"AssetIds":{"type":"object","properties":{"uid":{"type":["string","null"]},"externalIds":{"type":["object","null"],"additionalProperties":{"type":"string"}},"temporaryId":{"type":["string","null"]}}},"AssetProperties":{"type":"object","properties":{"source":{"type":["string","null"]},"simple":{"type":["object","null"],"additionalProperties":{"type":"string"}},"precise":{"type":["string","null"],"additionalProperties":{"$ref":"#/components/schemas/UpsertPublicAssetPrecisePropertiesDatum"},"description":"Each key represents the code of a property, mapped to its corresponding list of time-based values","example":{"TAUX_ROTATION_ANNUEL":[{"startDate":"2020-01-02","endDate":"2024-01-03","rawValue":"17,00"}]}}}},"EffectiveDate":{"type":"object","properties":{"value":{"type":"string","format":"date"},"isMinSystemDate":{"type":"boolean"}},"required":["isMinSystemDate","value"]},"ExpirationDate":{"type":"object","properties":{"value":{"type":"string","format":"date"}},"required":["value"]},"UpsertAssetsRequest":{"type":"object","description":"Request for creating or updating public asset","properties":{"assets":{"type":"array","items":{"$ref":"#/components/schemas/Asset"}},"options":{"oneOf":[{"$ref":"#/components/schemas/SaveAssetsCommandOptions"},{"type":"null"}]}},"required":["assets"]},"UpsertPublicAssetPrecisePropertiesDatum":{"type":"object","properties":{"rawValue":{"type":"string"},"startDate":{"oneOf":[{"$ref":"#/components/schemas/EffectiveDate"},{"type":"null"}]},"endDate":{"oneOf":[{"$ref":"#/components/schemas/ExpirationDate"},{"type":"null"}]}},"required":["rawValue"]},"SaveAssetsCommandOptions":{"type":"object","properties":{"properties":{"oneOf":[{"$ref":"#/components/schemas/SaveAssetsCommandPropertiesOptions"},{"type":"null"}]}}},"SaveAssetsCommandPropertiesOptions":{"type":"object","properties":{"ignoreUnknowns":{"type":["boolean","null"]},"ignoreNonApplicableToType":{"type":["boolean","null"]}}},"ErrorInfo":{"type":"object","properties":{"statusCode":{"type":"integer","format":"int32"},"code":{"type":"string"},"message":{"type":"string"},"details":{"type":["string","null"]},"payload":{"type":["object","null"],"additionalProperties":{}},"timestamp":{"type":"string"}},"required":["code","message","statusCode","timestamp"]},"IngestAssetsFailResponse":{"allOf":[{"$ref":"#/components/schemas/PublicAssetResponse"},{"type":"object","properties":{"error":{"$ref":"#/components/schemas/ErrorInfo","description":"Error response entity"}}}],"description":"Failure response containing error information","required":["error"]},"IngestAssetsIssue":{"type":"object","description":"A diagnostic about how the platform handled an input row. The asset may be persisted, possibly with reduced data.","properties":{"severity":{"type":"string","description":"Severity level of this issue","enum":["WARNING","ERROR"]},"asset":{"$ref":"#/components/schemas/AssetIds","description":"Identifiers of the affected input asset, echoed from the request"},"code":{"type":"string","description":"Stable machine-readable issue code: PROPERTY_NOT_APPLICABLE_TO_TYPE, UNKNOWN_PROPERTY or INVALID_ENUM_VALUE","example":"PROPERTY_NOT_APPLICABLE_TO_TYPE"},"field":{"type":["string","null"],"description":"JSON-pointer-like path to the offending input field, when applicable","example":"properties.precise[ADDRESS]"},"message":{"type":"string","description":"Human-readable description of the issue","example":"Property 'ADDRESS' is not applicable to type 'PLAN|INDOOR'"}},"required":["asset","code","message","severity"]},"IngestAssetsSuccessResponse":{"allOf":[{"$ref":"#/components/schemas/PublicAssetResponse"},{"type":"object","properties":{"assets":{"type":"array","description":"List of ingested assets","items":{"$ref":"#/components/schemas/Asset"}},"issues":{"type":"array","description":"Diagnostics raised while processing the ingest (warnings, errors, info). Empty when there is nothing to report.","items":{"$ref":"#/components/schemas/IngestAssetsIssue"}}}}],"description":"Response containing the list of ingested assets","required":["assets","issues"]},"PublicAssetResponse":{"description":"Base sealed class for public asset responses"},"SearchAssetBelongsTo":{"type":"object","properties":{"types":{"type":"array","description":"Asset type codes to resolve. Each code also matches its subtypes (`PLAN` matches `PLAN|INDOOR`). Between 1 and 10 distinct codes; duplicates and surrounding whitespace are ignored.","example":["SPACE","BUILDING"],"items":{"type":"string"}}},"required":["types"]},"SearchAssetDataCondition":{"type":"object","description":"A single filter condition on property data","properties":{"op":{"type":"string","description":"Condition operator","enum":["eq","neq","in","notIn","contains","notContains","regex","notRegex","gt","gte","lt","lte","isNull","isNotNull","and","or"],"example":"eq"},"property":{"type":["string","null"],"description":"Property code to filter on (leaf conditions only)","example":"ISSUES_NB"},"value":{"type":["string","null"],"description":"Comparison value (single-value operators)","example":"2"},"values":{"type":["array","null"],"description":"Comparison values (for in/notIn operators)","items":{"type":"string"}},"conditions":{"type":["array","null"],"description":"Nested conditions (for and/or group operators)","items":{"$ref":"#/components/schemas/SearchAssetDataCondition"}}},"required":["op"]},"SearchAssetFieldFilter":{"type":"object","description":"\n        Filter on an asset field.\n         \n        - Only one of 'equals' or 'matches' can be provided at the same time.\n        - Only one of 'notEquals' or 'notMatches' can be provided at the same time.\n        If both are set in either pair, the request is considered invalid.\n    ","properties":{"equals":{"type":["array","null"],"description":"Exact matching","example":["BUILDING_GROUP"],"items":{"type":"string"}},"matches":{"type":["array","null"],"description":"Regex matching","example":["EQUIPMENT\\|.*"],"items":{"type":"string"}},"notEquals":{"type":["array","null"],"description":"Exclude using exact matching","items":{"type":"string"}},"notMatches":{"type":["array","null"],"description":"Exclude using regex matching","items":{"type":"string"}}}},"SearchAssetFilters":{"type":"object","properties":{"asset":{"description":"Identifier of the asset to search for","oneOf":[{"$ref":"#/components/schemas/SearchAssetIds"},{"type":"null"}]},"assets":{"type":["array","null"],"description":"List of asset identifiers to search for. Returns assets matching any of the provided identifiers.","items":{"$ref":"#/components/schemas/SearchAssetIds"}},"parent":{"description":"Identifier of the parent asset used to search for its child assets","oneOf":[{"$ref":"#/components/schemas/SearchAssetIds"},{"type":"null"}]},"parentRecursive":{"description":"Identifier of an ancestor asset used to search recursively for all its descendant assets","oneOf":[{"$ref":"#/components/schemas/SearchAssetIds"},{"type":"null"}]},"child":{"description":"Identifier of the child asset used to search for its containing or grouping parent assets","oneOf":[{"$ref":"#/components/schemas/SearchAssetIds"},{"type":"null"}]},"childRecursive":{"description":"Identifier of a descendant asset used to search recursively for all its ancestor assets","oneOf":[{"$ref":"#/components/schemas/SearchAssetIds"},{"type":"null"}]},"groupingParent":{"description":"Identifier of the grouping parent asset used to search for assets grouped under it (GROUPS relation)","oneOf":[{"$ref":"#/components/schemas/SearchAssetIds"},{"type":"null"}]},"name":{"oneOf":[{"$ref":"#/components/schemas/SearchAssetFieldFilter"},{"type":"null"}]},"type":{"oneOf":[{"$ref":"#/components/schemas/SearchAssetFieldFilter"},{"type":"null"}]},"includeDeleted":{"type":["boolean","null"],"default":false,"description":"If `false` or undefined only returns non deleted assets. If `true` also includes deleted assets"},"isDeleted":{"type":["boolean","null"],"description":"If `true`, returns only soft-deleted assets. If `false` or undefined, returns only non-deleted assets. Cannot be combined with `includeDeleted: true`"},"includeExpired":{"type":["boolean","null"],"default":false,"description":"If `false` or undefined only returns non expired assets. If `true` also includes expired assets"},"updatedAtAfter":{"type":["string","null"],"description":"Filter on assets updated after this date. Use ISO 8601 format","example":"2025-11-10"},"representations":{"oneOf":[{"$ref":"#/components/schemas/SearchRepresentationsFilter"},{"type":"null"}]},"properties":{"description":"Filter assets by property data values. Conditions are combined with implicit AND.","oneOf":[{"$ref":"#/components/schemas/SearchAssetPropertyFilter"},{"type":"null"}]},"q":{"type":["string","null"],"description":"Free-text search over asset name and external id values (substring, case- and accent-insensitive). Between 3 and 500 characters. Combined with the other filters using AND, except `includeDeleted` and `isDeleted`: free-text search only covers non-deleted assets.","example":"01S"}}},"SearchAssetIds":{"type":"object","properties":{"uid":{"type":["string","null"],"description":"Unique identifier for the asset (typically UUID)","example":"519c00c9-29b1-4e16-8ed2-61bb4a8d6249"},"externalIds":{"type":["object","null"],"additionalProperties":{"type":"string"},"description":"Must contains only one external system identifier","example":{"CODE":"001"}}}},"SearchAssetPaginate":{"type":"object","properties":{"size":{"type":"integer","format":"int32","default":50,"description":"Number of results","maximum":2000},"cursor":{"type":["string","null"],"default":"0","description":"A marker indicating the position in a dataset, used to determine where to continue fetching results in paginated data"}}},"SearchAssetPreciseProperties":{"type":"object","properties":{"codes":{"type":"array","description":"Explicit property codes to return. The wildcard '*' is NOT supported for precise.","example":["TENANT_NAME"],"items":{"type":"string"}},"onlyReference":{"type":"boolean","default":true,"description":"If true (default) only the reference value is returned; if false all sources are returned."},"startDate":{"type":["string","null"],"description":"Lower bound of the validity window (ISO 8601 date). Defaults to now.","example":"2020-01-01"},"endDate":{"type":["string","null"],"description":"Upper bound of the validity window (ISO 8601 date). Defaults to now.","example":"2035-01-01"}},"required":["codes"]},"SearchAssetProperties":{"type":"object","properties":{"simple":{"type":"array","description":"Property codes whose current reference value is returned as a flat {code: value} map.","example":["ADDRESS"],"items":{"type":"string"}},"precise":{"description":"Property codes returned with their source and reference metadata, as a list of timeline entries per code.","oneOf":[{"$ref":"#/components/schemas/SearchAssetPreciseProperties"},{"type":"null"}]}},"required":["simple"]},"SearchAssetPropertyFilter":{"type":"object","description":"Filter assets by property data values","properties":{"conditions":{"type":"array","description":"List of conditions (implicit AND between root conditions)","items":{"$ref":"#/components/schemas/SearchAssetDataCondition"}}},"required":["conditions"]},"SearchAssetsRequest":{"type":"object","properties":{"search":{"$ref":"#/components/schemas/SearchAssetFilters"},"paginate":{"$ref":"#/components/schemas/SearchAssetPaginate","description":"Size is set to 50 by default"},"fields":{"type":"array","description":"Fields to include in the response, in addition to `uid` which is always included.\n                         Allowed values are: `uid`, `name`, `updatedAt`, `deletedAt`, `type`, `externalIds`, `representations`, `parent`, `groupedBy`, `effectiveDate`, `expirationDate`, `integrationDate`, `childCount`, `containsChildCount`, `groupsChildCount`.\n                         `childCount` counts all children, `containsChildCount` only hierarchy (contains) children, `groupsChildCount` only grouped (GROUPS) children.","example":["name","type"],"items":{"type":"string"}},"properties":{"oneOf":[{"$ref":"#/components/schemas/SearchAssetProperties"},{"type":"null"}]},"belongsTo":{"description":"Optional projection: for each requested asset type code, the assets this asset belongs to — reached upwards through containing and grouping relations at any depth, whose type is that code or one of its subtypes.\n                         This is the per-row, upward counterpart of the `childRecursive` filter — not of `parentRecursive`, which walks downwards from a single anchor.\n                         See the `belongsTo` field of the response for how to read the result: which codes come back as keys, in what order, and what each entry carries.","oneOf":[{"$ref":"#/components/schemas/SearchAssetBelongsTo"},{"type":"null"}]}},"required":["fields","paginate","search"]},"SearchRepresentationsFilter":{"type":"object","properties":{"isPresent":{"type":"boolean","description":"Filter on assets having or not a representation. `true`: Only assets with representation. `false`: Only assets without representation. If not specified, return both assets having or not a representation"}},"required":["isPresent"]},"AssetRepresentations":{"type":"object","properties":{"implicitPosition":{"oneOf":[{"$ref":"#/components/schemas/Coordinate"},{"type":"null"}]},"isGraphic":{"type":["boolean","null"]},"box":{},"outlines":{"type":["array","null"],"items":{"type":"array","items":{"$ref":"#/components/schemas/Coordinate"}}},"face":{},"polyline":{"type":["array","null"],"items":{"$ref":"#/components/schemas/PolylineCoordinate"}},"background":{"type":["string","null"]}}},"Coordinate":{"type":"object","properties":{"x":{"type":"number","format":"double"},"y":{"type":"number","format":"double"}},"required":["x","y"]},"PolylineCoordinate":{"type":"object","properties":{"x":{"type":"number","format":"double"},"y":{"type":"number","format":"double"},"z":{"type":["number","null"],"format":"double"}},"required":["x","y"]},"SearchAssetPreciseDatum":{"type":"object","properties":{"rawValue":{"type":"string"},"source":{"type":["string","null"],"description":"Raw source name of the value (e.g. REVIT, IKOS, DATALAKE), or the userUid for a manual (USER) source"},"startDate":{"type":["string","null"],"description":"Start of the value validity window; null when open (min system date)"},"endDate":{"type":["string","null"],"description":"End of the value validity window; null when open (max system date)"},"isReference":{"type":"boolean","description":"Whether this value is the reference (elected) value among its sources"}},"required":["isReference","rawValue"]},"SearchAssetResponseProperties":{"type":"object","properties":{"simple":{"type":["object","null"],"additionalProperties":{"type":"string"},"description":"Current reference value of each requested property, as a flat {code: value} map"},"precise":{"type":["object","null"],"additionalProperties":{"type":"array","items":{"$ref":"#/components/schemas/SearchAssetPreciseDatum"}},"description":"Each requested property mapped to its list of value entries, each carrying its source, validity window and reference flag"}}},"SearchAssetsResponse":{"type":"object","properties":{"assets":{"type":"array","items":{"$ref":"#/components/schemas/SearchPublicAsset"}},"paginate":{"$ref":"#/components/schemas/SearchAssetPaginate"}},"required":["assets","paginate"]},"SearchPublicAsset":{"type":"object","properties":{"uid":{"type":["string","null"]},"name":{"type":["string","null"]},"updatedAt":{"type":["string","null"]},"type":{"type":["string","null"]},"parent":{"oneOf":[{"$ref":"#/components/schemas/SearchAssetIds"},{"type":"null"}]},"groupedBy":{"type":["array","null"],"items":{"$ref":"#/components/schemas/SearchAssetIds"}},"belongsTo":{"type":["object","null"],"additionalProperties":{"type":"array","items":{"$ref":"#/components/schemas/SearchAssetIds"}},"description":"The assets this asset belongs to, keyed by requested asset type code. Only present when `belongsTo.types` was provided in the request.\n                         Only the codes actually matched are keys: a requested code with no match, or unknown to the organization, is absent from the map — read it as `belongsTo.<code> ?? []`. A missing key is normal and frequent, not a data gap: an equipment in a common area belongs to no rented unit, and a finish on an exterior wall belongs to no room.\n                         Each key maps to a list with no defined order: an asset usually belongs to several levels at once, and the first one is not the nearest. Picking a single one is a precedence rule of the calling system.\n                         Each entry carries the asset `uid`, the same shape `parent` and `groupedBy` use.","example":{"SPACE":[{"uid":"21bd52bf-9c4a-4e77-b1d2-0c8f5a6e3b90"}],"BUILDING":[{"uid":"1e74b23e-5f80-4a21-9de3-7b41c0a2f6d5"}]}},"deletedAt":{"type":["string","null"]},"externalIds":{"type":["object","null"],"additionalProperties":{"type":"string"}},"properties":{"oneOf":[{"$ref":"#/components/schemas/SearchAssetResponseProperties"},{"type":"null"}]},"representations":{"oneOf":[{"$ref":"#/components/schemas/AssetRepresentations"},{"type":"null"}]},"effectiveDate":{"type":["string","null"]},"expirationDate":{"type":["string","null"]},"integrationDate":{"type":["string","null"]},"childCount":{"type":["integer","null"],"format":"int64"},"containsChildCount":{"type":["integer","null"],"format":"int64"},"groupsChildCount":{"type":["integer","null"],"format":"int64"}}},"UpdateContactDetailsRequestBody":{"type":"object","properties":{"email":{"type":["string","null"],"description":"Email address of the contact (optional)","example":"john.doe@example.com"},"phoneNumber":{"type":["string","null"],"description":"Phone number of the contact (optional)","example":"0123456789"},"additionalInfos":{"type":["string","null"],"description":"Additional infos of the contact (optional)"},"creationDate":{"type":["string","null"],"description":"Date of creation of the contact (optional)","example":"2020-01-01"}}},"UpdateStakeHolderRequestBody":{"type":"object","description":"Request body for partially updating an existing stakeholder (HTTP PATCH)","properties":{"firstName":{"type":["string","null"],"description":"First name of the person (only for person stakeholders). Optional for a contact attached to a company (parentUid), where a blank value clears it.","example":"John"},"lastName":{"type":["string","null"],"description":"Last name of the person (only for person stakeholders)","example":"Doe"},"companyName":{"type":["string","null"],"description":"Company name (only for company stakeholders)","example":"Acme Corporation"},"siren":{"type":["string","null"],"description":"SIREN number (only for company stakeholders)","example":"123456789"},"address":{"type":["string","null"],"description":"Address of the company"},"postalCode":{"type":["string","null"],"description":"Postal code of the company"},"city":{"type":["string","null"],"description":"City of the company"},"externalCode":{"type":["string","null"],"description":"External code of the company"},"contactsDetails":{"type":["array","null"],"description":"Contact details list. If present, it REPLACES the existing list.","items":{"$ref":"#/components/schemas/UpdateContactDetailsRequestBody"}},"isActive":{"type":["boolean","null"],"description":"Active flag. If present, it updates the current value.","example":true},"fax":{"type":["string","null"],"description":"Fax of the company"},"function":{"type":["string","null"],"description":"Function of the person"},"phoneNumbers":{"type":["array","null"],"description":"Qualified phone numbers. If present, it REPLACES the existing list.","items":{"$ref":"#/components/schemas/QualifiedCoordinate"}},"emails":{"type":["array","null"],"description":"Qualified emails. If present, it REPLACES the existing list.","items":{"$ref":"#/components/schemas/QualifiedCoordinate"}},"isPrimaryContact":{"type":["boolean","null"],"description":"Whether this person is the primary contact of its parent company. If absent, it is kept while the parent is unchanged and cleared when the person is detached or moved. Setting true demotes the current primary contact of the same parent.","example":true},"parentUid":{"type":["string","null"],"description":"Refers to the stakeholder hierarchy only (not the asset perimeter or a contract): uid of this stakeholder's parent company — the mother company for a company, the attachment company for a person","example":"030f134a-fb24-4a16-8acb-d29d9ba50077"}}},"ContractAssetLinkRequest":{"type":"object","description":"An asset linked to the contract. Accepts the asset's bare Stonal identifier, or an object also carrying the link's explicit expiration date","properties":{"code":{"type":"string","description":"Stonal identifier of the asset"},"expirationDate":{"type":["string","null"],"description":"Expiration date of this asset link (accepts yyyy-MM-dd or dd/MM/yyyy). When sent, it sets the link's own date in either direction - reopening a closed link included - and wins over the termination-date closing. When omitted, the stored link keeps its own date","example":"3000-01-01"}},"required":["code"]},"ContractUpdateRequest":{"type":"object","description":"Request body for updating a contract","properties":{"contractCode":{"type":"string","description":"Code of the contract"},"assets":{"type":["array","null"],"description":"Assets linked of the contract. Each element is either the asset's Stonal identifier, or an object also carrying the link's explicit expiration date","items":{"anyOf":[{"type":"string"},{"$ref":"#/components/schemas/ContractAssetLinkRequest"}],"description":"The asset's Stonal identifier, or an object also carrying the link's explicit expiration date"},"uniqueItems":true},"stakeholders":{"type":["array","null"],"description":"Stakeholders linked of the contract","items":{"type":"string"},"uniqueItems":true},"equipments":{"type":["array","null"],"deprecated":true,"description":"Equipments linked of the contract (deprecated, use the V2 `installations` field instead)","items":{"type":"string"},"uniqueItems":true},"effectiveDate":{"type":["string","null"],"description":"Effective date of the contract (accepts yyyy-MM-dd or dd/MM/yyyy)","example":"2023-01-01"},"endDate":{"type":["string","null"],"description":"End date of the contract (accepts yyyy-MM-dd or dd/MM/yyyy)","example":"2023-01-01"},"terminationDate":{"type":["string","null"],"description":"Termination date of the contract (accepts yyyy-MM-dd or dd/MM/yyyy). When sent, also closes every asset link that would expire after it, except a link carrying its own explicit expiration date","example":"2023-01-01"},"label":{"type":["string","null"],"description":"Label of the contract"},"type":{"type":["string","null"],"description":"Type of the contract","example":"LEASE or OTHER"}},"required":["contractCode"]},"PageRequested":{"type":"object","description":"Information about the requested page in paginated responses","properties":{"page":{"type":"integer","format":"int32","description":"Page number (zero-based)","example":0},"size":{"type":"integer","format":"int32","description":"Number of items per page","example":10},"sort":{"type":["string","null"],"description":"Field used for sorting","example":"name"},"direction":{"type":["string","null"],"description":"Sort direction (ASC or DESC)","example":"ASC"}},"required":["page","size"]},"SearchStakeHolderResponseBody":{"type":"object","description":"Response body for stakeholder search operations","properties":{"error":{"type":["string","null"],"description":"Error message (present only if there was an error)","example":"Your request could not be processed. Please try again later or contact support."},"result":{"type":["array","null"],"description":"Collection of stakeholders matching the search criteria","items":{"$ref":"#/components/schemas/StakeHolderView"}},"total":{"type":["integer","null"],"format":"int64","description":"Total number of stakeholders matching the search criteria","example":42},"totalPages":{"type":["integer","null"],"format":"int32","description":"Total number of pages available","example":5},"pageRequested":{"description":"Information about the requested page","oneOf":[{"$ref":"#/components/schemas/PageRequested"},{"type":"null"}]}}},"GetSelectionSessionResponse":{"type":"object","description":"Response for getting a selection session containing its selection data and context","properties":{"selection":{"$ref":"#/components/schemas/SelectionData","description":"Selection data containing the list of selected asset UIDs","example":"{\n          \"selectedAssets\": [\"3d0eab45-e2cc-4b80-addf-5ee0e77a5dcc\", \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\"],\n        }"},"context":{"type":"object","additionalProperties":{},"description":"Context information including, among other things, base view, selectable assets, and UI options","example":"{\n          \"baseView\": [{\"uid\": \"550e8400-e29b-41d4-a716-446655440000\"}],\n          \"selectableAssets\": [{\"type\": \"EQUIPMENT|.*\"}],\n          \"uiOptions\": {\"viewAssetDetails\": true},\n          \"customField\": \"value\",\n        }"}},"required":["context","selection"]},"AssetBuildingStructure":{"type":"object","properties":{"stonalId":{"type":"string"},"level":{"type":"string"},"name":{"type":"string"},"parentStonalId":{"type":"string"},"numberOfChildren":{"type":"integer","format":"int32"},"holderTypeName":{"type":"array","items":{"$ref":"#/components/schemas/StructureHolderTypeName"},"uniqueItems":true},"plan3DLink":{"type":["string","null"]},"guid":{"type":["string","null"]}},"required":["holderTypeName","level","name","numberOfChildren","parentStonalId","stonalId"]},"StructureHolderTypeName":{"type":"object","properties":{"singular":{"type":"string"},"plural":{"type":"string"}},"required":["plural","singular"]},"GetSelectionSessionAssetsResponse":{"type":"object","description":"Response containing the details of selected assets in a selection session","properties":{"assets":{"type":"array","description":"List of selected asset details with their name and level information","items":{"$ref":"#/components/schemas/SelectionSessionAssetDetails"}}},"required":["assets"]},"SelectionSessionAssetDetails":{"type":"object","description":"Details of a selected asset including its level ancestor","properties":{"uid":{"type":"string","description":"Stonal identifier of the asset","example":"550e8400-e29b-41d4-a716-446655440001"},"name":{"type":"string","description":"Name of the asset","example":"A101"},"levelUid":{"type":["string","null"],"description":"Stonal identifier of the first LEVEL ancestor in the parent chain, null if no LEVEL ancestor exists","example":"660e8400-e29b-41d4-a716-446655440010"}},"required":["name","uid"]},"PlanRepresentationResponseBody":{"type":"object","description":"Response containing SVG plan representation","properties":{"svg":{"type":"string","description":"SVG content as a string","example":"<svg xmlns='http://www.w3.org/2000/svg'>...</svg>"}},"required":["svg"]},"DepositView":{"type":"object","description":"Deposit information","properties":{"organizationCode":{"type":"string","description":"Organization code","example":"ORG123"},"code":{"type":"string","description":"Deposit code","example":"DEP456"},"nature":{"type":"string","description":"Nature of the deposit","example":"BANKING"},"contractCode":{"type":"string","description":"Code of the contract this deposit belongs to","example":"CONT456"},"initialAmount":{"type":"number","format":"double","description":"Initial deposit amount","example":1200.0},"updatedAmount":{"type":["number","null"],"format":"double","description":"Updated deposit amount","example":1250.0},"numberOfMonthsOfRent":{"type":["integer","null"],"format":"int32","description":"Number of months of rent the deposit represents","example":3},"integrationDate":{"type":"string","format":"date-time","description":"Date when the deposit was integrated into the system"}},"required":["code","contractCode","initialAmount","integrationDate","nature","organizationCode"]},"DepositsGetResultResponse":{"type":"object","description":"Response wrapping a paginated list of deposits","properties":{"data":{"type":"array","description":"List of deposits","items":{"$ref":"#/components/schemas/DepositView"}},"paginate":{"$ref":"#/components/schemas/SearchAssetPaginate","description":"Pagination information. The `cursor` field is `null` when iteration has reached the end."}},"required":["data","paginate"]},"ContractAssetView":{"type":"object","description":"Asset associated with a contract","properties":{"assetErpCode":{"type":"string","description":"ERP code of the asset","example":"ERP123"},"assetCode":{"type":"string","deprecated":true,"description":"Asset code (deprecated, use assetErpCode instead)","example":"ERP123"},"area":{"type":["number","null"],"format":"double","description":"Area of the asset in square meters","example":150.5},"effectiveDate":{"type":"string","description":"Date when the asset was added to the contract","example":"2023-01-01"},"expirationDate":{"type":"string","description":"Date when the asset will be removed from the contract","example":"2025-12-31"},"initialRent":{"type":["number","null"],"format":"double","description":"Initial rent amount","example":1200.0},"actualRent":{"type":["number","null"],"format":"double","description":"Current rent amount","example":1250.0},"stonalIdentifier":{"type":["string","null"],"description":"Stonal identifier of the asset"}},"required":["assetCode","assetErpCode","effectiveDate","expirationDate"]},"ContractView":{"type":"object","description":"Contract information","properties":{"organizationCode":{"type":"string","description":"Organization code","example":"ORG123"},"code":{"type":"string","description":"Contract code","example":"CONT456"},"contractType":{"$ref":"#/components/schemas/HolderTypeView","description":"Type of contract"},"stakeholders":{"type":"array","description":"List of stakeholders involved in the contract","items":{"$ref":"#/components/schemas/StakeholderView"}},"effectiveDate":{"type":["string","null"],"format":"date","description":"Date when the contract becomes effective"},"endDate":{"type":["string","null"],"format":"date","description":"End date of the contract"},"terminationDate":{"type":["string","null"],"format":"date","description":"Termination date if contract was terminated early"},"deadlines":{"type":"array","description":"Important deadlines in the contract lifecycle","items":{"$ref":"#/components/schemas/DeadlineView"}},"assets":{"type":"array","description":"Assets associated with this contract","items":{"$ref":"#/components/schemas/ContractAssetView"}},"integrationDate":{"type":["string","null"],"format":"date-time","description":"Date when contract was integrated into the system"},"label":{"type":["string","null"],"description":"Label of the contract"},"equipments":{"type":"array","deprecated":true,"description":"List of equipments linked to the contract (deprecated, use the V2 `installations` field instead)","items":{"$ref":"#/components/schemas/EquipmentView"}},"notice":{"type":["integer","null"],"format":"int32","description":"Notice period in months"},"data":{"type":["object","null"],"additionalProperties":{"type":"array","items":{"$ref":"#/components/schemas/DataView"}},"description":"Property data values for the contract, keyed by property code. Populated only when `?include=data` is set on the request."}},"required":["assets","code","contractType","deadlines","equipments","organizationCode","stakeholders"]},"ContractsGetResultResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ContractView"}},"paginate":{"$ref":"#/components/schemas/SearchAssetPaginate"}},"required":["data","paginate"]},"DataView":{"type":"object","description":"Data value information","properties":{"organizationCode":{"type":"string","description":"Organization code","example":"ORG123"},"propertyCode":{"type":"string","description":"Property code","example":"SURFACE"},"value":{"description":"Data value (type depends on the property)","example":150.5},"rawValue":{"type":"string","description":"Raw string representation of the value","example":"150.5"},"holderCode":{"type":"string","description":"Holder code","example":"ASSET456"},"holderType":{"type":"string","description":"Type of holder","enum":["ASSET","LEASE","CONTRACT","PARTIAL","UNKNOWN"],"example":"BUILDING"},"source":{"$ref":"#/components/schemas/SourceView","description":"Source information"},"interval":{"$ref":"#/components/schemas/IntervalView","description":"Validity interval of the data"},"id":{"type":"integer","format":"int64","description":"Unique identifier of the data","example":42}},"required":["holderCode","holderType","id","interval","organizationCode","propertyCode","rawValue","source"]},"DeadlineView":{"type":"object","description":"A deadline in the contract","properties":{"value":{"type":"string","format":"date","description":"The deadline date"}},"required":["value"]},"EquipmentView":{"type":"object","description":"Equipment linked to a contract","properties":{"code":{"type":"string","description":"Equipment code","example":"EQUIPMENT"},"names":{"type":"array","description":"List of names for the equipment","items":{"$ref":"#/components/schemas/HolderTypeNameView"}}},"required":["code","names"]},"HolderTypeNameView":{"type":"object","description":"Localized name information for a holder type","properties":{"singular":{"type":"string","description":"Singular form of the name","example":"Building"},"plural":{"type":"string","description":"Plural form of the name","example":"Buildings"},"language":{"type":"string","description":"Language code","example":"en"}},"required":["language","plural","singular"]},"HolderTypeView":{"type":"object","description":"Holder type information","properties":{"organizationCode":{"type":"string","description":"Organization code","example":"ORG123"},"code":{"type":"string","description":"Code of the holder type","example":"BUILDING"},"type":{"type":"string","description":"Type category","example":"ASSET"},"nature":{"type":["string","null"],"description":"Nature of the holder type (PHYSICAL, LOGICAL, PROPERTY_DYNAMIC)","example":"PHYSICAL"},"equipmentDestination":{"type":["string","null"],"description":"Equipment destination classification","example":"WALL"},"names":{"type":"array","description":"Localized names for this holder type","items":{"$ref":"#/components/schemas/HolderTypeNameView"}},"numberOfAssets":{"type":["integer","null"],"format":"int32","description":"Number of assets of this holder type. Asynchronous: refreshed by a background job, may lag behind asset changes by ~10 minutes","example":42},"hasAssets":{"type":["boolean","null"],"description":"Whether at least one non-deleted asset of this type or of any of its subtypes exists. Live check, only returned when withHasAssets=true and the holder super type is ASSET. Unlike numberOfAssets (asynchronous and direct assets only), this includes subtype assets: a parent type reports true when only its subtypes hold assets","example":true},"importErrors":{"description":"Information about import errors","oneOf":[{"$ref":"#/components/schemas/ImportErrors"},{"type":"null"}]},"recommendedPropertyCodes":{"type":"array","description":"Codes of properties recommended for this holder type","example":["PROP_AREA","PROP_HEIGHT"],"items":{"type":"string"}},"mandatoryPropertyCodes":{"type":"array","description":"Codes of properties mandatory for this holder type","example":["PROP_REFERENCE"],"items":{"type":"string"}}},"required":["code","mandatoryPropertyCodes","names","organizationCode","recommendedPropertyCodes","type"]},"ImportErrors":{"type":"object","description":"Information about import errors","properties":{"duplicates":{"type":"integer","format":"int32","description":"Number of duplicate entries","example":0},"others":{"type":"integer","format":"int32","description":"Number of other errors","example":0}},"required":["duplicates","others"]},"IntervalView":{"type":"object","description":"Time interval of data validity","properties":{"effectiveDate":{"type":"string","format":"date","description":"Date when the data becomes valid"},"expirationDate":{"type":"string","format":"date","description":"Date when the data ceases to be valid"}},"required":["effectiveDate","expirationDate"]},"SourceView":{"type":"object","description":"Source information for data","properties":{"details":{"type":"string","description":"Source details","example":"Manually entered"},"type":{"type":"string","description":"Source type","example":"USER"},"value":{"type":"string","description":"Source value","example":"Manually entered"},"sourceDocumentUid":{"type":["string","null"],"description":"Source document id when applicable (DOCUMENT)","example":"185b19bd-cd1c-45ed-8f92-6b1641c72d0c"}},"required":["details","type","value"]},"StakeholderView":{"type":"object","description":"Information about a contract stakeholder","properties":{"name":{"type":"string","description":"Name of the stakeholder","example":"Acme Corporation"},"code":{"type":"string","description":"Code identifying the stakeholder","example":"STK789"},"uid":{"type":["string","null"],"description":"Unique identifier of the stakeholder","example":"33333333-3333-3333-3333-333333333333"},"externalCode":{"type":["string","null"],"description":"External code of the stakeholder","example":"EXT123"}},"required":["code","name"]},"CertificateView":{"type":"object","description":"Certificate information","properties":{"code":{"type":"string","description":"Certificate code","example":"CERT-123"},"name":{"type":"string","description":"Certificate name","example":"DPE"},"assetUid":{"type":"string","description":"Stonal identifier of the asset the certificate belongs to","example":"STN-xxxxx"},"assetCode":{"type":"string","description":"Preferred external identifier of the asset the certificate belongs to","example":"BAT001"},"effectiveDate":{"type":"string","format":"date","description":"Date from which the certificate is effective","example":"2024-01-01"},"expirationDate":{"type":"string","format":"date","description":"Date at which the certificate expires","example":"2034-01-01"},"documentationLink":{"type":["string","null"],"description":"Link to the certificate documentation","example":"https://example.org/certificate.pdf"},"updatedAt":{"type":"string","format":"date-time","description":"Date of the last update of the certificate"}},"required":["assetCode","assetUid","code","effectiveDate","expirationDate","name","updatedAt"]},"CertificatesGetResultResponse":{"type":"object","description":"Response wrapping a paginated list of certificates","properties":{"data":{"type":"array","description":"List of certificates","items":{"$ref":"#/components/schemas/CertificateView"}},"paginate":{"$ref":"#/components/schemas/SearchAssetPaginate","description":"Pagination information. The `cursor` field is `null` when iteration has reached the end."}},"required":["data","paginate"]},"BillingEventTypeView":{"type":"object","description":"Type of a billing event","properties":{"code":{"type":"string","description":"Billing event type code","example":"RENT"},"label":{"type":"string","description":"Billing event type label","example":"Loyer"}},"required":["code","label"]},"BillingEventView":{"type":"object","description":"Billing event of a contract (rent, rent increase, rent-free period, fees...)","properties":{"organizationCode":{"type":"string","description":"Organization code","example":"ORG123"},"code":{"type":"string","description":"Billing event code","example":"BE456"},"contractCode":{"type":"string","description":"Code of the contract this billing event belongs to","example":"CONT456"},"assetCode":{"type":["string","null"],"description":"Code of the asset this billing event applies to, if any","example":"LOT001"},"effectiveDate":{"type":"string","format":"date","description":"Date from which the billing event is effective","example":"2024-01-01"},"expirationDate":{"type":"string","format":"date","description":"Date at which the billing event expires","example":"2026-12-31"},"eventType":{"$ref":"#/components/schemas/BillingEventTypeView","description":"Type of the billing event"},"value":{"type":"number","format":"double","description":"Current amount of the billing event","example":1250.0},"currentIndex":{"type":["string","null"],"description":"Current index","example":"ILAT T2 2024"},"indexType":{"type":["string","null"],"description":"Index type","example":"ILAT"},"initialIndex":{"type":["string","null"],"description":"Initial index","example":"ILAT T2 2020"},"initialIndexDate":{"type":["string","null"],"format":"date","description":"Date of the initial index","example":"2020-06-30"}},"required":["code","contractCode","effectiveDate","eventType","expirationDate","organizationCode","value"]},"BillingEventsGetResultResponse":{"type":"object","description":"Response wrapping a paginated list of billing events","properties":{"data":{"type":"array","description":"List of billing events","items":{"$ref":"#/components/schemas/BillingEventView"}},"paginate":{"$ref":"#/components/schemas/SearchAssetPaginate","description":"Pagination information. The `cursor` field is `null` when iteration has reached the end."}},"required":["data","paginate"]},"PublicAssetTypeNameResponse":{"type":"object","description":"Name of the asset type","properties":{"singular":{"type":"string","description":"Singular name of the asset type"},"plural":{"type":"string","description":"Plural name of the asset type"},"language":{"type":"string","description":"Language of the asset type names"}},"required":["language","plural","singular"]},"PublicAssetTypeResponse":{"type":"object","description":"Asset type","properties":{"code":{"type":"string","description":"Code of the asset type"},"nature":{"type":["string","null"],"description":"Natuer of the asset type"},"names":{"type":"array","description":"List of names of the asset type","items":{"$ref":"#/components/schemas/PublicAssetTypeNameResponse"}}},"required":["code","names"]},"PublicAssetTypesResponse":{"type":"object","description":"List of asset types","properties":{"assetTypes":{"type":"array","items":{"$ref":"#/components/schemas/PublicAssetTypeResponse"}}},"required":["assetTypes"]},"PublicPropertiesResponse":{"type":"object","description":"List of properties for an organization","properties":{"properties":{"type":"array","items":{"$ref":"#/components/schemas/PublicPropertyResponse"}}},"required":["properties"]},"PublicPropertyResponse":{"type":"object","description":"Property for an organization","properties":{"code":{"type":"string","description":"Code of property for an organization"},"name":{"type":"string","description":"Name of property for an organization"},"type":{"type":"string","description":"Type of property for an organization"},"temporality":{"type":"string","description":"Temporality of property for an organization"},"description":{"type":["string","null"],"description":"Description of property for an organization"},"assetTypes":{"type":"array","description":"Asset types of property for an organization","items":{"type":"string"}},"defaultUnit":{"type":["string","null"],"description":"Default unit of property for an organization"},"enumValues":{"type":["array","null"],"description":"Enum values of property for an organization","items":{"type":"string"}},"enumLabels":{"type":["object","null"],"additionalProperties":{"type":"object","additionalProperties":{"type":"string"}},"description":"Label of each enum value, by language then value code","example":{"fr":{"OFFICE":"Bureau"},"en":{"OFFICE":"Office"}}},"aliases":{"type":"array","description":"Aliases supported for this property","items":{"type":"string"}},"hasValues":{"type":"boolean","description":"Whether at least one data row exists for this property in the organization"}},"required":["aliases","assetTypes","code","hasValues","name","temporality","type"]},"AmendmentView":{"type":"object","description":"Public view of an amendment exposed by the listing API","properties":{"organizationCode":{"type":"string","description":"Organization code that owns this amendment","example":"ORGA"},"code":{"type":"string","description":"Amendment business code (natural ID inside the organization)","example":"A1"},"contractCode":{"type":"string","description":"Business code of the contract this amendment applies to","example":"L1"},"effectiveDate":{"type":"string","format":"date","description":"Date on which the amendment takes effect","example":"2024-01-01"},"amendmentType":{"type":"string","description":"Type of the amendment (see AmendmentType enum). Unknown values from upstream are mapped to UNKNOWN.","example":"INFORMATION"},"name":{"type":["string","null"],"description":"Human-readable label for the amendment","example":"Renewal 2024"},"rentEvolution":{"type":["number","null"],"format":"double","description":"Variation of rent introduced by the amendment, when applicable","example":12.34},"areaEvolution":{"type":["number","null"],"format":"double","description":"Variation of area introduced by the amendment, when applicable","example":5.5},"signatureDate":{"type":["string","null"],"format":"date","description":"Date on which the amendment was signed","example":"2023-12-15"},"integrationDate":{"type":"string","format":"date-time","description":"Server-side timestamp recorded when the amendment was integrated","example":"2024-01-02T08:30:00"}},"required":["amendmentType","code","contractCode","effectiveDate","integrationDate","organizationCode"]},"AmendmentsGetResultResponse":{"type":"object","description":"Paginated list of amendments for an organization","properties":{"data":{"type":"array","description":"Page of amendments, ordered by ascending internal id","items":{"$ref":"#/components/schemas/AmendmentView"}},"paginate":{"$ref":"#/components/schemas/SearchAssetPaginate","description":"Pagination envelope; cursor is null when iteration is complete"}},"required":["data","paginate"]}},"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}}}}