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

    Create a service ticket

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

    Post
    /api/v1/maintenance/servicetickets

    [PREVIEW] Create a new service ticket.

    Description

    Insert (add) a service ticket related to maintenance or repair of one the real estate objects.

    The 200 response contains a field named 'reference'. It is important to save this value since it is used as an identifier in other operations to recognise this specific entity.

    Use Case

    The user wants to add a service ticket from a third party system to the Bloxs application. The data can be entered in the 'other system' and subsequently this endpoint can be used to register the service ticket in the Bloxs administration.

    Request fields

    The request contains the following fields:

    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.

    Response fields

    In addition to the data contained in the request, the response contains the fields in the table below. 

    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.
    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
    externalIdentifier
    string | null
    Min length0
    Max length100
    externalLink
    string | null
    Min length0
    Max length256
    reportingDate
    string (date) Required
    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
    realEstateObjectReference
    string Required
    Min length0
    Max length100
    reporterReference
    string Required
    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
    Responses
    200

    The service ticket was created

    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