NOTE: This API is provided by a separate service.
This service automatically reserves a routed logical and/or physical connection for an existing circuit section, without the caller having to resolve the route itself. Two lookup/routing styles are supported: (a) Use Case A - a specific active device port is given via premId together with portId or portName (deviceId + portName is equivalent to portId). The service routes the reservation starting from that port. (b) Use Case B - only the installation address (addressId, or sourceSystem + sourceSystemKey) and usageId are given. The service automatically discovers a free, ready port at that installation address and routes the reservation from it. deviceClassId can restrict which device class the free port is searched on.
The target circuit (and its unreserved section) is resolved using any combination of circuitId, sectionId, name, name2, contractNumber, orderNumber, addressId, or sourceSystem + sourceSystemKey. At least one of these lookup parameters is required. If the lookup only identifies an installation address (addressId or sourceSystem/sourceSystemKey), usageId is also required to find a single, unambiguous section. sourceSystem and sourceSystemKey must always be given together.
At least one of logicalReservations or physicalReservations must be true; logicalReservations defaults to true for this endpoint. For Use Case A, premId is required together with portId or portName.
If the circuit has several unreserved sections, Use Case A reserves only the first of them, because the given port can back a single section. Use Case B reserves each unreserved section in order, each from the next free port found at the installation address.
On success, the resolved circuit section's usage state, construction state, bitrate and connection dates are updated as given, and the routed logical and/or physical reservations are created for the section.
Token issued for API consumer.
search criteria identifying the circuit section, and route/update parameters for the automatic reservation
Optional parameter for filtering in cases of multiple circuits retrieved
Optional parameter for filtering in cases of multiple circuit sections retrieved
Circuit contract number as alternative search criteria or update value
Circuit identifier as alternative search criteria or update value
Circuit alternative identifier as alternative search criteria or update value
Circuit order number as alternative search criteria or update value
Apartment level ID of circuit installation address, used to look up the circuit
Device ID of the active device port (Note! Used together with portName, or with portId alone)
Port ID of the active device port
Port Name of the active device port (Note! Requires deviceId to also be given)
Usage purpose ID of circuit section, used to look up the circuit
Circuit section connect date planned
Circuit section connect date real
Circuit section disconnect date planned
Circuit section disconnect date real
External source system ID. Must be given together with sourceSystemKey.
External source system address/apartment key. Must be given together with sourceSystem.
Internal ID of circuit section speed information
Internal ID of circuit section construction state information
Internal ID restricting the device class of the automatically discovered free port (Use Case B)
Internal ID restricting the type of installation address used to resolve the circuit
If true, only follow logical other-end connections when routing the reservation. Default is set to false. Only JSON booleans true/false are accepted; any other value (e.g. "false", "0", 0 or null) returns 400 (err1200000011).
Allow logical reservations creation. Default is set to true for this endpoint. Only JSON booleans true/false are accepted; any other value (e.g. "false", "0", 0 or null) returns 400 (err1200000011).
Allow physical reservations creation. Default is set to false. Only JSON booleans true/false are accepted; any other value (e.g. "false", "0", 0 or null) returns 400 (err1200000011).
Telecom Premise ID of the active device (Use Case A). Required together with portId or portName.
Logical direction to follow when routing the automatic reservation. 1 = ascending (to-center), 2 = descending (from-center), -1 = both directions. Default is 1. Any other value returns 400.
Name for the circuit section, used when the reservation creates a new section
Internal ID of circuit section usage state to set after the reservation
Circuit and sections with the created reservation data, route information, total length and total attenuation.
[
{
"areaCode": null,
"comments": null,
"contractLength": 4,
"contractNumber": "O2738",
"customer": null,
"directLength": null,
"id": 2216174,
"identifier": "Circuit X",
"identifierAlt": "Circuit Test",
"importance": null,
"installationAddresses": [
"http://keycom.example.com/api/v2/circuitlocations/40934190/"
],
"length": null,
"orderNumber": "O4260",
"organisation": null,
"redundancy": null,
"sections": [
{
"abnormalConnections": [],
"circuit": "http://keycom.example.com/api/v2/circuits/2216174/",
"connectionsToDelete": [],
"constructionState": {
"groupname": "KN_CONST_STATE",
"id": 6050,
"list_url": "http://keycom.example.com/api/v2/txt_constants/groupname/KN_CONST_STATE/",
"logical_txt": "Valmis",
"num_value": 1.0,
"txt": "Ready"
},
"id": 34734341,
"listUrl": "http://keycom.example.com/api/v2/sections/",
"name": "Circuit Section X",
"provisioningDevices": [],
"reservations": {
"logical": [
{
"ccp": {
"id": 829922070,
"listUrl": "http://keycom.example.com/api/v2/ccps/",
"name": "1",
"terminal": "http://keycom.example.com/api/v2/devices/53336290/"
},
"circuit": "http://keycom.example.com/api/v2/circuits/2216174/",
"connection": null,
"device": "http://keycom.example.com/api/v2/devices/53336290/",
"id": 14886290,
"premises": "http://keycom.example.com/api/v2/premises/80538490/",
"section": "http://keycom.example.com/api/v2/sections/34734341/"
}
],
"physical": [
{
"componentId": 829922070,
"componentType": "ccp",
"id": 40521170,
"listUrl": "http://keycom.example.com/api/v2/circuitphysicalreservations/"
}
]
},
"totalAttenuation": 0.9,
"totalLength": 125.4,
"usagePurpose": {
"groupname": "USAGE",
"id": 14750,
"list_url": "http://keycom.example.com/api/v2/txt_constants/groupname/USAGE/",
"logical_txt": "5 rahapuhelin",
"num_value": 5.0,
"txt": "5 Coin phone"
},
"usageState": {
"groupname": "KN_USAGE_STATE",
"id": 63501,
"list_url": "http://keycom.example.com/api/v2/txt_constants/groupname/KN_USAGE_STATE/",
"logical_txt": "Pian käytössä",
"num_value": 4.0,
"txt": "Soon used"
}
}
]
}
]Circuit area code
Circuit comments. Available from product version 3.2.8.
Circuit contract length
Circuit contract number
Creation timestamp (date and time). Available from product version v2026.1.
Creator username
Creation date (date only, existing field)
Building id
Building name
Building city name
Building city name in alternative language
Building country
creator
Creation date and time
Building district
Address with this value as 1 is default address. Modifying or deleting such address is prohibited.
Primary key
Geographical location
Building municipality
Property number
Building province
External source system
Ending date time for availability
Beginning date time for availability
Is object deemed as available. Based on availability_start_ts and availability_end_ts values.
Group name of constant
Unique id of constant
Url to fetch all constants from this group
Logical textual value
Numeric value
Numeric value 2
Numeric value 3
Numeric value 4
Human readable textual representation
source system key
Building street name
Building street name in alternative language
Building number
Building municipality subdivision
Last updater
Last update date time
Building usage purpose
Ending date time for availability
Beginning date time for availability
Is object deemed as available. Based on availability_start_ts and availability_end_ts values.
Group name of constant
Unique id of constant
Url to fetch all constants from this group
Logical textual value
Numeric value
Numeric value 2
Numeric value 3
Numeric value 4
Human readable textual representation
Address usage purpose
Ending date time for availability
Beginning date time for availability
Is object deemed as available. Based on availability_start_ts and availability_end_ts values.
Group name of constant
Unique id of constant
Url to fetch all constants from this group
Logical textual value
Numeric value
Numeric value 2
Numeric value 3
Numeric value 4
Human readable textual representation
Building zipcode
apartment division
apartment letter
apartment number
Apartment with this value as 1 is default apartment. Modifying or deleting such apartment is prohibited.
Primary key
apartment original property id
apartment original streen number
External source system
Ending date time for availability
Beginning date time for availability
Is object deemed as available. Based on availability_start_ts and availability_end_ts values.
Group name of constant
Unique id of constant
Url to fetch all constants from this group
Logical textual value
Numeric value
Numeric value 2
Numeric value 3
Numeric value 4
Human readable textual representation
source system key
Apartment Usage purpose
Ending date time for availability
Beginning date time for availability
Is object deemed as available. Based on availability_start_ts and availability_end_ts values.
Group name of constant
Unique id of constant
Url to fetch all constants from this group
Logical textual value
Numeric value
Numeric value 2
Numeric value 3
Numeric value 4
Human readable textual representation
Address usage purpose
Ending date time for availability
Beginning date time for availability
Is object deemed as available. Based on availability_start_ts and availability_end_ts values.
Group name of constant
Unique id of constant
Url to fetch all constants from this group
Logical textual value
Numeric value
Numeric value 2
Numeric value 3
Numeric value 4
Human readable textual representation
Apartment status
Ending date time for availability
Beginning date time for availability
Is object deemed as available. Based on availability_start_ts and availability_end_ts values.
Group name of constant
Unique id of constant
Url to fetch all constants from this group
Logical textual value
Numeric value
Numeric value 2
Numeric value 3
Numeric value 4
Human readable textual representation
Building id
Building name
Building city name
Building city name in alternative language
Building country
creator
Creation date and time
Building district
Address with this value as 1 is default address. Modifying or deleting such address is prohibited.
Primary key
Geographical location
Building municipality
Property number
Building province
External source system
Ending date time for availability
Beginning date time for availability
Is object deemed as available. Based on availability_start_ts and availability_end_ts values.
Group name of constant
Unique id of constant
Url to fetch all constants from this group
Logical textual value
Numeric value
Numeric value 2
Numeric value 3
Numeric value 4
Human readable textual representation
source system key
Building street name
Building street name in alternative language
Building number
Building municipality subdivision
Last updater
Last update date time
Building usage purpose
Ending date time for availability
Beginning date time for availability
Is object deemed as available. Based on availability_start_ts and availability_end_ts values.
Group name of constant
Unique id of constant
Url to fetch all constants from this group
Logical textual value
Numeric value
Numeric value 2
Numeric value 3
Numeric value 4
Human readable textual representation
Address usage purpose
Ending date time for availability
Beginning date time for availability
Is object deemed as available. Based on availability_start_ts and availability_end_ts values.
Group name of constant
Unique id of constant
Url to fetch all constants from this group
Logical textual value
Numeric value
Numeric value 2
Numeric value 3
Numeric value 4
Human readable textual representation
Building zipcode
apartment division
apartment letter
apartment number
Apartment with this value as 1 is default apartment. Modifying or deleting such apartment is prohibited.
Primary key
apartment original property id
apartment original streen number
External source system
Ending date time for availability
Beginning date time for availability
Is object deemed as available. Based on availability_start_ts and availability_end_ts values.
Group name of constant
Unique id of constant
Url to fetch all constants from this group
Logical textual value
Numeric value
Numeric value 2
Numeric value 3
Numeric value 4
Human readable textual representation
source system key
Apartment Usage purpose
Ending date time for availability
Beginning date time for availability
Is object deemed as available. Based on availability_start_ts and availability_end_ts values.
Group name of constant
Unique id of constant
Url to fetch all constants from this group
Logical textual value
Numeric value
Numeric value 2
Numeric value 3
Numeric value 4
Human readable textual representation
Address usage purpose
Ending date time for availability
Beginning date time for availability
Is object deemed as available. Based on availability_start_ts and availability_end_ts values.
Group name of constant
Unique id of constant
Url to fetch all constants from this group
Logical textual value
Numeric value
Numeric value 2
Numeric value 3
Numeric value 4
Human readable textual representation
Apartment status
Ending date time for availability
Beginning date time for availability
Is object deemed as available. Based on availability_start_ts and availability_end_ts values.
Group name of constant
Unique id of constant
Url to fetch all constants from this group
Logical textual value
Numeric value
Numeric value 2
Numeric value 3
Numeric value 4
Human readable textual representation
Customer billing name
Customer bussiness id
Customer contact name or null. Available from product version 2026.1
creator
Creation date and time
Customer email
Primary key
Customer mobile phone number name
Customer name
Customer number
Customer phone number
Sending sms is prohibited to customer
Customer fax number
Customer type
Ending date time for availability
Beginning date time for availability
Is object deemed as available. Based on availability_start_ts and availability_end_ts values.
Group name of constant
Unique id of constant
Url to fetch all constants from this group
Logical textual value
Numeric value
Numeric value 2
Numeric value 3
Numeric value 4
Human readable textual representation
Last updater
Last update date time
Circuit direct length
Primary key
Circuit identifier
Circuit alternative identifier
Circuit importance
Ending date time for availability
Beginning date time for availability
Is object deemed as available. Based on availability_start_ts and availability_end_ts values.
Group name of constant
Unique id of constant
Url to fetch all constants from this group
Logical textual value
Numeric value
Numeric value 2
Numeric value 3
Numeric value 4
Human readable textual representation
Circuit installations addresses
Circuit length
Circuit order number
Circuit organisation
Ending date time for availability
Beginning date time for availability
Is object deemed as available. Based on availability_start_ts and availability_end_ts values.
Group name of constant
Unique id of constant
Url to fetch all constants from this group
Logical textual value
Numeric value
Numeric value 2
Numeric value 3
Numeric value 4
Human readable textual representation
Circuit redundancy
Ending date time for availability
Beginning date time for availability
Is object deemed as available. Based on availability_start_ts and availability_end_ts values.
Group name of constant
Unique id of constant
Url to fetch all constants from this group
Logical textual value
Numeric value
Numeric value 2
Numeric value 3
Numeric value 4
Human readable textual representation
Circuit sections
Bitrate description
Primary key
Bitrate value
Circuit the section is in
actual section connection date
Txt constants construction state
Ending date time for availability
Beginning date time for availability
Is object deemed as available. Based on availability_start_ts and availability_end_ts values.
Group name of constant
Unique id of constant
Url to fetch all constants from this group
Logical textual value
Numeric value
Numeric value 2
Numeric value 3
Numeric value 4
Human readable textual representation
Creator username. Available from product version v2026.1.
Creation timestamp. Available from product version v2026.1.
actual section disconnection date
Extra usages for the Circuit Section. Available from product version 2026.1
Hyperlink to the related customer
Circuit Section Extra Usage Txt Constant definition
Availability end timestamp
Availability start timestamp
Whether the constant is available
Group name of constant
Unique id of constant
Url to fetch all constants from this group
Logical textual value
Numeric value 1
Numeric value 2
Numeric value 3
Numeric value 4
Human readable textual representation
Free text information
Optional name field 1
Optional name field 2
Optional name field 3
Optional name field 4
Primary key
Primary key
Section name
planned section connection date
planned section disconnection date
Last updater username. Available from product version v2026.1.
Last update timestamp. Available from product version v2026.1.
Circuit usage
Ending date time for availability
Beginning date time for availability
Is object deemed as available. Based on availability_start_ts and availability_end_ts values.
Group name of constant
Unique id of constant
Url to fetch all constants from this group
Logical textual value
Numeric value
Numeric value 2
Numeric value 3
Numeric value 4
Human readable textual representation
Circuit usage state
Ending date time for availability
Beginning date time for availability
Is object deemed as available. Based on availability_start_ts and availability_end_ts values.
Group name of constant
Unique id of constant
Url to fetch all constants from this group
Logical textual value
Numeric value
Numeric value 2
Numeric value 3
Numeric value 4
Human readable textual representation
Super circuit (nested in Circuit responses). Available from product version v2026.2.
Primary key
Super circuit identifier
Ending date time for availability
Beginning date time for availability
Is object deemed as available. Based on availability_start_ts and availability_end_ts values.
Group name of constant
Unique id of constant
Url to fetch all constants from this group
Logical textual value
Numeric value
Numeric value 2
Numeric value 3
Numeric value 4
Human readable textual representation
Ending date time for availability
Beginning date time for availability
Is object deemed as available. Based on availability_start_ts and availability_end_ts values.
Group name of constant
Unique id of constant
Url to fetch all constants from this group
Logical textual value
Numeric value
Numeric value 2
Numeric value 3
Numeric value 4
Human readable textual representation
Ending date time for availability
Beginning date time for availability
Is object deemed as available. Based on availability_start_ts and availability_end_ts values.
Group name of constant
Unique id of constant
Url to fetch all constants from this group
Logical textual value
Numeric value
Numeric value 2
Numeric value 3
Numeric value 4
Human readable textual representation
Order number of this circuit within the super circuit. Available from product version v2026.2.
Last update timestamp (date and time). Available from product version v2026.1.
Last updater username
Last update date (date only, existing field)
Multiple Choices
{
"details": "Object has multiple resources"
}Detailed description of error
Request could not be processed because it was invalid.
Either validation failed (field-level errors are returned), or a generic bad request message is provided.
{
"email": [
"Email is required",
"Email must be valid"
],
"password": [
"Password must be at least 8 characters"
]
}Validation errors by field name or a generic bad request description
Description of the error for generic bad request responses
List of validation error messages for this field name
Validation error message
Authentication credentials are missing or invalid
{
"details": "Authentication credentials were not provided"
}Standard error response payload
Detailed description of error
Object was not found
{
"details": "Not found."
}Standard error response payload
Detailed description of error