Contents x
    Update a service ticket
    • 09 May 2025
    • 7 Minutes to read
    • Print
    • Dark
      Light
    Contents

    Update a service ticket

    • Updated on 09 May 2025
    • 7 Minutes to read
    • Print
    • Dark
      Light
    Article summary

    Put
    /api/v1/maintenance/servicetickets

    [PREVIEW] Update an existing service ticket.

    Description

    Update an existing service ticket. This will fully overwrite the service ticket with the data from the request. Both the 'reference' and the 'externalIdentifier' can be used to identify the service ticket which needs to be overwritten. Preferably only the reference is used. If this is not available, the externalIdentifier can be used. If both properties are used it is important that both are correct and match with the same service ticket. If this is not the case, the request will return with an error code and the service ticket will not be overwritten.

    The reference concerns the unique identifier created by Bloxs regarding this specific service ticket and is returned in the 200 response of the POST (create a service ticket). 

    Use Case

    The Bloxs user has added a service ticket with several incorrect properties. Therefore the user wants to change multiple properties at the same time rather than making several requests and changing one property at a time.    

    Request fields

    The request contains the following fields:

    FieldDescription
    referenceThe unique identifier for this service ticket within Bloxs. This is unique (per client specific environment) for all service tickets. This identifier is generated by the Bloxs system.
    externalIdentifierThe unique identifier within the system of the requesting party. This identifier is not generated by the Bloxs system.
    externalLinkThis field can be used to enter the url of the service ticket in a system outside of Bloxs. This allows the user to quickly navigate to the service ticket in another system, without searching for it.
    stateNameName of the current status of the service ticket. Bloxs provides a standard list with options, however the user can modify the list with options in the admin module. In order to retrieve the full list of currently available status names, the following endpoint can be used: GET states.
    priorityPriority level of the report. This is based on a fixed list predefined by Bloxs, and cannot be modified by users. Each priority level is linked to reminder settings, which trigger tasks or emails at a defined frequency.
    problemCategoryNamePertains to the problem category to which the service ticket belongs. This is a standard list predefined by Bloxs, that indicates the category of the issue, such as electrical, windows, etc. In order to retrieve the full list of available category names, the following endpoint can be used: GET problem categories.
    costsAreForTenantBoolean indicating whether the tenant is responsible for the costs associated with the service ticket. The default value is 'false', meaning the owner is responsible.
    costsCategoryName

    The cost category indicates the type of problem reported and serves as a tool to determine how the related costs should be allocated. For example, if the central heating system is not producing heat, the issue may require either a repair or a full replacement—each falling under a different cost category. Another example is the distinction between service charge costs and individual tenant charges. The available categories are predefined in a fixed list that cannot be modified by the user.

    In order to retrieve the full list of available cost categories, the following endpoint can be used: GET costs categories.

    descriptionDescription of the problem / the service ticket.
    supplierReferenceThis reference refers to the supplier. Please note that a relation reference (see relations API) must be included here and the supplier has to exist within Bloxs.
    handledBySupplierIf this is set to 'false', the supplier will receive a reminder to either accept or decline the order. The default value is false. The supplier is the party responsible for resolving the problem associated with the service ticket.
    expectedCostsThe estimated cost for resolving the issue.

    Response fields

    The 200 response contains the fields in the table below.

    FieldDescription
    externalIdentifierThe unique identifier within the system of the requesting party. This identifier is not generated by the Bloxs system.
    externalLink
    		This field can be used to enter the url of the service ticket in a system outside of Bloxs. This allows the user to quickly navigate to the service ticket in another system, without searching for it.
    reportingDate
    		The date on which the service ticket was created. This value is not automatically generated by the Bloxs system. If this field is left empty, the request will be invalid.
    stateName
    		Name of the current status of the service ticket. Bloxs provides a standard list with options, however the user can modify the list with options in the admin module. In order to retrieve the full list of currently available status names, the following endpoint can be used: GET states.
    priority
    		Priority level of the report. This is based on a fixed list predefined by Bloxs, and cannot be modified by users. Each priority level is linked to reminder settings, which trigger tasks or emails at a defined frequency.
    problemCategoryName
    		Pertains to the problem category to which the service ticket belongs. This is a standard list predefined by Bloxs, that indicates the category of the issue, such as electrical, windows, etc. In order to retrieve the full list of available category names, the following endpoint can be used: GET problem categories.
    costsAreForTenant
    		Boolean indicating whether the tenant is responsible for the costs associated with the service ticket. The default value is 'false', meaning the owner is responsible.
    costCategoryName

    The cost category indicates the type of problem reported and serves as a tool to determine how the related costs should be allocated. For example, if the central heating system is not producing heat, the issue may require either a repair or a full replacement—each falling under a different cost category. Another example is the distinction between service charge costs and individual tenant charges. The available categories are predefined in a fixed list that cannot be modified by the user.

    In order to retrieve the full list of available cost categories, the following endpoint can be used: GET cost categories.

    descriptionDescription of the problem / the service ticket.
    realEstateObjectReference
    		This pertains to the reference of the real estate object to which the service ticket applies. Please note, a reference relating to a real estate object must be included here.
    reporterReference

    This reference refers to the person who should be contacted with any communication regarding the service ticket. Please note that a reference of a relation (see relations API) must be included here and the contact has to exist within Bloxs.

    reporterContactPersonReference
    		This refers to the contact who reported the issue. Please note that a relation reference (see relations API) must be included here and the contact has to exist within Bloxs.
    reporterExternalContactPersonName
    		Name of the contact person. Please use this field only if the contact person is not available in Bloxs.
    reporterExternalContactPersonPhoneNumber
    		Telephone number of the contact person. Please use this field only if the contact person is not available in Bloxs.
    reporterExternalContactPersonMobileNumber
    		Mobile phone number of the contact person. Please use this field only if the contact person is not available in Bloxs.
    reporterExternalContactPersonEmail
    		Email address of the contact person. Please use this field only if the contact person is not available in Bloxs.
    supplierReference
    		This reference refers to the supplier. Please note that a relation reference (see relations API) must be included here and the supplier has to exist within Bloxs.
    handledBySupplierIf this is set to 'false', the supplier will receive a reminder to either accept or decline the order. The default value is false. The supplier is the party responsible for resolving the problem associated with the service ticket.
    expectedCosts

    The estimated cost for resolving the issue.

    reference

    The tenant reference. This will automatically be populated based on the date the service ticket was submitted and the registered tenant of the property at that time.

    mandateAmount
    		The maximum amount for which the supplier has the mandate to resolve the issues underlying the service ticket.
    Security
    HTTP
    Type Bearer

    Please enter a valid token

    Body parameters
    object
    reference
    string | null
    Min length0
    Max length100
    externalIdentifier
    string | null
    Min length0
    Max length100
    externalLink
    string | null
    Min length0
    Max length256
    stateName
    string Required
    Min length0
    Max length256
    priority
    integer (int32) Required

    1 = Low

    2 = Normal

    3 = High

    Valid values[ \1\, \2\, \3\ ]
    problemCategoryName
    string | null
    Min length0
    Max length256
    costsAreForTenant
    boolean
    costCategoryName
    string | null
    Min length0
    Max length256
    description
    string Required
    Min length0
    Max length512
    supplierReference
    string | null
    Min length0
    Max length100
    handledBySupplier
    boolean
    expectedCosts
    number (double) | null
    Responses
    200

    The service ticket was updated

    object
    externalIdentifier
    string | null
    Min length0
    Max length100
    externalLink
    string | null
    Min length0
    Max length256
    reportingDate
    string (date)
    stateName
    string
    Min length0
    Max length256
    priority
    integer (int32)

    1 = Low

    2 = Normal

    3 = High

    Valid values[ \1\, \2\, \3\ ]
    problemCategoryName
    string | null
    Min length0
    Max length256
    costsAreForTenant
    boolean
    costCategoryName
    string | null
    Min length0
    Max length256
    description
    string
    Min length0
    Max length512
    realEstateObjectReference
    string
    Min length0
    Max length100
    reporterReference
    string
    Min length0
    Max length100
    reporterContactPersonReference
    string | null
    Min length0
    Max length100
    reporterContactPersonType
    integer (int32)

    0 = ExistingRelation

    1 = External

    Valid values[ \0\, \1\ ]
    reporterExternalContactPersonName
    string | null
    Min length0
    Max length256
    reporterExternalContactPersonPhoneNumber
    string | null
    Min length0
    Max length512
    reporterExternalContactPersonMobileNumber
    string | null
    Min length0
    Max length512
    reporterExternalContactPersonEmail
    string | null
    Min length0
    Max length254
    supplierReference
    string | null
    Min length0
    Max length100
    handledBySupplier
    boolean
    expectedCosts
    number (double) | null
    reference
    string
    Min length0
    Max length100
    mandateAmount
    number (double) | null
    400

    The service ticket data has validation issues

    Expand All
    object
    type
    string | null
    title
    string | null
    traceId
    string | null
    status
    integer (int32)
    errors
    object | null
    property*
    Array of string | null additionalProperties
    string
    What's Next