Contents x
    Get a service ticket
    • 09 May 2025
    • 5 Minutes to read
    • Print
    • Dark
      Light
    Contents

    Get a service ticket

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

    Get
    /api/v1/maintenance/servicetickets

    [PREVIEW] Get an existing service ticket. Either reference or externalIdentifier must have a value. If both are given, both are used for retrieving the service ticket.

    Description

    Retrieve the information regarding an already existing service ticket. Either reference or externalIdentifier must have a value. Please note that if both identifiers are given, both must match; otherwise, an error message will be generated. It is recommended that the user utilizes only one identifier, with a preference for the reference. 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

    This operation allows the user to retrieve a specific service ticket along with its detailed information. For example, it can be used to display the service ticket’s description and current status in a client portal. This endpoint provides access to such details.

    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.

    Response fields

    The 200 response contains the fields in the table below. For the GET operation it gives a up-to-date insight in the data that is currently registered in Bloxs.

    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 costs 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 reference for the contact person and the details for any communication regarding the service ticket. Please note that a relation reference (see relations API) must be included here. Only fill this in if the contact person is listed in Bloxs. If the contact person is not available in Bloxs, please enter the name and phone number under reporterexternal.
    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 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.

    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

    Query parameters
    reference
    string

    The internal identifier of the model (i.e. Reference, Code, Name, depends on model).

    externalIdentifier
    string

    The external API identifier of the model.

    Responses
    200

    OK

    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
    404

    The requested service ticket was not found.

    What's Next