> ## Documentation Index > Fetch the complete documentation index at: https://support.keypro.fi/llms.txt > Use this file to discover all available pages before exploring further. # Create new circuit > NOTE: This API is provided by a separate service. Creates a new circuit into KeyCom with automatic reservation based on parameters given in request. Route reservevation would happen only in cases when KeyCom includes pre-connected logical route from the customer premises to the device which includes the given port. A new circuit would be created without connection reservations with the following scenarios: (a) Service finds none or several customer telecom premises based on the given address. (b) Service does not find given active device port based on given portId (or deviceId and portName). (c) No ready route found between customer premise and given device port. (d) If pre-connected logical route leads to the active device but in a different port. Special case is if logical route leads to central office premise, and port id is in a different device from last port in logical route. A new cross connection (state-under construction) is made between them and route is extended to include port id. Available from product version 3.6.8. If logical_res is true, the service will create logical reservations. The service will only create physical reservations if both logical_res and logical_physical_res are true. Available from product version 3.6.3. Given address is represented by addressId or sourceSystem, sourceSystemKey parameters, addressId can either be apartment-level or address-level. Additionally, it supports source system and key parameters for both levels. Priority is as follows: apartment >> address >> apartment-level source system >> address-level source system. Available from product version 3.6.3. ## OpenAPI ````json POST /createNewCircuit/ { "openapi": "3.0.4", "info": { "title": "KeyCom REST API", "termsOfService": "https://www.keypro.fi/en/terms-of-service", "contact": { "name": "Keypro Oy", "url": "https://keypro.fi/", "email": "keypro@keypro.fi" }, "license": { "name": "Copyright (C) Keypro Oy. All rights reserved.", "url": "https://www.keypro.fi/" }, "version": "2.0.0" }, "servers": [ { "url": "/api/v2" } ], "tags": [ { "name": "Plan", "description": "Plan related operations." }, { "name": "FreeArea", "description": "FreeArea related operations." }, { "name": "FreeLine", "description": "FreeLine related operations." }, { "name": "FreeText", "description": "FreeText related operations." }, { "name": "FreeTextComponent", "description": "FreeText component related operations." }, { "name": "Address", "description": "Building address related operations." }, { "name": "Apartment", "description": "Building apartments related operations." }, { "name": "Extra Attribute", "description": "Extra attributes related operations." }, { "name": "Extra Value", "description": "Extra attribute values related operations." }, { "name": "EAV Enum", "description": "EAV Enum value related operations." }, { "name": "EAV Enum Group", "description": "EAV Enum group related operations." }, { "name": "External Document", "description": "External documents related operations." }, { "name": "Attached Document", "description": "Attached Documents related operations." }, { "name": "Collections", "description": "Collection related operations." }, { "name": "Source system apartment", "description": "External source system derived apartment related operations." }, { "name": "Source system address", "description": "External source system derived address related operations." }, { "name": "Address alias", "description": "Address aliases related operations" }, { "name": "TxtConstant", "description": "TxtConstants related operations." }, { "name": "Point", "description": "Point objects related operations." }, { "name": "Survey Constant", "description": "Survey Constants related operations." }, { "name": "Survey Point", "description": "Survey Points related operations." }, { "name": "Survey Line String", "description": "Survey Line Strings related operations." }, { "name": "Template Catalog", "description": "Template Catalog related operations." }, { "name": "Route Following", "description": "Route following related operations." }, { "name": "Contact Person", "description": "Contact person related operations." }, { "name": "Contact Person Connection", "description": "Contact person connection related operations." }, { "name": "Telecom premises", "description": "Telecom premises related operations." }, { "name": "Device", "description": "Device related operations." }, { "name": "Device Group", "description": "Device Group related operations." }, { "name": "Splice", "description": "Telecom Splice related operations." }, { "name": "Telecom Conduit", "description": "Telecom Conduit related operations." }, { "name": "Telecom Conduit Link", "description": "Operations related to putting Telecom Cables and Ducts into Conduits." }, { "name": "Telecom Duct", "description": "Telecom Duct related operations." }, { "name": "Telecom Duct Link", "description": "Operations related to putting Telecom Cables into Ducts." }, { "name": "Telecom Conduit Connection", "description": "Operations related to connecting Conduits and endpoints." }, { "name": "Telecom Cable Connection", "description": "Operations related to connecting Cables and endpoints" }, { "name": "Telecom Thread/Port Connection", "description": "Operations related to connecting and disconnecting telecom cable threads and device ports" }, { "name": "Telecom Duct Connection", "description": "Operations related to connecting Telecom Ducts to Telecom Premises or Manhole." }, { "name": "Manhole", "description": "Telecom Manhole related operations." }, { "name": "Cable", "description": "Telecom Cable related operations." }, { "name": "Cable Appendix", "description": "Cable Appendix operations for connecting Cables to loops. Manages the relationship between Cables and loops, automatically adjusting Cable extra_length when appendixes are created, updated, or deleted." }, { "name": "Supercable", "description": "Telecom Supercable related operations." }, { "name": "Cross connection point", "description": "Cross connection point related operations." }, { "name": "Service Area", "description": "Service Area related operations." }, { "name": "Exchange Area", "description": "Exchange Area related operations." }, { "name": "Telecom Area", "description": "Telecom Area related operations." }, { "name": "Routefollower", "description": "Routefollower related operations." }, { "name": "Circuit", "description": "Circuit related operations." }, { "name": "Circuit Location", "description": "Circuit installation location related operations." }, { "name": "Circuit Section", "description": "Circuit section related operations." }, { "name": "Circuit Reservation Data", "description": "Circuit reservation data view and search operations." }, { "name": "Customer", "description": "Customer data related operations." }, { "name": "Passed Services", "description": "Passed Services related operations." }, { "name": "Circuit Connection", "description": "Circuit logical reservations related operations." }, { "name": "Circuit Physical Reservation", "description": "Circuit physical reservations related operations." }, { "name": "Create connections", "description": "Operation used to create new connections." }, { "name": "Terminal type", "description": "Terminal types related operations." }, { "name": "Logical connections", "description": "Logical connections related operations." }, { "name": "Circuit Services", "description": "Operations provided by micro services." }, { "name": "Contract", "description": "Contract related operations." }, { "name": "Contract Link", "description": "Contract link related operations." }, { "name": "Pole", "description": "Pole related operations." }, { "name": "Circuit faults", "description": "Circuit faults related operations." }, { "name": "Duct groups", "description": "Duct groups related operations." }, { "name": "Duct group rows", "description": "Duct group rows related operations." }, { "name": "Threads", "description": "Cable thread related operations." }, { "name": "Task", "description": "Task related operations." }, { "name": "Subregion", "description": "Subregion related operations." }, { "name": "SAttribute", "description": "SAttribute related operations." }, { "name": "Fault", "description": "Fault related operations." }, { "name": "Maintenance history", "description": "Maintenance history related operations." }, { "name": "Deflection", "description": "Deflection related operations." }, { "name": "Fault Component", "description": "Fault Component related operations." }, { "name": "Task Comment", "description": "Task comment related operations." }, { "name": "FaultComponentFault", "description": "FaultComponentFault related operations." } ], "paths": { "/createNewCircuit/": { "post": { "tags": [ "Circuit Services" ], "summary": "Create new circuit", "description": "NOTE: This API is provided by a separate service.\n\nCreates a new circuit into KeyCom with automatic reservation based on parameters given in request.\nRoute reservevation would happen only in cases when KeyCom includes pre-connected logical route from the customer\npremises to the device which includes the given port.\n\nA new circuit would be created without connection reservations with the following scenarios:\n(a) Service finds none or several customer telecom premises based on the given address.\n(b) Service does not find given active device port based on given portId (or deviceId and portName).\n(c) No ready route found between customer premise and given device port.\n(d) If pre-connected logical route leads to the active device but in a different port.\nSpecial case is if logical route leads to central office premise, and port id is in a different device from last port\nin logical route. A new cross connection (state-under construction) is made between them and route is extended to\ninclude port id. Available from product version 3.6.8.\n\nIf logical_res is true, the service will create logical reservations. The service will only create physical\nreservations if both logical_res and logical_physical_res are true. Available from product version 3.6.3.\n\nGiven address is represented by addressId or sourceSystem, sourceSystemKey parameters, addressId can either be\napartment-level or address-level. Additionally, it supports source system and key parameters for both levels.\nPriority is as follows: apartment >> address >> apartment-level source system >> address-level source system.\nAvailable from product version 3.6.3.\n", "operationId": "createNewCircuit", "requestBody": { "description": "properties to create circuit with and device with port to reserve to it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateNewCircuitBody" } } }, "required": true, "x-bodyName": "createNewCircuitBody" }, "responses": { "201": { "description": "New Circuit with section and location. Section also has logical and physical reservations if there is a preconnected logical route.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatedNewCircuit" }, "example": [ { "areaCode": "", "comments": "", "contractLength": null, "contractNumber": "100", "createdBy": "KEYCOM_STAGE", "createdTs": "2021-09-06", "customer": 2810, "directLength": null, "errors": [], "id": 287254, "identifier": "circuitName", "identifierAlt": "circuitOtherName", "importance": null, "installationAddresses": [ { "apartment": 4289, "circuit": 287254, "id": 43286990, "installationType": 6410 } ], "length": null, "orderNumber": "100", "organisation": null, "redundancy": null, "sections": [ { "bitrate": 2850, "circuit": 287254, "connectionDate": null, "constructionState": 6050, "disconnectionDate": null, "id": 3370741, "name": "sectionName", "plannedConnectionDate": null, "plannedDisconnectionDate": null, "reservations": [ { "logical": [ { "address": 80750, "ccp": 1319590, "circuit": 287254, "connection": null, "details": "", "device": 21050, "hierarchy": null, "id": 2414290, "order": 1, "premises": 23610, "section": 3370741 } ], "physical": [ { "circuit": "https://keycom.example.com/api/v2/circuits/287254/", "circuitOrder": 1, "component": "1", "componentAttenuation": 0.5, "componentLength": null, "componentState": "Ready", "componentType": "connector", "container": "1", "containerId": 21050, "containerState": "", "containerType": "device", "section": "https://keycom.example.com/api/v2/sections/3370741/", "topContainer": "PUISTIKKOKATU 1", "topContainerState": "In use", "topContainerType": "telecom premises" } ] } ], "usagePurpose": 15050, "usageState": 6350 } ], "updatedBy": "KEYCOM_STAGE", "updatedTs": "2021-09-06" } ] } } }, "400": { "$ref": "#/components/responses/Http400" }, "401": { "$ref": "#/components/responses/Http401" } }, "security": [ { "Token": [] } ] } } }, "components": { "schemas": { "CreateNewCircuitBody": { "allOf": [ { "$ref": "#/components/schemas/CreateCircuitSection" }, { "$ref": "#/components/schemas/CreateCircuitParams" }, { "type": "object", "properties": { "addressId": { "type": "integer", "description": "addressId with portId as search criteria for which automatic reservation is connected to new circuit." }, "countOfSections": { "type": "integer", "description": "The number of sections to be created. 0 indicates no section level information to be created.\nDefault of 1 if not provided.\n" }, "deviceId": { "type": "integer", "description": "deviceId with portName as alternative to PortId in search criteria." }, "logicalPhysicalReservations": { "type": "boolean", "description": "indicates if port will be reserved only for physical reservations" }, "logicalReservations": { "type": "boolean", "description": "indicates if port will be reserved only for logical reservations" }, "portId": { "type": "integer", "description": "portId with addressId as search criteria for which automatic reservation is connected to new circuit." }, "portName": { "type": "string", "description": "portName with deviceId as alternative to PortId in search criteria." }, "reservationDirection": { "enum": [ 1, 2 ], "type": "integer", "description": "Direction in which reservation is ordered. Default of 1 if not provided. Available from product version 3.6.8.\n1 - Ascending (Customer premise to Central office), 2 - Descending (Central office to Customer premise)\n" }, "sourceSystem": { "type": "integer", "description": "alternative to addressId together with sourceSystemKey. Available from product version 3.6.3." }, "sourceSystemKey": { "type": "integer", "description": "alternative to addressId together with sourceSystem. Available from product version 3.6.3." } } } ] }, "CreatedNewCircuit": { "allOf": [ { "$ref": "#/components/schemas/Circuit" }, { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Field error code" } }, "additionalProperties": { "type": "array", "items": { "type": "string", "description": "Validation error" }, "description": "List of validation errors for this fieldname" }, "description": "Fields which failed validation" }, "description": "Circuit list of errors when it is partially created" }, "installationAddresses": { "type": "array", "items": { "$ref": "#/components/schemas/FlatCircuitLocation" }, "description": "Circuit installations addresses" }, "sections": { "type": "array", "items": { "$ref": "#/components/schemas/CreatedNewSection" }, "description": "Circuit sections" } } } ] }, "CreateCircuitSection": { "type": "object", "properties": { "bitrateId": { "type": "integer", "description": "ID of section bitrate which is related to the speed of section" }, "connectDatePlanned": { "type": "string", "description": "section connect date planned", "format": "date-time" }, "connectDateReal": { "type": "string", "description": "section connect date real", "format": "date-time" }, "constStateId": { "type": "integer", "description": "ID of section construction state" }, "disconnectionDate": { "type": "string", "description": "section disconnect date real", "format": "date-time" }, "plannedDisconnectionDate": { "type": "string", "description": "section disconnect date planned", "format": "date-time" }, "sectionName": { "type": "string", "description": "section name" }, "usageId": { "type": "integer", "description": "ID of section usage purpose.\nREQUIRED for circuit section and created if countOfSections is greater than 1.\n" }, "usageStateId": { "type": "integer", "description": "ID of section usage state" } } }, "CreateCircuitParams": { "type": "object", "properties": { "contractLength": { "type": "integer", "description": "Circuit contract length for new or update circuit" }, "contractNumber": { "type": "string", "description": "circuit contract number for new or update circuit" }, "customerId": { "type": "integer", "description": "ID of customer related to circuit customer for new or update circuit" }, "importanceId": { "type": "integer", "description": "Internal ID of circuit importance information for new or update circuit" }, "name": { "type": "string", "description": "circuit identifier for new or update circuit" }, "name2": { "type": "string", "description": "circuit alternate identifier for new or update circuit" }, "orderNumber": { "type": "string", "description": "circuit order number for new or update circuit" }, "organisationId": { "type": "integer", "description": "Internal ID of circuit organisation information for new or update circuit" }, "redundancyId": { "type": "integer", "description": "Internal ID of circuit redundancy information for new or update circuit" }, "supercircuit": { "type": "integer", "description": "ID of super circuit for new or update circuit. Available from product version v2026.2." }, "supercircuitOrderNo": { "type": "integer", "description": "Order number within super circuit for new or update circuit. Available from product version v2026.2." } } }, "Circuit": { "type": "object", "properties": { "areaCode": { "type": "string", "description": "Circuit area code" }, "comments": { "type": "string", "description": "Circuit comments. Available from product version 3.2.8." }, "contractLength": { "type": "integer", "description": "Circuit contract length" }, "contractNumber": { "type": "string", "description": "Circuit contract number" }, "createdAt": { "type": "string", "description": "Creation timestamp (date and time). Available from product version v2026.1.", "format": "date-time", "readOnly": true }, "createdBy": { "type": "string", "description": "Creator username", "readOnly": true }, "createdTs": { "type": "string", "description": "Creation date (date only, existing field)", "format": "date", "readOnly": true }, "customer": { "$ref": "#/components/schemas/Customer" }, "directLength": { "type": "number", "description": "Circuit direct length", "format": "float" }, "id": { "type": "integer", "description": "Primary key", "readOnly": true }, "identifier": { "type": "string", "description": "Circuit identifier" }, "identifierAlt": { "type": "string", "description": "Circuit alternative identifier" }, "importance": { "$ref": "#/components/schemas/CircuitImportance" }, "installationAddresses": { "type": "array", "items": { "type": "string", "format": "url" }, "description": "Circuit installations addresses" }, "length": { "type": "number", "description": "Circuit length", "format": "float" }, "orderNumber": { "type": "string", "description": "Circuit order number" }, "organisation": { "$ref": "#/components/schemas/CircuitOrganisation" }, "redundancy": { "$ref": "#/components/schemas/CircuitRedundancy" }, "sections": { "type": "array", "items": { "$ref": "#/components/schemas/CircuitSection" }, "description": "Circuit sections" }, "supercircuit": { "$ref": "#/components/schemas/SuperCircuit" }, "supercircuitOrderNo": { "type": "integer", "description": "Order number of this circuit within the super circuit. Available from product version v2026.2." }, "updatedAt": { "type": "string", "description": "Last update timestamp (date and time). Available from product version v2026.1.", "format": "date-time", "readOnly": true }, "updatedBy": { "type": "string", "description": "Last updater username", "readOnly": true }, "updatedTs": { "type": "string", "description": "Last update date (date only, existing field)", "format": "date", "readOnly": true } } }, "FlatCircuitLocation": { "required": [ "circuit", "apartment", "installationType" ], "type": "object", "properties": { "apartment": { "type": "integer", "description": "apartment of the location id" }, "circuit": { "type": "integer", "description": "Circuit of the location id" }, "id": { "type": "integer", "description": "Primary key", "readOnly": true }, "installationType": { "type": "integer", "description": "Circuit location installation type" } } }, "CreatedNewSection": { "allOf": [ { "$ref": "#/components/schemas/CircuitSection" }, { "type": "object", "properties": { "reservations": { "type": "array", "items": { "type": "object", "properties": { "logical": { "type": "array", "items": { "$ref": "#/components/schemas/FlatCircuitConnection" }, "description": "logical reservations" }, "physical": { "type": "array", "items": { "$ref": "#/components/schemas/CircuitReservationData" }, "description": "physical reservations" } } }, "description": "automatically created reservations" } } } ] }, "ErrorDetailsResponse": { "required": [ "details" ], "type": "object", "properties": { "details": { "type": "string", "description": "Detailed description of error" } }, "description": "Standard error response payload" }, "Customer": { "required": [ "number", "address" ], "type": "object", "properties": { "address": { "$ref": "#/components/schemas/Apartment" }, "addressAlt": { "$ref": "#/components/schemas/Apartment" }, "billingName": { "type": "string", "description": "Customer billing name" }, "businessId": { "type": "string", "description": "Customer bussiness id" }, "contactName": { "type": "string", "description": "Customer contact name or null. Available from product version 2026.1" }, "createdBy": { "type": "string", "description": "creator", "readOnly": true }, "createdTs": { "type": "string", "description": "Creation date and time", "format": "date-time", "readOnly": true }, "email": { "type": "string", "description": "Customer email" }, "id": { "type": "integer", "description": "Primary key", "readOnly": true }, "mobilePhone": { "type": "string", "description": "Customer mobile phone number name" }, "name": { "type": "string", "description": "Customer name" }, "number": { "type": "string", "description": "Customer number" }, "phone": { "type": "string", "description": "Customer phone number" }, "smsProhibited": { "type": "boolean", "description": "Sending sms is prohibited to customer" }, "telefax": { "type": "string", "description": "Customer fax number" }, "type": { "$ref": "#/components/schemas/CustomerType" }, "updatedBy": { "type": "string", "description": "Last updater", "readOnly": true }, "updatedTs": { "type": "string", "description": "Last update date time", "format": "date-time", "readOnly": true } } }, "CircuitImportance": { "required": [ "id", "groupname", "logical_txt", "txt", "list_url" ], "type": "object", "properties": { "availability_end_ts": { "type": "string", "description": "Ending date time for availability", "format": "date-time" }, "availability_start_ts": { "type": "string", "description": "Beginning date time for availability", "format": "date-time" }, "available": { "type": "boolean", "description": "Is object deemed as available. Based on availability_start_ts and availability_end_ts values.", "readOnly": true }, "groupname": { "enum": [ "CIRCUIT_IMPORTANCE" ], "description": "Group name of constant" }, "id": { "type": "integer", "description": "Unique id of constant" }, "list_url": { "type": "string", "description": "Url to fetch all constants from this group", "format": "url" }, "logical_txt": { "type": "string", "description": "Logical textual value" }, "num_value": { "type": "number", "description": "Numeric value", "format": "float" }, "num_value2": { "type": "number", "description": "Numeric value 2", "format": "float" }, "num_value3": { "type": "number", "description": "Numeric value 3", "format": "float" }, "num_value4": { "type": "number", "description": "Numeric value 4", "format": "float" }, "txt": { "type": "string", "description": "Human readable textual representation" } }, "description": "Circuit importance" }, "CircuitOrganisation": { "required": [ "id", "groupname", "logical_txt", "txt", "list_url" ], "type": "object", "properties": { "availability_end_ts": { "type": "string", "description": "Ending date time for availability", "format": "date-time" }, "availability_start_ts": { "type": "string", "description": "Beginning date time for availability", "format": "date-time" }, "available": { "type": "boolean", "description": "Is object deemed as available. Based on availability_start_ts and availability_end_ts values.", "readOnly": true }, "groupname": { "enum": [ "KN_ORGANISATION" ], "description": "Group name of constant" }, "id": { "type": "integer", "description": "Unique id of constant" }, "list_url": { "type": "string", "description": "Url to fetch all constants from this group", "format": "url" }, "logical_txt": { "type": "string", "description": "Logical textual value" }, "num_value": { "type": "number", "description": "Numeric value", "format": "float" }, "num_value2": { "type": "number", "description": "Numeric value 2", "format": "float" }, "num_value3": { "type": "number", "description": "Numeric value 3", "format": "float" }, "num_value4": { "type": "number", "description": "Numeric value 4", "format": "float" }, "txt": { "type": "string", "description": "Human readable textual representation" } }, "description": "Circuit organisation" }, "CircuitRedundancy": { "required": [ "id", "groupname", "logical_txt", "txt", "list_url" ], "type": "object", "properties": { "availability_end_ts": { "type": "string", "description": "Ending date time for availability", "format": "date-time" }, "availability_start_ts": { "type": "string", "description": "Beginning date time for availability", "format": "date-time" }, "available": { "type": "boolean", "description": "Is object deemed as available. Based on availability_start_ts and availability_end_ts values.", "readOnly": true }, "groupname": { "enum": [ "CIRCUIT_REDUNDANCY" ], "description": "Group name of constant" }, "id": { "type": "integer", "description": "Unique id of constant" }, "list_url": { "type": "string", "description": "Url to fetch all constants from this group", "format": "url" }, "logical_txt": { "type": "string", "description": "Logical textual value" }, "num_value": { "type": "number", "description": "Numeric value", "format": "float" }, "num_value2": { "type": "number", "description": "Numeric value 2", "format": "float" }, "num_value3": { "type": "number", "description": "Numeric value 3", "format": "float" }, "num_value4": { "type": "number", "description": "Numeric value 4", "format": "float" }, "txt": { "type": "string", "description": "Human readable textual representation" } }, "description": "Circuit redundancy" }, "CircuitSection": { "required": [ "usageState", "usagePurpose", "circuit" ], "type": "object", "properties": { "bitrate": { "$ref": "#/components/schemas/Bitrate" }, "circuit": { "type": "string", "description": "Circuit the section is in", "format": "url" }, "connectionDate": { "type": "string", "description": "actual section connection date", "format": "date-time" }, "constructionState": { "$ref": "#/components/schemas/ConstructionState" }, "createdBy": { "type": "string", "description": "Creator username. Available from product version v2026.1.", "readOnly": true }, "createdTs": { "type": "string", "description": "Creation timestamp. Available from product version v2026.1.", "format": "date-time", "readOnly": true }, "disconnectionDate": { "type": "string", "description": "actual section disconnection date", "format": "date-time" }, "extraUsages": { "type": "array", "items": { "$ref": "#/components/schemas/CircuitSectionExtraUsage" }, "description": "Extra usages for the Circuit Section. Available from product version 2026.1" }, "id": { "type": "integer", "description": "Primary key", "readOnly": true }, "name": { "type": "string", "description": "Section name" }, "plannedConnectionDate": { "type": "string", "description": "planned section connection date", "format": "date-time" }, "plannedDisconnectionDate": { "type": "string", "description": "planned section disconnection date", "format": "date-time" }, "updatedBy": { "type": "string", "description": "Last updater username. Available from product version v2026.1.", "readOnly": true }, "updatedTs": { "type": "string", "description": "Last update timestamp. Available from product version v2026.1.", "format": "date-time", "readOnly": true }, "usagePurpose": { "$ref": "#/components/schemas/CircuitUsage" }, "usageState": { "$ref": "#/components/schemas/CircuitUsageState" } } }, "SuperCircuit": { "type": "object", "properties": { "id": { "type": "integer", "description": "Primary key" }, "identifier": { "type": "string", "description": "Super circuit identifier" }, "itemType": { "$ref": "#/components/schemas/TxtConstant" }, "networkType": { "$ref": "#/components/schemas/TxtConstant" }, "state": { "$ref": "#/components/schemas/TxtConstant" } }, "description": "Super circuit (nested in Circuit responses). Available from product version v2026.2." }, "FlatCircuitConnection": { "required": [ "section" ], "type": "object", "properties": { "address": { "type": "integer", "description": "Address id", "readOnly": true }, "ccp": { "type": "integer", "description": "Cross connection point id" }, "circuit": { "type": "integer", "description": "Circuit id", "readOnly": true }, "connection": { "type": "integer", "description": "Cross connection point connection id" }, "createdBy": { "type": "string", "description": "Creator username. Available from product version v2026.1.", "readOnly": true }, "createdTs": { "type": "string", "description": "Creation timestamp. Available from product version v2026.1.", "format": "date-time", "readOnly": true }, "details": { "type": "string", "description": "Circuit connection details in text" }, "device": { "type": "integer", "description": "Device id", "readOnly": true }, "hierarchy": { "type": "integer", "description": "Circuit hierarchy id", "readOnly": true }, "id": { "type": "integer", "description": "Primary key", "readOnly": true }, "order": { "type": "integer", "description": "The order number in section's circuit connections" }, "premises": { "type": "integer", "description": "Telecom premises id", "readOnly": true }, "section": { "type": "integer", "description": "Circuit section id" }, "updatedBy": { "type": "string", "description": "Last updater username. Available from product version v2026.1.", "readOnly": true }, "updatedTs": { "type": "string", "description": "Last update timestamp. Available from product version v2026.1.", "format": "date-time", "readOnly": true } } }, "CircuitReservationData": { "type": "object", "properties": { "circuit": { "type": "string", "description": "Reservation circuit", "format": "url" }, "circuitOrder": { "type": "integer", "description": "Reservation circuit order number" }, "component": { "type": "string", "description": "Reservation component name" }, "componentAttenuation": { "type": "number", "description": "Reservation component attenuation", "format": "float" }, "componentId": { "type": "integer", "description": "Reservation component Id" }, "componentLength": { "type": "number", "description": "Reservation component length. This field cannot be used for filtering or ordering", "format": "float" }, "componentState": { "type": "string", "description": "Reservation component state" }, "componentType": { "type": "string", "description": "Reservation component type" }, "container": { "type": "string", "description": "Reservation container name" }, "containerId": { "type": "integer", "description": "Reservation container Id" }, "containerState": { "type": "string", "description": "Reservation container state" }, "containerType": { "type": "string", "description": "Reservation container type" }, "lineLocation": { "type": "string", "description": "Linear geographical location of component", "format": "ewkt" }, "pointLocation": { "type": "string", "description": "Point geographical location of component", "format": "ewkt" }, "section": { "type": "string", "description": "Reservation section", "format": "url" }, "topContainer": { "type": "string", "description": "Reservation top container name" }, "topContainerId": { "type": "integer", "description": "Reservation top container Id" }, "topContainerState": { "type": "string", "description": "Reservation top container state" }, "topContainerType": { "type": "string", "description": "Reservation top container type" } } }, "Apartment": { "required": [ "address" ], "type": "object", "properties": { "address": { "$ref": "#/components/schemas/Address" }, "apartmentDivision": { "type": "string", "description": "apartment division" }, "apartmentLetter": { "type": "string", "description": "apartment letter" }, "apartmentNumber": { "type": "string", "description": "apartment number" }, "empty": { "enum": [ 0, 1 ], "type": "integer", "description": "Apartment with this value as 1 is default apartment. Modifying or deleting such apartment is prohibited.", "readOnly": true }, "id": { "type": "integer", "description": "Primary key", "readOnly": true }, "originProperty": { "type": "string", "description": "apartment original property id" }, "originalStreetno": { "type": "string", "description": "apartment original streen number" }, "sourceSystem": { "$ref": "#/components/schemas/SourceSystem" }, "sourceSystemKey": { "type": "integer", "description": "source system key" }, "usagePurpose": { "$ref": "#/components/schemas/ApartmentUsage" }, "usagePurposeAlt": { "$ref": "#/components/schemas/AddressSecondaryUsage" }, "usageState": { "$ref": "#/components/schemas/ApartmentStatus" } } }, "CustomerType": { "required": [ "id", "groupname", "logical_txt", "txt", "list_url" ], "type": "object", "properties": { "availability_end_ts": { "type": "string", "description": "Ending date time for availability", "format": "date-time" }, "availability_start_ts": { "type": "string", "description": "Beginning date time for availability", "format": "date-time" }, "available": { "type": "boolean", "description": "Is object deemed as available. Based on availability_start_ts and availability_end_ts values.", "readOnly": true }, "groupname": { "enum": [ "KN_CUST_TYPE" ], "description": "Group name of constant" }, "id": { "type": "integer", "description": "Unique id of constant" }, "list_url": { "type": "string", "description": "Url to fetch all constants from this group", "format": "url" }, "logical_txt": { "type": "string", "description": "Logical textual value" }, "num_value": { "type": "number", "description": "Numeric value", "format": "float" }, "num_value2": { "type": "number", "description": "Numeric value 2", "format": "float" }, "num_value3": { "type": "number", "description": "Numeric value 3", "format": "float" }, "num_value4": { "type": "number", "description": "Numeric value 4", "format": "float" }, "txt": { "type": "string", "description": "Human readable textual representation" } }, "description": "Customer type" }, "Bitrate": { "type": "object", "properties": { "description": { "type": "string", "description": "Bitrate description", "readOnly": true }, "id": { "type": "integer", "description": "Primary key", "readOnly": true }, "rate": { "type": "integer", "description": "Bitrate value", "readOnly": true } } }, "ConstructionState": { "required": [ "id", "groupname", "logical_txt", "txt", "list_url" ], "type": "object", "properties": { "availability_end_ts": { "type": "string", "description": "Ending date time for availability", "format": "date-time" }, "availability_start_ts": { "type": "string", "description": "Beginning date time for availability", "format": "date-time" }, "available": { "type": "boolean", "description": "Is object deemed as available. Based on availability_start_ts and availability_end_ts values.", "readOnly": true }, "groupname": { "enum": [ "KN_CONST_STATE" ], "description": "Group name of constant" }, "id": { "type": "integer", "description": "Unique id of constant" }, "list_url": { "type": "string", "description": "Url to fetch all constants from this group", "format": "url" }, "logical_txt": { "type": "string", "description": "Logical textual value" }, "num_value": { "type": "number", "description": "Numeric value", "format": "float" }, "num_value2": { "type": "number", "description": "Numeric value 2", "format": "float" }, "num_value3": { "type": "number", "description": "Numeric value 3", "format": "float" }, "num_value4": { "type": "number", "description": "Numeric value 4", "format": "float" }, "txt": { "type": "string", "description": "Human readable textual representation" } }, "description": "Txt constants construction state" }, "CircuitSectionExtraUsage": { "type": "object", "properties": { "customerUrl": { "type": "string", "description": "Hyperlink to the related customer", "format": "uri" }, "extraUsage": { "$ref": "#/components/schemas/ExtraUsage" }, "information": { "type": "string", "description": "Free text information" }, "name1": { "type": "string", "description": "Optional name field 1", "example": "John Doe" }, "name2": { "type": "string", "description": "Optional name field 2", "example": "Jane Doe" }, "name3": { "type": "string", "description": "Optional name field 3", "example": "Jane Doe" }, "name4": { "type": "string", "description": "Optional name field 4", "example": "Jane Doe" }, "pk": { "type": "integer", "description": "Primary key", "example": 1 } } }, "CircuitUsage": { "required": [ "id", "groupname", "logical_txt", "txt", "list_url" ], "type": "object", "properties": { "availability_end_ts": { "type": "string", "description": "Ending date time for availability", "format": "date-time" }, "availability_start_ts": { "type": "string", "description": "Beginning date time for availability", "format": "date-time" }, "available": { "type": "boolean", "description": "Is object deemed as available. Based on availability_start_ts and availability_end_ts values.", "readOnly": true }, "groupname": { "enum": [ "USAGE" ], "description": "Group name of constant" }, "id": { "type": "integer", "description": "Unique id of constant" }, "list_url": { "type": "string", "description": "Url to fetch all constants from this group", "format": "url" }, "logical_txt": { "type": "string", "description": "Logical textual value" }, "num_value": { "type": "number", "description": "Numeric value", "format": "float" }, "num_value2": { "type": "number", "description": "Numeric value 2", "format": "float" }, "num_value3": { "type": "number", "description": "Numeric value 3", "format": "float" }, "num_value4": { "type": "number", "description": "Numeric value 4", "format": "float" }, "txt": { "type": "string", "description": "Human readable textual representation" } }, "description": "Circuit usage" }, "CircuitUsageState": { "required": [ "id", "groupname", "logical_txt", "txt", "list_url" ], "type": "object", "properties": { "availability_end_ts": { "type": "string", "description": "Ending date time for availability", "format": "date-time" }, "availability_start_ts": { "type": "string", "description": "Beginning date time for availability", "format": "date-time" }, "available": { "type": "boolean", "description": "Is object deemed as available. Based on availability_start_ts and availability_end_ts values.", "readOnly": true }, "groupname": { "enum": [ "KN_USAGE_STATE" ], "description": "Group name of constant" }, "id": { "type": "integer", "description": "Unique id of constant" }, "list_url": { "type": "string", "description": "Url to fetch all constants from this group", "format": "url" }, "logical_txt": { "type": "string", "description": "Logical textual value" }, "num_value": { "type": "number", "description": "Numeric value", "format": "float" }, "num_value2": { "type": "number", "description": "Numeric value 2", "format": "float" }, "num_value3": { "type": "number", "description": "Numeric value 3", "format": "float" }, "num_value4": { "type": "number", "description": "Numeric value 4", "format": "float" }, "txt": { "type": "string", "description": "Human readable textual representation" } }, "description": "Circuit usage state" }, "TxtConstant": { "type": "object", "properties": { "availability_end_ts": { "type": "string", "description": "Ending date time for availability", "format": "date-time" }, "availability_start_ts": { "type": "string", "description": "Beginning date time for availability", "format": "date-time" }, "available": { "type": "boolean", "description": "Is object deemed as available. Based on availability_start_ts and availability_end_ts values.", "readOnly": true }, "groupname": { "type": "string", "description": "Group name of constant" }, "id": { "type": "integer", "description": "Unique id of constant" }, "list_url": { "type": "string", "description": "Url to fetch all constants from this group", "format": "url" }, "logical_txt": { "type": "string", "description": "Logical textual value" }, "num_value": { "type": "number", "description": "Numeric value", "format": "float" }, "num_value2": { "type": "number", "description": "Numeric value 2", "format": "float" }, "num_value3": { "type": "number", "description": "Numeric value 3", "format": "float" }, "num_value4": { "type": "number", "description": "Numeric value 4", "format": "float" }, "txt": { "type": "string", "description": "Human readable textual representation" } } }, "Address": { "required": [ "streetname", "city" ], "type": "object", "properties": { "buildingId": { "type": "string", "description": "Building id" }, "buildingName": { "type": "string", "description": "Building name" }, "city": { "type": "string", "description": "Building city name" }, "cityAlt": { "type": "string", "description": "Building city name in alternative language" }, "country": { "type": "string", "description": "Building country" }, "createdBy": { "type": "string", "description": "creator", "readOnly": true }, "createdTs": { "type": "string", "description": "Creation date and time", "format": "date-time", "readOnly": true }, "district": { "type": "string", "description": "Building district" }, "empty": { "enum": [ 0, 1 ], "type": "integer", "description": "Address with this value as 1 is default address. Modifying or deleting such address is prohibited.", "readOnly": true }, "id": { "type": "integer", "description": "Primary key", "readOnly": true }, "location": { "type": "string", "description": "Geographical location", "format": "ewkt" }, "municipality": { "type": "string", "description": "Building municipality" }, "propertyId": { "type": "string", "description": "Property number" }, "province": { "type": "string", "description": "Building province" }, "sourceSystem": { "$ref": "#/components/schemas/SourceSystem" }, "sourceSystemKey": { "type": "integer", "description": "source system key" }, "streetname": { "type": "string", "description": "Building street name" }, "streetnameAlt": { "type": "string", "description": "Building street name in alternative language" }, "streetno": { "type": "string", "description": "Building number" }, "subdivision": { "type": "string", "description": "Building municipality subdivision" }, "updatedBy": { "type": "string", "description": "Last updater", "readOnly": true }, "updatedTs": { "type": "string", "description": "Last update date time", "format": "date-time", "readOnly": true }, "usagePurpose": { "$ref": "#/components/schemas/BuildingUsage" }, "usagePurposeAlt": { "$ref": "#/components/schemas/AddressSecondaryUsage" }, "zipcode": { "type": "string", "description": "Building zipcode" } } }, "SourceSystem": { "required": [ "id", "groupname", "logical_txt", "txt", "list_url" ], "type": "object", "properties": { "availability_end_ts": { "type": "string", "description": "Ending date time for availability", "format": "date-time" }, "availability_start_ts": { "type": "string", "description": "Beginning date time for availability", "format": "date-time" }, "available": { "type": "boolean", "description": "Is object deemed as available. Based on availability_start_ts and availability_end_ts values.", "readOnly": true }, "groupname": { "enum": [ "SOURCE_SYSTEM" ], "description": "Group name of constant" }, "id": { "type": "integer", "description": "Unique id of constant" }, "list_url": { "type": "string", "description": "Url to fetch all constants from this group", "format": "url" }, "logical_txt": { "type": "string", "description": "Logical textual value" }, "num_value": { "type": "number", "description": "Numeric value", "format": "float" }, "num_value2": { "type": "number", "description": "Numeric value 2", "format": "float" }, "num_value3": { "type": "number", "description": "Numeric value 3", "format": "float" }, "num_value4": { "type": "number", "description": "Numeric value 4", "format": "float" }, "txt": { "type": "string", "description": "Human readable textual representation" } }, "description": "External source system" }, "ApartmentUsage": { "required": [ "id", "groupname", "logical_txt", "txt", "list_url" ], "type": "object", "properties": { "availability_end_ts": { "type": "string", "description": "Ending date time for availability", "format": "date-time" }, "availability_start_ts": { "type": "string", "description": "Beginning date time for availability", "format": "date-time" }, "available": { "type": "boolean", "description": "Is object deemed as available. Based on availability_start_ts and availability_end_ts values.", "readOnly": true }, "groupname": { "enum": [ "APARTMENT_USAGE" ], "description": "Group name of constant" }, "id": { "type": "integer", "description": "Unique id of constant" }, "list_url": { "type": "string", "description": "Url to fetch all constants from this group", "format": "url" }, "logical_txt": { "type": "string", "description": "Logical textual value" }, "num_value": { "type": "number", "description": "Numeric value", "format": "float" }, "num_value2": { "type": "number", "description": "Numeric value 2", "format": "float" }, "num_value3": { "type": "number", "description": "Numeric value 3", "format": "float" }, "num_value4": { "type": "number", "description": "Numeric value 4", "format": "float" }, "txt": { "type": "string", "description": "Human readable textual representation" } }, "description": "Apartment Usage purpose" }, "AddressSecondaryUsage": { "required": [ "id", "groupname", "logical_txt", "txt", "list_url" ], "type": "object", "properties": { "availability_end_ts": { "type": "string", "description": "Ending date time for availability", "format": "date-time" }, "availability_start_ts": { "type": "string", "description": "Beginning date time for availability", "format": "date-time" }, "available": { "type": "boolean", "description": "Is object deemed as available. Based on availability_start_ts and availability_end_ts values.", "readOnly": true }, "groupname": { "enum": [ "KN_ADDR_SPEC" ], "description": "Group name of constant" }, "id": { "type": "integer", "description": "Unique id of constant" }, "list_url": { "type": "string", "description": "Url to fetch all constants from this group", "format": "url" }, "logical_txt": { "type": "string", "description": "Logical textual value" }, "num_value": { "type": "number", "description": "Numeric value", "format": "float" }, "num_value2": { "type": "number", "description": "Numeric value 2", "format": "float" }, "num_value3": { "type": "number", "description": "Numeric value 3", "format": "float" }, "num_value4": { "type": "number", "description": "Numeric value 4", "format": "float" }, "txt": { "type": "string", "description": "Human readable textual representation" } }, "description": "Address usage purpose" }, "ApartmentStatus": { "required": [ "id", "groupname", "logical_txt", "txt", "list_url" ], "type": "object", "properties": { "availability_end_ts": { "type": "string", "description": "Ending date time for availability", "format": "date-time" }, "availability_start_ts": { "type": "string", "description": "Beginning date time for availability", "format": "date-time" }, "available": { "type": "boolean", "description": "Is object deemed as available. Based on availability_start_ts and availability_end_ts values.", "readOnly": true }, "groupname": { "enum": [ "APARTMENT_STATUS" ], "description": "Group name of constant" }, "id": { "type": "integer", "description": "Unique id of constant" }, "list_url": { "type": "string", "description": "Url to fetch all constants from this group", "format": "url" }, "logical_txt": { "type": "string", "description": "Logical textual value" }, "num_value": { "type": "number", "description": "Numeric value", "format": "float" }, "num_value2": { "type": "number", "description": "Numeric value 2", "format": "float" }, "num_value3": { "type": "number", "description": "Numeric value 3", "format": "float" }, "num_value4": { "type": "number", "description": "Numeric value 4", "format": "float" }, "txt": { "type": "string", "description": "Human readable textual representation" } }, "description": "Apartment status" }, "ExtraUsage": { "type": "object", "properties": { "availability_end_ts": { "type": "string", "description": "Availability end timestamp", "format": "date-time" }, "availability_start_ts": { "type": "string", "description": "Availability start timestamp", "format": "date-time" }, "available": { "type": "boolean", "description": "Whether the constant is available" }, "groupname": { "enum": [ "KN_EXTRAUSAGE" ], "description": "Group name of constant" }, "id": { "type": "integer", "description": "Unique id of constant" }, "list_url": { "type": "string", "description": "Url to fetch all constants from this group", "format": "url", "example": "https://keycom.example.com/api/v2/txt_constants/groupname/KN_EXTRAUSAGE/" }, "logical_txt": { "type": "string", "description": "Logical textual value", "example": "IPTV DSL-liittymälle" }, "num_value": { "type": "integer", "description": "Numeric value 1", "example": 3.0 }, "num_value2": { "type": "integer", "description": "Numeric value 2" }, "num_value3": { "type": "integer", "description": "Numeric value 3" }, "num_value4": { "type": "integer", "description": "Numeric value 4" }, "txt": { "type": "string", "description": "Human readable textual representation" } }, "description": "Circuit Section Extra Usage Txt Constant definition" }, "BuildingUsage": { "required": [ "id", "groupname", "logical_txt", "txt", "list_url" ], "type": "object", "properties": { "availability_end_ts": { "type": "string", "description": "Ending date time for availability", "format": "date-time" }, "availability_start_ts": { "type": "string", "description": "Beginning date time for availability", "format": "date-time" }, "available": { "type": "boolean", "description": "Is object deemed as available. Based on availability_start_ts and availability_end_ts values.", "readOnly": true }, "groupname": { "enum": [ "BUILDING_USAGE" ], "description": "Group name of constant" }, "id": { "type": "integer", "description": "Unique id of constant" }, "list_url": { "type": "string", "description": "Url to fetch all constants from this group", "format": "url" }, "logical_txt": { "type": "string", "description": "Logical textual value" }, "num_value": { "type": "number", "description": "Numeric value", "format": "float" }, "num_value2": { "type": "number", "description": "Numeric value 2", "format": "float" }, "num_value3": { "type": "number", "description": "Numeric value 3", "format": "float" }, "num_value4": { "type": "number", "description": "Numeric value 4", "format": "float" }, "txt": { "type": "string", "description": "Human readable textual representation" } }, "description": "Building usage purpose" } }, "responses": { "Http400": { "description": "Request could not be processed because it was invalid.\n\nEither validation failed (field-level errors are returned),\nor a generic bad request message is provided.\n", "content": { "application/json": { "schema": { "minProperties": 1, "type": "object", "properties": { "details": { "type": "string", "description": "Description of the error for generic bad request responses" } }, "additionalProperties": { "type": "array", "items": { "type": "string", "description": "Validation error message" }, "description": "List of validation error messages for this field name" }, "description": "Validation errors by field name or a generic bad request description" }, "example": { "email": [ "Email is required", "Email must be valid" ], "password": [ "Password must be at least 8 characters" ] } } } }, "Http401": { "description": "Authentication credentials are missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetailsResponse" }, "example": { "details": "Authentication credentials were not provided" } } } } }, "securitySchemes": { "Token": { "type": "apiKey", "description": "Token issued for API consumer.", "name": "Authorization", "in": "header" } } } } ````